Не подтверждена Коммит d6b9a87c создал по автору Andrey Aksenov's avatar Andrey Aksenov Зафиксировано автором GitHub
Просмотр файлов

KTOR-4924 update API docs for the client (#3176)

владелец c44dffae
Развернуть все Скрыть пробелы
Построчно Рядом
ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt
Просмотр файла @ d6b9a87c
......@@ -18,10 +18,10 @@ import kotlinx.coroutines.*
import kotlin.coroutines.*
/**
* Constructs an asynchronous [HttpClient] using optional [block] for configuring this client.
* Creates an asynchronous [HttpClient] with the specified [block] configuration.
*
* The [HttpClientEngine] is selected from the dependencies.
* https://ktor.io/docs/http-client-engines.html
* Note that the client requires an engine for processing network requests.
* The [HttpClientEngine] is selected from the [dependencies](https://ktor.io/docs/client-dependencies.html).
*/
@KtorDsl
public expect fun HttpClient(
......@@ -29,8 +29,9 @@ public expect fun HttpClient(
): HttpClient
/**
* Constructs an asynchronous [HttpClient] using the specified [engineFactory]
* and an optional [block] for configuring this client.
* Creates an asynchronous [HttpClient] with the specified [HttpClientEngineFactory] and optional [block] configuration.
* Note that a specific platform may require a specific engine for processing requests.
* You can learn more about available engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/
@KtorDsl
public fun <T : HttpClientEngineConfig> HttpClient(
......@@ -51,8 +52,9 @@ public fun <T : HttpClientEngineConfig> HttpClient(
}
/**
* Constructs an asynchronous [HttpClient] using the specified [engine]
* and a [block] for configuring this client.
* Creates an asynchronous [HttpClient] with the specified [HttpClientEngine] and optional [block] configuration.
* Note that a specific platform may require a specific engine for processing requests.
* You can learn more about available engines from [Engines](https://ktor.io/docs/http-client-engines.html).
*/
@KtorDsl
public fun HttpClient(
......@@ -61,10 +63,12 @@ public fun HttpClient(
): HttpClient = HttpClient(engine, HttpClientConfig<HttpClientEngineConfig>().apply(block), manageEngine = false)
/**
* Asynchronous client to perform HTTP requests.
* A multiplatform asynchronous HTTP client, which allows you to make requests and handle responses,
* extend its functionality with plugins, such as authentication, JSON serialization, and so on.
*
* This is a generic implementation that uses a specific engine [HttpClientEngine].
* @property engine: [HttpClientEngine] for executing requests.
* You can learn how to create a configure [HttpClient] from
* [Creating and configuring a client](https://ktor.io/docs/create-client.html).
* @property engine [HttpClientEngine] used to execute network requests.
*/
@OptIn(InternalAPI::class)
public class HttpClient(
......@@ -88,22 +92,22 @@ public class HttpClient(
public override val coroutineContext: CoroutineContext = engine.coroutineContext + clientJob
/**
* Pipeline used for processing all the requests sent by this client.
* A pipeline used for processing all requests sent by this client.
*/
public val requestPipeline: HttpRequestPipeline = HttpRequestPipeline(userConfig.developmentMode)
/**
* Pipeline used for processing all the responses sent by the server.
* A pipeline used for processing all responses sent by the server.
*/
public val responsePipeline: HttpResponsePipeline = HttpResponsePipeline(userConfig.developmentMode)
/**
* Pipeline used for sending the request.
* A pipeline used for sending a request.
*/
public val sendPipeline: HttpSendPipeline = HttpSendPipeline(userConfig.developmentMode)
/**
* Pipeline used for receiving request.
* A pipeline used for receiving a request.
*/
public val receivePipeline: HttpReceivePipeline = HttpReceivePipeline(userConfig.developmentMode)
......@@ -113,12 +117,12 @@ public class HttpClient(
public val attributes: Attributes = Attributes(concurrent = true)
/**
* Client engine config.
* Provides access to the client's engine configuration.
*/
public val engineConfig: HttpClientEngineConfig = engine.config
/**
* Provides events on client lifecycle
* Provides access to the events of the client's lifecycle.
*/
public val monitor: Events = Events()
......@@ -188,14 +192,14 @@ public class HttpClient(
}
/**
* Check if the specified [capability] is supported by this client.
* Checks if the specified [capability] is supported by this client.
*/
public fun isSupported(capability: HttpClientEngineCapability<*>): Boolean {
return engine.supportedCapabilities.contains(capability)
}
/**
* Returns a new [HttpClient] copying this client configuration,
* Returns a new [HttpClient] by copying this client's configuration
* and additionally configured by the [block] parameter.
*/
public fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient = HttpClient(
......
ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt
Просмотр файла @ d6b9a87c
......@@ -12,7 +12,9 @@ import io.ktor.utils.io.concurrent.*
import kotlin.collections.set
/**
* Mutable configuration used by [HttpClient].
* A mutable [HttpClient] configuration.
* Learn more about the client's configuration from
* [Creating and configuring a client](https://ktor.io/docs/create-client.html).
*/
@KtorDsl
public class HttpClientConfig<T : HttpClientEngineConfig> {
......@@ -23,7 +25,9 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
internal var engineConfig: T.() -> Unit = {}
/**
* Configure engine parameters.
* Allows you to configure engine parameters.
*
* You can learn more from [Engines](https://ktor.io/docs/http-client-engines.html).
*/
public fun engine(block: T.() -> Unit) {
val oldConfig = engineConfig
......@@ -34,27 +38,31 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
}
/**
* Use [HttpRedirect] plugin to automatically follow redirects.
* Specifies whether the client redirects to URLs provided in the `Location` header.
* You can disable redirections by setting this property to `false`.
*/
public var followRedirects: Boolean = true
/**
* Use [defaultTransformers] to automatically handle simple [ContentType].
* Uses [defaultTransformers] to automatically handle simple [ContentType].
*/
public var useDefaultTransformers: Boolean = true
/**
* Terminate [HttpClient.receivePipeline] if status code is not successful (>=300).
* Terminates [HttpClient.receivePipeline] if the status code is not successful (>=300).
* Learn more from [Response validation](https://ktor.io/docs/response-validation.html).
*/
public var expectSuccess: Boolean = false
/**
* Indicate if client should use development mode. In development mode client pipelines have advanced stack traces.
* Indicates whether the client should use [development mode](https://ktor.io/docs/development-mode.html).
* In development mode, the client's pipelines have advanced stack traces.
*/
public var developmentMode: Boolean = PlatformUtils.IS_DEVELOPMENT_MODE
/**
* Installs a specific [plugin] and optionally [configure] it.
* Installs the specified [plugin] and optionally configures it using the [configure] block.
* Learn more from [Plugins](https://ktor.io/docs/http-client-plugins.html).
*/
public fun <TBuilder : Any, TPlugin : Any> install(
plugin: HttpClientPlugin<TBuilder, TPlugin>,
......@@ -98,7 +106,7 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
}
/**
* Clones this [HttpClientConfig] duplicating all the [plugins] and [customInterceptors].
* Clones this [HttpClientConfig] by duplicating all the [plugins] and [customInterceptors].
*/
public fun clone(): HttpClientConfig<T> {
val result = HttpClientConfig<T>()
......@@ -107,7 +115,7 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
}
/**
* Install plugin from [other] client config.
* Installs the plugin from the [other] client's configuration.
*/
public operator fun plusAssign(other: HttpClientConfig<out T>) {
followRedirects = other.followRedirects
......
ktor-client/ktor-client-core/common/src/io/ktor/client/call/HttpClientCall.kt
Просмотр файла @ d6b9a87c
......@@ -18,9 +18,9 @@ import kotlin.coroutines.*
import kotlin.reflect.*
/**
* A class that represents a single pair of [request] and [response] for a specific [HttpClient].
* A pair of a [request] and [response] for a specific [HttpClient].
*
* @property client: client that executed the call.
* @property client the client that executed the call.
*/
public open class HttpClientCall(
public val client: HttpClient
......@@ -35,13 +35,13 @@ public open class HttpClientCall(
public val attributes: Attributes get() = request.attributes
/**
* Represents the [request] sent by the client
* The [request] sent by the client.
*/
public lateinit var request: HttpRequest
protected set
/**
* Represents the [response] sent by the server.
* The [response] sent by the server.
*/
public lateinit var response: HttpResponse
protected set
......
ktor-client/ktor-client-core/common/src/io/ktor/client/engine/HttpClientEngine.kt
Просмотр файла @ d6b9a87c
......@@ -19,16 +19,16 @@ internal val CALL_COROUTINE = CoroutineName("call-context")
internal val CLIENT_CONFIG = AttributeKey<HttpClientConfig<*>>("client-config")
/**
* Base interface use to define engines for [HttpClient].
* Serves as the base interface for an [HttpClient]'s engine.
*/
public interface HttpClientEngine : CoroutineScope, Closeable {
/**
* [CoroutineDispatcher] specified for io operations.
* Specifies [CoroutineDispatcher] for I/O operations.
*/
public val dispatcher: CoroutineDispatcher
/**
* Engine configuration
* Provides access to an engine's configuration.
*/
public val config: HttpClientEngineConfig
......@@ -48,7 +48,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
public suspend fun execute(data: HttpRequestData): HttpResponseData
/**
* Install engine into [HttpClient].
* Installs the engine to [HttpClient].
*/
@InternalAPI
public fun install(client: HttpClient) {
......@@ -84,7 +84,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
}
/**
* Create call context and use it as a coroutine context to [execute] request.
* Creates a call context and uses it as a coroutine context to [execute] a request.
*/
@OptIn(InternalAPI::class)
private suspend fun executeWithinCallContext(requestData: HttpRequestData): HttpResponseData {
......@@ -108,7 +108,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
}
/**
* Factory of [HttpClientEngine] with a specific [T] of [HttpClientEngineConfig].
* A factory of [HttpClientEngine] with a specific [T] of [HttpClientEngineConfig].
*/
public interface HttpClientEngineFactory<out T : HttpClientEngineConfig> {
/**
......@@ -135,7 +135,7 @@ public fun <T : HttpClientEngineConfig> HttpClientEngineFactory<T>.config(
}
/**
* Create call context with the specified [parentJob] to be used during call execution in the engine. Call context
* Creates a call context with the specified [parentJob] to be used during call execution in the engine. Call context
* inherits [coroutineContext], but overrides job and coroutine name so that call job's parent is [parentJob] and
* call coroutine's name is "call-context".
*/
......
ktor-client/ktor-client-core/common/src/io/ktor/client/engine/HttpClientEngineBase.kt
Просмотр файла @ d6b9a87c
......@@ -35,13 +35,13 @@ public abstract class HttpClientEngineBase(private val engineName: String) : Htt
}
/**
* Exception that indicates that client engine is already closed.
* An exception indicating that the client's engine is already closed.
*/
public class ClientEngineClosedException(override val cause: Throwable? = null) :
IllegalStateException("Client already closed")
/**
* Close [CoroutineDispatcher] if it's [CloseableCoroutineDispatcher] or [Closeable].
* Closes [CoroutineDispatcher] if it's [CloseableCoroutineDispatcher] or [Closeable].
*/
@OptIn(ExperimentalCoroutinesApi::class)
private fun CoroutineDispatcher.close() {
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/HttpRequest.kt
Просмотр файла @ d6b9a87c
......@@ -53,7 +53,9 @@ public interface HttpRequest : HttpMessage, CoroutineScope {
}
/**
* Class for building [HttpRequestData].
* Contains parameters used to make an HTTP request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
@Suppress("DEPRECATION")
public class HttpRequestBuilder : HttpMessageBuilder {
......@@ -98,7 +100,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
internal set
/**
* Call specific attributes.
* Provides access to attributes specific for this request.
*/
public val attributes: Attributes = Attributes(concurrent = true)
......@@ -108,7 +110,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
public fun url(block: URLBuilder.(URLBuilder) -> Unit): Unit = url.block(url)
/**
* Create immutable [HttpRequestData]
* Creates immutable [HttpRequestData].
*/
@OptIn(InternalAPI::class)
public fun build(): HttpRequestData = HttpRequestData(
......@@ -121,14 +123,14 @@ public class HttpRequestBuilder : HttpMessageBuilder {
)
/**
* Set request specific attributes specified by [block].
* Sets request-specific attributes specified by [block].
*/
public fun setAttributes(block: Attributes.() -> Unit) {
attributes.apply(block)
}
/**
* Mutates [this] copying all the data from another [builder] using it as base.
* Mutates [this] copying all the data from another [builder] using it as the base.
*/
@InternalAPI
public fun takeFromWithExecutionContext(builder: HttpRequestBuilder): HttpRequestBuilder {
......@@ -137,7 +139,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
}
/**
* Mutates [this] copying all the data but execution context from another [builder] using it as base.
* Mutates [this] by copying all the data but execution context from another [builder] using it as the base.
*/
@OptIn(InternalAPI::class)
public fun takeFrom(builder: HttpRequestBuilder): HttpRequestBuilder {
......@@ -153,7 +155,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
}
/**
* Set capability configuration.
* Sets capability configuration.
*/
@OptIn(InternalAPI::class)
public fun <T : Any> setCapability(key: HttpClientEngineCapability<T>, capability: T) {
......@@ -162,7 +164,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
}
/**
* Retrieve capability by key.
* Retrieves capability by the key.
*/
public fun <T : Any> getCapabilityOrNull(key: HttpClientEngineCapability<T>): T? {
@Suppress("UNCHECKED_CAST")
......@@ -257,14 +259,14 @@ public fun HttpRequestBuilder.takeFrom(request: HttpRequestData): HttpRequestBui
}
/**
* Executes a [block] that configures the [URLBuilder] associated to thisrequest.
* Executes a [block] that configures the [URLBuilder] associated to this request.
*/
public operator fun HttpRequestBuilder.Companion.invoke(block: URLBuilder.() -> Unit): HttpRequestBuilder =
HttpRequestBuilder().apply { url(block) }
/**
* Sets the [url] using the specified [scheme], [host], [port] and [path].
* Pass `null` to keep existing value in the [URLBuilder].
* Pass `null` to keep the existing value in the [URLBuilder].
*/
public fun HttpRequestBuilder.url(
scheme: String? = null,
......@@ -279,7 +281,7 @@ public fun HttpRequestBuilder.url(
/**
* Constructs a [HttpRequestBuilder] from URL information: [scheme], [host], [port] and [path]
* and optionally further configures it using [block].
* Pass `null` to keep existing value in the [URLBuilder].
* Pass `null` to keep the existing value in the [URLBuilder].
*/
public operator fun HttpRequestBuilder.Companion.invoke(
scheme: String? = null,
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/HttpRequestPipeline.kt
Просмотр файла @ d6b9a87c
......@@ -9,45 +9,45 @@ import io.ktor.client.call.*
import io.ktor.util.pipeline.*
/**
* [HttpClient] Pipeline used for executing [HttpRequest].
* An [HttpClient]'s pipeline used for executing [HttpRequest].
*/
public class HttpRequestPipeline(
override val developmentMode: Boolean = false
) : Pipeline<Any, HttpRequestBuilder>(Before, State, Transform, Render, Send) {
/**
* All interceptors accept payload as [subject] and try to convert it to [OutgoingContent]
* Last phase should proceed with [HttpClientCall]
* All interceptors accept payload as [subject] and try to convert it to [OutgoingContent].
* Last phase should proceed with [HttpClientCall].
*/
public companion object Phases {
/**
* The earliest phase that happens before any other
* The earliest phase that happens before any other.
*/
public val Before: PipelinePhase = PipelinePhase("Before")
/**
* Use this phase to modify request with shared state
* Use this phase to modify a request with a shared state.
*/
public val State: PipelinePhase = PipelinePhase("State")
/**
* Transform request body to supported render format
* Transform a request body to supported render format.
*/
public val Transform: PipelinePhase = PipelinePhase("Transform")
/**
* Encode request body to [OutgoingContent]
* Encode a request body to [OutgoingContent].
*/
public val Render: PipelinePhase = PipelinePhase("Render")
/**
* Phase for [HttpSend] plugin
* A phase for the [HttpSend] plugin.
*/
public val Send: PipelinePhase = PipelinePhase("Send")
}
}
/**
* [HttpClient] Pipeline used for sending [HttpRequest] to remote server.
* An [HttpClient]'s pipeline used for sending [HttpRequest] to a remote server.
*/
public class HttpSendPipeline(
override val developmentMode: Boolean = false
......@@ -60,22 +60,22 @@ public class HttpSendPipeline(
public val Before: PipelinePhase = PipelinePhase("Before")
/**
* Use this phase to modify request with shared state.
* Use this phase to modify request with a shared state.
*/
public val State: PipelinePhase = PipelinePhase("State")
/**
* Use this phase for logging and other actions that don't modify request or shared data.
* Use this phase for logging and other actions that don't modify a request or shared data.
*/
public val Monitoring: PipelinePhase = PipelinePhase("Monitoring")
/**
* Send request to remote server.
* Send a request to a remote server.
*/
public val Engine: PipelinePhase = PipelinePhase("Engine")
/**
* Receive pipeline execution phase.
* Receive a pipeline execution phase.
*/
public val Receive: PipelinePhase = PipelinePhase("Receive")
}
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/builders.kt
Просмотр файла @ d6b9a87c
Это отличие свёрнуто
ktor-client/ktor-client-core/common/src/io/ktor/client/request/buildersWithUrl.kt
Просмотр файла @ d6b9a87c
......@@ -9,8 +9,10 @@ import io.ktor.client.statement.*
import io.ktor.http.*
/**
* Executes a [HttpClient] GET request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] GET request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.get(
url: Url,
......@@ -21,8 +23,8 @@ public suspend inline fun HttpClient.get(
}
/**
* Prepares a [HttpClient] GET request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] GET request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.prepareGet(
url: Url,
......@@ -33,8 +35,10 @@ public suspend inline fun HttpClient.prepareGet(
}
/**
* Executes a [HttpClient] POST request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] POST request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.post(
url: Url,
......@@ -45,8 +49,8 @@ public suspend inline fun HttpClient.post(
}
/**
* Prepares a [HttpClient] POST request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] POST request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.preparePost(
url: Url,
......@@ -57,8 +61,10 @@ public suspend inline fun HttpClient.preparePost(
}
/**
* Executes a [HttpClient] PUT request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] PUT request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.put(
url: Url,
......@@ -69,8 +75,8 @@ public suspend inline fun HttpClient.put(
}
/**
* Prepares a [HttpClient] PUT request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] PUT request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.preparePut(
url: Url,
......@@ -81,8 +87,10 @@ public suspend inline fun HttpClient.preparePut(
}
/**
* Executes a [HttpClient] PATCH request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] PATCH request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.patch(
url: Url,
......@@ -93,8 +101,8 @@ public suspend inline fun HttpClient.patch(
}
/**
* Prepares a [HttpClient] PATCH request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] PATCH request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.preparePatch(
url: Url,
......@@ -105,8 +113,10 @@ public suspend inline fun HttpClient.preparePatch(
}
/**
* Executes a [HttpClient] OPTIONS request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] OPTIONS request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.options(
url: Url,
......@@ -117,8 +127,8 @@ public suspend inline fun HttpClient.options(
}
/**
* Prepares a [HttpClient] OPTIONS request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] OPTIONS request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.prepareOptions(
url: Url,
......@@ -129,8 +139,10 @@ public suspend inline fun HttpClient.prepareOptions(
}
/**
* Executes a [HttpClient] HEAD request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] HEAD request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.head(
url: Url,
......@@ -141,8 +153,8 @@ public suspend inline fun HttpClient.head(
}
/**
* Prepares a [HttpClient] HEAD request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] HEAD request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.prepareHead(
url: Url,
......@@ -153,8 +165,10 @@ public suspend inline fun HttpClient.prepareHead(
}
/**
* Executes a [HttpClient] HEAD request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Executes a [HttpClient] HEAD request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*
* Learn more from [Making requests](https://ktor.io/docs/request.html).
*/
public suspend inline fun HttpClient.delete(
url: Url,
......@@ -165,8 +179,8 @@ public suspend inline fun HttpClient.delete(
}
/**
* Prepares a [HttpClient] HEAD request, with the specified [url] as Url and
* an optional [block] receiving an [HttpRequestBuilder] for further configuring the request.
* Prepares a [HttpClient] HEAD request with the specified [url] and
* an optional [block] receiving an [HttpRequestBuilder] for configuring the request.
*/
public suspend inline fun HttpClient.prepareDelete(
url: Url,
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/forms/FormDataContent.kt
Просмотр файла @ d6b9a87c
......@@ -14,7 +14,9 @@ import kotlin.random.*
private val RN_BYTES = "\r\n".toByteArray()
/**
* [OutgoingContent] with for application/x-www-form-urlencoded formatted request.
* [OutgoingContent] with for the `application/x-www-form-urlencoded` formatted request.
*
* Example: [Form parameters](https://ktor.io/docs/request.html#form_parameters).
*
* @param formData: data to send.
*/
......@@ -30,7 +32,9 @@ public class FormDataContent(
}
/**
* [OutgoingContent] for multipart/form-data formatted request.
* [OutgoingContent] for a `multipart/form-data` formatted request.
*
* Example: [Upload a file](https://ktor.io/docs/request.html#upload_file).
*
* @param parts: form part data
*/
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/forms/formBuilders.kt
Просмотр файла @ d6b9a87c
......@@ -11,12 +11,12 @@ import io.ktor.http.*
import io.ktor.http.content.*
/**
* Submit [formParameters] request.
* Makes a request containing form parameters encoded using the `x-www-form-urlencoded` format.
*
* If [encodeInQuery] specified encode [formParameters] in url parameters and use [HttpMethod.Get] for the request.
* Otherwise send [HttpMethod.Post] request with [formParameters] encoded in body.
* If [encodeInQuery] is set to `true`, form parameters are sent as URL parameters using the GET request.
* Otherwise, form parameters are sent in a POST request body.
*
* [formParameters] encoded using application/x-www-form-urlencoded format.
* Example: [Form parameters](https://ktor.io/docs/request.html#form_parameters).
*/
public suspend inline fun HttpClient.submitForm(
formParameters: Parameters = Parameters.Empty,
......@@ -35,13 +35,12 @@ public suspend inline fun HttpClient.submitForm(
}
/**
* Submit [formParameters] request.
* Makes a request containing form parameters encoded using the `x-www-form-urlencoded` format.
*
* If [encodeInQuery] specified encode [formParameters] in url parameters and use [HttpMethod.Get] for the request.
* Otherwise send [HttpMethod.Post] request with [formParameters] encoded in body.
* If [encodeInQuery] is set to `true`, form parameters are sent as URL parameters using the GET request.
* Otherwise, form parameters are sent in a POST request body.
*
* [url] destination
* [formParameters] encoded using application/x-www-form-urlencoded format.
* Example: [Form parameters](https://ktor.io/docs/request.html#form_parameters).
*/
public suspend fun HttpClient.submitForm(
url: String,
......@@ -54,9 +53,9 @@ public suspend fun HttpClient.submitForm(
}
/**
* Send [HttpMethod.Post] request with [formData] encoded in body.
* [formData] encoded using multipart/form-data format.
* https://tools.ietf.org/html/rfc2045
* Makes a POST request containing form parameters encoded using the `multipart/form-data` format.
*
* Example: [Upload a file](https://ktor.io/docs/request.html#upload_file).
*/
public suspend inline fun HttpClient.submitFormWithBinaryData(
formData: List<PartData>,
......@@ -68,11 +67,9 @@ public suspend inline fun HttpClient.submitFormWithBinaryData(
}
/**
* Send [HttpMethod.Post] request with [formData] encoded in body.
* [url] destination
* [formData] encoded using multipart/form-data format.
* Makes a POST request containing form parameters encoded using the `multipart/form-data` format.
*
* https://tools.ietf.org/html/rfc2045
* Example: [Upload a file](https://ktor.io/docs/request.html#upload_file).
*/
public suspend inline fun HttpClient.submitFormWithBinaryData(
url: String,
......@@ -84,12 +81,10 @@ public suspend inline fun HttpClient.submitFormWithBinaryData(
}
/**
* Prepare [formParameters] request.
*
* If [encodeInQuery] specified encode [formParameters] in url parameters and use [HttpMethod.Get] for the request.
* Otherwise send [HttpMethod.Post] request with [formParameters] encoded in body.
* Prepares a request containing form parameters encoded using the `x-www-form-urlencoded` format.
*
* [formParameters] encoded using application/x-www-form-urlencoded format.
* If [encodeInQuery] is set to `true`, form parameters are sent as URL parameters using the GET request.
* Otherwise, form parameters are sent in a POST request body.
*/
public suspend inline fun HttpClient.prepareForm(
formParameters: Parameters = Parameters.Empty,
......@@ -108,13 +103,10 @@ public suspend inline fun HttpClient.prepareForm(
}
/**
* Prepare [formParameters] request.
* Prepares a request containing form parameters encoded using the `x-www-form-urlencoded` format.
*
* If [encodeInQuery] specified encode [formParameters] in url parameters and use [HttpMethod.Get] for the request.
* Otherwise send [HttpMethod.Post] request with [formParameters] encoded in body.
*
* [url] destination
* [formParameters] encoded using application/x-www-form-urlencoded format.
* If [encodeInQuery] is set to `true`, form parameters are sent as URL parameters using the GET request.
* Otherwise, form parameters are sent in a POST request body.
*/
public suspend fun HttpClient.prepareForm(
url: String,
......@@ -127,9 +119,7 @@ public suspend fun HttpClient.prepareForm(
}
/**
* Prepare [HttpMethod.Post] request with [formData] encoded in body.
* [formData] encoded using multipart/form-data format.
* https://tools.ietf.org/html/rfc2045
* Prepares a POST request containing form parameters encoded using the `multipart/form-data` format.
*/
public suspend inline fun HttpClient.prepareFormWithBinaryData(
formData: List<PartData>,
......@@ -141,11 +131,7 @@ public suspend inline fun HttpClient.prepareFormWithBinaryData(
}
/**
* Prepare [HttpMethod.Post] request with [formData] encoded in body.
* [url] destination
* [formData] encoded using multipart/form-data format.
*
* https://tools.ietf.org/html/rfc2045
* Prepares a POST request containing form parameters encoded using the `multipart/form-data` format.
*/
public suspend inline fun HttpClient.prepareFormWithBinaryData(
url: String,
......
ktor-client/ktor-client-core/common/src/io/ktor/client/request/forms/formDsl.kt
Просмотр файла @ d6b9a87c
......@@ -12,7 +12,7 @@ import io.ktor.utils.io.core.*
import kotlin.contracts.*
/**
* Multipart form item. Use it to build form in client.
* A multipart form item. Use it to build a form in client.
*
* @param key multipart name
* @param value content, could be [String], [Number], [ByteArray], [ByteReadPacket] or [InputProvider]
......@@ -21,7 +21,9 @@ import kotlin.contracts.*
public data class FormPart<T : Any>(val key: String, val value: T, val headers: Headers = Headers.Empty)
/**
* Build multipart form from [values].
* Builds a multipart form from [values].
*
* Example: [Upload a file](https://ktor.io/docs/request.html#upload_file).
*/
public fun formData(vararg values: FormPart<*>): List<PartData> {
val result = mutableListOf<PartData>()
......@@ -74,13 +76,13 @@ public fun formData(block: FormBuilder.() -> Unit): List<PartData> =
formData(*FormBuilder().apply(block).build().toTypedArray())
/**
* Form builder type used in [formData] builder function.
* A form builder type used in the [formData] builder function.
*/
public class FormBuilder internal constructor() {
private val parts = mutableListOf<FormPart<*>>()
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
@InternalAPI
public fun <T : Any> append(key: String, value: T, headers: Headers = Headers.Empty) {
......@@ -88,56 +90,56 @@ public class FormBuilder internal constructor() {
}
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
public fun append(key: String, value: String, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
public fun append(key: String, value: Number, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
public fun append(key: String, value: ByteArray, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
public fun append(key: String, value: InputProvider, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a pair [key]:[InputProvider(block)] with optional [headers].
* Appends a pair [key]:[InputProvider(block)] with optional [headers].
*/
public fun appendInput(key: String, headers: Headers = Headers.Empty, size: Long? = null, block: () -> Input) {
parts += FormPart(key, InputProvider(size, block), headers)
}
/**
* Append a pair [key]:[value] with optional [headers].
* Appends a pair [key]:[value] with optional [headers].
*/
public fun append(key: String, value: ByteReadPacket, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a pair [key]:[ChannelProvider] with optional [headers].
* Appends a pair [key]:[ChannelProvider] with optional [headers].
*/
public fun append(key: String, value: ChannelProvider, headers: Headers = Headers.Empty) {
parts += FormPart(key, value, headers)
}
/**
* Append a form [part].
* Appends a form [part].
*/
public fun <T : Any> append(part: FormPart<T>) {
parts += part
......@@ -147,7 +149,7 @@ public class FormBuilder internal constructor() {
}
/**
* Append a form part with the specified [key] using [bodyBuilder] for it's body.
* Appends a form part with the specified [key] using [bodyBuilder] for its body.
*/
@OptIn(ExperimentalContracts::class)
public inline fun FormBuilder.append(
......@@ -163,7 +165,7 @@ public inline fun FormBuilder.append(
}
/**
* Reusable [Input] form entry.
* A reusable [Input] form entry.
*
* @property size estimate for data produced by the block or `null` if no size estimation known
* @param block: content generator
......@@ -171,14 +173,14 @@ public inline fun FormBuilder.append(
public class InputProvider(public val size: Long? = null, public val block: () -> Input)
/**
* Supplies a new [ByteReadChannel]
* Supplies a new [ByteReadChannel].
* @property size is total amount of bytes that can be read from [ByteReadChannel] or `null` if [size] is unknown
* @param block returns a new [ByteReadChannel]
*/
public class ChannelProvider(public val size: Long? = null, public val block: () -> ByteReadChannel)
/**
* Append a form part with the specified [key], [filename] and optional [contentType] using [bodyBuilder] for it's body.
* Appends a form part with the specified [key], [filename], and optional [contentType] using [bodyBuilder] for its body.
*/
@OptIn(ExperimentalContracts::class)
public fun FormBuilder.append(
......
ktor-client/ktor-client-core/common/src/io/ktor/client/statement/HttpResponse.kt
Просмотр файла @ d6b9a87c
......@@ -16,7 +16,9 @@ import io.ktor.utils.io.core.*
import kotlinx.coroutines.*
/**
* A response for [HttpClient], second part of [HttpClientCall].
* An [HttpClient]'s response, a second part of [HttpClientCall].
*
* Learn more from [Receiving responses](https://ktor.io/docs/response.html).
*/
public abstract class HttpResponse : HttpMessage, CoroutineScope {
/**
......@@ -50,7 +52,7 @@ public abstract class HttpResponse : HttpMessage, CoroutineScope {
* Unmodified [ByteReadChannel] with the raw payload of the response.
*
* **Note:** this content doesn't go through any interceptors from [HttpResponsePipeline].
* If you need modified content, use [bodyChannel] function.
* If you need the modified content, use the [bodyChannel] function.
*/
@InternalAPI
public abstract val content: ByteReadChannel
......@@ -59,7 +61,7 @@ public abstract class HttpResponse : HttpMessage, CoroutineScope {
}
/**
* [HttpRequest] associated with this response.
* Gets [HttpRequest] associated with this response.
*/
public val HttpResponse.request: HttpRequest get() = call.request
......@@ -71,8 +73,8 @@ internal fun HttpResponse.complete() {
}
/**
* Read the [HttpResponse.content] as a String. You can pass an optional [charset]
* to specify a charset in the case no one is specified as part of the Content-Type response.
* Reads the [HttpResponse.content] as a String. You can pass an optional [charset]
* to specify a charset in the case no one is specified as part of the `Content-Type` response.
* If no charset specified either as parameter or as part of the response,
* [io.ktor.client.plugins.HttpPlainText] settings will be used.
*
......@@ -88,6 +90,6 @@ public suspend fun HttpResponse.bodyAsText(fallbackCharset: Charset = Charsets.U
}
/**
* Read the [HttpResponse.content] as a [ByteReadChannel].
* Reads the [HttpResponse.content] as a [ByteReadChannel].
*/
public suspend fun HttpResponse.bodyAsChannel(): ByteReadChannel = body()
ktor-client/ktor-client-core/common/src/io/ktor/client/statement/HttpStatement.kt
Просмотр файла @ d6b9a87c
......@@ -18,10 +18,11 @@ import io.ktor.utils.io.core.*
import kotlinx.coroutines.*
/**
* Prepared statement for http client request.
* Prepared statement for a HTTP client request.
* This statement doesn't perform any network requests until [execute] method call.
*
* [HttpStatement] is safe to execute multiple times.
*
* Example: [Streaming data](https://ktor.io/docs/response.html#streaming)
*/
public class HttpStatement(
private val builder: HttpRequestBuilder,
......@@ -33,7 +34,7 @@ public class HttpStatement(
}
/**
* Executes this statement and call the [block] with the streaming [response].
* Executes this statement and calls the [block] with the streaming [response].
*
* The [response] argument holds a network connection until the [block] isn't completed. You can read the body
* on-demand or at once with [body<T>()] method.
......@@ -54,9 +55,9 @@ public class HttpStatement(
/**
* Executes this statement and download the response.
* After the method finishes, the client downloads the response body in memory and release the connection.
* After the method execution finishes, the client downloads the response body in memory and release the connection.
*
* To receive exact type consider using [body<T>()] method.
* To receive exact type, consider using [body<T>()] method.
*/
public suspend fun execute(): HttpResponse = execute {
val savedCall = it.call.save()
......@@ -65,7 +66,7 @@ public class HttpStatement(
}
/**
* Executes this statement and run [HttpClient.responsePipeline] with the response and expected type [T].
* Executes this statement and runs [HttpClient.responsePipeline] with the response and expected type [T].
*
* Note if T is a streaming type, you should manage how to close it manually.
*/
......@@ -80,7 +81,7 @@ public class HttpStatement(
}
/**
* Executes this statement and run the [block] with a [HttpClient.responsePipeline] execution result.
* Executes this statement and runs the [block] with a [HttpClient.responsePipeline] execution result.
*
* Note that T can be a streamed type such as [ByteReadChannel].
*/
......@@ -97,7 +98,7 @@ public class HttpStatement(
}
/**
* Return [HttpResponse] with open streaming body.
* Returns [HttpResponse] with open streaming body.
*/
@PublishedApi
@OptIn(InternalAPI::class)
......@@ -109,7 +110,7 @@ public class HttpStatement(
}
/**
* Complete [HttpResponse] and release resources.
* Completes [HttpResponse] and releases resources.
*/
@PublishedApi
@OptIn(InternalAPI::class)
......@@ -127,7 +128,7 @@ public class HttpStatement(
}
/**
* Check that all request configuration related to client capabilities have correspondent plugin installed.
* Checks that all request configuration related to client capabilities have correspondent plugin installed.
*/
private fun checkCapabilities() {
builder.attributes.getOrNull(ENGINE_CAPABILITIES_KEY)?.keys
......
ktor-client/ktor-client-core/common/src/io/ktor/client/statement/Readers.kt
Просмотр файла @ d6b9a87c
......@@ -9,7 +9,7 @@ import io.ktor.utils.io.*
import io.ktor.utils.io.core.*
/**
* Exactly reads [count] bytes of the [HttpResponse.content].
* Reads exactly [count] bytes of the [HttpResponse.content].
*/
@OptIn(InternalAPI::class)
public suspend fun HttpResponse.readBytes(count: Int): ByteArray = ByteArray(count).also {
......@@ -17,8 +17,8 @@ public suspend fun HttpResponse.readBytes(count: Int): ByteArray = ByteArray(cou
}
/**
* Reads the whole [HttpResponse.content] if Content-Length was specified.
* Otherwise it just reads one byte.
* Reads the whole [HttpResponse.content] if `Content-Length` is specified.
* Otherwise, it just reads one byte.
*/
@OptIn(InternalAPI::class)
public suspend fun HttpResponse.readBytes(): ByteArray = content.readRemaining().readBytes()
......
Поддерживает Markdown
0% или .
You are about to add 0 people to the discussion. Proceed with caution.
Сначала завершите редактирование этого сообщения!
Пожалуйста, зарегистрируйтесь или чтобы прокомментировать