Bigloo

Bigloo provides various facilities for handling mails. It provides facilities for parsing many formats commonly used in composing mails (quoted printable, vcard, mime types). It also provides facilities for dealing with mail servers. For that it proposes an abstracted view of mail servers with two implementations: imap and maildir.

20.1 RFC 2045 -- MIME, Part one

This section described the functions offered by Bigloo to encode and decode some of the formats specified in the RFC 2045 http://tools.ietf.org/html/rfc2045.

quoted-printable-encode string

Bigloo Mail procedure

quoted-printable-decode string

Bigloo Mail procedure

These functions encode/decode a string into and from the quoted-printable format.

Examples:

(quoted-printable-encode "foo bar") => "foobar=20"
(quoted-printable-decode "foobar=20") => "foo bar"

quoted-printable-encode-port ip op

Bigloo Mail procedure

quoted-printable-decode-port ip op [rfc2047]

Bigloo Mail procedure

These functions are similar to quoted-printable-encode and quoted-printable-decode except that they operate on input-ports and output-ports.

The function quoted-printable-decode-port accepts an optional argument: rfc2047. If this argument is #t, then the parsing stops on the prefix ?=, which is a marker in the mail subject as specified by the RFC 2047, (see http://tools.ietf.org/html/rfc2047) is found.

mime-content-decode string

Bigloo Mail procedure

mime-content-decode-port input-port

Bigloo Mail procedure

These two functions parse respectively a string and an input-port and return a list of three elements:

a content type,
a content subtype,
options.

Example:

(mime-content-type-decode "text/plain; boundary=Apple-Mail-11") 
  => (text plain ((boundary . Apple-Mail-11)))

mime-content-disposition-decode string

Bigloo Mail procedure

mime-content-disposition-decode-port input-port

Bigloo Mail procedure

These two functions parse respectively a string and an input-port and return a list describing the content disposition.

Example:

(mime-content-disposition-decode "attachment; filename=\"smine.p7s\"")
  => (attachment ((filename . smine.p7s)))

mime-multipart-decode string boundary [recursive]

Bigloo Mail procedure

mime-multipart-decode-port input-port boundary [recursive]

Bigloo Mail procedure

These two functions parse respectively a string and an input-port and return a list of mime sections.

If the optional argument recursive controls whether subparts of a multipart section must be decoded are not. If the recursive is #t then all subparts of the multipart content are decoded. The result is a fully decoded multipart section. If recursive is #f subparts are not decoded and included in the result as plain strings.

20.2 RFC 2047 -- MIME, Part three

