RESTinio
Loading...
Searching...
No Matches
Namespaces | Classes | Enumerations | Functions
restinio::multipart_body Namespace Reference

Namespaces

namespace  impl
 

Classes

struct  parsed_part_t
 A description of parsed content of one part of a multipart body. More...
 

Enumerations

enum class  handling_result_t { continue_enumeration , stop_enumeration , terminate_enumeration }
 The result to be returned from user-provided handler of parts of multipart body. More...
 
enum class  enumeration_error_t {
  content_type_field_not_found , content_type_field_parse_error , content_type_field_inappropriate_value , illegal_boundary_value ,
  no_parts_found , terminated_by_handler , unexpected_error
}
 The result of an attempt to enumerate parts of a multipart body. More...
 

Functions

std::vector< string_view_tsplit_multipart_body (string_view_t body, string_view_t boundary)
 Helper function for spliting a multipart body into a serie of separate parts.
 
expected_t< parsed_part_t, restinio::easy_parser::parse_error_ttry_parse_part (string_view_t part)
 Helper function for parsing content of one part of a multipart body.
 
std::optional< enumeration_error_tcheck_boundary_value (string_view_t value)
 A helper function for checking the validity of 'boundary' value.
 
template<typename Extra_Data >
expected_t< std::string, enumeration_error_tdetect_boundary_for_multipart_body (const generic_request_t< Extra_Data > &req, string_view_t expected_media_type, std::optional< string_view_t > expected_media_subtype)
 Helper function for parsing Content-Type field and extracting the value of 'boundary' parameter.
 
template<typename User_Type , typename Handler >
expected_t< std::size_t, enumeration_error_tenumerate_parts (const generic_request_t< User_Type > &req, Handler &&handler, string_view_t expected_media_type=string_view_t{ "multipart" }, std::optional< string_view_t > expected_media_subtype=std::nullopt)
 A helper function for enumeration of parts of a multipart body.
 

Enumeration Type Documentation

◆ enumeration_error_t

The result of an attempt to enumerate parts of a multipart body.

Since
v.0.6.1
Enumerator
content_type_field_not_found 

Content-Type field is not found. If Content-Type is absent there is no way to detect 'boundary' parameter.

content_type_field_parse_error 

Unable to parse Content-Type field value.

content_type_field_inappropriate_value 

Content-Type field value parsed but doesn't contain an appropriate value. For example there can be media-type different from 'multipart' or 'boundary' parameter can be absent.

illegal_boundary_value 

Value of 'boundary' parameter is invalid (for example it contains some illegal characters).

no_parts_found 

No parts of a multipart body actually found.

terminated_by_handler 

Enumeration of parts was aborted by user-provided handler. This code is returned when user-provided handler returns handling_result_t::terminate_enumeration.

unexpected_error 

Some unexpected error encountered during the enumeration.

Definition at line 361 of file multipart_body.hpp.

◆ handling_result_t

The result to be returned from user-provided handler of parts of multipart body.

Since
v.0.6.1
Enumerator
continue_enumeration 

Enumeration of parts should be continued. If there is another part the user-provided handler will be called for it.

stop_enumeration 

Enumeration of parts should be stopped. All remaining parts of multipart body will be skipped. But the result of the enumeration will be successful.

terminate_enumeration 

Enumeration of parts should be ignored. All remaining parts of multipart body will be skipped and the result of the enumeration will be a failure.

Definition at line 337 of file multipart_body.hpp.

Function Documentation

◆ check_boundary_value()

std::optional< enumeration_error_t > restinio::multipart_body::check_boundary_value ( string_view_t value)
inline

A helper function for checking the validity of 'boundary' value.

The allowed format for 'boundary' value is defined here: https://tools.ietf.org/html/rfc2046

     boundary := 0*69<bchars> bcharsnospace

     bchars := bcharsnospace / " "

     bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
                      "+" / "_" / "," / "-" / "." /
                      "/" / ":" / "=" / "?"
Returns
enumeration_error_t::illegal_boundary_value if value has illegal value or an empty optional if there is no errros detected.
Since
v.0.6.1

Definition at line 457 of file multipart_body.hpp.

◆ detect_boundary_for_multipart_body()

template<typename Extra_Data >
expected_t< std::string, enumeration_error_t > restinio::multipart_body::detect_boundary_for_multipart_body ( const generic_request_t< Extra_Data > & req,
string_view_t expected_media_type,
std::optional< string_view_t > expected_media_subtype )

Helper function for parsing Content-Type field and extracting the value of 'boundary' parameter.

It finds Content-Type field, then parses it, then checks the value of media-type, then finds 'boundary' parameter, the checks the validity of 'boundary' value and then adds two leading hypens to the value of 'boundary' parameter.

The returned value (if there is no error) can be used for spliting a multipart body to separate parts.

Since
v.0.6.1

Definition at line 497 of file multipart_body.hpp.

◆ enumerate_parts()

