# The Mail Kit: The Mail Daemon

Derived from: none

Declared in: be/kit/mail/E-mail.h

Library: libmail.so

## Overview

Every computer running the BeOS has a mail daemon; this is a local process that's responsible for sending e-mail to and receiving e-mail from a mail server. The mail server that the daemon talks to is a networking application that's either part of your Internet Service Provider's services, or that's running on a local "mail repository" machine.

The functions described in this section tell you how to manage the mail daemon's connection with the mail server--how to tell the daemon which mail server to communicate with, how to tell the mail daemon to send and retrieve e-mail, how to automate mail retrieval, and so forth.

Many of the functions described here are user-accessible through the E-mail preference application. These functions should generally not be used; the settings they control belong to the user, and your application should usually avoid changing the user's settings. The only legitimate reason to use these configuration setting functions is if you want to build your own E-mail preference application.

The other functions, such as `forward_mail()`, `check_for_mail()`, `encode_base64()`, and `decode_base64()`, might be legitimately used by your e-mail program.

The architecture of an e-mail message isn't discussed here; for that information, see "Mail Messages (BMailMessage)."

### The Mail Daemon and the Mail Server

The mail daemon can talk to two different kinds of mail server:

- The Post Office Protocol ("POP") server manages individual mail accounts. When the BeOS mail daemon wants to retrieve mail that's been sent to a user, it must tell the mail server which POP accouant it's retrieving mail for.

- The Simple Mail Transfer Protocol ("SMTP") server manages mail that's being sent out onto the network. Messages sent through an SMTP server will eventually find their way to a POP server to be received by the destination user.

The POP and the SMTP servers are identified by their hosts' names (in other words, the names of the machines on which the servers are running). The mail daemon can only talk to one POP and one SMTP server at a time, but can talk to the two of them simultaneously. Usually--but not always--the POP and SMTP servers reside on the same machine, and so are identified by the same name.

To set the identities of the POP host, you fill in the fields of a `mail_pop_account` structure and pass the structure to the `set_pop_account()` function. As the name of the structure implies, `mail_pop_account` encodes more than just the names of the server's host. It also identifies a specific user's POP mail account; the complete definition of the structure is this:

       typedef struct
       {
          char pop_name[B_MAX_USER_NAME_LENGTH];
          char pop_password[B_MAX_USER_NAME_LENGTH];
          char pop_host[B_MAX_HOST_NAME_LENGTH];
          char real_name[128];
          char reply_to[128];
          int32 days;
          int32 interval;
          int32 begin_time;
          int32 end_time;
       } mail_pop_account;

The `pop_name`, `pop_password`, and `pop_host` fields in the `mail_pop_account` structure represent the username, password, and POP server host of the e-mail user. The `real_name` is the user's real name, and `reply_to` is the e-mail address to which replies should be sent.

The `days` field can contain any of the following flags to specify which days of the week the mail daemon should automatically check mail for the described account:

`Constant` | Meaning
`B_CHECK_NEVER` | Don't automatically check the account's mail.
`B_CHECK_WEEKDAYS` | Check the mail only on weekdays.
`B_CHECK_DAILY` | Check the mail every day.
`B_CHECK_CONTINUOUSLY` | Check continuously every day.

The `interval` specifies how many seconds apart each e-mail retrieval should be, and the `begin_time` and `end_time` specify the time of day (in seconds) that automatic retrieval should begin and end.

The SMTP server can be selected by calling `set_smtp_host()`, passing in a pointer to the SMTP host's name.

### Sending and Retrieving Mail

Messages that are retrieved (from the mail server) by the mail daemon are stored as individual files on the user's hard disk, from whence they are plucked and displayed by a mail-reading application (a "mail reader"; Be supplies a simple mail reader called BeMail). Similarly, messages that the user composes (in a mail composition application) and sends are stored as individual files until the mail daemon comes along and passes them on to the mail server.

Sending and retrieving mail is the mail daemon's most important function. Both actions (server-to-database and database-to-server transmission) are performed through the `check_for_mail()` function.

The BMailMessage class provides a convenient means for creating and sending new mail messages; visit the section on that class for further information and a simple example.

