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_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. More...
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. More...
RESTINIO_NODISCARD optional_t< enumeration_error_t > | check_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_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. More...
template<typename User_Type , typename Handler >
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. More...

## Enumeration Type Documentation

## ◆ enumeration_error_t

enum class restinio::multipart_body::enumeration_error_t
| strong

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

enum class restinio::multipart_body::handling_result_t
| strong

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(parsed_part_t part);
handling_result_t(parsed_part_t && part);
handling_result_t(const parsed_part_t & part);
restinio::multipart_body::handling_result_t
handling_result_t
The result to be returned from user-provided handler of parts of multipart body.
Definition: multipart_body.hpp:338
restinio::multipart_body::parsed_part_t
A description of parsed content of one part of a multipart body.
Definition: multipart_body.hpp:144

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.
return handling_result_t::continue_enumeration;
},
"multipart", "form-data" );
if(result) {
... // Producing positive response.
}
else {
... // Producing negative response.
}
return restinio::request_accepted();
}
restinio::multipart_body
Definition: multipart_body.hpp:33
restinio::multipart_body::handling_result_t::continue_enumeration
@ continue_enumeration
Enumeration of parts should be continued. If there is another part the user-provided handler will be ...
restinio::multipart_body::enumerate_parts
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.
Definition: multipart_body.hpp:686
restinio::request_accepted
RESTINIO_NODISCARD constexpr request_handling_status_t request_accepted() noexcept
Definition: common_types.hpp:46
restinio::request_handle_t
std::shared_ptr< request_t > request_handle_t
An alias for handle for incoming request without additional extra-data.
Definition: request_handler.hpp:463

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

  req | The request to be handled.
  handler | The handler to be called for every parsed part.
  expected_media_type | The 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_subtype | The 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::multipart_body::split_multipart_body
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.
Definition: multipart_body.hpp:72
restinio::multipart_body::detect_boundary_for_multipart_body
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.
Definition: multipart_body.hpp:497
restinio::string_view_t
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::multipart_body::try_parse_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.
Definition: multipart_body.hpp:315

Since
  v.0.6.1

Definition at line 315 of file multipart_body.hpp.