RESTinio
Namespaces | Classes | Typedefs | Enumerations | Functions
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_tanalyze_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_tenumerate_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

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

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.
}
},
"multipart", "form-data" );
if(result) {
... // Producing positive response.
}
else {
... // Producing negative response.
}
}
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 ...
@ 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.
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:

restinio::multipart_body::handling_result_t handling_result_t
The result to be returned from user-provided handler of parts of multipart body.
A description of one part with an uploaded file.

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.
},
"multipart", "form-data" );
if(result) {
... // Producing positive response.
}
else {
... // Producing negative response.
}
}
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.
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
reqRequest to be processed.
handlerHandler to be called for every part with uploaded file.
expected_media_typeThe value of 'type' part of media-type in Content-Type field. Please note: the special value '*' is not supported here.
expected_media_subtypeThe 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.