20. Bigloo The Programming Language (4.6a) User manual for version 4.6a January 2025 -- Mail

main page

top: | Bigloo The Programming Language (4.6a) User manual for version 4.6a January 2025

Mail

Chapters

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.

vcard | bigloo mail class

    (class vcard
      (version::bstring (default "2.1"))
      (uid (default #f))
      (fn (default #f))
      (familyname (default #f))
      (firstname (default #f))
      (nickname (default #f))
      (photo (default #f))
      (sound (default #f))
      (url (default #f))
      (org (default #f))
      (emails::pair-nil (default '()))
      (phones::pair-nil (default '()))
      (birthday (default #f))
      (addresses::pair-nil (default '()))
      (lang (default #f))
      (related (default #f))
      (key (default #f))
      (notes::pair-nil (default '()))
      (x-thumbnail (default #f))
      (x-color (default #f))
      (xx-extras::pair-nil (default '())))

The class `vard` is used to reify in memory a vcard as parsed by the functions `port->vcard`, `read-vcard`, and `string->vcard`.
Except `emails`, `phones`, and `addresses`, all fields are optional. They should be either `#f` or a string. Field meanings are given by the RFC 2426 specification, apart the `x-thumbnail`, `x-color`, and `xx-extras` that are Bigloo specific.

- `photo` is a flat list of strings.
- `x-thumbnail` an optional thumbnail image.
- `x-color` an optional color.
- `xx-extras` a list of non standard properties.
- `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.

read-vcard::vcard ip [:charset-encoder] | bigloo mail function

port->vcard::vcard ip [:charset-encoder] | bigloo mail function

string->vcard::vcard str [:charset-encoder] | bigloo mail function

These three 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.
`port->vcard` is similar to `read-vcard` but it returns `#f` on end-of-file, while `read-vcard` returns the eof-object.

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

This Html page has been produced by Skribe.
Last update Mon Jan 27 07:55:49 2025.