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

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

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

<synopsis>
                    <link linkend="CamelOperation">CamelOperation</link>;
<link linkend="void">void</link>                (<link linkend="CamelOperationStatusFunc">*CamelOperationStatusFunc</link>)         (<link linkend="struct--CamelOperation">struct _CamelOperation</link> *op,
                                                         const <link linkend="char">char</link> *what,
                                                         <link linkend="int">int</link> pc,
                                                         <link linkend="void">void</link> *data);
enum                <link linkend="camel-operation-status-t">camel_operation_status_t</link>;
<link linkend="CamelOperation">CamelOperation</link>*     <link linkend="camel-operation-new">camel_operation_new</link>                 (<link linkend="CamelOperationStatusFunc">CamelOperationStatusFunc</link> status,
                                                         <link linkend="void">void</link> *status_data);
<link linkend="void">void</link>                <link linkend="camel-operation-mute">camel_operation_mute</link>                (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-ref">camel_operation_ref</link>                 (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-unref">camel_operation_unref</link>               (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-cancel">camel_operation_cancel</link>              (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-uncancel">camel_operation_uncancel</link>            (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="CamelOperation">CamelOperation</link>*     <link linkend="camel-operation-register">camel_operation_register</link>            (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-unregister">camel_operation_unregister</link>          (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-cancel-block">camel_operation_cancel_block</link>        (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="void">void</link>                <link linkend="camel-operation-cancel-unblock">camel_operation_cancel_unblock</link>      (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="int">int</link>                 <link linkend="camel-operation-cancel-check">camel_operation_cancel_check</link>        (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="int">int</link>                 <link linkend="camel-operation-cancel-fd">camel_operation_cancel_fd</link>           (<link linkend="CamelOperation">CamelOperation</link> *cc);
struct <link linkend="PRFileDesc">PRFileDesc</link>*  <link linkend="camel-operation-cancel-prfd">camel_operation_cancel_prfd</link>         (<link linkend="CamelOperation">CamelOperation</link> *cc);
<link linkend="CamelOperation">CamelOperation</link>*     <link linkend="camel-operation-registered">camel_operation_registered</link>          (void);
<link linkend="void">void</link>                <link linkend="camel-operation-start">camel_operation_start</link>               (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="char">char</link> *what,
                                                         ...);
<link linkend="void">void</link>                <link linkend="camel-operation-start-transient">camel_operation_start_transient</link>     (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="char">char</link> *what,
                                                         ...);
<link linkend="void">void</link>                <link linkend="camel-operation-progress">camel_operation_progress</link>            (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="int">int</link> pc);
<link linkend="void">void</link>                <link linkend="camel-operation-progress-count">camel_operation_progress_count</link>      (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="int">int</link> sofar);
<link linkend="void">void</link>                <link linkend="camel-operation-end">camel_operation_end</link>                 (<link linkend="CamelOperation">CamelOperation</link> *cc);
</synopsis>
</refsynopsisdiv>









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

</para>
</refsect1>

<refsect1 id="camel-camel-operation.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CamelOperation" role="struct">
<title>CamelOperation</title>
<indexterm zone="CamelOperation"><primary>CamelOperation</primary></indexterm><programlisting>typedef struct _CamelOperation CamelOperation;</programlisting>
<para>

</para></refsect2>
<refsect2 id="CamelOperationStatusFunc" role="function">
<title>CamelOperationStatusFunc ()</title>
<indexterm zone="CamelOperationStatusFunc"><primary>CamelOperationStatusFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*CamelOperationStatusFunc)         (<link linkend="struct--CamelOperation">struct _CamelOperation</link> *op,
                                                         const <link linkend="char">char</link> *what,
                                                         <link linkend="int">int</link> pc,
                                                         <link linkend="void">void</link> *data);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>op</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>what</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pc</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-status-t" role="enum">
<title>enum camel_operation_status_t</title>
<indexterm zone="camel-operation-status-t"><primary>camel_operation_status_t</primary></indexterm><programlisting>typedef enum _camel_operation_status_t {
	CAMEL_OPERATION_START = -1,
	CAMEL_OPERATION_END = -2
} camel_operation_status_t;
</programlisting>
<para>

</para></refsect2>
<refsect2 id="camel-operation-new" role="function">
<title>camel_operation_new ()</title>
<indexterm zone="camel-operation-new"><primary>camel_operation_new</primary></indexterm><programlisting><link linkend="CamelOperation">CamelOperation</link>*     camel_operation_new                 (<link linkend="CamelOperationStatusFunc">CamelOperationStatusFunc</link> status,
                                                         <link linkend="void">void</link> *status_data);</programlisting>
<para>
Create a new camel operation handle.  Camel operation handles can
be used in a multithreaded application (or a single operation
handle can be used in a non threaded appliation) to cancel running
operations and to obtain notification messages of the internal
status of messages.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter>&nbsp;:</term>
<listitem><simpara> Callback for receiving status messages.  This will always
be called with an internal lock held.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>status_data</parameter>&nbsp;:</term>
<listitem><simpara> User data.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new operation handle.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-mute" role="function">
<title>camel_operation_mute ()</title>
<indexterm zone="camel-operation-mute"><primary>camel_operation_mute</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_mute                (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
mutes a camel operation permanently.  from this point on you will never
receive operation updates, even if more are sent.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-ref" role="function">
<title>camel_operation_ref ()</title>
<indexterm zone="camel-operation-ref"><primary>camel_operation_ref</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_ref                 (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Add a reference to the CamelOperation <parameter>cc</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-unref" role="function">
<title>camel_operation_unref ()</title>
<indexterm zone="camel-operation-unref"><primary>camel_operation_unref</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_unref               (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Unref and potentially free <parameter>cc</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel" role="function">
<title>camel_operation_cancel ()</title>
<indexterm zone="camel-operation-cancel"><primary>camel_operation_cancel</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_cancel              (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Cancel a given operation.  If <parameter>cc</parameter> is NULL then all outstanding
operations are cancelled.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-uncancel" role="function">
<title>camel_operation_uncancel ()</title>
<indexterm zone="camel-operation-uncancel"><primary>camel_operation_uncancel</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_uncancel            (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Uncancel a cancelled operation.  If <parameter>cc</parameter> is NULL then the current
operation is uncancelled.
</para>
<para>
This is useful, if e.g. you need to do some cleaning up where a
cancellation lying around in the same thread will abort any
processing.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-register" role="function">
<title>camel_operation_register ()</title>
<indexterm zone="camel-operation-register"><primary>camel_operation_register</primary></indexterm><programlisting><link linkend="CamelOperation">CamelOperation</link>*     camel_operation_register            (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Register a thread or the main thread for cancellation through <parameter>cc</parameter>.
If <parameter>cc</parameter> is NULL, then a new cancellation is created for this thread.
</para>
<para>
All calls to <link linkend="operation-register"><function>operation_register()</function></link> should save their value and call
operation_register again with that, to automatically stack
registrations.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> Returns the previously registered operatoin.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-unregister" role="function">
<title>camel_operation_unregister ()</title>
<indexterm zone="camel-operation-unregister"><primary>camel_operation_unregister</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_unregister          (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Unregister the current thread for all cancellations.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel-block" role="function">
<title>camel_operation_cancel_block ()</title>
<indexterm zone="camel-operation-cancel-block"><primary>camel_operation_cancel_block</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_cancel_block        (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Block cancellation for this operation.  If <parameter>cc</parameter> is NULL, then the
current thread is blocked.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel-unblock" role="function">
<title>camel_operation_cancel_unblock ()</title>
<indexterm zone="camel-operation-cancel-unblock"><primary>camel_operation_cancel_unblock</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_cancel_unblock      (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Unblock cancellation, when the unblock count reaches the block
count, then this operation can be cancelled.  If <parameter>cc</parameter> is NULL, then
the current thread is unblocked.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel-check" role="function">
<title>camel_operation_cancel_check ()</title>
<indexterm zone="camel-operation-cancel-check"><primary>camel_operation_cancel_check</primary></indexterm><programlisting><link linkend="int">int</link>                 camel_operation_cancel_check        (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Check if cancellation has been applied to <parameter>cc</parameter>.  If <parameter>cc</parameter> is NULL,
then the CamelOperation registered for the current thread is used.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> TRUE if the operation has been cancelled.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel-fd" role="function">
<title>camel_operation_cancel_fd ()</title>
<indexterm zone="camel-operation-cancel-fd"><primary>camel_operation_cancel_fd</primary></indexterm><programlisting><link linkend="int">int</link>                 camel_operation_cancel_fd           (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Retrieve a file descriptor that can be waited on (select, or poll)
for read, to asynchronously detect cancellation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The fd, or -1 if cancellation is not available
(blocked, or has not been registered for this thread).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-cancel-prfd" role="function">
<title>camel_operation_cancel_prfd ()</title>
<indexterm zone="camel-operation-cancel-prfd"><primary>camel_operation_cancel_prfd</primary></indexterm><programlisting>struct <link linkend="PRFileDesc">PRFileDesc</link>*  camel_operation_cancel_prfd         (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Retrieve a file descriptor that can be waited on (select, or poll)
for read, to asynchronously detect cancellation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The fd, or NULL if cancellation is not available
(blocked, or has not been registered for this thread).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-registered" role="function">
<title>camel_operation_registered ()</title>
<indexterm zone="camel-operation-registered"><primary>camel_operation_registered</primary></indexterm><programlisting><link linkend="CamelOperation">CamelOperation</link>*     camel_operation_registered          (void);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the registered operation, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none registered.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-start" role="function">
<title>camel_operation_start ()</title>
<indexterm zone="camel-operation-start"><primary>camel_operation_start</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_start               (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="char">char</link> *what,
                                                         ...);</programlisting>
<para>
Report the start of an operation.  All start operations should have
similar end operations.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>what</parameter>&nbsp;:</term>
<listitem><simpara> action being performed (printf-style format string)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> varargs
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-start-transient" role="function">
<title>camel_operation_start_transient ()</title>
<indexterm zone="camel-operation-start-transient"><primary>camel_operation_start_transient</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_start_transient     (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="char">char</link> *what,
                                                         ...);</programlisting>
<para>
Start a transient event.  We only update this to the display if it
takes very long to process, and if we do, we then go back to the
previous state when finished.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>what</parameter>&nbsp;:</term>
<listitem><simpara> printf-style format string describing the action being performed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> varargs
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-progress" role="function">
<title>camel_operation_progress ()</title>
<indexterm zone="camel-operation-progress"><primary>camel_operation_progress</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_progress            (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="int">int</link> pc);</programlisting>
<para>
Report progress on the current operation.  If <parameter>cc</parameter> is NULL, then the
currently registered operation is used.  <parameter>pc</parameter> reports the current
percentage of completion, which should be in the range of 0 to 100.
</para>
<para>
If the total percentage is not know, then use
<link linkend="camel-operation-progress-count"><function>camel_operation_progress_count()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> Operation to report to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pc</parameter>&nbsp;:</term>
<listitem><simpara> Percent complete, 0 to 100.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-progress-count" role="function">
<title>camel_operation_progress_count ()</title>
<indexterm zone="camel-operation-progress-count"><primary>camel_operation_progress_count</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_progress_count      (<link linkend="CamelOperation">CamelOperation</link> *cc,
                                                         <link linkend="int">int</link> sofar);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sofar</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-operation-end" role="function">
<title>camel_operation_end ()</title>
<indexterm zone="camel-operation-end"><primary>camel_operation_end</primary></indexterm><programlisting><link linkend="void">void</link>                camel_operation_end                 (<link linkend="CamelOperation">CamelOperation</link> *cc);</programlisting>
<para>
Report the end of an operation.  If <parameter>cc</parameter> is NULL, then the currently
registered operation is notified.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cc</parameter>&nbsp;:</term>
<listitem><simpara> operation context
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
