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

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

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

<synopsis>
struct              <link linkend="CamelService">CamelService</link>;
#define             <link linkend="CAMEL-SERVICE-USERNAME:CAPS">CAMEL_SERVICE_USERNAME</link>
#define             <link linkend="CAMEL-SERVICE-AUTH:CAPS">CAMEL_SERVICE_AUTH</link>
#define             <link linkend="CAMEL-SERVICE-HOSTNAME:CAPS">CAMEL_SERVICE_HOSTNAME</link>
#define             <link linkend="CAMEL-SERVICE-PORT:CAPS">CAMEL_SERVICE_PORT</link>
#define             <link linkend="CAMEL-SERVICE-PATH:CAPS">CAMEL_SERVICE_PATH</link>
enum                <link linkend="CamelServiceConnectionStatus">CamelServiceConnectionStatus</link>;
                    <link linkend="CamelServiceAuthType">CamelServiceAuthType</link>;
<link linkend="void">void</link>                <link linkend="camel-service-construct">camel_service_construct</link>             (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelSession">CamelSession</link> *session,
                                                         <link linkend="CamelProvider">CamelProvider</link> *provider,
                                                         <link linkend="CamelURL">CamelURL</link> *url,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="gboolean">gboolean</link>            <link linkend="camel-service-connect">camel_service_connect</link>               (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="gboolean">gboolean</link>            <link linkend="camel-service-disconnect">camel_service_disconnect</link>            (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="gboolean">gboolean</link> clean,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-service-cancel-connect">camel_service_cancel_connect</link>        (<link linkend="CamelService">CamelService</link> *service);
<link linkend="char">char</link>*               <link linkend="camel-service-get-url">camel_service_get_url</link>               (<link linkend="CamelService">CamelService</link> *service);
<link linkend="char">char</link>*               <link linkend="camel-service-get-name">camel_service_get_name</link>              (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="gboolean">gboolean</link> brief);
<link linkend="char">char</link>*               <link linkend="camel-service-get-path">camel_service_get_path</link>              (<link linkend="CamelService">CamelService</link> *service);
<link linkend="CamelSession">CamelSession</link>*       <link linkend="camel-service-get-session">camel_service_get_session</link>           (<link linkend="CamelService">CamelService</link> *service);
<link linkend="CamelProvider">CamelProvider</link>*      <link linkend="camel-service-get-provider">camel_service_get_provider</link>          (<link linkend="CamelService">CamelService</link> *service);
<link linkend="GList">GList</link>*              <link linkend="camel-service-query-auth-types">camel_service_query_auth_types</link>      (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelException">CamelException</link> *ex);
</synopsis>
</refsynopsisdiv>









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

</para>
</refsect1>

<refsect1 id="camel-CamelService.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CamelService" role="struct">
<title>struct CamelService</title>
<indexterm zone="CamelService"><primary>CamelService</primary></indexterm><programlisting>struct CamelService {
	CamelObject parent_object;
	struct _CamelServicePrivate *priv;

	CamelSession *session;
	CamelProvider *provider;
	CamelServiceConnectionStatus status;
	CamelOperation *connect_op;
	CamelURL *url;
};
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CAMEL-SERVICE-USERNAME:CAPS" role="macro">
<title>CAMEL_SERVICE_USERNAME</title>
<indexterm zone="CAMEL-SERVICE-USERNAME:CAPS"><primary>CAMEL_SERVICE_USERNAME</primary></indexterm><programlisting>#define CAMEL_SERVICE_USERNAME     (CAMEL_SERVICE_ARG_USERNAME | CAMEL_ARG_STR)
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CAMEL-SERVICE-AUTH:CAPS" role="macro">
<title>CAMEL_SERVICE_AUTH</title>
<indexterm zone="CAMEL-SERVICE-AUTH:CAPS"><primary>CAMEL_SERVICE_AUTH</primary></indexterm><programlisting>#define CAMEL_SERVICE_AUTH         (CAMEL_SERVICE_ARG_AUTH | CAMEL_ARG_STR)
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CAMEL-SERVICE-HOSTNAME:CAPS" role="macro">
<title>CAMEL_SERVICE_HOSTNAME</title>
<indexterm zone="CAMEL-SERVICE-HOSTNAME:CAPS"><primary>CAMEL_SERVICE_HOSTNAME</primary></indexterm><programlisting>#define CAMEL_SERVICE_HOSTNAME     (CAMEL_SERVICE_ARG_HOSTNAME | CAMEL_ARG_STR)
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CAMEL-SERVICE-PORT:CAPS" role="macro">
<title>CAMEL_SERVICE_PORT</title>
<indexterm zone="CAMEL-SERVICE-PORT:CAPS"><primary>CAMEL_SERVICE_PORT</primary></indexterm><programlisting>#define CAMEL_SERVICE_PORT         (CAMEL_SERVICE_ARG_PORT | CAMEL_ARG_INT)
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CAMEL-SERVICE-PATH:CAPS" role="macro">
<title>CAMEL_SERVICE_PATH</title>
<indexterm zone="CAMEL-SERVICE-PATH:CAPS"><primary>CAMEL_SERVICE_PATH</primary></indexterm><programlisting>#define CAMEL_SERVICE_PATH         (CAMEL_SERVICE_ARG_PATH | CAMEL_ARG_STR)
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CamelServiceConnectionStatus" role="enum">
<title>enum CamelServiceConnectionStatus</title>
<indexterm zone="CamelServiceConnectionStatus"><primary>CamelServiceConnectionStatus</primary></indexterm><programlisting>typedef enum {
	CAMEL_SERVICE_DISCONNECTED,
	CAMEL_SERVICE_CONNECTING,
	CAMEL_SERVICE_CONNECTED,
	CAMEL_SERVICE_DISCONNECTING
} CamelServiceConnectionStatus;
</programlisting>
<para>

</para></refsect2>
<refsect2 id="CamelServiceAuthType" role="struct">
<title>CamelServiceAuthType</title>
<indexterm zone="CamelServiceAuthType"><primary>CamelServiceAuthType</primary></indexterm><programlisting>typedef struct {
	char *name;               /* user-friendly name */
	char *description;
	char *authproto;
	
	gboolean need_password;   /* needs a password to authenticate */
} CamelServiceAuthType;
</programlisting>
<para>

</para></refsect2>
<refsect2 id="camel-service-construct" role="function">
<title>camel_service_construct ()</title>
<indexterm zone="camel-service-construct"><primary>camel_service_construct</primary></indexterm><programlisting><link linkend="void">void</link>                camel_service_construct             (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelSession">CamelSession</link> *session,
                                                         <link linkend="CamelProvider">CamelProvider</link> *provider,
                                                         <link linkend="CamelURL">CamelURL</link> *url,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Constructs a <link linkend="CamelService"><type>CamelService</type></link> initialized with the given parameters.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="CamelSession"><type>CamelSession</type></link> for <parameter>service</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>provider</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="CamelProvider"><type>CamelProvider</type></link> associated with <parameter>service</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> the default URL for the service (may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-connect" role="function">
<title>camel_service_connect ()</title>
<indexterm zone="camel-service-connect"><primary>camel_service_connect</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            camel_service_connect               (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Connect to the service using the parameters it was initialized
with.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>%TRUE if the connection is made or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-disconnect" role="function">
<title>camel_service_disconnect ()</title>
<indexterm zone="camel-service-disconnect"><primary>camel_service_disconnect</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            camel_service_disconnect            (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="gboolean">gboolean</link> clean,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Disconnect from the service. If <parameter>clean</parameter> is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, it should not
try to do any synchronizing or other cleanup of the connection.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>clean</parameter>&nbsp;:</term>
<listitem><simpara> whether or not to try to disconnect cleanly
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>%TRUE if the disconnect was successful or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-cancel-connect" role="function">
<title>camel_service_cancel_connect ()</title>
<indexterm zone="camel-service-cancel-connect"><primary>camel_service_cancel_connect</primary></indexterm><programlisting><link linkend="void">void</link>                camel_service_cancel_connect        (<link linkend="CamelService">CamelService</link> *service);</programlisting>
<para>
If <parameter>service</parameter> is currently attempting to connect to or disconnect
from a server, this causes it to stop and fail. Otherwise it is a
no-op.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-get-url" role="function">
<title>camel_service_get_url ()</title>
<indexterm zone="camel-service-get-url"><primary>camel_service_get_url</primary></indexterm><programlisting><link linkend="char">char</link>*               camel_service_get_url               (<link linkend="CamelService">CamelService</link> *service);</programlisting>
<para>
Gets the URL representing <parameter>service</parameter>. The returned URL must be
freed when it is no longer needed. For security reasons, this
routine does not return the password.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the URL representing <parameter>service</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-get-name" role="function">
<title>camel_service_get_name ()</title>
<indexterm zone="camel-service-get-name"><primary>camel_service_get_name</primary></indexterm><programlisting><link linkend="char">char</link>*               camel_service_get_name              (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="gboolean">gboolean</link> brief);</programlisting>
<para>
This gets the name of the service in a "friendly" (suitable for
humans) form. If <parameter>brief</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, this should be a brief description
such as for use in the folder tree. If <parameter>brief</parameter> is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, it should
be a more complete and mostly unambiguous description.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>brief</parameter>&nbsp;:</term>
<listitem><simpara> whether or not to use a briefer form
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>a description of the service which the caller must free
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-get-path" role="function">
<title>camel_service_get_path ()</title>
<indexterm zone="camel-service-get-path"><primary>camel_service_get_path</primary></indexterm><programlisting><link linkend="char">char</link>*               camel_service_get_path              (<link linkend="CamelService">CamelService</link> *service);</programlisting>
<para>
This gets a valid UNIX relative path describing <parameter>service</parameter>, which
is guaranteed to be different from the path returned for any
different service. This path MUST start with the name of the
provider, followed by a "/", but after that, it is up to the
provider.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the path, which the caller must free
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-get-session" role="function">
<title>camel_service_get_session ()</title>
<indexterm zone="camel-service-get-session"><primary>camel_service_get_session</primary></indexterm><programlisting><link linkend="CamelSession">CamelSession</link>*       camel_service_get_session           (<link linkend="CamelService">CamelService</link> *service);</programlisting>
<para>
Gets the <link linkend="CamelSession"><type>CamelSession</type></link> associated with the service.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the session
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-get-provider" role="function">
<title>camel_service_get_provider ()</title>
<indexterm zone="camel-service-get-provider"><primary>camel_service_get_provider</primary></indexterm><programlisting><link linkend="CamelProvider">CamelProvider</link>*      camel_service_get_provider          (<link linkend="CamelService">CamelService</link> *service);</programlisting>
<para>
Gets the <link linkend="CamelProvider"><type>CamelProvider</type></link> associated with the service.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the provider
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-service-query-auth-types" role="function">
<title>camel_service_query_auth_types ()</title>
<indexterm zone="camel-service-query-auth-types"><primary>camel_service_query_auth_types</primary></indexterm><programlisting><link linkend="GList">GList</link>*              camel_service_query_auth_types      (<link linkend="CamelService">CamelService</link> *service,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
This is used by the mail source wizard to get the list of
authentication types supported by the protocol, and information
about them.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelService"><type>CamelService</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="CamelException"><type>CamelException</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>a list of <link linkend="CamelServiceAuthType"><type>CamelServiceAuthType</type></link> records. The caller
must free the list with <link linkend="g-list-free"><type>g_list_free</type></link> when it is done with it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
