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),
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
=head1 SEE ALSO
+L<BIO_should_retry(3)>,
+L<BIO_wait(3)>,
+L<OSSL_HTTP_get(3)>,
L<OSSL_HTTP_transfer(3)>
=head1 COPYRIGHT
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()
=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.