Trait rocket::data::FromData
[−]
[src]
pub trait FromData: Sized { type Error; fn from_data(request: &Request, data: Data) -> Outcome<Self, Self::Error>; }
Trait used to derive an object from incoming request data.
Types that implement this trait can be used as a target for the data = "<param>"
route parmater, as illustrated below:
#[post("/submit", data = "<var>")] fn submit(var: T) -> ... { ... }
In this example, T
can be any type that implements FromData
.
Outcomes
The returned Outcome of a from_data
call
determines how the incoming request will be processed.
Success(S)
If the
Outcome
isSuccess
, then theSuccess
value will be used as the value for the data parameter. As long as all other parsed types succeed, the request will be handled by the requesting handler.Failure(Status, E)
If the
Outcome
isFailure
, the request will fail with the given status code and error. The designated error Catcher will be used to respond to the request. Note that users can request types ofResult<S, E>
andOption<S>
to catchFailure
s and retrieve the error value.Forward(Data)
If the
Outcome
isForward
, the request will be forwarded to the next matching request. This requires that no data has been read from theData
parameter. Note that users can request anOption<S>
to catchForward
s.
Example
Say that you have a custom type, Person
:
struct Person { name: String, age: u16 }
Person
has a custom serialization format, so the built-in JSON
type
doesn't suffice. The format is <name>:<age>
with Content-Type: application/x-person
. You'd like to use Person
as a FromData
type so
that you can retrieve it directly from a client's request body:
#[post("/person", data = "<person>")] fn person(person: Person) -> &'static str { "Saved the new person to the database!" }
A FromData
implementation allowing this looks like:
use std::io::Read; use rocket::{Request, Data, Outcome}; use rocket::data::{self, FromData}; use rocket::http::{Status, ContentType}; use rocket::Outcome::*; impl FromData for Person { type Error = String; fn from_data(req: &Request, data: Data) -> data::Outcome<Self, String> { // Ensure the content type is correct before opening the data. let person_ct = ContentType::new("application", "x-person"); if req.content_type() != person_ct { return Outcome::Forward(data); } // Read the data into a String. let mut string = String::new(); if let Err(e) = data.open().read_to_string(&mut string) { return Failure((Status::InternalServerError, format!("{:?}", e))); } // Split the string into two pieces at ':'. let (name, age) = match string.find(':') { Some(i) => (&string[..i], &string[(i + 1)..]), None => return Failure((Status::BadRequest, "Missing ':'.".into())) }; // Parse the age. let age: u16 = match age.parse() { Ok(age) => age, Err(e) => return Failure((Status::BadRequest, "Bad age.".into())) }; // Return successfully. Success(Person { name: name.into(), age: age }) } }
Associated Types
type Error
The associated error to be returned when parsing fails.
Required Methods
fn from_data(request: &Request, data: Data) -> Outcome<Self, Self::Error>
Parses an instance of Self
from the incoming request body data.
If the parse is successful, an outcome of Success
is returned. If the
data does not correspond to the type of Self
, Forward
is returned.
If parsing fails, Failure
is returned.