Camel.Transport

CamelTransport is the base object of any backends which support sending of mail messages. It is a subclass of Evolution/Camel.Service.

Although implementations are only provided for Camel.InternetAddress it would be possible to implement other addressing schemes.

A CamelTransport only adds a single additional virtual method over CamelService:

 gboolean camel_transport_send_to(CamelTransport *transport,
                                  CamelMimeMessage *message,
                                  CamelAddress *from,
                                  CamelAddress *recipients,
                                  CamelException *ex);

The receipients list needn't match the recipients in the message, this is used to implement Bcc for example. It is just the envelope recipients. Likewise for the from address.

send_to should honour connected state from Evolution/Camel.Service and the online state from Evolution/Camel.Session.

Although it is up to the implementation as to whether message sending fails whilst offline/disconnected, or they are merely queued for later transmission.

The send_to method is also free to alter various parts of the message; headers it doesn't want to send, and content-encodings of various parts to match the transport capabilities. The actual content will not be changed though. Actually if it doesn't want to send headers it should remove them, write the message out, and then add them back in the same order.

Examples

See camel/providers/sendmail or camel/providers/smtp for example implementations.

Example: Sending a message

See Evolution/Camel.DataWrapper#Example: Creating a simple one part message for how to create an example message.

 static char *types[] = { "to", "cc", "bcc" };
 
 void sendMail(CamelMimeMessage *msg, CamelException *ex)
 {
        CamelInternetAddress *from, *addr, *to;
        CamelTransport *trans;
 
        if (camel_mime_message_get_from(msg) == NULL) {
                camel_exception_setv(ex, CAMEL_EXCEPTION_SYSTEM, _("Cannot send message: No from address set");
                return;
        }
 
        trans = (CamelTransport *)camel_session_get_service(session, "smtp://localhost/", ex);
        if (camel_exception_is_set(ex))
                return;
        camel_service_connect(trans, ex);
        if (camel_exception_is_set(ex))
                goto noconnect;
 
        to = camel_internet_address_new();
        for (i=0;i<sizeof(types)/sizeof(types[0]);i++) {
                CamelInternetAddress *addr = camel_mime_message_get_recipients(msg, types[i]);
 
                if (addr)
                        camel_address_cat(to, addr);
        }
 
        camel_transport_send_to(trans, msg, camel_mime_message_get_from(msg), to, ex);
        camel_object_unref(to);
        camel_transport_disconnect(trans, FALSE, NULL);
 noconnect:
        camel_object_unref(trans);
 }

The above just talks to a smtp server setup on the local machine. Note that Camel currently has no support for managing accounts themselves, including any default account or identity. So resolving the service URL has to be done external to Camel.

It sends the message to everyone in the to, cc and bcc headers.

Notes

Why this is called send_to and not send is beyond me.

This should really be an interface which could be attached to CamelService by implementations.

See Evolution/Camel.Service#Notes for some additional comments on the interface idea, and relevent problems with the connection state.

Do I need to write at least some overview of all of the implementations of Camel.Transport, e.g. SMTP and Sendmail? Here or some separate page group?