= nng_http_hijack(3http)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_http_hijack - hijack HTTP server connection

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>
#include <nng/supplemental/http/http.h>

void nng_http_hijack(nng_http_conn *conn);
----

== DESCRIPTION
(((HTTP, hijack)))
The `nng_http_hijack()` function hijacks the connection _conn_, causing it
to be disassociated from the HTTP server where it was created.

The purpose of this function is the creation of HTTP upgraders (such as
WebSocket), where the underlying HTTP connection will be taken over for
some other purpose, and should not be used any further by the server.

This function is most useful when called from a handler function.
(See xref:nng_http_handler_alloc.3http.adoc[`nng_http_handler_alloc()`].)

NOTE: 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 xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`].)

TIP: This function is intended to facilitate uses cases that involve changing
the protocol from HTTP, such as WebSocket.
Most applications will never need to use this function.

== RETURN VALUES

None.

== ERRORS

[horizontal]
`NNG_ECLOSED`:: The connection was closed.
`NNG_ENOMEM`:: Insufficient free memory exists.
`NNG_ENOTSUP`:: HTTP not supported.

== SEE ALSO

[.text-left]
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)],
xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)],
xref:nng.7.adoc[nng(7)]