Struct tk_http::client::Encoder

pub struct Encoder<S> { /* fields omitted */ }

This a request writer that you receive in Codec

Methods of this structure ensure that everything you write into a buffer is consistent and valid protocol

Methods

impl<S> Encoder<S>

fn request_line(&mut self, method: &str, path: &str, version: Version)

Write request line.

This puts request line into a buffer immediately. If you don't continue with request it will be sent to the network shortly.

Panics

When request line is already written. It's expected that your request handler state machine will never call the method twice.

fn add_header<V: AsRef<[u8]>>(
    &mut self,
    name: &str,
    value: V
) -> Result<(), HeaderError>

Add a header to the message.

Header is written into the output buffer immediately. And is sent as soon as the next loop iteration

Content-Length header must be send using the add_length method and Transfer-Encoding: chunked must be set with the add_chunked method. These two headers are important for the security of HTTP.

Note that there is currently no way to use a transfer encoding other than chunked.

We return Result here to make implementing proxies easier. In the application handler it's okay to unwrap the result and to get a meaningful panic (that is basically an assertion).

Panics

Panics when add_header is called in the wrong state.

fn format_header<D: Display>(
    &mut self,
    name: &str,
    value: D
) -> Result<(), HeaderError>

Same as add_header but allows value to be formatted directly into the buffer

Useful for dates and numeric headers, as well as some strongly typed wrappers

fn add_length(&mut self, n: u64) -> Result<(), HeaderError>

Add a content length to the message.

The Content-Length header is written to the output buffer immediately. It is checked that there are no other body length headers present in the message. When the body is send the length is validated.

Panics

Panics when add_length is called in the wrong state.

fn add_chunked(&mut self) -> Result<(), HeaderError>

Sets the transfer encoding to chunked.

Writes Transfer-Encoding: chunked to the output buffer immediately. It is assured that there is only one body length header is present and the body is written in chunked encoding.

Panics

Panics when add_chunked is called in the wrong state.

fn done_headers(&mut self) -> Result<(), HeaderError>

Closes the HTTP header

Similarly to add_header() it's fine to unwrap() here, unless you're doing some proxying.

Panics

Panics when the request is in a wrong state.

fn write_body(&mut self, data: &[u8])

Write a chunk of body

If add_chunked was specified before the data will be written as a chunk (prefixed with length). Otherwise encoder will ensure that data fits content-length

Panics

Panics when data is larger than what was specified in add_length or when no body is allowed in this kind of request.

fn done(self) -> EncoderDone<S>

Finish writing request and return EncoderDone which can be moved to

Panics

Panics when the request is in a wrong state.

fn flush(&mut self) -> Result<(), Error> where
    S: AsyncWrite, 

Flush the data to underlying socket

If the whole buffer could not be flushed it schedules a wakeup of the current task when the the socket is writable.

You can find out how many bytes are left using bytes_buffered() method

fn bytes_buffered(&mut self) -> usize

Returns bytes currently lying in the buffer

It's possible that these bytes are left from the previous request if pipelining is enabled.

fn wait_flush(self, watermark: usize) -> WaitFlush<S>

Returns future which yield encoder back when buffer is flushed

More specifically when butes_buffered() < watermark

Trait Implementations

impl<S> Write for Encoder<S>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.