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

<refnamediv>
<refname>camel-exception</refname>
<refpurpose></refpurpose>
</refnamediv>

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

<synopsis>
enum                <link linkend="ExceptionId">ExceptionId</link>;
struct              <link linkend="CamelException">CamelException</link>;
#define             <link linkend="CAMEL-EXCEPTION-INITIALISER--CAPS">CAMEL_EXCEPTION_INITIALISER</link>
<link linkend="CamelException">CamelException</link> *    <link linkend="camel-exception-new">camel_exception_new</link>                 (void);
<link linkend="void">void</link>                <link linkend="camel-exception-free">camel_exception_free</link>                (<link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-exception-init">camel_exception_init</link>                (<link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-exception-clear">camel_exception_clear</link>               (<link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-exception-set">camel_exception_set</link>                 (<link linkend="CamelException">CamelException</link> *ex,
                                                         <link linkend="ExceptionId">ExceptionId</link> id,
                                                         const <link linkend="char">char</link> *desc);
<link linkend="void">void</link>                <link linkend="camel-exception-setv">camel_exception_setv</link>                (<link linkend="CamelException">CamelException</link> *ex,
                                                         <link linkend="ExceptionId">ExceptionId</link> id,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);
<link linkend="void">void</link>                <link linkend="camel-exception-xfer">camel_exception_xfer</link>                (<link linkend="CamelException">CamelException</link> *ex_dst,
                                                         <link linkend="CamelException">CamelException</link> *ex_src);
<link linkend="ExceptionId">ExceptionId</link>         <link linkend="camel-exception-get-id">camel_exception_get_id</link>              (<link linkend="CamelException">CamelException</link> *ex);
const <link linkend="char">char</link> *        <link linkend="camel-exception-get-description">camel_exception_get_description</link>     (<link linkend="CamelException">CamelException</link> *ex);
#define             <link linkend="camel-exception-is-set">camel_exception_is_set</link>              (ex)
</synopsis>
</refsynopsisdiv>









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

<refsect1 id="camel-camel-exception.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="ExceptionId" role="enum">
<title>enum ExceptionId</title>
<indexterm zone="ExceptionId"><primary sortas="ExceptionId">ExceptionId</primary></indexterm><programlisting>typedef enum {
#include "camel-exception-list.def"

} ExceptionId;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="CamelException" role="struct">
<title>struct CamelException</title>
<indexterm zone="CamelException"><primary sortas="CamelException">CamelException</primary></indexterm><programlisting>struct CamelException {
	/* do not access the fields directly */
	ExceptionId id;
	char *desc;
};
</programlisting>
<para>
</para></refsect2>
<refsect2 id="CAMEL-EXCEPTION-INITIALISER--CAPS" role="macro">
<title>CAMEL_EXCEPTION_INITIALISER</title>
<indexterm zone="CAMEL-EXCEPTION-INITIALISER--CAPS"><primary sortas="CAMEL_EXCEPTION_INITIALISER">CAMEL_EXCEPTION_INITIALISER</primary></indexterm><programlisting>#define CAMEL_EXCEPTION_INITIALISER { 0, NULL }
</programlisting>
<para>
</para></refsect2>
<refsect2 id="camel-exception-new" role="function">
<title>camel_exception_new ()</title>
<indexterm zone="camel-exception-new"><primary sortas="camel_exception_new">camel_exception_new</primary></indexterm><programlisting><link linkend="CamelException">CamelException</link> *    camel_exception_new                 (void);</programlisting>
<para>
Create and returns a new exception object.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated exception object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-free" role="function">
<title>camel_exception_free ()</title>
<indexterm zone="camel-exception-free"><primary sortas="camel_exception_free">camel_exception_free</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_free                (<link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Free an exception object. If the exception is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, nothing is
done, the routine simply returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-init" role="function">
<title>camel_exception_init ()</title>
<indexterm zone="camel-exception-init"><primary sortas="camel_exception_init">camel_exception_init</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_init                (<link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Init an exception. This routine is mainly useful when using a
statically allocated exception.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-clear" role="function">
<title>camel_exception_clear ()</title>
<indexterm zone="camel-exception-clear"><primary sortas="camel_exception_clear">camel_exception_clear</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_clear               (<link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Clear an exception, that is, set the exception ID to
<link linkend="CAMEL-EXCEPTION-NONE--CAPS"><type>CAMEL_EXCEPTION_NONE</type></link> and free the description text.  If the
exception is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, this funtion just returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-set" role="function">
<title>camel_exception_set ()</title>
<indexterm zone="camel-exception-set"><primary sortas="camel_exception_set">camel_exception_set</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_set                 (<link linkend="CamelException">CamelException</link> *ex,
                                                         <link linkend="ExceptionId">ExceptionId</link> id,
                                                         const <link linkend="char">char</link> *desc);</programlisting>
<para>
Set the value of an exception. The exception id is 
a unique number representing the exception. The 
textual description is a small text explaining 
what happened and provoked the exception.
</para>
<para>
When <parameter>ex</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, nothing is done, this routine
simply returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>id</parameter>&#160;:</term>
<listitem><simpara> exception id 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>desc</parameter>&#160;:</term>
<listitem><simpara> textual description of the exception
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-setv" role="function">
<title>camel_exception_setv ()</title>
<indexterm zone="camel-exception-setv"><primary sortas="camel_exception_setv">camel_exception_setv</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_setv                (<link linkend="CamelException">CamelException</link> *ex,
                                                         <link linkend="ExceptionId">ExceptionId</link> id,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);</programlisting>
<para>
Set the value of an exception. The exception id is 
a unique number representing the exception. The 
textual description is a small text explaining 
what happened and provoked the exception. 
In this version, the string is created from the format 
string and the variable argument list.
</para>
<para>
It is safe to say:
  camel_exception_setv (ex, ..., camel_exception_get_description (ex), ...);
</para>
<para>
When <parameter>ex</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, nothing is done, this routine
simply returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>id</parameter>&#160;:</term>
<listitem><simpara> exception id 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara> format of the description string. The format string is
used as in <link linkend="printf"><function>printf()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-xfer" role="function">
<title>camel_exception_xfer ()</title>
<indexterm zone="camel-exception-xfer"><primary sortas="camel_exception_xfer">camel_exception_xfer</primary></indexterm><programlisting><link linkend="void">void</link>                camel_exception_xfer                (<link linkend="CamelException">CamelException</link> *ex_dst,
                                                         <link linkend="CamelException">CamelException</link> *ex_src);</programlisting>
<para>
Transfer the content of an exception from an exception object to
another.  The destination exception receives the id and the
description text of the source exception.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex_dst</parameter>&#160;:</term>
<listitem><simpara> Destination exception object 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex_src</parameter>&#160;:</term>
<listitem><simpara> Source exception object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-get-id" role="function">
<title>camel_exception_get_id ()</title>
<indexterm zone="camel-exception-get-id"><primary sortas="camel_exception_get_id">camel_exception_get_id</primary></indexterm><programlisting><link linkend="ExceptionId">ExceptionId</link>         camel_exception_get_id              (<link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Get the id of an exception.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the exception id (<link linkend="CAMEL-EXCEPTION-NONE--CAPS"><type>CAMEL_EXCEPTION_NONE</type></link> will be returned if
<parameter>ex</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or unset)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-get-description" role="function">
<title>camel_exception_get_description ()</title>
<indexterm zone="camel-exception-get-description"><primary sortas="camel_exception_get_description">camel_exception_get_description</primary></indexterm><programlisting>const <link linkend="char">char</link> *        camel_exception_get_description     (<link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Get the exception description text.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the exception description text (<link linkend="NULL--CAPS"><literal>NULL</literal></link> will be returned if
<parameter>ex</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or unset)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-exception-is-set" role="macro">
<title>camel_exception_is_set()</title>
<indexterm zone="camel-exception-is-set"><primary sortas="camel_exception_is_set">camel_exception_is_set</primary></indexterm><programlisting>#define camel_exception_is_set(ex) (camel_exception_get_id (ex) != CAMEL_EXCEPTION_NONE)
</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ex</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
