diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-01-25 20:44:39 +0100 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2021-02-02 07:54:37 +0100 |
commit | 6aab42c39060c7aa39d96c7a265ddc661cea2ed8 (patch) | |
tree | c893760190f2a922f4250a32f69c6b6c42994a81 | |
parent | 4d190f99ef1b6fa8c49ca1fd9bda872e5f51ec93 (diff) | |
download | openssl-new-6aab42c39060c7aa39d96c7a265ddc661cea2ed8.tar.gz |
OSSL_HTTP_REQ_CTX.pod and OSSL_HTTP_transfer.pod: various improvements
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13960)
-rw-r--r-- | doc/man3/OSSL_HTTP_REQ_CTX.pod | 31 | ||||
-rw-r--r-- | doc/man3/OSSL_HTTP_transfer.pod | 14 |
2 files changed, 27 insertions, 18 deletions
diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index ec18e36d95..0b730b4e17 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -56,8 +56,8 @@ should be preferred. OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure, which gets populated with the B<BIO> to send the request to (I<wbio>), the B<BIO> to read the response from (I<rbio>, which may be equal to I<wbio>), -the maximum expected response header line length (I<maxline>, where any -zero or less indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB; +the maximum expected response header line length (I<maxline>, where a value <= 0 +indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB should be used; this length is also used as the number of content bytes read at a time), the request method (I<method_POST>, which may be 1 to indicate that the C<POST> method is to be used, or 0 to indicate that the C<GET> method is to be used), @@ -90,27 +90,31 @@ For example, to add a C<Host> header for C<example.com> you would call: OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); -OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding the DER -encoding of I<req>, using the ASN.1 template I<it> to do the encoding. The -HTTP header C<Content-Length> is automatically filled out, and if +OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding +the DER encoding of I<req>, using the ASN.1 template I<it> to do the encoding. +The HTTP header C<Content-Length> is automatically filled out, and if I<content_type> isn't NULL, the HTTP header C<Content-Type> is also added with its content as value. All of this ends up in the internal memory B<BIO>. This requires that I<method_POST> was 1 in the OSSL_HTTP_REQ_CTX_new() call. -OSSL_HTTP_REQ_CTX_nbio() attempts the exchange of request and response via HTTP, -using the I<rbio> and I<wbio> that were given in the OSSL_HTTP_REQ_CTX_new() -call. When successful, the contents of the internal memory B<BIO> is replaced -with the contents of the HTTP response, without the response headers. +OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared I<rctx> +and gathering the response via HTTP, using the I<rbio> and I<wbio> +that were given when calling OSSL_HTTP_REQ_CTX_new(). +When successful, the contents of the internal memory B<BIO> contains +the contents of the HTTP response, without the response headers. It may need to be called again if its result is -1, which indicates L<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in -between to prevent a busy loop. +between using L<BIO_wait(3)> on the read BIO to prevent a busy loop. OSSL_HTTP_REQ_CTX_sendreq_d2i() calls OSSL_HTTP_REQ_CTX_nbio(), possibly several times until a timeout is reached, and DER decodes the received response using the ASN.1 template I<it>. -OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. This can -be used to affect the HTTP request text. I<Use with caution!> +OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. +Before sending the request, this could used to modify the HTTP request text. +I<Use with caution!> +After receiving a response via HTTP, the BIO represents +the current state of reading the response headers and contents. OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed response content length for I<rctx> to I<len>. If not set or I<len> is 0 @@ -173,6 +177,9 @@ OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. =head1 SEE ALSO +L<BIO_should_retry(3)>, +L<BIO_wait(3)>, +L<OSSL_HTTP_get(3)>, L<OSSL_HTTP_transfer(3)> =head1 COPYRIGHT diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 33ae25685b..cb38d0124f 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -123,10 +123,11 @@ while using a proxy for HTTPS connections requires a suitable callback function such as OSSL_HTTP_proxy_connect(), described below. The I<maxline> parameter specifies the response header maximum line length, -where a value <= 0 indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB. -This length is also used as the number of content bytes read at a time. +where a value <= 0 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB +should be used. +This length is also used as the number of content bytes that are read at a time. The I<max_resp_len> parameter specifies the maximum response length, -where 0 indicates the B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB. +where 0 indicates B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB. An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer() @@ -218,9 +219,10 @@ other HTTP client implementations such as wget, curl, and git. =head1 RETURN VALUES -OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and -OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL. -Error conditions include connection/transfer timeout, parse errors, etc. +On success, OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and +OSSL_HTTP_transfer() return a memory BIO containing the data received via HTTP. +This must be freed by the caller. On failure, NULL is returned. +Failure conditions include connection/transfer timeout, parse errors, etc. OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url() return 1 on success, 0 on error. |