Struct rocket::Request

pub struct Request<'r> { /* fields omitted */ }

The type of an incoming web request.

This should be used sparingly in Rocket applications. In particular, it should likely only be used when writing FromRequest implementations. It contains all of the information for a given web request except for the body data. This includes the HTTP method, URI, cookies, headers, and more.

Methods

impl<'r> Request<'r>

fn new<U: Into<URI<'r>>>(method: Method, uri: U) -> Request<'r>

Create a new Request with the given method and uri. The uri parameter can be of any type that implements Into<URI> including &str and String; it must be a valid absolute URI.

Example

use rocket::Request;
use rocket::http::Method;

let request = Request::new(Method::Get, "/uri");

fn method(&self) -> Method

Retrieve the method from self.

Example

use rocket::Request;
use rocket::http::Method;

let request = Request::new(Method::Get, "/uri");
assert_eq!(request.method(), Method::Get);

fn set_method(&mut self, method: Method)

Set the method of self.

Example

use rocket::Request;
use rocket::http::Method;

let mut request = Request::new(Method::Get, "/uri");
assert_eq!(request.method(), Method::Get);

request.set_method(Method::Post);
assert_eq!(request.method(), Method::Post);

fn uri(&self) -> &URI

Borrow the URI from self, which must be an absolute URI.

Example

use rocket::Request;
use rocket::http::Method;

let request = Request::new(Method::Get, "/uri");
assert_eq!(request.uri().as_str(), "/uri");

fn set_uri<'u: 'r, U: Into<URI<'u>>>(&mut self, uri: U)

Set the URI in self. The uri parameter can be of any type that implements Into<URI> including &str and String; it must be a valid absolute URI.

Example

use rocket::Request;
use rocket::http::Method;

let mut request = Request::new(Method::Get, "/uri");

request.set_uri("/hello/Sergio?type=greeting");
assert_eq!(request.uri().as_str(), "/hello/Sergio?type=greeting");

fn remote(&self) -> Option<SocketAddr>

Returns the address of the remote connection that initiated this request if the address is known. If the address is not known, None is returned.

Example

use rocket::Request;
use rocket::http::Method;

let request = Request::new(Method::Get, "/uri");
assert!(request.remote().is_none());

fn headers(&self) -> &HeaderMap<'r>

Returns a HeaderMap of all of the headers in self.

Example

use rocket::Request;
use rocket::http::Method;

let request = Request::new(Method::Get, "/uri");
let header_map = request.headers();
assert!(header_map.is_empty());

fn add_header<H: Into<Header<'r>>>(&mut self, header: H)

Add the header to self's headers.

Example

use rocket::Request;
use rocket::http::{Method, ContentType};

let mut request = Request::new(Method::Get, "/uri");
assert!(request.headers().is_empty());

request.add_header(ContentType::HTML);
assert!(request.headers().contains("Content-Type"));
assert_eq!(request.headers().len(), 1);

fn replace_header<H: Into<Header<'r>>>(&mut self, header: H)

Replaces the value of the header with header.name with header.value. If no such header existed, header is added.

Example

use rocket::Request;
use rocket::http::{Method, ContentType};

let mut request = Request::new(Method::Get, "/uri");
assert!(request.headers().is_empty());

request.add_header(ContentType::HTML);
assert_eq!(request.content_type(), Some(ContentType::HTML));

request.replace_header(ContentType::JSON);
assert_eq!(request.content_type(), Some(ContentType::JSON));

fn cookies(&self) -> &Cookies

Returns a borrow to the cookies in self.

Note that Cookies implements internal mutability, so this method allows you to get and set cookies in self.

Example

Add a new cookie to a request's cookies:

use rocket::Request;
use rocket::http::{Cookie, Method};

let request = Request::new(Method::Get, "/uri");
request.cookies().add(Cookie::new("key", "val"));
request.cookies().add(Cookie::new("ans", format!("life: {}", 38 + 4)));

fn content_type(&self) -> Option<ContentType>

Returns Some of the Content-Type header of self. If the header is not present, returns None.

Example

use rocket::Request;
use rocket::http::{Method, ContentType};

let mut request = Request::new(Method::Get, "/uri");
assert_eq!(request.content_type(), None);

request.replace_header(ContentType::JSON);
assert_eq!(request.content_type(), Some(ContentType::JSON));

fn get_param<'a, T: FromParam<'a>>(&'a self, n: usize) -> Result<T, Error>

Retrieves and parses into T the 0-indexed nth dynamic parameter from the request. Returns Error::NoKey if n is greater than the number of params. Returns Error::BadParse if the parameter type T can't be parsed from the parameter.

This method exists only to be used by manual routing. To retrieve parameters from a request, use Rocket's code generation facilities.

Example

Retrieve parameter 0, which is expected to be an &str, in a manual route:

use rocket::{Request, Data};
use rocket::handler::Outcome;

fn name<'a>(req: &'a Request, _: Data) -> Outcome<'a> {
    Outcome::of(req.get_param(0).unwrap_or("unnamed"))
}

fn get_segments<'a, T: FromSegments<'a>>(&'a self, n: usize) -> Result<T, Error>

Retrieves and parses into T all of the path segments in the request URI beginning at the 0-indexed nth dynamic parameter. T must implement FromSegments, which is used to parse the segments.

This method exists only to be used by manual routing. To retrieve segments from a request, use Rocket's code generation facilities.

Error

If there are less than n segments, returns an Err of NoKey. If parsing the segments failed, returns an Err of BadParse.

Example

If the request URI is "/hello/there/i/am/here", and the matched route path for this request is "/hello/<name>/i/<segs..>", then request.get_segments::<T>(1) will attempt to parse the segments "am/here" as type T.

Trait Implementations

impl<'r> Display for Request<'r>

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

Pretty prints a Request. This is primarily used by Rocket's logging infrastructure.