Mail that has been retrieved by the mail daemon can be identified and queried using the mail attributes defined by the Mail Kit. By using the BQuery class, you can scan all newly-received mail messages and parse the message file to present each message to the user. For a more in-depth discussion of the mail attributes and how to use them to your benefit, read "Querying Mail Messages."

### Other Mail Daemon Features

The other mail structures and functions define the other features that are provided by the mail daemon. These features are:

- Mail notification. The `mail_notification` structure (passed through the `set_mail_notification()` function) lets you tell the daemon how you would like it to tap you on the shoulder when it has new mail for you to read. Would you like it to display an alert panel? Squawk at you? Both? This can be configured by the user in the E-mail preference application.

- Mail forwarding. The `forward_mail()` function lets you ask the Mail Kit to forward a message to one or more other accounts.

- Base-64 encoding and decoding. The `encode_base64()` and `decode_base64()` functions let you easily handle ASCII-encoded file attachments.

## Functions

### check_for_mail()

          status_t check_for_mail(int32 *incoming_count = NULL)

Sends and retrieves mail. More specifically, this function asks the mail daemon to retrieve incoming messages from the POP server and send any queued outgoing messages to the SMTP server. The number of POP messages that were retrieved are stored in the variable pointed to by incoming_count. If you specify `NULL` for incoming_count, `check_for_mail()` won't return the number of messages retrieved. You should specify `NULL` unless you really want to know how many messages were retrieved, since requesting this information could potentially slow down the retrieval process.

If all is well in the mail world, this function returns `B_OK`; otherwise, it returns a highly useful result code.

RETURN CODES

- `B_OK`. Mail was sent and retrieved without incident.
- `B_MAIL_NO_DAEMON`. The mail daemon isn't running.
- `B_MAIL_UNKNOWN_USER`. The POP server doesn't recognize the user name.
- `B_MAIL_WRONG_PASSWORD`. The POP server doesn't recognize the password.
- `B_MAIL_UNKNOWN_HOST`. The POP or SMTP server can't be found.
- `B_MAIL_ACCESS_ERROR`. The connection to the POP or SMTP server failed.

### count_pop_accounts()

          int32 count_pop_accounts(void)

Returns the number of POP accounts that have been configured.

|  | The mail daemon currently supports only one POP account, so this function will always return 1. You shouldn't assume there will only be one POP account, though, as this will probably change in the future.

### decode_base64()

          ssize_t decode_base64(char *out, char *in, off_t length, bool replace_cr = false)

Decodes the base-64 data pointed to by in, which is length bytes long, and writes the decoded output into the buffer pointed to by out. If replace_cr is `true`, carriage return characters in the output are converted into newlines, otherwise the data is returned in its original, unaltered, form.

You would typically specify replace_cr as `true` if you're decoding an ASCII text document, and as `false` if decoding a binary file.

This function returns the size of the output data that's been stored in the out buffer.

|  | You must be certain, in advance, that the output buffer is large enough to hold the decoded data, or this function will do bad things.

### encode_base64()

          ssize_t encode_base64(char *out, char *in, off_t length)

Encodes the data pointed to by in, which is length bytes long, and writes the base-64 encoded output into the buffer pointed to by out.

This function returns the size of the output data that's been stored in the out buffer.

|  | You must be certain, in advance, that the output buffer is large enough to hold the encoded data, or this function will do bad things.

### forward_mail()

          status_t forward_mail(entry_ref *message_ref, const char *recipients,
             bool now = true)

Forwards the mail message specified by message_ref to the list of users given by recipients. The list of user names specified in recipients must be separated by commas and/or whitespace, and must be null-terminated.

If the now parameter is `true`, the messages will be sent immediately; if `false`, the message will be queued up to be sent the next time `check_for_mail()` is called, or the next time the mail daemon performs an automatic mail check.

RETURN CODES

- `B_OK`. The message was forwarded without error.
- `B_MAIL_NO_RECIPIENT`. No valid recipients were specified.
- Errors returned by `send_queued_mail()`, if now is `true`.