expected_t< std::size_t, enumeration_error_t > restinio::multipart_body::enumerate_parts ( const generic_request_t< User_Type > & req,
Handler && handler,
string_view_t expected_media_type = string_view_t{ "multipart" },
std::optional< string_view_t > expected_media_subtype = std::nullopt )

A helper function for enumeration of parts of a multipart body.

This function:

  • finds Content-Type field for req;
  • parses Content-Type field, checks the media-type and extracts the value of 'boundary' parameter. The extracted 'boundary' parameter is checked for validity;
  • splits the body of req using value of 'boundary' parameter;
  • enumerates every part of body, parses every part and calls @handler for every parsed part.

Enumeration stops if handler returns handling_result_t::stop_enumeration or handling_result_t::terminate_enumeration. If handler returns handling_result_t::terminate_enumeration the enumerate_parts() returns enumeration_error_t::terminated_by_handler error code.

A handler passed as handler argument should be a function or lambda/functor with one of the following formats:

handling_result_t
The result to be returned from user-provided handler of parts of multipart body.
run_on_this_thread_settings_t< Traits > on_this_thread()
A special marker for the case when http_server must be run on the context of the current thread.
A description of parsed content of one part of a multipart body.

Note that enumerate_part() passes parsed_part_t instance to handler as rvalue reference. And this reference will be invalidaded after the return from handler.

Usage example:

using namespace restinio::multipart_body;
const auto result = enumerate_parts( *req,
... // Some actions with the current part.
},
"multipart", "form-data" );
if(result) {
... // Producing positive response.
}
else {
... // Producing negative response.
}
}
@ continue_enumeration
Enumeration of parts should be continued. If there is another part the user-provided handler will be ...
expected_t< std::size_t, enumeration_error_t > enumerate_parts(const generic_request_t< User_Type > &req, Handler &&handler, string_view_t expected_media_type=string_view_t{ "multipart" }, std::optional< string_view_t > expected_media_subtype=std::nullopt)
A helper function for enumeration of parts of a multipart body.
std::shared_ptr< request_t > request_handle_t
An alias for handle for incoming request without additional extra-data.
constexpr request_handling_status_t request_accepted() noexcept
Returns
the count of parts successfuly handled by handler or error code in the case if some error is detected.
Since
v.0.6.1
Parameters
reqThe request to be handled.
handlerThe handler to be called for every parsed part.
expected_media_typeThe expected value of 'type' part of 'media-type' from Content-Type. If 'type' part is not equal to expected_media_type then enumeration won't be performed.
Note
The special value '*' is not handled here.
Parameters
expected_media_subtypeThe optional expected value of 'subtype' part of 'media-type' from Content-Type. If expected_media_subtype is specified and missmatch with 'subtype' part then enumeration won't be performed.
Note
The special value '*' is not handled here.

Definition at line 686 of file multipart_body.hpp.

◆ split_multipart_body()

std::vector< string_view_t > restinio::multipart_body::split_multipart_body ( string_view_t body,
string_view_t boundary )
inline

Helper function for spliting a multipart body into a serie of separate parts.

Returns
A list of separate parts. This list will be empty if no parts are found or if there is some error in the body format (for example if some part is opened by boundary but is not closed properly).
Note
A user should extract the value of boundary should from Content-Type field and modify it proper way (two leading hypens should be added to the value of "boundary" parameter) by him/herself. Helper function detect_boundary_for_multipart_body() can be used for that purpose.

Usage example:

using namespace restinio::multipart_body;
req, "multipart", "form-data" );
if( boundary )
{
const auto parts = split_multipart_body( req.body(), *boundary );
{
... // Handling of a part.
}
}
std::vector< string_view_t > split_multipart_body(string_view_t body, string_view_t boundary)
Helper function for spliting a multipart body into a serie of separate parts.
expected_t< std::string, enumeration_error_t > detect_boundary_for_multipart_body(const generic_request_t< Extra_Data > &req, string_view_t expected_media_type, std::optional< string_view_t > expected_media_subtype)
Helper function for parsing Content-Type field and extracting the value of 'boundary' parameter.
std::string_view string_view_t
Since
v.0.6.1

Definition at line 72 of file multipart_body.hpp.

◆ try_parse_part()

expected_t< parsed_part_t, restinio::easy_parser::parse_error_t > restinio::multipart_body::try_parse_part ( string_view_t part)

Helper function for parsing content of one part of a multipart body.

This function is intended to be used with split_multipart_body():

using namespace restinio::multipart_body;
req, "multipart", "form-data" );
if( boundary )
{
const auto parts = split_multipart_body( req.body(), *boundary );
{
{
... // Handle the content of the parsed part.
}
}
}
expected_t< parsed_part_t, restinio::easy_parser::parse_error_t > try_parse_part(string_view_t part)
Helper function for parsing content of one part of a multipart body.
Since
v.0.6.1

Definition at line 315 of file multipart_body.hpp.