Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OSSL_HTTP_REQ_CTX 3ossl"
way too many mistakes in technical documents.
This file documents low-level \s-1HTTP\s0 functions rarely used directly. High-level \s-1HTTP\s0 client functions like OSSL_HTTP_get\|(3) and OSSL_HTTP_transfer\|(3) should be preferred.
\fBOSSL_HTTP_REQ_CTX_new() allocates a new \s-1HTTP\s0 request context structure, which gets populated with the \s-1BIO\s0 to write/send the request to (wbio), the \s-1BIO\s0 to read/receive the response from (rbio, which may be equal to \fIwbio), and the maximum expected response header line length buf_size. A value <= 0 indicates that the \s-1OSSL_HTTP_DEFAULT_MAX_LINE_LEN\s0 of 4KiB should be used. \fIbuf_size is also used as the number of content bytes that are read at a time. The allocated context structure includes an internal memory \s-1BIO\s0, which collects the \s-1HTTP\s0 request header lines.
\fBOSSL_HTTP_REQ_CTX_free() frees up the \s-1HTTP\s0 request context rctx. The rbio is not free'd, wbio will be free'd if free_wbio is set.
\fBOSSL_HTTP_REQ_CTX_set_request_line() adds the 1st \s-1HTTP\s0 request line to rctx. The \s-1HTTP\s0 method is determined by method_POST, which should be 1 to indicate \*(C`POST\*(C' or 0 to indicate \*(C`GET\*(C'. \fIserver and port may be set to give the server and the optional port that an \s-1HTTP\s0 proxy shall forward the request to, otherwise they must be left \s-1NULL.\s0 \fIpath provides the \s-1HTTP\s0 request path; if left \s-1NULL,\s0 \*(C`/\*(C' is used. For backward compatibility, path may begin with \*(C`http://\*(C' and thus convey an absoluteURI. In this case it indicates \s-1HTTP\s0 proxy use and provides also the server (and optionally the port) that the proxy shall forward the request to. In this case the server and port arguments must be \s-1NULL.\s0
\fBOSSL_HTTP_REQ_CTX_add1_header() adds header name with value value to the context rctx. It can be called more than once to add multiple header lines. For example, to add a \*(C`Host\*(C' header for \*(C`example.com\*(C' you would call:
.Vb 1 OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); .Ve
\fBOSSL_HTTP_REQ_CTX_set_expected() optionally sets in rctx some expectations of the \s-1HTTP\s0 client on the response. Due to the structure of an \s-1HTTP\s0 request, if the keep_alive argument is nonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req(). If the content_type parameter is not \s-1NULL\s0 then the client will check that the given content type string is included in the \s-1HTTP\s0 header of the response and return an error if not. If the asn1 parameter is nonzero a structure in \s-1ASN.1\s0 encoding will be expected as the response content and input streaming is disabled. This means that an \s-1ASN.1\s0 sequence header is required, its length field is checked, and \fBOSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered response. Otherwise (by default) any input format is allowed without length checks. In this case the \s-1BIO\s0 given as rbio argument to OSSL_HTTP_REQ_CTX_new() should be used directly to read the response contents, which may support streaming. If the timeout parameter is > 0 this indicates the maximum number of seconds the subsequent \s-1HTTP\s0 transfer (sending the request and receiving a response) is allowed to take. \fItimeout == 0 enables waiting indefinitely, i.e., no timeout can occur. This is the default. \fItimeout < 0 takes over any value set via the overall_timeout argument of \fBOSSL_HTTP_open\|(3) with the default being 0, which means no timeout. If the keep_alive parameter is 0, which is the default, the connection is not kept open after receiving a response. This is the default behavior for \s-1HTTP 1.0.\s0 If the value is 1 or 2 then a persistent connection is requested. If the value is 2 then a persistent connection is required, i.e., an error occurs in case the server does not grant it.
\fBOSSL_HTTP_REQ_CTX_set1_req() finalizes the \s-1HTTP\s0 request context. It is needed if the method_POST parameter in the \fBOSSL_HTTP_REQ_CTX_set_request_line() call was 1 and an \s-1ASN\s0.1-encoded request should be sent. It must also be used when requesting \*(L"keep-alive\*(R", even if a \s-1GET\s0 request is going to be sent, in which case req must be \s-1NULL.\s0 Unless req is \s-1NULL,\s0 the function adds the \s-1DER\s0 encoding of req using the \s-1ASN.1\s0 template it to do the encoding (which does not support streaming). The \s-1HTTP\s0 header \*(C`Content-Length\*(C' is filled out with the length of the request. \fIcontent_type must be \s-1NULL\s0 if req is \s-1NULL.\s0 If content_type isn't \s-1NULL,\s0 the \s-1HTTP\s0 header \*(C`Content-Type\*(C' is also added with the given string value. The header lines are added to the internal memory \s-1BIO\s0 for the request header.
\fBOSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in rctx and to gather the response via \s-1HTTP,\s0 using the wbio and rbio that were given when calling OSSL_HTTP_REQ_CTX_new(). The function may need to be called again if its result is -1, which indicates \fBBIO_should_retry\|(3). In such a case it is advisable to sleep a little in between, using BIO_wait\|(3) on the read \s-1BIO\s0 to prevent a busy loop.
\fBOSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on success in addition parses the response, which must be a DER-encoded \s-1ASN.1\s0 structure, using the \s-1ASN.1\s0 template it and places the result in *pval.
\fBOSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed in order to exchange a request and response or until a timeout is reached. On success it returns a pointer to the \s-1BIO\s0 that can be used to read the result. If an \s-1ASN\s0.1-encoded response was expected, this is the \s-1BIO\s0 returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange. This memory \s-1BIO\s0 does not support streaming. Otherwise the returned \s-1BIO\s0 is the rbio given to OSSL_HTTP_REQ_CTX_new(), which may support streaming. When this \s-1BIO\s0 is returned, it has been read past the end of the response header, such that the actual response body can be read from it. The returned \s-1BIO\s0 pointer \s-1MUST NOT\s0 be freed by the caller.
\fBOSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory \s-1BIO\s0. Before the \s-1HTTP\s0 request is sent, this could be used to adapt its header lines. \fIUse with caution! After receiving a response via \s-1HTTP,\s0 the \s-1BIO\s0 represents the current state of reading the response header. If the response was expected to be \s-1ASN.1\s0 encoded, its contents can be read via this \s-1BIO,\s0 which does not support streaming. The returned \s-1BIO\s0 pointer must not be freed by the caller.
\fBOSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents in rctx if provided by the server as <Content-Length> header field, else 0.
\fBOSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed response content length for rctx to len. If not set or len is 0 then the \s-1OSSL_HTTP_DEFAULT_MAX_RESP_LEN\s0 is used, which currently is 100 KiB. If the \*(C`Content-Length\*(C' header is present and exceeds this value or the content is an \s-1ASN.1\s0 encoded structure with a length exceeding this value or both length indications are present but disagree then an error occurs.
\fBOSSL_HTTP_is_alive() can be used to query if the \s-1HTTP\s0 connection given by rctx is still alive, i.e., has not been closed. It returns 0 if rctx is \s-1NULL.\s0
If the client application requested or required a persistent connection and this was granted by the server, it can keep rctx as long as it wants to send further requests and OSSL_HTTP_is_alive() returns nonzero, else it should call OSSL_HTTP_REQ_CTX_free(rctx) or OSSL_HTTP_close\|(3). In case the client application keeps rctx but the connection then dies for any reason at the server side, it will notice this obtaining an I/O error when trying to send the next request via rctx.
Many of these functions must be called in a certain order.
First, the \s-1HTTP\s0 request context must be allocated: \fBOSSL_HTTP_REQ_CTX_new().
Then, the \s-1HTTP\s0 request must be prepared with request data:
When the request context is fully prepared, the \s-1HTTP\s0 exchange may be performed with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_exchange().
\fBOSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length() do not return values.
\fBOSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(), \fBOSSL_HTTP_REQ_CTX_set1_req(), and OSSL_HTTP_REQ_CTX_set_expected() return 1 for success and 0 for failure.
\fBOSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i() return 1 for success, 0 on error or redirection, -1 if retry is needed.
\fBOSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio() return a pointer to a \s-1BIO\s0 on success as described above or \s-1NULL\s0 on failure. The returned \s-1BIO\s0 must not be freed by the caller.
\fBOSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents or 0 if not available or an error occurred.
\fBOSSL_HTTP_is_alive() returns 1 if its argument is non-NULL and the client requested a persistent connection and the server did not disagree on keeping the connection open, else 0.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.