path: root/main/minimime/mm-docs/latex/group__mimepart.tex

\section{Accessing and manipulating MIME parts}
\label{group__mimepart}\index{Accessing and manipulating MIME parts@{Accessing and manipulating MIME parts}}
\subsection*{Creating and destroying MIME parts}
\begin{CompactItemize}
\item 
mm\_\-mimepart $\ast$ {\bf mm\_\-mimepart\_\-new} (void)
\item 
mm\_\-mimepart $\ast$ {\bf mm\_\-mimepart\_\-fromfile} (const char $\ast$filename)
\item 
void {\bf mm\_\-mimepart\_\-free} (struct mm\_\-mimepart $\ast$part)
\end{CompactItemize}
\subsection*{Accessing the MIME part's mail header}
\begin{CompactItemize}
\item 
int {\bf mm\_\-mimepart\_\-attachheader} (struct mm\_\-mimepart $\ast$part, struct mm\_\-mimeheader $\ast$header)
\item 
int {\bf mm\_\-mimepart\_\-countheaders} (struct mm\_\-mimepart $\ast$part)
\item 
int {\bf mm\_\-mimepart\_\-countheaderbyname} (struct mm\_\-mimepart $\ast$part, const char $\ast$name)
\item 
mm\_\-mimeheader $\ast$ {\bf mm\_\-mimepart\_\-getheaderbyname} (struct mm\_\-mimepart $\ast$part, const char $\ast$name, int idx)
\item 
const char $\ast$ {\bf mm\_\-mimepart\_\-getheadervalue} (struct mm\_\-mimepart $\ast$part, const char $\ast$name, int idx)
\item 
int {\bf mm\_\-mimepart\_\-headers\_\-start} (struct mm\_\-mimepart $\ast$part, struct mm\_\-mimeheader $\ast$$\ast$id)
\item 
mm\_\-mimeheader $\ast$ {\bf mm\_\-mimepart\_\-headers\_\-next} (struct mm\_\-mimepart $\ast$part, struct mm\_\-mimeheader $\ast$$\ast$id)
\end{CompactItemize}
\subsection*{Accessing and manipulating the MIME part's body}
\begin{CompactItemize}
\item 
char $\ast$ {\bf mm\_\-mimepart\_\-getbody} (struct mm\_\-mimepart $\ast$part, int opaque)
\item 
void {\bf mm\_\-mimepart\_\-setbody} (struct mm\_\-mimepart $\ast$part, const char $\ast$data, int opaque)
\item 
size\_\-t {\bf mm\_\-mimepart\_\-getlength} (struct mm\_\-mimepart $\ast$part)
\item 
char $\ast$ {\bf mm\_\-mimepart\_\-decode} (struct mm\_\-mimepart $\ast$part)
\item 
int {\bf mm\_\-mimepart\_\-flatten} (struct mm\_\-mimepart $\ast$part, char $\ast$$\ast$result, size\_\-t $\ast$length, int opaque)
\item 
int {\bf mm\_\-mimepart\_\-setdefaultcontenttype} (struct mm\_\-mimepart $\ast$part, int composite)
\end{CompactItemize}
\subsection*{Accessing the MIME part's Content-Type information}
\begin{CompactItemize}
\item 
void {\bf mm\_\-mimepart\_\-attachcontenttype} (struct mm\_\-mimepart $\ast$part, struct mm\_\-content $\ast$ct)
\item 
mm\_\-content $\ast$ {\bf mm\_\-mimepart\_\-gettype} (struct mm\_\-mimepart $\ast$part)
\end{CompactItemize}


\subsection{Detailed Description}
MIME parts, also called entities, represent the structure of a MIME message. ``Normal'' internet messages have only a single part, and are called ``flat'' messages. Multipart messages have more then one part, and each MIME part can have it's own subset of headers.

Provided here are functions to easily access all informations from a MIME part, including their specific headers and bodies. 

\subsection{Function Documentation}
\index{mimepart@{mimepart}!mm_mimepart_attachcontenttype@{mm\_\-mimepart\_\-attachcontenttype}}
\index{mm_mimepart_attachcontenttype@{mm\_\-mimepart\_\-attachcontenttype}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void mm\_\-mimepart\_\-attachcontenttype (struct mm\_\-mimepart $\ast$ {\em part}, struct mm\_\-content $\ast$ {\em ct})}\label{group__mimepart_g01822bc93b4741af75b5379384354e37}


Attaches a context type object to a MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em ct}]The content type object to attach \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Nothing\end{Desc}
This function attaches a Content-Type object to a MIME part. It does not care whether the Content-Type suites the actual content in the MIME part, so the programmer should take care of that. \index{mimepart@{mimepart}!mm_mimepart_attachheader@{mm\_\-mimepart\_\-attachheader}}
\index{mm_mimepart_attachheader@{mm\_\-mimepart\_\-attachheader}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-attachheader (struct mm\_\-mimepart $\ast$ {\em part}, struct mm\_\-mimeheader $\ast$ {\em header})}\label{group__mimepart_g46a674ff6b9873c0c45fa4eb5d94fd62}


Attaches a mm\_\-mimeheader object to a MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em header}]A valid MIME header object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 if successfull or -1 if the header could not be attached \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_countheaderbyname@{mm\_\-mimepart\_\-countheaderbyname}}
\index{mm_mimepart_countheaderbyname@{mm\_\-mimepart\_\-countheaderbyname}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-countheaderbyname (struct mm\_\-mimepart $\ast$ {\em part}, const char $\ast$ {\em name})}\label{group__mimepart_gf89da502ac54306994bdb452448a8026}


