Struct solicit::http::connection::HttpConnection

pub struct HttpConnection {
    pub scheme: HttpScheme,
    // some fields omitted
}

The struct implements the HTTP/2 connection level logic.

This means that the struct is a bridge between the low level raw frame reads/writes (i.e. what the SendFrame and ReceiveFrame traits do) and the higher session-level logic.

Therefore, it provides an API that exposes higher-level write operations, such as writing headers or data, that take care of all the underlying frame construction that is required.

Similarly, it provides an API for handling events that arise from receiving frames, without requiring the higher level to directly look at the frames themselves, rather only the semantic content within the frames.

Fields

scheme: HttpScheme

The scheme of the connection

Implementations

impl HttpConnection

pub fn new(scheme: HttpScheme) -> HttpConnection

Creates a new HttpConnection that will use the given sender for writing frames.

pub fn sender<'a, S: SendFrame>(
    &'a mut self,
    sender: &'a mut S
) -> HttpConnectionSender<S>

Creates a new HttpConnectionSender instance that will use the given SendFrame instance to send the frames that it prepares. This is a convenience struct so that clients do not have to pass the same sender reference to multiple send methods.

Example

use solicit::http::{HttpScheme, HttpResult};
use solicit::http::frame::FrameIR;
use solicit::http::connection::{HttpConnection, SendFrame};
struct FakeSender;
impl SendFrame for FakeSender {
    fn send_frame<F: FrameIR>(&mut self, frame: F) -> HttpResult<()> {
        // Does not actually send anything!
        Ok(())
    }
}
let mut conn = HttpConnection::new(HttpScheme::Http);
{
    let mut frame_sender = FakeSender;
    let mut sender = conn.sender(&mut frame_sender);
    // Now we can use the provided sender to queue multiple HTTP/2 write operations,
    // without passing the same FakeSender reference to every single method.
    sender.send_settings_ack().unwrap();
    // While the `sender` is active, though, the original `conn` cannot be used, as the
    // sender holds on a mutable reference to it...
}
// A sender can be obtained, immediately used, and discarded:
conn.sender(&mut FakeSender).send_settings_ack();

pub fn in_window_size(&self) -> i32

Returns the current size of the inbound flow control window (i.e. the number of octets that the connection will accept and the peer will send at most, unless the window is updated).

pub fn out_window_size(&self) -> i32

Returns the current size of the outbound flow control window (i.e. the number of octets that can be sent on the connection to the peer without violating flow control).

pub fn expect_settings<Recv: ReceiveFrame, Sess: Session>(
    &mut self,
    rx: &mut Recv,
    session: &mut Sess
) -> HttpResult<()>

The method processes the next frame provided by the given ReceiveFrame instance, expecting it to be a SETTINGS frame. Additionally, the frame cannot be an ACK settings frame, but rather it should contain the peer's settings.

The method can be used when the receipt of the peer's preface needs to be asserted, such as when the connection is first initiated (the first frame on a fresh HTTP/2 connection that any peer sends must be a SETTINGS frame).

If the received frame is not a SETTINGS frame, an HttpError::UnableToConnect variant is returned. (TODO: Change this variant's name, as it is a byproduct of this method's legacy)

pub fn handle_next_frame<Recv: ReceiveFrame, Sess: Session>(
    &mut self,
    rx: &mut Recv,
    session: &mut Sess
) -> HttpResult<()>

Handles the next frame incoming on the given ReceiveFrame instance.

The HttpConnection takes care of parsing the frame and extracting the semantics behind it and passes this on to the higher level by invoking (possibly multiple) callbacks on the given Session instance. For information on which events can be passed to the session, check out the Session trait.

If the handling is successful, a unit Ok is returned; all HTTP and IO errors are propagated.