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,
                                                         gboolean remove,
                                                         GError **err);

Object Hierarchy


  GInterface
   +----TnySendQueue

Prerequisites

TnySendQueue requires GObject.

Known Implementations

TnySendQueue is implemented by TnyCamelSendQueue and TnyGenericSendQueue.

Signals


  "error-happened"                                 : Run First
  "msg-sending"                                    : Run First
  "msg-sent"                                       : 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;


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);

	/* methods */
	void (*add_func) (TnySendQueue *self, TnyMsg *msg, GError **err);
	TnyFolder* (*get_sentbox_func) (TnySendQueue *self);
	TnyFolder* (*get_outbox_func) (TnySendQueue *self);
	void (*cancel_func) (TnySendQueue *self, gboolean remove, 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);

Add a message to the send queue.

self : A TnySendQueue instance
msg : a TnyMsg instance
err : a GError instance or NULL

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 return value must be unreferenced after use

self : A TnySendQueue instance
Returns : a TnyFolder instance

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 return 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 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 outbox).

self : A TnySendQueue instance
Returns : a TnyFolder instance

tny_send_queue_cancel ()

void                tny_send_queue_cancel               (TnySendQueue *self,
                                                         gboolean remove,
                                                         GError **err);

Cancels the current operation

self : A TnySendQueue instance
remove : Whether or not to also remove queued messages
err : a GError instance or NULL

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 : The header of the message that was supposed to be sent or NULL
arg2 : The message that was supposed to be sent or NULL
arg3 : a GError containing the error that happened
arg4 : 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 proccessed to sending it

@: @: @: @: @:
self : the object on which the signal is emitted
arg1 : The message that is being
arg2 : The current nth number of the message that is being sending
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 : user data
user_data : user data set when the signal handler was connected.

See Also

TnyTransportAccount