Struct aahc::SendBody

pub struct SendBody<'socket, Socket: AsyncWrite + ?Sized> { /* fields omitted */ }

An in-progress HTTP request which is currently sending a request body.

After the headers are sent, an instance of this type is obtained. It implements AsyncWrite, which allows the application to write the request body. When the request body is finished (or immediately, if there is no request body to send), finish should be called to proceed to the next step.

The 'socket lifetime parameter is the lifetime of the transport socket. The Socket type parameter is the type of transport-layer socket over which the HTTP request will be sent.

Implementations

impl<'socket, Socket: AsyncWrite + ?Sized> Send<'socket, Socket>

pub fn hint_length(&mut self, length: u64)

Gives a hint about how many bytes of body remain to be sent.

The length parameter is the minimum number of bytes of body that will be sent from this point forward.

The application must send at least length bytes before finishing the request. However, it is permitted to send more than length bytes (subject to any other constraints, such as not sending more than specified in the content-length header).

For a fixed-length request (e.g. one whose length was set by a content-length header), this function does nothing.

For a chunked request, this function sets the size of the next chunk; this allows a large chunk size to be sent without the entire contents of the chunk needing to be available at once. For example, if the application knows that the body will contain at least another 100,000 bytes, it could call this function passing a length parameter of 100,000, but then write just 10,000 bytes at a time, ten times over. Without calling this function, that would result in ten 10,000-byte chunks being sent; by calling this function, a single 100,000-byte chunk is sent instead, reducing the overhead due to chunk headers, without requiring that the application load all 100,000 bytes into memory at once.

pub async fn finish(self) -> Result<Metadata>

Finishes the request.

On success, a metadata instance is returned. This instance must be passed in when the application is ready to receive the response headers.

Important: This function does not flush the socket. If the application is going to read a response, or if the socket is a buffered wrapper around an underlying socket and the application intends to unwrap the wrapper, it must flush the socket before proceeding to read the response, otherwise a hang might occur due to the server waiting for the remainder of the request which will never arrive. If the application intends to send another request instead, using HTTP pipelining, the flush is not necessary.

Errors

This function returns an error if writing to the underlying socket fails.

Panics

This function panics in a debug build:

• if the body has a fixed length and was not fully sent
• if the body is chunked and the most recent chunk was not fully sent

These are debug-build panics, not errors, because it is expected that the application will provide a request body consistent with the request headers; since both of these things are under the application’s control, an inconsistency between them represents a bug in the application.

Trait Implementations

impl<Socket: AsyncWrite + ?Sized, '_> AsyncWrite for Send<'_, Socket>

fn poll_write(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>,
    bufs: &[IoSlice<'_>]
) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl<'socket, Socket: Debug + AsyncWrite + ?Sized> Debug for Send<'socket, Socket>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'socket, Socket: Eq + AsyncWrite + ?Sized> Eq for Send<'socket, Socket>

impl<'socket, Socket: PartialEq + AsyncWrite + ?Sized> PartialEq<Send<'socket, Socket>> for Send<'socket, Socket>

fn eq(&self, other: &Send<'socket, Socket>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Send<'socket, Socket>) -> bool

This method tests for !=.

impl<'socket, Socket: AsyncWrite + ?Sized> StructuralEq for Send<'socket, Socket>

impl<'socket, Socket: AsyncWrite + ?Sized> StructuralPartialEq for Send<'socket, Socket>