diff options
Diffstat (limited to 'ref/api/http.html')
| -rw-r--r-- | ref/api/http.html | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/ref/api/http.html b/ref/api/http.html index 67c7048e..1d137541 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -266,7 +266,7 @@ performed after the first transaction is complete.</p> <p>At any given point in time, an <code>nng_http</code> object can only refer to a single HTTP transaction. In NNG, these <code>nng_http</code> objects are used in both the client and server APIs.</p> <p>The <code>nng_http</code> object is created by either <a href="/api/http.html#creating-connections"><code>nng_http_client_connect</code></a> or by an HTTP server -object which then passes it to an [<code>nng_http_handler</code>] callback function.</p> +object which then passes it to an <a href="/api/http.html#handlers"><code>nng_http_handler</code></a> callback function.</p> <h3 id="http-method"><a class="header" href="#http-method">HTTP Method</a></h3> <pre><code class="language-c">void nng_http_set_method(nng_http *conn, const char *method); const char *nng_http_get_method(nng_http *conn); @@ -460,12 +460,12 @@ to never have body content, such as “HEAD”.)</p> <pre><code class="language-c">void nng_http_set_body(nng_http_conn *conn, void *data, size_t size); void nng_http_copy_body(nng_http_conn *conn, const void *data, size_t size); </code></pre> -<p>The <a name="a019"></a><code>nng_http_set_data</code> function sets the outgoing body content to <em>data</em>, +<p>The <a name="a019"></a><code>nng_http_set_body</code> function sets the outgoing body content to <em>data</em>, which must be <em>size</em> bytes long. The caller must ensure that <em>data</em> remains valid for the duration of the transaction.</p> -<p>The <a name="a020"></a><code>nng_http_copy_data</code> function makes a copy of <em>data</em>, which +<p>The <a name="a020"></a><code>nng_http_copy_body</code> function makes a copy of <em>data</em>, which will be freed automatically when the transaction is finished, but otherwise -behaves like <code>nng_http_set_data</code>.</p> +behaves like <code>nng_http_set_body</code>.</p> <p>On client <em>conn</em> objects, these functions update the request object, but on server <em>conn</em> objects, they update the response object.</p> <p>These functions also update the relevant “Content-Length” header.</p> @@ -529,7 +529,7 @@ to be disassociated from the HTTP server where it was created.</p> WebSocket), where the underlying HTTP connection will be taken over for some other purpose, and should not be used any further by the server.</p> <p>This function is most useful when called from a handler function. -(See [<code>nng_http_handler_alloc</code>].)</p> +(See <a href="/api/http.html#handlers"><code>nng_http_handler_alloc</code></a>.)</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -537,7 +537,7 @@ some other purpose, and should not be used any further by the server.</p> </p> <p>It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed. Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate. -(See [<code>nng_http_write_response</code>].)</p> +(See <a href="/api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a>.)</p> </div> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> @@ -660,7 +660,7 @@ the HTTP request associated with <em>conn</em>. The entire request is sent, including headers, and if present, the request body data. (The request body can be set with -[<code>nng_http_set_data</code>] or [<code>nng_http_copy_data</code>].)</p> +<a href="/api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="/api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.)</p> <p>This function returns immediately, with no return value. Completion of the operation is signaled via the <em>aio</em>, and the final result may be obtained via <a href="/api/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> @@ -754,8 +754,8 @@ URIs from being supported, but doing so will require setting the handler to matc <p>The NNG HTTP framework is optimized for URLs shorter than 200 characters.</p> </div> <p>Additionally each handler has a method it is registered to handle -(the default is “GET” andc can be changed with [<code>nng_http_handler_set_method</code>]), and -optionally a “Host” header it can be matched against (see [<code>nng_http_handler_set_host</code>]).</p> +(the default is “GET” andc can be changed with <a href="/api/http.html#setting-the-method"><code>nng_http_handler_set_method</code></a>), and +optionally a “Host” header it can be matched against (see <a href="/api/http.html#filtering-byt-host"><code>nng_http_handler_set_host</code></a>).</p> <p>In some cases, a handler may reference a logical tree rather (directory) rather than just a single element. (See [<code>nng_http_handler_set_tree</code>]).</p> @@ -770,9 +770,9 @@ On success, a pointer to the handler is stored at the located pointed to by <em> <p>The handler function is specified by <em>cb</em>. This function uses the asynchronous I/O framework.</p> <p>The function receives the connection on <em>conn</em>, and an optional data pointer that was set -previously with [<code>nng_http_handler_set_data</code>] as the second argument. The +previously with <a href="/api/http.html#setting-the-callback-argument"><code>nng_http_handler_set_data</code></a> as the second argument. The final argument is the <a href="/api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, which must be “finished” to complete the operation.</p> -<p>The handler may call [<code>nng_http_write_response</code>] to send the response, or +<p>The handler may call <a href="/api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a> to send the response, or it may simply let the framework do so on its behalf. The server will perform this step if the callback has not already done so.</p> <p>Response headers may be set using <a href="/api/http.html#modifying-headers"><code>nng_http_set_header</code></a>, and request headers @@ -786,11 +786,11 @@ the response body may be set using either <a href="/api/http.html#storing-body-c note </p> <p>The request body is only collected for the handler if the -[<code>nng_http_handler_collect_body</code>] function has been called for the handler.</p> +<a href="/api/http.html#collecting-request-body"><code>nng_http_handler_collect_body</code></a> function has been called for the handler.</p> </div> <p>The HTTP status should be set for the transaction using <a href="/api/http.html#http-status"><code>nng_http_set_status</code></a>.</p> <p>Finally, the handler should finish the operation by calling the <a href="/TODO.html"><code>nng_aio_finish</code></a> function -after having set the status to [<code>NNG_OK</code>]. +after having set the status to <a href="/api/errors.html#NNG_OK"><code>NNG_OK</code></a>. If any other status is set on the <em>aio</em>, then a generic 500 response will be created and sent, if possible, and the connection will be closed.</p> <p>The <em>aio</em> may be scheduled for deferred completion using the <a href="/TODO.html"><code>nng_aio_start</code></a>.</p> @@ -819,7 +819,7 @@ then a value of <code>application/octet-stream</code> is assumed.</p> </code></pre> <p>The <a name="a045"></a><code>nng_http_handler_alloc_redirect</code> function creates a handler with a function that simply directions from the URI at <em>path</em> to the given <em>location</em>.</p> -<p>The HTTP reply it creates will be with [status code][<code>nng_http_status</code>] <em>status</em>, +<p>The HTTP reply it creates will be with <a href="/api/http.html#http-status">status code</a> <em>status</em>, which should be a 3XX code such as 301, and a <code>Location:</code> header will contain the URL referenced by <em>location</em>, with any residual suffix from the request URI appended.</p> @@ -840,9 +840,9 @@ of the new site, such as <code>https://newsite.example.com</code> as the new loc </p> <p>Be sure to use the appropriate value for <em>status</em>. Permanent redirection should use [<code>NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY</code>] (301) -and temporary redirections should use [<code>NNG_HTTP_STATUS_TEMPORARY_REDIRECT</code>] (307). +and temporary redirections should use <a href="/api/http.html#NNG_HTTP_STATUS_TEMPORARY_REDIRECT"><code>NNG_HTTP_STATUS_TEMPORARY_REDIRECT</code></a> (307). In REST APIs, using a redirection to supply the new location of an object -created with <code>POST</code> should use [<code>NNG_HTTP_STATUS_SEE_OTHER</code>] (303).</p> +created with <code>POST</code> should use <a href="/api/http.html#NNG_HTTP_STATUS_SEE_OTHER"><code>NNG_HTTP_STATUS_SEE_OTHER</code></a> (303).</p> </div> <h3 id="collecting-request-body"><a class="header" href="#collecting-request-body">Collecting Request Body</a></h3> <pre><code class="language-c">void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); @@ -856,7 +856,7 @@ connection before calling the callback for the <em>handler</em>.</p> Furthermore, the data that the client may sent is limited by the value of <em>maxsz</em>. If the client attempts to send more data than <em>maxsz</em>, then the -request will be terminated with [<code>NNG_HTTP_STATUS_CONTENT_TOO_LARGE</code>] (413).</p> +request will be terminated with <a href="/api/http.html#NNG_HTTP_STATUS_CONTENT_TOO_LARGE"><code>NNG_HTTP_STATUS_CONTENT_TOO_LARGE</code></a> (413).</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -963,6 +963,7 @@ explicitly by setting the “Connection: close” header, the connection will be response is fully sent.</p> <!-- Symbol cross reference --> <!-- HTTP --> +<!-- HTTP Status --> <!-- Macros --> <!-- Protocols --> <!-- Transports --> |