Retrieves the number of MIME headers with a given name in a MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em name}]The name of the MIME header which to count for \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The number of MIME headers within the MIME part \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_countheaders@{mm\_\-mimepart\_\-countheaders}}
\index{mm_mimepart_countheaders@{mm\_\-mimepart\_\-countheaders}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-countheaders (struct mm\_\-mimepart $\ast$ {\em part})}\label{group__mimepart_g44c78abfb0535312bcb427a2cd220026}


Retrieves the number of MIME headers available in a MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The number of MIME headers within the MIME part \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_decode@{mm\_\-mimepart\_\-decode}}
\index{mm_mimepart_decode@{mm\_\-mimepart\_\-decode}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ mm\_\-mimepart\_\-decode (struct mm\_\-mimepart $\ast$ {\em part})}\label{group__mimepart_g4551bf4460e5d165bbcd9f32d4f625de}


Decodes a MIME part according to it's encoding using Mini\-MIME codecs

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em A}]valid MIME part object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 if the MIME part could be successfully decoded or -1 if not \end{Desc}
\begin{Desc}
\item[Note:]Sets mm\_\-errno on error\end{Desc}
This function decodes the body of a MIME part with a registered decoder according to it's Content-Transfer-Encoding header field. \index{mimepart@{mimepart}!mm_mimepart_flatten@{mm\_\-mimepart\_\-flatten}}
\index{mm_mimepart_flatten@{mm\_\-mimepart\_\-flatten}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-flatten (struct mm\_\-mimepart $\ast$ {\em part}, char $\ast$$\ast$ {\em result}, size\_\-t $\ast$ {\em length}, int {\em opaque})}\label{group__mimepart_gf19d3ace5ae174b3eaa35f9ddbe6e216}


Creates an ASCII representation of the given MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em result}]Where to store the result \item[{\em length}]Where to store the length of the result \item[{\em opaque}]Whether to use the opaque MIME part  0 on success or -1 on error. \end{description}
\end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-context\_\-flatten}{p.}{group__context_g5288136ab923605f6508c09359ae5772}\end{Desc}
This function creates an ASCII representation of a given MIME part. It will dynamically allocate the memory needed and stores the result in the memory region pointed to by result. The length of the result will be stored in length. If opaque is set to 1, mm\_\-mimepart\_\-flatten will store an opaque version of the MIME part in result, which means no headers will be created or sanitized. This is particulary useful if the part is digitally signed by e.g. PGP, and the signature spans the header fields of the part in question. \index{mimepart@{mimepart}!mm_mimepart_free@{mm\_\-mimepart\_\-free}}
\index{mm_mimepart_free@{mm\_\-mimepart\_\-free}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void mm\_\-mimepart\_\-free (struct mm\_\-mimepart $\ast$ {\em part})}\label{group__mimepart_gbf47790a0bb96b22bc5e236bc40cb32e}


Frees all memory allocated by a mm\_\-mimepart object.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A pointer to an allocated mm\_\-mimepart object \end{description}
\end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-new}{p.}{group__mimepart_g417e5dd361e30cddb91e1d9a5e30b223} \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_fromfile@{mm\_\-mimepart\_\-fromfile}}
\index{mm_mimepart_fromfile@{mm\_\-mimepart\_\-fromfile}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}struct mm\_\-mimepart$\ast$ mm\_\-mimepart\_\-fromfile (const char $\ast$ {\em filename})}\label{group__mimepart_ged8112012a337371ae8093adb1ab6d27}


