[−][src]Function aahc::send_headers

pub async fn send_headers<'socket, Socket: AsyncWrite + ?Sized, '_, '_, '_, '_>(
    method: &'_ str, 
    request_target: &'_ str, 
    headers: &'_ [Header<'_>], 
    __arg3: Pin<&'socket mut Socket>
) -> Result<Send<'socket, Socket>>

Sends an HTTP request line and request headers.

The method parameter holds the method for the request (e.g. GET, POST, or DELETE). The request_target parameter holds the “request target”, which is typically the path and query string parts of the URL, though it may include the scheme, host, and port parts if a proxy request is being made. The headers parameter holds the request headers to send. The socket parameter is the transport-layer socket over which the HTTP request will be sent, which must already be connected to the remote host; it is recommended that the socket provide write buffering (e.g. that the raw transport socket be wrapped in a BufWriter) for good performance.

The 'socket lifetime parameter is the lifetime of socket, which, once this function returns, must continue to live in the returned Send instance. The Socket type parameter is the type of socket.

This function returns once the headers have been written to socket. The return value is a Send instance that can be used to write the request body, if any.

Important: This function does not flush the socket. Normally the application will proceed to sending the request body, so no flush is necessary; however, if the socket is a buffered wrapper around an underlying socket and the application intends to unwrap the wrapper (either temporarily, creating a new wrapper while sending the request body, or permanently), it must flush the socket before unwrapping, otherwise data may be lost.

Errors

This function returns an error if writing to socket fails.

Panics

This function panics under any of the following conditions, in a debug build:

  • if the request method is CONNECT (this method is not supported) or not a valid token
  • if the path is not a valid path (only the absence of characters outside the range 0x21 to 0x7F is checked, not the full request-target production)
  • if the Transfer-Encoding header is present and is set to any value other than chunked (other transfer encodings are not supported)
  • if the Content-Length header is present and is set to something other than a non-negative 64-bit integer
  • if more than one of Transfer-Encoding and Content-Length headers is present (either both headers or multiple instances of the same header)
  • if the Upgrade header is present (protocol switching is not supported)
  • if the TE header is present (neither transfer encodings other than chunked nor trailers are supported)
  • if any header name is not a valid token
  • if any header value is invalid (a valid header value is one that does not contain any bytes 0x00 through 0x08 or 0x0A through 0x1F, and which does not start or end with a space or tab)

The word “token” refers to the token production in the HTTP RFC, namely a string that comprises only digits, letters, and the characters !#$%&'*+-.^_`|~, and is at least one character long.

These are debug-build panics, not errors, because it is expected that the application will not construct invalid or unsupported requests; thus, such requests represent bugs in the application.