Struct multer::Field

pub struct Field { /* fields omitted */ }

A single field in a multipart stream.

Its content can be accessed via the Stream API or the methods defined in this type.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let content = field.text().await.unwrap();
    assert_eq!(content, "abcd");
}

Warning About Leaks

To avoid the next field being initialized before this one is done being read or dropped, only one instance per Multipart instance is allowed at a time. A Drop implementation is used to notify Multipart that this field is done being read.

If this value is leaked (via std::mem::forget() or some other mechanism), then the parent Multipart will never be able to yield the next field in the stream. The task waiting on the Multipart will also never be notified, which, depending on the executor implementation, may cause a deadlock.

Implementations

impl Field

pub fn name(&self) -> Option<&str>

The field name found in the Content-Disposition header.

pub fn file_name(&self) -> Option<&str>

The file name found in the Content-Disposition header.

pub fn content_type(&self) -> Option<&Mime>

Get the content type of the field.

pub fn headers(&self) -> &HeaderMap

Get a map of headers as HeaderMap.

pub async fn bytes(self) -> Result<Bytes>

Get the full data of the field as Bytes.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let bytes = field.bytes().await.unwrap();
    assert_eq!(bytes.len(), 4);
}

pub async fn chunk<'_>(&'_ mut self) -> Result<Option<Bytes>>

Stream a chunk of the field data.

When the field data has been exhausted, this will return None.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(mut field) = multipart.next_field().await.unwrap() {
    while let Some(chunk) = field.chunk().await.unwrap() {
        println!("Chunk: {:?}", chunk);
    }
}

pub async fn json<T: DeserializeOwned>(self) -> Result<T>

Try to deserialize the field data as JSON.

Optional

This requires the optional json feature to be enabled.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;
use serde::Deserialize;

// This `derive` requires the `serde` dependency.
#[derive(Deserialize)]
struct User {
    name: String
}

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\n{ \"name\": \"Alice\" }\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let user = field.json::<User>().await.unwrap();
    println!("User Name: {}", user.name);
}

Errors

This method fails if the field data is not in JSON format or it cannot be properly deserialized to target type T. For more details please see serde_json::from_slice;

pub async fn text(self) -> Result<String>

Get the full field data as text.

This method decodes the field data with BOM sniffing and with malformed sequences replaced with the REPLACEMENT CHARACTER. Encoding is determined from the charset parameter of Content-Type header, and defaults to utf-8 if not presented.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(mut field) = multipart.next_field().await.unwrap() {
   let content = field.text().await.unwrap();
   assert_eq!(content, "abcd");
}

pub async fn text_with_charset<'_>(
    self,
    default_encoding: &'_ str
) -> Result<String>

Get the full field data as text given a specific encoding.

This method decodes the field data with BOM sniffing and with malformed sequences replaced with the REPLACEMENT CHARACTER. You can provide a default encoding for decoding the raw message, while the charset parameter of Content-Type header is still prioritized. For more information about the possible encoding name, please go to encoding_rs docs.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(mut field) = multipart.next_field().await.unwrap() {
   let content = field.text_with_charset("utf-8").await.unwrap();
   assert_eq!(content, "abcd");
}

pub fn index(&self) -> usize

Get the index of this field in order they appeared in the stream.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures::stream::once;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let idx = field.index();
    println!("Field index: {}", idx);
}

Trait Implementations

impl Drop for Field

fn drop(&mut self)

Executes the destructor for this type.

impl Stream for Field

type Item = Result<Bytes, Error>

Values yielded by the stream.

fn poll_next(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.