Struct h2::client::SendRequest
source · pub struct SendRequest<B: Buf> { /* private fields */ }
Expand description
Initializes new HTTP/2 streams on a connection by sending a request.
This type does no work itself. Instead, it is a handle to the inner
connection state held by Connection
. If the associated connection
instance is dropped, all SendRequest
functions will return Error
.
SendRequest
instances are able to move to and operate on separate tasks
/ threads than their associated Connection
instance. Internally, there
is a buffer used to stage requests before they get written to the
connection. There is no guarantee that requests get written to the
connection in FIFO order as HTTP/2 prioritization logic can play a role.
SendRequest
implements Clone
, enabling the creation of many
instances that are backed by a single connection.
See module level documentation for more details.
Implementations§
source§impl<B> SendRequest<B>where
B: Buf,
impl<B> SendRequest<B>where
B: Buf,
sourcepub fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Error>>
pub fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Error>>
Returns Ready
when the connection can initialize a new HTTP/2
stream.
This function must return Ready
before send_request
is called. When
Poll::Pending
is returned, the task will be notified once the readiness
state changes.
See module level docs for more details.
sourcepub fn ready(self) -> ReadySendRequest<B> ⓘ
pub fn ready(self) -> ReadySendRequest<B> ⓘ
Consumes self
, returning a future that returns self
back once it is
ready to send a request.
This function should be called before calling send_request
.
This is a functional combinator for poll_ready
. The returned future
will call SendStream::poll_ready
until Ready
, then returns self
to
the caller.
§Examples
// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();
// Use `send_request` here.
See module level docs for more details.
sourcepub fn send_request(
&mut self,
request: Request<()>,
end_of_stream: bool,
) -> Result<(ResponseFuture, SendStream<B>), Error>
pub fn send_request( &mut self, request: Request<()>, end_of_stream: bool, ) -> Result<(ResponseFuture, SendStream<B>), Error>
Sends a HTTP/2 request to the server.
send_request
initializes a new HTTP/2 stream on the associated
connection, then sends the given request using this new stream. Only the
request head is sent.
On success, a ResponseFuture
instance and SendStream
instance
are returned. The ResponseFuture
instance is used to get the
server’s response and the SendStream
instance is used to send a
request body or trailers to the server over the same HTTP/2 stream.
To send a request body or trailers, set end_of_stream
to false
.
Then, use the returned SendStream
instance to stream request body
chunks or send trailers. If end_of_stream
is not set to false
then attempting to call SendStream::send_data
or
SendStream::send_trailers
will result in an error.
If no request body or trailers are to be sent, set end_of_stream
to
true
and drop the returned SendStream
instance.
§A note on HTTP versions
The provided Request
will be encoded differently depending on the
value of its version field. If the version is set to 2.0, then the
request is encoded as per the specification recommends.
If the version is set to a lower value, then the request is encoded to
preserve the characteristics of HTTP 1.1 and lower. Specifically, host
headers are permitted and the :authority
pseudo header is not
included.
The caller should always set the request’s version field to 2.0 unless specifically transmitting an HTTP 1.1 request over 2.0.
§Examples
Sending a request with no body
// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();
// Prepare the HTTP request to send to the server.
let request = Request::get("https://www.example.com/")
.body(())
.unwrap();
// Send the request to the server. Since we are not sending a
// body or trailers, we can drop the `SendStream` instance.
let (response, _) = send_request.send_request(request, true).unwrap();
let response = response.await.unwrap();
// Process the response
Sending a request with a body and trailers
// First, wait until the `send_request` handle is ready to send a new
// request
let mut send_request = send_request.ready().await.unwrap();
// Prepare the HTTP request to send to the server.
let request = Request::get("https://www.example.com/")
.body(())
.unwrap();
// Send the request to the server. If we are not sending a
// body or trailers, we can drop the `SendStream` instance.
let (response, mut send_stream) = send_request
.send_request(request, false).unwrap();
// At this point, one option would be to wait for send capacity.
// Doing so would allow us to not hold data in memory that
// cannot be sent. However, this is not a requirement, so this
// example will skip that step. See `SendStream` documentation
// for more details.
send_stream.send_data(b"hello", false).unwrap();
send_stream.send_data(b"world", false).unwrap();
// Send the trailers.
let mut trailers = HeaderMap::new();
trailers.insert(
header::HeaderName::from_bytes(b"my-trailer").unwrap(),
header::HeaderValue::from_bytes(b"hello").unwrap());
send_stream.send_trailers(trailers).unwrap();
let response = response.await.unwrap();
// Process the response
sourcepub fn is_extended_connect_protocol_enabled(&self) -> bool
pub fn is_extended_connect_protocol_enabled(&self) -> bool
Returns whether the extended CONNECT protocol is enabled or not.
This setting is configured by the server peer by sending the
SETTINGS_ENABLE_CONNECT_PROTOCOL
parameter in a SETTINGS
frame.
This method returns the currently acknowledged value received from the
remote.
Trait Implementations§
source§impl<B> Clone for SendRequest<B>where
B: Buf,
impl<B> Clone for SendRequest<B>where
B: Buf,
Auto Trait Implementations§
impl<B> Freeze for SendRequest<B>
impl<B> RefUnwindSafe for SendRequest<B>
impl<B> Send for SendRequest<B>where
B: Send,
impl<B> Sync for SendRequest<B>where
B: Send,
impl<B> Unpin for SendRequest<B>
impl<B> UnwindSafe for SendRequest<B>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)