Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.101.0/docs/handbook/_sources/libraries/http_multipart.rst.txt

.. _library_http_multipart:

http_multipart

This library provides a higher-level multipart helper layer on top of the http_core library. It does not replace the low-level multipart wire support already implemented in http_core; instead it wraps the normalized multipart body and part terms, adds form-data field and file helpers, and delegates raw parsing and generation to the existing http_core predicates.

API documentation

Open the `../../apis/library_index.html#http_multipart <../../apis/library_index.html#http_multipart>`__ link in a web browser.

Loading

To load the library, load the loader.lgt file:

::

| ?- logtalk_load(http_multipart(loader)).

Testing

To test this library, load the tester.lgt file:

::

| ?- logtalk_load(http_multipart(tester)).

Current scope

The current version provides:

  • body/3 for constructing validated normalized multipart body terms.
  • part/4 for constructing validated normalized multipart part terms.
  • is_body/1 and is_part/1 for testing normalized multipart body and part terms.
  • media_type/2 and parts/2 for inspecting multipart body terms.
  • part_headers/2, part_body/2, and part_properties/2 for inspecting multipart part terms.
  • field/4 and fields/2 for inspecting textual form-data field parts and multipart/form-data bodies.
  • file/6 and files/2 for inspecting form-data file parts and multipart/form-data bodies.
  • field_part/4 and file_part/6 for constructing outgoing form-data field and file parts.
  • form_data_body/2 for constructing a multipart/form-data body from an ordered list of parameter-aware field and file descriptors.
  • parse/4 and generate/3 as multipart-specific wrappers around the existing http_core::parse_body/4 and http_core::generate_body/3 predicates.

Form-data descriptors

The parameter-aware helper predicates use the following descriptor shapes:

  • field(Name, Value, Parameters)
  • file(Name, Filename, MediaType, Payload, Parameters) In both cases, Parameters is an ordered list of extra Content-Disposition: form-data parameters represented as Name-Value pairs. The reserved name and filename parameters remain explicit helper arguments and must not be repeated in the Parameters list.

    Additional Content-Disposition: form-data parameters are preserved as ordered Name-Value pairs. Any special semantics for extended parameters such as filename* are intentionally left to callers.

Normalized terms

Multipart bodies use the normalized http_core body term:

::

content(MediaType, multipart(Parts))

Multipart parts use the recursive normalized term:

::

part(Headers, Body, Properties)

Current workflow

  • Use form_data_body/2 when you want to assemble a normalized multipart/form-data body explicitly.
  • Use the field/4, fields/2, file/6, and files/2 predicates when you want to inspect multipart form-data bodies after parsing.
  • The http_client library can send common form-data requests directly from a form_data(Items) descriptor.
  • The http_server_core library keeps multipart request bodies in the normalized form expected by this library, so handlers can inspect incoming multipart requests without reparsing them.

Current limitations

  • The library is entirely in-memory.
  • Textual field helpers target simple text field payloads. If a part has a non-text body or a more specialized encoding, callers should use the generic part accessors instead.
  • Multipart wire parsing and generation require a boundary parameter in the effective Content-Type metadata or an explicit boundary/1 option, exactly as in the underlying http_core library.
  • The library does not provide streaming sinks, temp-file policies, or large-upload orchestration.