This section described the function offered by Bigloo to decode the RFC 2047 encoding used in mail headers (see http://tools.ietf.org/html/rfc2047).

rfc2047-decode-port ip op [:charset iso-latin-1]

Bigloo Mail procedure

rfc2047-decode string [:charset iso-latin-1]

Bigloo Mail procedure

These functions decode mail header fields encoded using the RFC 2047 specification. The optional argument charset specified in which charset the result should be encoded. The allowed values are:

utf-8
iso-latin-1
cp-1252

Example:

(map char->integer
  (string->list (rfc2047-decode "Poste =?ISO-8859-1?Q?t=E9l=E9phonique?=")))
  => (80 111 115 116 101 32 116 233 108 233 112 104 111 110 105 113 117 101)
(string-for-read (rfc2047-decode "Poste =?ISO-8859-1?Q?t=E9l=E9phonique?=" :charset 'utf8))
  => "Poste t\303\251l\303\251phonique"

20.3 RFC 2426 -- MIME, Part three

This section presents the facilities supported by Bigloo for dealing with vcards.

vcard

Bigloo Mail class

(class vcard
  (version::bstring (default "2.1"))
  (fn (default #f))
  (familyname (default #f))
  (firstname (default #f))
  (face (default #f))
  (url (default #f))
  (org (default #f))
  (emails::pair-nil (default '()))
  (phones::pair-nil (default '()))
  (addresses::pair-nil (default '())))

The class vard is used to reify in memory a vcard as parsed by the function port->vcard and string->vcard.

Except emails, phones, and addresses, all fields are optional. They should be either #f or a string.

face is a flat list of strings.
phones is an alist whose elements are pairs of two strings.
addresses is a list composed of:
- the postoffice, a string,
- a list of strings denoting the street address,
- a string denoting the city,
- a string denoting the region,
- a string denoting the zip code,
- a string denoting the zip country.
All street values are required and must be provided. The empty string should be used to denote empty values.

port->vcard::vcard ip [:charset-encoder]

Bigloo Mail function

string->vcard::vcard str [:charset-encoder]

Bigloo Mail function

These two functions parse a vcard to produce a vcard instance. The optional argument charset-encoder, when provided, must be a function of argument: a string to be decoded. Vcard strings are UTF-8 encoded. The charset-encoder can be used to encode on-the-fly the strings found in the vcard in a difference encoding.

20.4 RFC 2822 -- Internet Message Format

This section described the functions offered by Bigloo to encode and decode some of the formats specified in the RFC 2822 (http://tools.ietf.org/html/rfc2045). It mainly supports functions for parsing email headers and for decoding email addresses.

mail-header->list obj

Bigloo Mail procedure

The function mail-header->list parses a mail header that can either be implemented as a string or an input port. It returns a list of fields.

Example:

(mail-header->list "Return-Path: <foo.bar@inria.fr>
Received: from eurus.inria.fr ([unix socket])")
  =>
  ((return-path . "<foo.bar@inria.fr>") (received . "from eurus.inria.fr ([unix socket])"))

email-normalize string

Bigloo Mail procedure

The function email-normalize extracts the actual email address from an email representation.

Example:

(email-normalize "foo bar <foo.bar@inria.fr>") => "foo.bar@inria.fr"

rfc2822-address-display-name string

Bigloo Mail procedure

Extract the name component of an email.

Example:

(rfc2822-address-display-name "Foo Bar <foo.bar@inria.fr>") => "Foo Bar"
(rfc2822-address-display-name "<foo.bar@inria.fr>") => "foo bar"

20.5 Mail servers -- imap and maildir

Bigloo implements the imap protocol (http://tools.ietf.org/html/rfc3501) and the maildir format. This section presents the API for manipulating them both.

20.5.1 Mailboxes

mailbox

Bigloo Mail class

(abstract-class mailbox
  (label::bstring (default "")))

The abstract class mailbox is the common ancestors to all the mailbox implementations. It allows the definitions of various generic functions that deal with mail messages and mail folders.

&mailbox-error

Bigloo Mail class

(abstract-class &mailbox-error::&error)

The &mailbox-error is the super class of all the errors that can be raised when accessing mail servers, except the parsing errors that inherit from the &parse-error super class.

mailbox-close mailbox

Bigloo Mail procedure

Close the mailbox connection.

Example:

(let ((mbox (if (network-up?)
                (instantiate::imap (socket ...))
                (instantiate::maildir (path my-local-cache)))))
   (mailbox-close mbox))

mailbox-separator mailbox

Bigloo Mail procedure

Returns a string denoting the separator (commonly " or .) used by the mailbox.

mailbox-prefix mailbox

Bigloo Mail procedure

Returns the prefix of the mailbox, a string or #f.

mailbox-hostname mailbox

Bigloo Mail procedure

Returns the hostname of the mailbox, a string or #f.

mailbox-folders mailbox

Bigloo Mail procedure

Returns a list of strings denoting the folder names of the mailbox.

mailbox-folder-select! mailbox string

Bigloo Mail procedure

Selects one folder of the mailbox. This function is central to mailboxes because all messages are referenced relatively to the folder selection. All the functions that operates on uid implicitly access the current folder selection.

mailbox-folder-unselect! mailbox

Bigloo Mail procedure

Unselects the mailbox current selected folder.

mailbox-folder-create! mailbox folder

Bigloo Mail procedure

Creates a new folder denotes by a fully qualified name.

Example

(mailbox-create! mbox "INBOX.scheme.bigloo")

mailbox-folder-delete! mailbox folder

Bigloo Mail procedure

Deletes an empty folder.

mailbox-folder-rename! mailbox old new

Bigloo Mail procedure

Renames a folder.

mailbox-folder-move! mailbox folder dest

Bigloo Mail procedure

Moves the folder into the destination folder dest.

mailbox-subscribe! mailbox folder

Bigloo Mail procedure

mailbox-unsubscribe! mailbox folder

Bigloo Mail procedure

Subscribe/unsubscribe to a folder. This allows imap servers not to present the entire list of folders. Only subscribed folders are returned by mailbox-folders. These functions have no effect on maildir servers.

mailbox-folder-exists? mailbox folder

Bigloo Mail procedure

Returns #t if and only if folder exists in mailbox. Returns #f otherwise.

mailbox-folder-status mailbox folder

Bigloo Mail procedure

Returns the status of the folder. A status is an alist made of the number of unseen mail, the uid validity information, the uid next value, the number of recent messages, and the overall number of messages.

mailbox-folder-uids mailbox

Bigloo Mail procedure

Returns the list of UIDs (a list of integers) of the messages contained in the currently selected folder.

mailbox-folder-dates mailbox

Bigloo Mail procedure

Returns the list of dates of the messages contained in the currently selected folder.

mailbox-folder-delete-messages! mailbox

Bigloo Mail procedure

Deletes the messages marked as deleted of the currently selected folder.

mailbox-folder-header-fields mailbox field

Bigloo Mail procedure

Returns the list of headers fields of the message of the current folder.

mailbox-message mailbox uid

Bigloo Mail procedure

Returns the message uid in the current folder.

mailbox-message-path mailbox uid

Bigloo Mail procedure

Returns the full path name of the message uid.

mailbox-message-body mailbox uid [len]

Bigloo Mail procedure

Returns the body of the message uid. If len is provided, only returns the first len characters of the body.

mailbox-message-header mailbox uid

Bigloo Mail procedure

Returns the header as a string of the message uid.

mailbox-message-header-list mailbox uid

Bigloo Mail procedure

Returns the header as an alist of the message uid.

mailbox-message-header-field mailbox uid field

Bigloo Mail procedure

Extracts one field from the message header.

mailbox-message-size mailbox uid

Bigloo Mail procedure

Returns the size of the message.

mailbox-message-info mailbox uid

Bigloo Mail procedure

Returns the information relative to the message uid. This a list containing the message identifier, its uid, the message date, the message size, and the message flags.

mailbox-message-flags mailbox uid

Bigloo Mail procedure

mailbox-message-flags-set! mailbox uid lst

Bigloo Mail procedure

Sets/Gets the flags of the message uid. This is a list of strings. Typical flags are:

\Flagged
\Answered
\Deleted
\Seen

mailbox-message-delete! mailbox uid

Bigloo Mail procedure

Deletes the message uid.

mailbox-message-move! mailbox uid folder

Bigloo Mail procedure

Moves the message uid into the new folder (denoted by a string).

mailbox-message-create! mailbox folder content

Bigloo Mail procedure

Creates a new message in the folder whose content is given the string content.

20.5.2 IMAP (RFC 3501)

imap

Bigloo Mail class

(class imap::mailbox
  (socket::socket read-only))

(define mbox
  (instantiate::maildir
    (label "My Remote Mailbox")
    (socket (imap-login (make-client-socket "imap.inria.fr" 993)
                        "serrano" "XXX"))))

&imap-parse-error

Bigloo Mail class

(class &imap-parse-error::&io-parse-error)

&imap-error

Bigloo Mail class

(class &imap-error::&mailbox-error)

imap-login socket user password

Bigloo Mail procedure

Log a user into an imap server. The socket must have been created first. The argument user is a string and denotes the user name. The argument password is a string too and it contains the user password. This function returns as value the socket it has received. If the operation fails the function raises a &imap-error exception.

Example:

(define mbox (imap-login (make-client-socket "imap.inria.fr" 993 :timeout 200000) "serrano" "XXX"))

(print (mailbox-folders mbox))

imap-logout socket

Bigloo Mail procedure

Closes an imap connection.

imap-capability socket

Bigloo Mail procedure

Returns the list of capabilities supported the imap server.

20.5.3 Maildir

maildir

Bigloo Mail class

(class maildir::mailbox
  (prefix::bstring read-only (default "INBOX"))
  (path::bstring read-only))

Example:

(define mbox
  (instantiate::maildir
    (label "My Mailbox")
    (path (make-file-name (getenv "HOME") ".maildir"))))

(tprint (mailbox-folders mbox))

&maildir-error

Bigloo Mail class

(class &maildir-error::&mailbox-error)