<refentry id="camel-camel-imap-command">
<refmeta>
<refentrytitle role="top_of_page" id="camel-camel-imap-command.top_of_page">camel-imap-command</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAMEL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>camel-imap-command</refname>
<refpurpose></refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="camel-camel-imap-command.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
enum                <link linkend="CamelImapResponseType">CamelImapResponseType</link>;
struct              <link linkend="CamelImapResponse">CamelImapResponse</link>;
<link linkend="CamelImapResponse">CamelImapResponse</link>*  <link linkend="camel-imap-command">camel_imap_command</link>                  (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder,
                                                         <link linkend="CamelException">CamelException</link> *ex,
                                                         const <link linkend="char">char</link> *fmt,
                                                         ...);
<link linkend="CamelImapResponse">CamelImapResponse</link>*  <link linkend="camel-imap-command-continuation">camel_imap_command_continuation</link>     (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         const <link linkend="char">char</link> *cmd,
                                                         <link linkend="size-t">size_t</link> cmdlen,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-imap-response-free">camel_imap_response_free</link>            (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response);
<link linkend="void">void</link>                <link linkend="camel-imap-response-free-without-processing">camel_imap_response_free_without_processing</link>
                                                        (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response);
<link linkend="char">char</link>*               <link linkend="camel-imap-response-extract">camel_imap_response_extract</link>         (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response,
                                                         const <link linkend="char">char</link> *type,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="char">char</link>*               <link linkend="camel-imap-response-extract-continuation">camel_imap_response_extract_continuation</link>
                                                        (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="gboolean">gboolean</link>            <link linkend="camel-imap-command-start">camel_imap_command_start</link>            (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder,
                                                         <link linkend="CamelException">CamelException</link> *ex,
                                                         const <link linkend="char">char</link> *fmt,
                                                         ...);
<link linkend="CamelImapResponseType">CamelImapResponseType</link> <link linkend="camel-imap-command-response">camel_imap_command_response</link>       (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="char">char</link> **respbuf,
                                                         <link linkend="CamelException">CamelException</link> *ex);
</synopsis>
</refsynopsisdiv>









<refsect1 id="camel-camel-imap-command.description" role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="camel-camel-imap-command.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CamelImapResponseType" role="enum">
<title>enum CamelImapResponseType</title>
<indexterm zone="CamelImapResponseType"><primary>CamelImapResponseType</primary></indexterm><programlisting>typedef enum {
	CAMEL_IMAP_RESPONSE_ERROR,
	CAMEL_IMAP_RESPONSE_CONTINUATION,
	CAMEL_IMAP_RESPONSE_UNTAGGED,
	CAMEL_IMAP_RESPONSE_TAGGED
} CamelImapResponseType;
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CamelImapResponse" role="struct">
<title>struct CamelImapResponse</title>
<indexterm zone="CamelImapResponse"><primary>CamelImapResponse</primary></indexterm><programlisting>struct CamelImapResponse {
	CamelFolder *folder;
	GPtrArray *untagged;
	char *status;
};
</programlisting>
<para>

</para></refsect2>
<refsect2 id="camel-imap-command" role="function">
<title>camel_imap_command ()</title>
<indexterm zone="camel-imap-command"><primary>camel_imap_command</primary></indexterm><programlisting><link linkend="CamelImapResponse">CamelImapResponse</link>*  camel_imap_command                  (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder,
                                                         <link linkend="CamelException">CamelException</link> *ex,
                                                         const <link linkend="char">char</link> *fmt,
                                                         ...);</programlisting>
<para>
This function calls <link linkend="camel-imap-command-start"><function>camel_imap_command_start()</function></link> to send the
command, then reads the complete response to it using
<link linkend="camel-imap-command-response"><function>camel_imap_command_response()</function></link> and returns a CamelImapResponse
structure.
</para>
<para>
As a special case, if <parameter>fmt</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, it will just select <parameter>folder</parameter>
and return the response from doing so.
</para>
<para>
See <link linkend="camel-imap-command-start"><function>camel_imap_command_start()</function></link> for details on <parameter>fmt</parameter>.
</para>
<para>
On success, the store's connect_lock will be locked. It will be freed
when you call camel_imap_response_free. (The lock is recursive, so
callers can grab and release it themselves if they need to run
multiple commands atomically.)</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the IMAP store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>folder</parameter>&nbsp;:</term>
<listitem><simpara> The folder to perform the operation in (or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if not
relevant).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
<listitem><simpara> a sort of printf-style format string, followed by arguments
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="NULL:CAPS"><literal>NULL</literal></link> if an error occurred (in which case <parameter>ex</parameter> will
be set). Otherwise, a CamelImapResponse describing the server's
response, which the caller must free with <link linkend="camel-imap-response-free"><function>camel_imap_response_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-command-continuation" role="function">
<title>camel_imap_command_continuation ()</title>
<indexterm zone="camel-imap-command-continuation"><primary>camel_imap_command_continuation</primary></indexterm><programlisting><link linkend="CamelImapResponse">CamelImapResponse</link>*  camel_imap_command_continuation     (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         const <link linkend="char">char</link> *cmd,
                                                         <link linkend="size-t">size_t</link> cmdlen,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
This method is for sending continuing responses to the IMAP server
after <link linkend="camel-imap-command"><function>camel_imap_command()</function></link> or <link linkend="camel-imap-command-response"><function>camel_imap_command_response()</function></link> returns
a continuation response.
</para>
<para>
This function assumes you have an exclusive lock on the imap stream.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the IMAP store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmd</parameter>&nbsp;:</term>
<listitem><simpara> buffer containing the response/request data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmdlen</parameter>&nbsp;:</term>
<listitem><simpara> command length
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> as for <link linkend="camel-imap-command"><function>camel_imap_command()</function></link>. On failure, the store's
connect_lock will be released.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-response-free" role="function">
<title>camel_imap_response_free ()</title>
<indexterm zone="camel-imap-response-free"><primary>camel_imap_response_free</primary></indexterm><programlisting><link linkend="void">void</link>                camel_imap_response_free            (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response);</programlisting>
<para>
Frees all of the data in <parameter>response</parameter> and processes any untagged
EXPUNGE and EXISTS responses in it. Releases <parameter>store</parameter>'s connect_lock.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the CamelImapStore the response is from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response</parameter>&nbsp;:</term>
<listitem><simpara> a CamelImapResponse
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-response-free-without-processing" role="function">
<title>camel_imap_response_free_without_processing ()</title>
<indexterm zone="camel-imap-response-free-without-processing"><primary>camel_imap_response_free_without_processing</primary></indexterm><programlisting><link linkend="void">void</link>                camel_imap_response_free_without_processing
                                                        (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response);</programlisting>
<para>
Frees all of the data in <parameter>response</parameter> without processing any untagged
responses. Releases <parameter>store</parameter>'s command lock.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the CamelImapStore the response is from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response</parameter>&nbsp;:</term>
<listitem><simpara> a CamelImapResponse:
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-response-extract" role="function">
<title>camel_imap_response_extract ()</title>
<indexterm zone="camel-imap-response-extract"><primary>camel_imap_response_extract</primary></indexterm><programlisting><link linkend="char">char</link>*               camel_imap_response_extract         (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response,
                                                         const <link linkend="char">char</link> *type,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
This checks that <parameter>response</parameter> contains a single untagged response of
type <parameter>type</parameter> and returns just that response data. If <parameter>response</parameter>
doesn't contain the right information, the function will set <parameter>ex</parameter>
and return <link linkend="NULL:CAPS"><literal>NULL</literal></link>. Either way, <parameter>response</parameter> will be freed and the
store's connect_lock released.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the store the response came from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response</parameter>&nbsp;:</term>
<listitem><simpara> the response data returned from camel_imap_command
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> the response type to extract
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the desired response string, which the caller must free.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-response-extract-continuation" role="function">
<title>camel_imap_response_extract_continuation ()</title>
<indexterm zone="camel-imap-response-extract-continuation"><primary>camel_imap_response_extract_continuation</primary></indexterm><programlisting><link linkend="char">char</link>*               camel_imap_response_extract_continuation
                                                        (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelImapResponse">CamelImapResponse</link> *response,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
This checks that <parameter>response</parameter> contains a continuation response, and
returns just that data. If <parameter>response</parameter> doesn't contain a continuation
response, the function will set <parameter>ex</parameter>, release <parameter>store</parameter>'s connect_lock,
and return <link linkend="NULL:CAPS"><literal>NULL</literal></link>. Either way, <parameter>response</parameter> will be freed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the store the response came from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response</parameter>&nbsp;:</term>
<listitem><simpara> the response data returned from camel_imap_command
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the desired response string, which the caller must free.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-command-start" role="function">
<title>camel_imap_command_start ()</title>
<indexterm zone="camel-imap-command-start"><primary>camel_imap_command_start</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            camel_imap_command_start            (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder,
                                                         <link linkend="CamelException">CamelException</link> *ex,
                                                         const <link linkend="char">char</link> *fmt,
                                                         ...);</programlisting>
<para>
This function makes sure that <parameter>folder</parameter> (if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>) is the
currently-selected folder on <parameter>store</parameter> and then sends the IMAP command
specified by <parameter>fmt</parameter> and the following arguments.
</para>
<para>
<parameter>fmt</parameter> can include the following <link linkend="escapes"><literal>-escapes</literal></link> ONLY:
<link linkend="s"><literal>s</literal></link>, <link linkend="d"><literal>d</literal></link>, %%: as with printf
<link linkend="S:CAPS"><literal>S</literal></link>: an IMAP "string" (quoted string or literal)
<link linkend="F:CAPS"><literal>F</literal></link>: an IMAP folder name
<link linkend="G:CAPS"><literal>G</literal></link>: an IMAP folder name, with namespace already prepended
</para>
<para>
<link linkend="S:CAPS"><literal>S</literal></link> strings will be passed as literals if the server supports LITERAL+
and quoted strings otherwise. (<link linkend="S:CAPS"><literal>S</literal></link> does not support strings that
contain newlines.)
</para>
<para>
<link linkend="F:CAPS"><literal>F</literal></link> will have the imap store's namespace prepended; <link linkend="F:CAPS"><literal>F</literal></link> and <link linkend="G:CAPS"><literal>G</literal></link> will then
be converted to UTF-7 and processed like <link linkend="S:CAPS"><literal>S</literal></link>.
</para>
<para>
On success, the store's connect_lock will be locked. It will be
freed when <link linkend="CAMEL-IMAP-RESPONSE-TAGGED:CAPS"><literal>CAMEL_IMAP_RESPONSE_TAGGED</literal></link> or <link linkend="CAMEL-IMAP-RESPONSE-ERROR:CAPS"><literal>CAMEL_IMAP_RESPONSE_ERROR</literal></link>
is returned from <link linkend="camel-imap-command-response"><function>camel_imap_command_response()</function></link>. (The lock is
recursive, so callers can grab and release it themselves if they
need to run multiple commands atomically.)</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the IMAP store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>folder</parameter>&nbsp;:</term>
<listitem><simpara> The folder to perform the operation in (or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if not
relevant).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
<listitem><simpara> a sort of printf-style format string, followed by arguments
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the command was sent successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if
an error occurred (in which case <parameter>ex</parameter> will be set).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-imap-command-response" role="function">
<title>camel_imap_command_response ()</title>
<indexterm zone="camel-imap-command-response"><primary>camel_imap_command_response</primary></indexterm><programlisting><link linkend="CamelImapResponseType">CamelImapResponseType</link> camel_imap_command_response       (<link linkend="CamelImapStore">CamelImapStore</link> *store,
                                                         <link linkend="char">char</link> **respbuf,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
This reads a single tagged, untagged, or continuation response from
<parameter>store</parameter> into *<parameter>response</parameter>. The caller must free the string when it is
done with it.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>store</parameter>&nbsp;:</term>
<listitem><simpara> the IMAP store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>respbuf</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a CamelException
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> One of <link linkend="CAMEL-IMAP-RESPONSE-CONTINUATION:CAPS"><literal>CAMEL_IMAP_RESPONSE_CONTINUATION</literal></link>,
<link linkend="CAMEL-IMAP-RESPONSE-UNTAGGED:CAPS"><literal>CAMEL_IMAP_RESPONSE_UNTAGGED</literal></link>, <link linkend="CAMEL-IMAP-RESPONSE-TAGGED:CAPS"><literal>CAMEL_IMAP_RESPONSE_TAGGED</literal></link>, or
<link linkend="CAMEL-IMAP-RESPONSE-ERROR:CAPS"><literal>CAMEL_IMAP_RESPONSE_ERROR</literal></link>. If either of the last two, <parameter>store</parameter>'s
command lock will be unlocked.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
