a unique identifier string
the service protocol
the service type
Look up in an address book book_uid for an address email_address
and returns whether any such contact exists.
The book_uid can be either one of the special constants
%CAMEL_SESSION_BOOK_UID_ANY or %CAMEL_SESSION_BOOK_UID_COMPLETION,
or it can be a UID of a configured address book.
The email_address can contain multiple addresses, then the function
checks whether any of the given addresses is in the address book.
an address book UID
an email address to check for
optional #GCancellable object, or %NULL
Asynchronously authenticates service, which may involve repeated calls
to camel_service_authenticate() or camel_service_authenticate_sync().
A #CamelSession subclass is largely responsible for implementing this,
and should handle things like user prompts and secure password storage.
These issues are out-of-scope for Camel.
When the operation is finished, callback will be called. You can
then call camel_session_authenticate_finish() to get the result of
the operation.
a #CamelService
a SASL mechanism name, or %NULL
the I/O priority for the request
optional #GCancellable object, or %NULL
a #GAsyncReadyCallback to call when the request is satisfied
Finishes the operation started with camel_session_authenticate().
If an error occurred, or if authentication was aborted, the function
sets error and returns %FALSE.
a #GAsyncResult
Authenticates service, which may involve repeated calls to
camel_service_authenticate() or camel_service_authenticate_sync().
A #CamelSession subclass is largely responsible for implementing this,
and should handle things like user prompts and secure password storage.
These issues are out-of-scope for Camel.
If an error occurs, or if authentication is aborted, the function sets
error and returns %FALSE.
a #CamelService
a SASL mechanism name, or %NULL
optional #GCancellable object, or %NULL
Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.
If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
#GBinding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A #GObject can have multiple bindings.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default
a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default
This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
This function is used by a #CamelService to tell the application that the authentication information it provided via camel_session_get_password() was rejected by the service. If the application was caching this information, it should stop, and if the service asks for it again, it should ask the user.
service and item identify the rejected authentication information,
as with camel_session_get_password().
the #CamelService rejecting the password
an identifier, unique within this service, for the information
Asynchronously forwards message in folder to the email address(s)
given by address.
When the operation is finished, callback will be called. You can
then call camel_session_forward_to_finish() to get the result of the
operation.
the #CamelFolder where message is located
the #CamelMimeMessage to forward
the recipient's email address
the I/O priority for the request
optional #GCancellable object, or %NULL
a #GAsyncReadyCallback to call when the request is satisfied
Finishes the operation started with camel_session_forward_to().
If an error occurred, the function sets error and returns %FALSE.
a #GAsyncResult
Forwards message in folder to the email address(es) given by address.
If an error occurs, the function sets error and returns %FALSE.
the #CamelFolder where message is located
the #CamelMimeMessage to forward
the recipient's email address
optional #GCancellable object, or %NULL
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
#GObject::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
The optional for_folder can be used to determine which filters
to add and which not.
the type of filter (eg, "incoming")
an optional #CamelFolder, for which the filter driver will run, or %NULL
Returns the #CamelJunkFilter instance used to classify messages as junk or not junk during filtering.
Note that #CamelJunkFilter itself is just an interface. The application must implement the interface and install a #CamelJunkFilter instance for junk filtering to take place.
Obtains the OAuth 2.0 access token for service along with its expiry
in seconds from the current time (or 0 if unknown).
Free the returned access token with g_free() when no longer needed.
a #CamelService
optional #GCancellable object, or %NULL
This function is used by a #CamelService to ask the application and the user for a password or other authentication data.
service and item together uniquely identify the piece of data the
caller is concerned with.
prompt is a question to ask the user (if the application doesn't
already have the answer cached). If %CAMEL_SESSION_PASSWORD_SECRET
is set, the user's input will not be echoed back.
If %CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned will be stored statically by the caller automatically, for the current session.
The authenticator should set error to %G_IO_ERROR_CANCELLED if
the user did not provide the information. The caller must g_free()
the information returned when it is done with it.
the #CamelService this query is being made by
prompt to provide to user
an identifier, unique within this service, for the information
%CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt %CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret %CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().
Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.
the name of the property to get
return location for the property value
This function gets back user data pointers stored via g_object_set_qdata().
A #GQuark, naming the user data pointer
Searches for S/MIME certificates or PGP keys for the given recipients,
which are returned as base64 encoded strings in out_certificates.
This is used when encrypting messages. The flags influence what
the out_certificates will contain. The order of items in out_certificates
should match the order of items in recipients, with %NULL data for those
which could not be found.
The function should return failure only if some fatal error happened. It's not an error when certificates for some, or all, recipients could not be found.
This method is optional and the default implementation returns %TRUE
and sets the out_certificates to %NULL. It's the only exception
when the length of recipients and out_certificates can differ.
In all other cases the length of the two should match.
The out_certificates will be freed with g_slist_free_full (certificates, g_free);
when done with it.
bit-or of #CamelRecipientCertificateFlags
a #GPtrArray of recipients
optional #GCancellable object, or %NULL
Returns the base directory under which to store user-specific mail cache.
Returns the base directory under which to store user-specific mail data.
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Adds a function to be called whenever there are no higher priority events
pending. If function returns %FALSE it is automatically removed from the
list of event sources and will not be called again.
This internally creates a main loop source using g_idle_source_new()
and attaches it to session's own #CamelSession:main-context using
g_source_attach().
The priority is typically in the range between %G_PRIORITY_DEFAULT_IDLE
and %G_PRIORITY_HIGH_IDLE.
the priority of the idle source
a function to call
Checks whether object has a [floating][floating-ref] reference.
Returns a list of all #CamelService objects previously added using camel_session_add_service().
The services returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().
An easy way to free the list property in one step is as follows:
|[ g_list_free_full (list, g_object_unref);
Looks up for the name in address books.
a name/address to lookup for
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than g_object_notify().
One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:
enum
{
PROP_0,
PROP_FOO,
PROP_LAST
};
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
0, 100,
50,
G_PARAM_READWRITE);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the #GParamSpec of a property installed on the class of object.
Returns the #GMainContext on which event sources for session are to
be attached.
References a #GNetworkMonitor instance, which had been previously set by camel_session_set_network_monitor(). If none is set, then the default #GNetworkMonitor is returned, as provided by g_network_monitor_get_default(). The returned pointer is referenced for thread safety, unref it with g_object_unref() when no longer needed.
Looks up a #CamelService by its unique identifier string. The service must have been previously added using camel_session_add_service().
The returned #CamelService is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.
a unique identifier string
Looks up a #CamelService by trying to match its #CamelURL against the
given url and then checking that the object is of the desired type.
The service must have been previously added using
camel_session_add_service().
The returned #CamelService is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.
Note this function is significantly slower than camel_session_ref_service().
a #CamelURL
a #CamelProviderType
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
Removes all #CamelService instances added by camel_session_add_service().
This can be useful during application shutdown to ensure all #CamelService instances are freed properly, especially since #CamelSession instances are prone to reference cycles.
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a #GQuark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the #GQuark storage growing unbounded.
name of the key
data to associate with that key
Installs the #CamelJunkFilter instance used to classify messages as junk or not junk during filtering.
Note that #CamelJunkFilter itself is just an interface. The application must implement the interface and install a #CamelJunkFilter instance for junk filtering to take place.
a #CamelJunkFilter, or %NULL
Sets a network monitor instance for the session. This can be used
to override which #GNetworkMonitor should be used to check network
availability and whether a server is reachable.
a #GNetworkMonitor or %NULL
Sets the online status of session to online.
whether or not the session should be online
Sets a property on an object.
the name of the property to set
the value
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().
A #GQuark, naming the user data pointer
This function provides a simple mechanism for providers to initiate low-priority background jobs. Jobs can be submitted from any thread, but execution of the jobs is always as follows:
The #CamelSession:job-started signal is emitted from the thread
in which session was created. This is typically the same thread
that hosts the global default #GMainContext, or "main" thread.
The callback function is invoked from a different thread where
it's safe to call synchronous functions.
Once callback has returned, the #CamelSesson:job-finished signal
is emitted from the same thread as #CamelSession:job-started was
emitted.
Finally if a notify function was provided, it is invoked and
passed user_data so that user_data can be freed.
human readable description of the job, shown to a user
a #CamelSessionCallback
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Prompts the user whether to accept certificate for service. The
set of flags given in errors indicate why the certificate failed
validation.
If an error occurs during prompting or if the user declines to respond, the function returns #CAMEL_CERT_TRUST_UNKNOWN and the certificate will be rejected.
a #CamelService
the peer's #GTlsCertificate
the problems with certificate
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.
Emits a #CamelSession:user_alert signal from an idle source on the main loop. The idle source's priority is #G_PRIORITY_LOW.
The purpose of the signal is to propagate a server-issued alert message
from service to a user interface. The type hints at the nature of the
alert message.
a #CamelService
a #CamelSessionAlertType
the message for the user
Instantiates a new #CamelService for session. The uid identifies the
service for future lookup. The protocol indicates which #CamelProvider
holds the #GType of the #CamelService subclass to instantiate. The type
explicitly designates the service as a #CamelStore or #CamelTransport.
If the given uid has already been added, the existing #CamelService
with that uid is returned regardless of whether it agrees with the
given protocol and type.
If no #CamelProvider is available to handle the given protocol, or
if the #CamelProvider does not specify a valid #GType for type, the
function sets error and returns %NULL.
The returned #CamelService is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.
a unique identifier string
the service protocol
the service type
Look up in an address book book_uid for an address email_address
and returns whether any such contact exists.
The book_uid can be either one of the special constants
%CAMEL_SESSION_BOOK_UID_ANY or %CAMEL_SESSION_BOOK_UID_COMPLETION,
or it can be a UID of a configured address book.
The email_address can contain multiple addresses, then the function
checks whether any of the given addresses is in the address book.
an address book UID
an email address to check for
optional #GCancellable object, or %NULL
Authenticates service, which may involve repeated calls to
camel_service_authenticate() or camel_service_authenticate_sync().
A #CamelSession subclass is largely responsible for implementing this,
and should handle things like user prompts and secure password storage.
These issues are out-of-scope for Camel.
If an error occurs, or if authentication is aborted, the function sets
error and returns %FALSE.
a #CamelService
a SASL mechanism name, or %NULL
optional #GCancellable object, or %NULL
This function is used by a #CamelService to tell the application that the authentication information it provided via camel_session_get_password() was rejected by the service. If the application was caching this information, it should stop, and if the service asks for it again, it should ask the user.
service and item identify the rejected authentication information,
as with camel_session_get_password().
the #CamelService rejecting the password
an identifier, unique within this service, for the information
Forwards message in folder to the email address(es) given by address.
If an error occurs, the function sets error and returns %FALSE.
the #CamelFolder where message is located
the #CamelMimeMessage to forward
the recipient's email address
optional #GCancellable object, or %NULL
The optional for_folder can be used to determine which filters
to add and which not.
the type of filter (eg, "incoming")
an optional #CamelFolder, for which the filter driver will run, or %NULL
Obtains the OAuth 2.0 access token for service along with its expiry
in seconds from the current time (or 0 if unknown).
Free the returned access token with g_free() when no longer needed.
a #CamelService
optional #GCancellable object, or %NULL
This function is used by a #CamelService to ask the application and the user for a password or other authentication data.
service and item together uniquely identify the piece of data the
caller is concerned with.
prompt is a question to ask the user (if the application doesn't
already have the answer cached). If %CAMEL_SESSION_PASSWORD_SECRET
is set, the user's input will not be echoed back.
If %CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned will be stored statically by the caller automatically, for the current session.
The authenticator should set error to %G_IO_ERROR_CANCELLED if
the user did not provide the information. The caller must g_free()
the information returned when it is done with it.
the #CamelService this query is being made by
prompt to provide to user
an identifier, unique within this service, for the information
%CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt %CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret %CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally
Searches for S/MIME certificates or PGP keys for the given recipients,
which are returned as base64 encoded strings in out_certificates.
This is used when encrypting messages. The flags influence what
the out_certificates will contain. The order of items in out_certificates
should match the order of items in recipients, with %NULL data for those
which could not be found.
The function should return failure only if some fatal error happened. It's not an error when certificates for some, or all, recipients could not be found.
This method is optional and the default implementation returns %TRUE
and sets the out_certificates to %NULL. It's the only exception
when the length of recipients and out_certificates can differ.
In all other cases the length of the two should match.
The out_certificates will be freed with g_slist_free_full (certificates, g_free);
when done with it.
bit-or of #CamelRecipientCertificateFlags
a #GPtrArray of recipients
optional #GCancellable object, or %NULL
Looks up for the name in address books.
a name/address to lookup for
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
Prompts the user whether to accept certificate for service. The
set of flags given in errors indicate why the certificate failed
validation.
If an error occurs during prompting or if the user declines to respond, the function returns #CAMEL_CERT_TRUST_UNKNOWN and the certificate will be rejected.
a #CamelService
the peer's #GTlsCertificate
the problems with certificate
Emits a #CamelSession:user_alert signal from an idle source on the main loop. The idle source's priority is #G_PRIORITY_LOW.
The purpose of the signal is to propagate a server-issued alert message
from service to a user interface. The type hints at the nature of the
alert message.
a #CamelService
a #CamelSessionAlertType
the message for the user
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
#GClosure to watch
Find the #GParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
#GTypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the #GParamSpec for the new property
Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Creates a new instance of a #GObject subtype and sets its properties.
Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
the type id of the #GObject subtype to instantiate
an array of #GParameter
Instantiates a new #CamelService for
session. Theuididentifies the service for future lookup. Theprotocolindicates which #CamelProvider holds the #GType of the #CamelService subclass to instantiate. Thetypeexplicitly designates the service as a #CamelStore or #CamelTransport.If the given
uidhas already been added, the existing #CamelService with thatuidis returned regardless of whether it agrees with the givenprotocolandtype.If no #CamelProvider is available to handle the given
protocol,or if the #CamelProvider does not specify a valid #GType fortype,the function setserrorand returns %NULL.The returned #CamelService is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.