% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/mimepack): Create a MIME message}

\label{sec:mimepack}

Simple and partial implementation of MIME encoding. MIME is covered by
RFC 2045. This library is used by e.g., \predref{http_post_data}{3} when using the
\verb$form_data(+ListOfData)$ input specification.

MIME decoding is now arranged through \verb$library(mime)$ from the clib
package, based on the external librfc2045 library. Most likely the
functionality of this package will be moved to the same library someday.
Packing however is a lot simpler then parsing.\vspace{0.7cm}

\begin{description}
    \predicate[det]{mime_pack}{3}{+Inputs, +Out:stream, ?Boundary}
Pack a number of inputs into a MIME package using a specified or
generated boundary. The generated boundary consists of the
current time in milliseconds since the epoch and 10 random
hexadecimal numbers. \arg{Inputs} is a list of \textit{documents} that is
added to the mime message. Each element is one of:

\begin{description}
    \infixtermitem{\Seq}{\arg{Name}}{\arg{Value}}
\arg{Name} the document. This emits a header of the form below. The
\const{filename} is present if \arg{Value} is of the form \verb$file(File)$.
\arg{Value} may be any of remaining value specifications.

\begin{code}
Content-Disposition: form-data; name="Name"[; filename="<File>"
\end{code}

    \termitem{html}{Tokens}
\arg{Tokens} is a list of HTML tokens as produced by \dcgref{html}{1}. The
token list is emitted using \predref{print_html}{1}.
    \termitem{file}{File}
Emit the contents of \arg{File}. The \verb$Content-type$ is derived
from the \arg{File} using \predref{file_mime_type}{2}. If the content-type
is \verb$text/_$, the file data is copied in text mode, which
implies that it is read in the default encoding of the system
and written using the encoding of the \arg{Out} stream. Otherwise
the file data is copied binary.
    \termitem{stream}{In, Len}
Content is the next \arg{Len} units from \arg{In}. Data is copied using
\predref{copy_stream_data}{3}. Units is bytes for binary streams and
characters codes for text streams.
    \termitem{stream}{In}
Content of the stream \arg{In}, copied using \predref{copy_stream_data}{2}.
This is often used with memory files (see \predref{new_memory_file}{1}).
    \termitem{mime}{Attributes, Value, []}
Create a MIME header from \arg{Attributes} and add \arg{Value}, which can
be any of remaining values of this list. \arg{Attributes} may
contain \verb$type(ContentType)$ and/or \verb$character_set(CharSet)$. This
can be used to give a content-type to values that otherwise
do not have a content-type. For example:

\begin{code}
mime([type(text/html)], '<b>Hello World</b>', [])
\end{code}

    \termitem{mime}{[], , Parts}
Creates a nested multipart MIME message. \arg{Parts} is passed
as \arg{Inputs} to a recursive call to \predref{mime_pack}{2}.
    \termitem{\arg{Atomic}}{}
\arg{Atomic} values are passed to \predref{write}{1}. This embeds simple atoms
and numbers.
\end{description}

\begin{arguments}
\arg{Out} & is a stream opened for writing. Typically, it should
be opened in text mode using UTF-8 encoding. \\
\end{arguments}

\begin{tags}
    \tag{bug}
Does not validate that the boundary does not appear in
any of the input documents.
\end{tags}
\end{description}