restinio::file_upload Namespace Reference

## Namespaces

namespace | impl

## Classes

struct | part_description_t
| A description of one part with an uploaded file. More...

## Typedefs

using | handling_result_t = restinio::multipart_body::handling_result_t
| The result to be returned from user-provided handler of parts of multipart body. More...

## Enumerations

enum class | enumeration_error_t { content_type_field_not_found , content_type_field_parse_error , content_type_field_inappropriate_value , illegal_boundary_value , content_disposition_field_parse_error , content_disposition_field_inappropriate_value , no_parts_found , no_files_found , terminated_by_handler , unexpected_error }
| The result of an attempt to enumerate parts of a multipart body that contains uploaded file. More...

## Functions

RESTINIO_NODISCARD expected_t< part_description_t, enumeration_error_t > | analyze_part (restinio::multipart_body::parsed_part_t parsed_part)
| Helper function for analyzing an already parsed part of a multipart body for presence of an uploaded file. More...
template<typename Extra_Data , typename Handler >
expected_t< std::size_t, enumeration_error_t > | enumerate_parts_with_files (const generic_request_t< Extra_Data > &req, Handler &&handler, string_view_t expected_media_type=string_view_t{"multipart"}, string_view_t expected_media_subtype=string_view_t{"form-data"})
| A helper function for enumeration of parts of a multipart body those contain uploaded files. More...

## Typedef Documentation

## handling_result_t

using restinio::file_upload::handling_result_t = typedef restinio::multipart_body::handling_result_t

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

Since
  v.0.6.1

Definition at line 131 of file file_upload.hpp.

## Enumeration Type Documentation

## enumeration_error_t

enum class restinio::file_upload::enumeration_error_t

strong

The result of an attempt to enumerate parts of a multipart body that contains uploaded file.

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).
content_disposition_field_parse_error | Unable to parse Content-Disposition field.
content_disposition_field_inappropriate_value | Content-Disposition field value parsed but doesn't contain an appropriate value. For example, there is no 'name' parameter.
no_parts_found | No parts of a multipart body actually found.
no_files_found | No files found in the current part. For example, there is no Content-Disposition field for that part, or Content-Disposition hasn't 'filename' and 'filename*' parameters.
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 39 of file file_upload.hpp.

## Function Documentation

## analyze_part()

RESTINIO_NODISCARD expected_t< part_description_t, enumeration_error_t > restinio::file_upload::analyze_part | ( | restinio::multipart_body::parsed_part_t | parsed_part | ) |

inline

Helper function for analyzing an already parsed part of a multipart body for presence of an uploaded file.

This function returns an instance of part_description_t if an uploaded file is found in parsed_part.

If an uploaded file isn't found or any error detected during analysis of parsed_part then enumeration_error_t returned.

Usage example:

auto on_post(const restinio::request_handle_t & req) {
using namespace restinio::multipart_body;
using namespace restinio::file_upload;
const auto result = enumerate_parts( *req,
[](parsed_part_t part) {
// Try to find an uploaded file in that part.
const auto uploaded_file = analyze_part(part);
if(uploaded_file) {
... // Some handling of the file content.
}
return handling_result_t::continue_enumeration;
},
"multipart", "form-data" );
if(result) {
... // Producing positive response.
}
else {
... // Producing negative response.
}
return restinio::request_accepted();
}
restinio::file_upload
Definition: file_upload.hpp:28
restinio::file_upload::analyze_part
RESTINIO_NODISCARD expected_t< part_description_t, enumeration_error_t > analyze_part(restinio::multipart_body::parsed_part_t parsed_part)
Helper function for analyzing an already parsed part of a multipart body for presence of an uploaded ...
Definition: file_upload.hpp:221
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

Since
  v.0.6.1

Definition at line 221 of file file_upload.hpp.

## enumerate_parts_with_files()

template<typename Extra_Data , typename Handler >

expected_t< std::size_t, enumeration_error_t > restinio::file_upload::enumerate_parts_with_files | ( | const generic_request_t< Extra_Data > & | req,
|  | Handler && | handler,
|  | string_view_t | expected_media_type = `string_view_t{"multipart"}`,
|  | string_view_t | expected_media_subtype = `string_view_t{"form-data"}`
| ) |  |

A helper function for enumeration of parts of a multipart body those contain uploaded files.

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 tries to find a Content-Disposition field with appropriate 'name' and 'filename*'/'filename' parameters;
- if a part with appropriate Content-Disposition is found the handler is called for it.

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(part_description_t part);
handling_result_t(part_description_t && part);
handling_result_t(const part_description_t & part);
restinio::file_upload::handling_result_t
restinio::multipart_body::handling_result_t handling_result_t
The result to be returned from user-provided handler of parts of multipart body.
Definition: file_upload.hpp:131
restinio::file_upload::part_description_t
A description of one part with an uploaded file.
Definition: file_upload.hpp:147

Note that enumerate_parts_with_files() passes part_description_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::file_upload;
const auto result = enumerate_parts_with_files( *req,
[](part_description_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::file_upload::enumerate_parts_with_files
expected_t< std::size_t, enumeration_error_t > enumerate_parts_with_files(const generic_request_t< Extra_Data > &req, Handler &&handler, string_view_t expected_media_type=string_view_t{"multipart"}, string_view_t expected_media_subtype=string_view_t{"form-data"})
A helper function for enumeration of parts of a multipart body those contain uploaded files.
Definition: file_upload.hpp:360

Returns
  the count of parts passed to handler or error code in the case if some error is detected.

Since
  v.0.6.1

Parameters

  req | Request to be processed.
  handler | Handler to be called for every part with uploaded file.
  expected_media_type | The value of 'type' part of media-type in Content-Type field. Please note: the special value '*' is not supported here.
  expected_media_subtype | The value of 'subtype' part of media-type in Content-Type field.

Examples
  sample/file_upload/main.cpp.

Definition at line 360 of file file_upload.hpp.