### get_mail_notification(), set_mail_notification()

          status_t get_mail_notification(mail_notification *notification_settings)

          status_t set_mail_notification(mail_notification *notification_settings,
             bool save = true)

`get_mail_notification()` fills the specified `mail_notification` structure with information describing how the user is currently being notified of received e-mail. There are two possible notification signals: the mail alert panel and the system beep. The `mail_notification` structure looks like this:

       typedef struct
       {
          bool alert;
          bool beep;
       } mail_notification;

`get_mail_notification()` always returns `B_OK`. If the current settings can't be checked (for example, if the user has never configured mail), alert will be returned as the default value of `false`, and beep will be `true`.

`set_mail_notification()` accepts a pointer to a `mail_notification` structure and configures the system to report incoming mail using the methods specified therein. If the save argument is `true`, the change is set as the new default and will be remembered when the computer is shut down. If `false`, the change is temporary.

RETURN CODES

- `B_OK`. The notification was successfully set or retrieved.
- `B_NO_REPLY`. The mail daemon didn't respond to the request.

### get_pop_account(), set_pop_account()

          status_t get_pop_account(mail_pop_account *account_info, int32 index = 0)

          status_t set_pop_account(mail_pop_account *account_info, int32 index = 0)

Get and set the specified POP account's information. The `mail_pop_account` structure is defined as follows:

       typedef struct
       {
          char pop_name[B_MAX_USER_NAME_LENGTH];
          char pop_password[B_MAX_USER_NAME_LENGTH];
          char pop_host[B_MAX_HOST_NAME_LENGTH];
          char real_name[128];
          char reply_to[128];
          int32 days;
          int32 interval;
          int32 begin_time;
          int32 end_time;
       } mail_pop_account;

The `pop_name`, `pop_password`, and `pop_host` fields in the `mail_pop_account` structure represent the username, password, and POP server host of the e-mail user. The `real_name` is the user's real name, and `reply_to` is the e-mail address to which replies should be sent.

The `days` field can contain any of the following flags to specify which days of the week the mail daemon should automatically check mail for the described account:

`Constant` | `Meaning`
`B_CHECK_NEVER` | Don't automatically check the account's mail.
`B_CHECK_WEEKDAYS` | Check the mail only on weekdays.
`B_CHECK_DAILY` | Check the mail every day.
`B_CHECK_CONTINUOUSLY` | Check continuously every day.

The `interval` specifies how many seconds apart each e-mail retrieval should be, and the `begin_time` and `end_time` specify the time of day (in seconds) that automatic retrieval should begin and end. If `begin_time` and `end_time` are the same, the daemon checks mail round-the-clock.

|  | Eventually these functions will support multiple POP accounts; at this time, the Mail Kit only supports one POP account, so you must use an index of 0. Any other index will result in a `B_BAD_INDEX` error.

`get_pop_account()` fills the specified `mail_pop_account` structure with the information on the POP account, and `set_pop_account()` takes the information in the buffer and saves it as the new default.

RETURN CODES

- `B_OK`. The notification was successfully set or retrieved.
- `B_BAD_INDEX`. An index other than 0 was specified.
- `B_NO_REPLY`. The mail daemon didn't reply to the request.

### get_smtp_host(), set_smtp_host()

          status_t get_smtp_host(char *smtp_host)

          status_t set_smtp_host(char *smtp_host, bool save = true)

`get_smtp_host()` returns in the buffer pointed to by smtp_host the name of the SMTP host as currently configured. The buffer should be at lest `B_MAX_HOST_NAME_LENGTH` bytes long.

`set_smtp_host()` sets the SMTP host through which mail will be sent in the future to the specified host. If save is `true`, the new setting becomes the default and will persist through a reboot of the computer; otherwise, the change is only temporary.

RETURN CODES

- `B_OK`. The notification was successfully set or retrieved.
- `B_NO_REPLY`. The mail daemon didn't respond to the request.

### send_queued_mail()

          status_t send_queued_mail(void)

Tells the mail daemon to send all pending outgoing mail.

RETURN CODES

- `B_OK`. Mail transfer intitiated successfully.
- Errors from BMessage::`SendMessage()`.

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.