TnySendQueue

TnySendQueue — A type for sending mail

Synopsis




                    TnySendQueue;
                    TnySendQueueIface;
#define             TNY_TYPE_SEND_QUEUE_SIGNAL
void                tny_send_queue_add                  (TnySendQueue *self,
                                                         TnyMsg *msg,
                                                         GError **err);
TnyFolder*          tny_send_queue_get_sentbox          (TnySendQueue *self);
TnyFolder*          tny_send_queue_get_outbox           (TnySendQueue *self);
void                tny_send_queue_cancel               (TnySendQueue *self,
                                                         TnySendQueueCancelAction cancel_action,
                                                         GError **err);

Object Hierarchy


  GInterface
   +----TnySendQueue

Prerequisites

TnySendQueue requires GObject.

Known Implementations

TnySendQueue is implemented by TnyCamelSendQueue.

Signals


  "error-happened"                                 : Run First
  "msg-sending"                                    : Run First
  "msg-sent"                                       : Run First
  "queue-start"                                    : Run First
  "queue-stop"                                     : Run First

Description

A type for sending mail. Typically using a TnyTransportAccount. The send queue will asynchonously handle sending the queued E-mails. It will signal when a message got sent. While the queue is busy, it permits adding new messages to it.

The TnySendQueue implementation does not necessarily have to classify between multiple TnyTransportAccount nor is it specified that it should not do this. The contract for the type is that it WILL send the message.

It's recommended to make implementations that persist to-send messages on a persistent storage like a filesystem. For example in a so called Outbox folder. Else would your user upon application or device shutdown obviously lose the unsent messages.

Details

TnySendQueue

typedef struct _TnySendQueue TnySendQueue;

A queue for sending messages

free-function: g_object_unref


TnySendQueueIface

typedef struct {
	GTypeInterface parent;
	
	/* Signals */
	void (*msg_sending) (TnySendQueue *self, TnyHeader *header, TnyMsg *msg, guint nth, guint total);
	void (*msg_sent) (TnySendQueue *self, TnyHeader *header, TnyMsg *msg, guint nth, guint total);
	void (*error_happened) (TnySendQueue *self, TnyHeader *header, TnyMsg *msg, GError *err, gpointer user_data);
	void (*queue_start) (TnySendQueue *self, gpointer user_data);
	void (*queue_stop) (TnySendQueue *self, gpointer user_data);

	/* methods */
	void (*add) (TnySendQueue *self, TnyMsg *msg, GError **err);
	void (*add_async) (TnySendQueue *self, TnyMsg *msg, TnySendQueueAddCallback callback, TnyStatusCallback status_callback, gpointer user_data);
	TnyFolder* (*get_sentbox) (TnySendQueue *self);
	TnyFolder* (*get_outbox) (TnySendQueue *self);
	void (*cancel) (TnySendQueue *self, TnySendQueueCancelAction cancel_action, GError **err);
} TnySendQueueIface;


TNY_TYPE_SEND_QUEUE_SIGNAL

#define TNY_TYPE_SEND_QUEUE_SIGNAL (tny_send_queue_signal_get_type ())


tny_send_queue_add ()

void                tny_send_queue_add                  (TnySendQueue *self,
                                                         TnyMsg *msg,
                                                         GError **err);

Warning

tny_send_queue_add has been deprecated since version 1.0 and should not be used in newly-written code. Use tny_send_queue_add_async in stead

Add a message to the send queue, usually adding it to the outbox too.

self : A TnySendQueue
msg : a TnyMsg
err : (null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_send_queue_get_sentbox ()

TnyFolder*          tny_send_queue_get_sentbox          (TnySendQueue *self);

Get the folder which contains the messages that have been sent. The returned value must be unreferenced after use

self : A TnySendQueue
Returns : (caller-owns): a TnyFolder instance

Since 1.0 audience: application-developer


tny_send_queue_get_outbox ()

TnyFolder*          tny_send_queue_get_outbox           (TnySendQueue *self);

Get the folder which contains the messages that have not yet been sent. The returned value must be unreferenced after use. It's not guaranteed that when changing the content of outbox, self will automatically adjust itself to the new situation. Although some implementations of TnySendQueue might indeed do this, it's advisable to use tny_send_queue_add() in stead of tny_folder_add_msg() on the outbox. The reason for that is lack of specification and a TnySendQueue implementation not having to implement TnyFolderObserver too (which makes it possible to act on changes happening to the outbox).

self : A TnySendQueue instance
Returns : (caller-owns): a TnyFolder instance

Since 1.0 audience: application-developer


tny_send_queue_cancel ()

void                tny_send_queue_cancel               (TnySendQueue *self,
                                                         TnySendQueueCancelAction cancel_action,
                                                         GError **err);

Cancels the current operation

self : a TnySendQueue
cancel_action : a TnySendQueueCancelAction, it could remove messages or just mark them as suspended
err : (null-ok): a GError or NULL

Since 1.0 audience: application-developer

Signal Details

The "error-happened" signal

void                user_function                      (TnySendQueue *self,
                                                        TnyHeader    *arg1,
                                                        TnyMsg       *arg2,
                                                        gpointer      arg3,
                                                        gpointer      user_data)      : Run First

Emitted when a message didn't get sent because of an error

self : the object on which the signal is emitted
arg1 : (null-ok): The header of the message that was supposed to be sent or NULL
arg2 : (null-ok): The message that was supposed to be sent or NULL
arg3 : a GError containing the error that happened
arg4 : (null-ok): user data
user_data : user data set when the signal handler was connected.

The "msg-sending" signal

void                user_function                      (TnySendQueue *self,
                                                        TnyHeader    *arg1,
                                                        TnyMsg       *arg2,
                                                        guint         arg3,
                                                        guint         arg4,
                                                        gpointer      user_data)      : Run First

API WARNING: This API might change

Emitted when a message is being sent.

self : the object on which the signal is emitted
arg1 : The message that is being sent
arg2 : The current nth number of the message that is being sent
arg3 : The total amount of messages currently being processed
user_data : user data set when the signal handler was connected.

The "msg-sent" signal

void                user_function                      (TnySendQueue *self,
                                                        TnyHeader    *arg1,
                                                        TnyMsg       *arg4,
                                                        guint         arg3,
                                                        guint         arg4,
                                                        gpointer      user_data)      : Run First

Emitted when a message got sent

self : the object on which the signal is emitted
arg1 : The message that got sent
arg4 : (null-ok): user data
user_data : user data set when the signal handler was connected.

The "queue-start" signal

void                user_function                      (TnySendQueue *self,
                                                        gpointer      user_data)      : Run First

Emitted when the queue starts to process messages

@:
self : a TnySendQueue, the object on which the signal is emitted
user_data : user data set when the signal handler was connected.

The "queue-stop" signal

void                user_function                      (TnySendQueue *self,
                                                        gpointer      user_data)      : Run First

Emitted when the queue stops to process messages

@:
self : a TnySendQueue, the object on which the signal is emitted
user_data : user data set when the signal handler was connected.

See Also

TnyTransportAccount