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-port s and output-port s.
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
vcard
s.
(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.
(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 .
|
(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.
|
(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)
|
|