20. Bigloo
A practical Scheme compiler
User manual for version 4.2a
September 2015 -- Mail
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 stringBigloo Mail procedure
quoted-printable-decode stringBigloo 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 opBigloo 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-portBigloo 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 stringBigloo Mail procedure
mime-content-disposition-decode-port input-portBigloo 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:

(rfc2047-decode "Poste =?ISO-8859-1?Q?t=E9l=E9phonique?=")
  => "Poste téléphonique"
(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.

vcardBigloo 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 objBigloo 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 stringBigloo 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 stringBigloo 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

mailboxBigloo 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-errorBigloo 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 mailboxBigloo 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 mailboxBigloo Mail procedure
Returns a string denoting the separator (commonly " or .) used by the mailbox.

mailbox-prefix mailboxBigloo Mail procedure
Returns the prefix of the mailbox, a string or #f.

mailbox-hostname mailboxBigloo Mail procedure
Returns the hostname of the mailbox, a string or #f.

mailbox-folders mailboxBigloo Mail procedure
Returns a list of strings denoting the folder names of the mailbox.

mailbox-folder-select! mailbox stringBigloo 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! mailboxBigloo Mail procedure
Unselects the mailbox current selected folder.

mailbox-folder-create! mailbox folderBigloo Mail procedure
Creates a new folder denotes by a fully qualified name.

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

mailbox-folder-delete! mailbox folderBigloo Mail procedure
Deletes an empty folder.

mailbox-folder-rename! mailbox old newBigloo Mail procedure
Renames a folder.

mailbox-folder-move! mailbox folder destBigloo Mail procedure
Moves the folder into the destination folder dest.

mailbox-subscribe! mailbox folderBigloo Mail procedure
mailbox-unsubscribe! mailbox folderBigloo 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 folderBigloo Mail procedure
Returns #t if and only if folder exists in mailbox. Returns #f otherwise.

mailbox-folder-status mailbox folderBigloo 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 mailboxBigloo Mail procedure
Returns the list of UIDs (a list of integers) of the messages contained in the currently selected folder.

mailbox-folder-dates mailboxBigloo Mail procedure
Returns the list of dates of the messages contained in the currently selected folder.

mailbox-folder-delete-messages! mailboxBigloo Mail procedure
Deletes the messages marked as deleted of the currently selected folder.

mailbox-folder-header-fields mailbox fieldBigloo Mail procedure
Returns the list of headers fields of the message of the current folder.

mailbox-message mailbox uidBigloo Mail procedure
Returns the message uid in the current folder.

mailbox-message-path mailbox uidBigloo 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 uidBigloo Mail procedure
Returns the header as a string of the message uid.

mailbox-message-header-list mailbox uidBigloo Mail procedure
Returns the header as an alist of the message uid.

mailbox-message-header-field mailbox uid fieldBigloo Mail procedure
Extracts one field from the message header.

mailbox-message-size mailbox uidBigloo Mail procedure
Returns the size of the message.

mailbox-message-info mailbox uidBigloo 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 uidBigloo Mail procedure
mailbox-message-flags-set! mailbox uid lstBigloo 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 uidBigloo Mail procedure
Deletes the message uid.

mailbox-message-move! mailbox uid folderBigloo Mail procedure
Moves the message uid into the new folder (denoted by a string).

mailbox-message-create! mailbox folder contentBigloo Mail procedure
Creates a new message in the folder whose content is given the string content.



20.5.2 IMAP (RFC 3501)

imapBigloo 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-errorBigloo Mail class
(class &imap-parse-error::&io-parse-error)

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

imap-login socket user passwordBigloo 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 socketBigloo Mail procedure
Closes an imap connection.

imap-capability socketBigloo Mail procedure
Returns the list of capabilities supported the imap server.




20.5.3 Maildir

maildirBigloo 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-errorBigloo Mail class
(class &maildir-error::&mailbox-error)





This Html page has been produced by Skribe.
Last update Thu Sep 3 08:07:38 2015.