RESTinio
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

RESTINIO_NODISCARD 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. More...
 
RESTINIO_NODISCARD 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. More...
 
RESTINIO_NODISCARD optional_t< enumeration_error_tcheck_boundary_value (string_view_t value)
 A helper function for checking the validity of 'boundary' value. More...
 
template<typename Extra_Data >
RESTINIO_NODISCARD expected_t< std::string, enumeration_error_tdetect_boundary_for_multipart_body (const generic_request_t< Extra_Data > &req, string_view_t expected_media_type, optional_t< string_view_t > expected_media_subtype)
 Helper function for parsing Content-Type field and extracting the value of 'boundary' parameter. More...
 
template<typename User_Type , typename Handler >
RESTINIO_NODISCARD 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" }, optional_t< string_view_t > expected_media_subtype=nullopt)
 A helper function for enumeration of parts of a multipart body. More...
 

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()

RESTINIO_NODISCARD optional_t< 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 >
RESTINIO_NODISCARD 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,
optional_t< 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()

template<typename User_Type , typename Handler >
RESTINIO_NODISCARD 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" },
optional_t< string_view_t expected_media_subtype = 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.
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:

auto on_post(const restinio::request_handle_t & req) {
using namespace restinio::multipart_body;
const auto result = enumerate_parts( *req,
[](parsed_part_t part) {
... // 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 ...
RESTINIO_NODISCARD 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" }, optional_t< string_view_t > expected_media_subtype=nullopt)
A helper function for enumeration of parts of a multipart body.
RESTINIO_NODISCARD constexpr request_handling_status_t request_accepted() noexcept
std::shared_ptr< request_t > request_handle_t
An alias for handle for incoming request without additional extra-data.
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()

RESTINIO_NODISCARD 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;
const auto boundary = detect_boundary_for_multipart_body(
req, "multipart", "form-data" );
if( boundary )
{
const auto parts = split_multipart_body( req.body(), *boundary );
for( restinio::string_view_t one_part : parts )
{
... // Handling of a part.
}
}
RESTINIO_NODISCARD 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.
RESTINIO_NODISCARD 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, optional_t< string_view_t > expected_media_subtype)
Helper function for parsing Content-Type field and extracting the value of 'boundary' parameter.
nonstd::string_view string_view_t
Definition: string_view.hpp:19
Since
v.0.6.1

Definition at line 72 of file multipart_body.hpp.

◆ try_parse_part()

RESTINIO_NODISCARD 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;
const auto boundary = detect_boundary_for_multipart_body(
req, "multipart", "form-data" );
if( boundary )
{
const auto parts = split_multipart_body( req.body(), *boundary );
for( restinio::string_view_t one_part : parts )
{
const auto parsed_part = try_parse_part( one_part );
if( parsed_part )
{
... // Handle the content of the parsed part.
}
}
}
RESTINIO_NODISCARD 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.