ktor-client-core / io.ktor.client / HttpClient

HttpClient

class HttpClient : CoroutineScope

Asynchronous client to perform HTTP requests.

This is a generic implementation that uses a specific engine HttpClientEngine.

Constructors

<init>

HttpClient(engine: HttpClientEngine, userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig())

Asynchronous client to perform HTTP requests.

Properties

attributes

val attributes: Attributes

Typed attributes used as a lightweight container for this client.

coroutineContext

val coroutineContext: <ERROR CLASS>

dispatcher

val dispatcher: CoroutineDispatcher

Dispatcher handles io operations.

engine

val engine: HttpClientEngine

: HttpClientEngine for executing requests.

engineConfig

val engineConfig: HttpClientEngineConfig

Client engine config.

receivePipeline

val receivePipeline: HttpReceivePipeline

Pipeline used for receiving request.

requestPipeline

val requestPipeline: HttpRequestPipeline

Pipeline used for processing all the requests sent by this client.

responsePipeline

val responsePipeline: HttpResponsePipeline

Pipeline used for processing all the responses sent by the server.

sendPipeline

val sendPipeline: HttpSendPipeline

Pipeline used for sending the request.

Functions

close

fun close(): Unit

Closes the underlying engine.

config

fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient

Returns a new HttpClient copying this client configuration, and additionally configured by the block parameter.

execute

suspend fun execute(builder: HttpRequestBuilder): HttpClientCall

Creates a new HttpRequest from a request data and a specific client call.

isSupported

fun isSupported(capability: HttpClientEngineCapability<*>): Boolean

Check if the specified capability is supported by this client.

toString

fun toString(): String

Extension Functions

call

suspend fun HttpClient.call(block: suspend HttpRequestBuilder.() -> Unit = {}): HttpClientCall

Constructs a HttpClientCall from this HttpClient and with the specified HttpRequestBuilder configured inside the block.

suspend fun HttpClient.call(builder: HttpRequestBuilder): HttpClientCall

Constructs a HttpClientCall from this HttpClient and with the specified HTTP request builder.

suspend fun HttpClient.call(urlString: String, block: suspend HttpRequestBuilder.() -> Unit = {}): HttpClientCall
suspend fun HttpClient.call(url: Url, block: suspend HttpRequestBuilder.() -> Unit = {}): HttpClientCall
suspend fun HttpClient.call(url: URL, block: HttpRequestBuilder.() -> Unit = {}): HttpClientCall

Constructs a HttpClientCall from this HttpClient, an url and an optional block configuring a HttpRequestBuilder.

cookies

suspend fun HttpClient.cookies(url: Url): List<Cookie>

Gets all the cookies for the specified url for this HttpClient.

suspend fun HttpClient.cookies(urlString: String): List<Cookie>

Gets all the cookies for the specified urlString for this HttpClient.

defaultTransformers

fun HttpClient.defaultTransformers(): Unit

Install default transformers. Usually installed by default so there is no need to use it unless you have disabled it via HttpClientConfig.useDefaultTransformers.

delete

suspend fun <T> HttpClient.delete(builder: HttpRequestBuilder): T