Creates a MIME part from a file

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em filename}]The name of the file to create the MIME part from \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to a new MIME part object\end{Desc}
This function creates a new MIME part object from a file. The object should be freed using \doxyref{mm\_\-mimepart\_\-free()}{p.}{group__mimepart_gbf47790a0bb96b22bc5e236bc40cb32e} later on. This function does NOT set the Content-Type and neither does any encoding work. \index{mimepart@{mimepart}!mm_mimepart_getbody@{mm\_\-mimepart\_\-getbody}}
\index{mm_mimepart_getbody@{mm\_\-mimepart\_\-getbody}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ mm\_\-mimepart\_\-getbody (struct mm\_\-mimepart $\ast$ {\em part}, int {\em opaque})}\label{group__mimepart_g52dc9f27a2801e4f6abb1effd2ed838d}


Gets the pointer to the MIME part's body data

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em opaque}]Whether to get the opaque part or not \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the MIME part's body \end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-setbody}{p.}{group__mimepart_gd1def098c00edc546b03e98e9ff8b27a} \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_getheaderbyname@{mm\_\-mimepart\_\-getheaderbyname}}
\index{mm_mimepart_getheaderbyname@{mm\_\-mimepart\_\-getheaderbyname}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}struct mm\_\-mimeheader$\ast$ mm\_\-mimepart\_\-getheaderbyname (struct mm\_\-mimepart $\ast$ {\em part}, const char $\ast$ {\em name}, int {\em idx})}\label{group__mimepart_ga3ca298eaa82f4ef3ea731511ac84e53}


Get a MIME header object from a MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em name}]The name of the MIME header which to retrieve \item[{\em idx}]Which header field to get (in case of multiple headers of the same name). \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the requested MIME header on success, or NULL if there either isn't a header with the requested name or idx is out of range. \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_getheadervalue@{mm\_\-mimepart\_\-getheadervalue}}
\index{mm_mimepart_getheadervalue@{mm\_\-mimepart\_\-getheadervalue}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ mm\_\-mimepart\_\-getheadervalue (struct mm\_\-mimepart $\ast$ {\em part}, const char $\ast$ {\em name}, int {\em idx})}\label{group__mimepart_g779f11f7a6a54f83763b5ef6ff87e48f}


Gets the value of a MIME header object

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em name}]The name of the header field to get the value from \item[{\em idx}]The index of the header field to get, in case there are multiple headers with the same name. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the requested value on success, or NULL if there either isn't a header with the requested name or idx is out of range. \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_getlength@{mm\_\-mimepart\_\-getlength}}
\index{mm_mimepart_getlength@{mm\_\-mimepart\_\-getlength}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}size\_\-t mm\_\-mimepart\_\-getlength (struct mm\_\-mimepart $\ast$ {\em part})}\label{group__mimepart_gf8ccae1737dc4b9b91958fe448da677f}


Gets the length of a given MIME part object

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The size of the part's body in byte.\end{Desc}
This function returns the total length of the given MIME part's body. The length does not include the headers of the MIME parts. If the function returns 0, no body part is set currently. \index{mimepart@{mimepart}!mm_mimepart_gettype@{mm\_\-mimepart\_\-gettype}}
\index{mm_mimepart_gettype@{mm\_\-mimepart\_\-gettype}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}struct mm\_\-content$\ast$ mm\_\-mimepart\_\-gettype (struct mm\_\-mimepart $\ast$ {\em part})}\label{group__mimepart_g210e2ceee56f8349f6778006da87d080}


Gets the Content-Type of a given MIME part object

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The Content-Type object of the specified MIME part\end{Desc}
This function returns a pointer to the Content-Type object of the given MIME part. This pointer might be set to NULL, indicating that there is no Content-Type object for the given MIME part currently. \index{mimepart@{mimepart}!mm_mimepart_headers_next@{mm\_\-mimepart\_\-headers\_\-next}}
\index{mm_mimepart_headers_next@{mm\_\-mimepart\_\-headers\_\-next}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}struct mm\_\-mimeheader$\ast$ mm\_\-mimepart\_\-headers\_\-next (struct mm\_\-mimepart $\ast$ {\em part}, struct mm\_\-mimeheader $\ast$$\ast$ {\em id})}\label{group__mimepart_g8e9064736efdeebf4b257cc45f8a6adf}


Returns the next MIME header of a given MIME part object

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em id}]A previously initialized MIME header object \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the MIME header object or NULL if end of headers was reached. \end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-headers\_\-start}{p.}{group__mimepart_g4440bdcfddf88eb642b6a834a0557176} \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_headers_start@{mm\_\-mimepart\_\-headers\_\-start}}
\index{mm_mimepart_headers_start@{mm\_\-mimepart\_\-headers\_\-start}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-headers\_\-start (struct mm\_\-mimepart $\ast$ {\em part}, struct mm\_\-mimeheader $\ast$$\ast$ {\em id})}\label{group__mimepart_g4440bdcfddf88eb642b6a834a0557176}


Initializes a header loop for a given MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em id}]The address of a MIME header object (to allow reentrance) \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success or -1 on failure \end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-headers\_\-next}{p.}{group__mimepart_g8e9064736efdeebf4b257cc45f8a6adf}\end{Desc}
Looping through headers can be done in the following way:



\begin{Code}\begin{verbatim} struct mm_mimeheader *header, *lheader;

 mm_mimepart_headers_start(part, &lheader);

 while ((header = mm_mimepart_headers_next(part, &lheader)) != NULL) {
        printf("%s: %s\n", header->name, header->value);        
 }
\end{verbatim}\end{Code}



For convienience, the macro mm\_\-mimepart\_\-headers\_\-foreach() can be used to loop through headers in a one-shot manner. \index{mimepart@{mimepart}!mm_mimepart_new@{mm\_\-mimepart\_\-new}}
\index{mm_mimepart_new@{mm\_\-mimepart\_\-new}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}struct mm\_\-mimepart$\ast$ mm\_\-mimepart\_\-new (void)}\label{group__mimepart_g417e5dd361e30cddb91e1d9a5e30b223}


Allocates memory for a new mm\_\-mimepart structure and initializes it.

\begin{Desc}
\item[Returns:]A pointer to a struct of type mm\_\-mimeheader or NULL on failure \end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-free}{p.}{group__mimepart_gbf47790a0bb96b22bc5e236bc40cb32e} \end{Desc}
\begin{Desc}
\item[Note:]The memory must be freed by using \doxyref{mm\_\-mimepart\_\-free()}{p.}{group__mimepart_gbf47790a0bb96b22bc5e236bc40cb32e} later on. \end{Desc}
\index{mimepart@{mimepart}!mm_mimepart_setbody@{mm\_\-mimepart\_\-setbody}}
\index{mm_mimepart_setbody@{mm\_\-mimepart\_\-setbody}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void mm\_\-mimepart\_\-setbody (struct mm\_\-mimepart $\ast$ {\em part}, const char $\ast$ {\em data}, int {\em opaque})}\label{group__mimepart_gd1def098c00edc546b03e98e9ff8b27a}


Sets the MIME part's body data

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em data}]A pointer to the data which to set \end{description}
\end{Desc}
\begin{Desc}
\item[See also:]\doxyref{mm\_\-mimepart\_\-getbody}{p.}{group__mimepart_g52dc9f27a2801e4f6abb1effd2ed838d}\end{Desc}
This functions sets the body data for a given MIME part. The string pointed to by data must be NUL-terminated. The data is copied into the MIME part's body, and thus, the memory pointed to by data can be freed after the operation. \index{mimepart@{mimepart}!mm_mimepart_setdefaultcontenttype@{mm\_\-mimepart\_\-setdefaultcontenttype}}
\index{mm_mimepart_setdefaultcontenttype@{mm\_\-mimepart\_\-setdefaultcontenttype}!mimepart@{mimepart}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int mm\_\-mimepart\_\-setdefaultcontenttype (struct mm\_\-mimepart $\ast$ {\em part}, int {\em composite})}\label{group__mimepart_g164bb39a266559574c252f11266809ff}


Sets the default Content-Type for a given MIME part

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em part}]A valid MIME part object \item[{\em part}]Whether the Content-Type should be for composite or not \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success or -1 on failure\end{Desc}
This function sets a default Content-Type according to RFC 2045 with a value of \char`\"{}text/plain; charset=\char`\"{}us-ascii\char`\"{}\char`\"{}. This function should only be used if the MIME part in question does not have a valid Content-Type specification.