Executes a HttpClient DELETE request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.delete(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient DELETE request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.delete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient DELETE request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.delete(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient HEAD request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.delete(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient HEAD request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

feature

fun <B : Any, F : Any> HttpClient.feature(feature: HttpClientFeature<B, F>): F?

Try to get the feature installed in this client. Returns null if the feature was not previously installed.

get

operator fun <B : Any, F : Any> HttpClient.get(feature: HttpClientFeature<B, F>): F

Find the feature installed in HttpClient.

get

suspend fun <T> HttpClient.get(builder: HttpRequestBuilder): T

Executes a HttpClient GET request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.get(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient GET request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.get(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.get(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient GET request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.get(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient GET request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

head

suspend fun <T> HttpClient.head(builder: HttpRequestBuilder): T

Executes a HttpClient HEAD request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.head(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient HEAD request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.head(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.head(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient HEAD request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.head(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient HEAD request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

mapEngineExceptions

fun CoroutineScope.mapEngineExceptions(input: ByteReadChannel, request: HttpRequestData): ByteReadChannel

Returns ByteReadChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.

fun CoroutineScope.mapEngineExceptions(output: ByteWriteChannel, request: HttpRequestData): ByteWriteChannel

Returns ByteWriteChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.

options

suspend fun <T> HttpClient.options(builder: HttpRequestBuilder): T

Executes a HttpClient OPTIONS request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.options(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient OPTIONS request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.options(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.options(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient OPTIONS request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.options(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient OPTIONS request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

patch

suspend fun <T> HttpClient.patch(builder: HttpRequestBuilder): T

Executes a HttpClient PATCH request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.patch(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PATCH request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.patch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.patch(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PATCH request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.patch(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PATCH request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

post

suspend fun <T> HttpClient.post(builder: HttpRequestBuilder): T

Executes a HttpClient POST request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.post(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient POST request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.post(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.post(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient POST request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.post(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient POST request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

put

suspend fun <T> HttpClient.put(builder: HttpRequestBuilder): T

Executes a HttpClient PUT request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.put(scheme: String = "http", host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", body: Any = EmptyContent, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PUT request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.put(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.put(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PUT request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.put(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient PUT request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

request

suspend fun <T> HttpClient.request(builder: HttpRequestBuilder = HttpRequestBuilder()): T

Executes a HttpClient request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(block: HttpRequestBuilder.() -> Unit): T

Executes a HttpClient request, with the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient request, with the urlString and the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(url: Url, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient request, with the url and the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(url: URL, block: HttpRequestBuilder.() -> Unit = {}): T

Executes a HttpClient request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

submitForm

suspend fun <T> HttpClient.submitForm(formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.submitForm(url: String, formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.submitForm(scheme: String = "http", host: String = "localhost", port: Int = 80, path: String = "/", formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): T

Submit formParameters request.

submitFormWithBinaryData

suspend fun <T> HttpClient.submitFormWithBinaryData(formData: List<PartData>, block: HttpRequestBuilder.() -> Unit = {}): T
suspend fun <T> HttpClient.submitFormWithBinaryData(scheme: String = "http", host: String = "localhost", port: Int = 80, path: String = "/", formData: List<PartData> = emptyList(), block: HttpRequestBuilder.() -> Unit = {}): T

Send HttpMethod.Post request with formData encoded in body. formData encoded using multipart/form-data format. https://tools.ietf.org/html/rfc2045

suspend fun <T> HttpClient.submitFormWithBinaryData(url: String, formData: List<PartData>, block: HttpRequestBuilder.() -> Unit = {}): T

Send HttpMethod.Post request with formData encoded in body. url destination formData encoded using multipart/form-data format.

webSocket

suspend fun HttpClient.webSocket(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.webSocket(method: HttpMethod = HttpMethod.Get, host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.webSocket(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit

Open block with DefaultClientWebSocketSession.

webSocketSession

suspend fun HttpClient.webSocketSession(block: HttpRequestBuilder.() -> Unit): DefaultClientWebSocketSession
suspend fun HttpClient.webSocketSession(method: HttpMethod = HttpMethod.Get, host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", block: HttpRequestBuilder.() -> Unit = {}): DefaultClientWebSocketSession

Open DefaultClientWebSocketSession.

ws

suspend fun HttpClient.ws(method: HttpMethod = HttpMethod.Get, host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.ws(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.ws(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit

Open block with DefaultClientWebSocketSession.

wss

suspend fun HttpClient.wss(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.wss(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit
suspend fun HttpClient.wss(method: HttpMethod = HttpMethod.Get, host: String = "localhost", port: Int = DEFAULT_PORT, path: String = "/", request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit): Unit

Open block with secure DefaultClientWebSocketSession.