Application Development

Chapter 49. Sending Mail in Panther

In Panther 5 for Windows, you can send mail. Mail is available to all Windows Panther components including COM/MTS and EJB components. Starting with Panther 5.40 you can also use CDO (Collaborative Data Objects) to send mail. This may work better than MAPI (the Windows Messaging API) on Windows Server systems.

This feature uses a combination of properties and functions. There is a global mail object PR_MAIL_SYSTEM that accepts the information needed to communicate with MAPI or CDO. Using the PR_MAIL_SYSTEM object, you can also set default values for some mail properties.

The sm_mail_new function creates a new mail object; other functions attach files to the message, get the message text from a field or a text file, and send the mail message.

The sm_mail_message function can send simple mail messages.

Defining Global Mail Properties

The global mail object PR_MAIL_SYSTEM is created at startup. You can set values for the following properties:

Optional MAPI profile name for the MAPILogon function.

The mail server to use by CDO, for example "".

The port that CDO will use when connecting to the mail server. The default is to use port 25. Other commonly used ports are 465 and 587.

The UserName CDO should use when connecting to the mail server. If omitted, anonymous SMTP will be used. PR_MAIL_PASSWORD, when set, will be used as the password for UserName.

Optional password for the MAPILogon function and for CDO when the PR_MAIL_USERNAME property is set.

Optional flags that describe how to logon to the MAPI session or the CDO option to use. One or more can be used. Values are:

Always create a new session. By default, logging into an existing session will be attempted and if that fails, then a new session will be created.

Display a logon dialog asking for the logon information when logging onto a MAPI session. If PR_MAIL_PROFILE is set, it will be used as the default profile name.

Display a password dialog when logging onto a MAPI session. This setting is ignored if PV_MAPI_LOGON_UI is also set.

Use CDO when sending mail. The flags PV_MAPI_NEW_SESSION; PV_MAPI_LOGON_UI and PV_MAPI_PASSWORD_UI must not be set. PR_MAIL_SERVER and PR_MAIL_FROM must be set before mail can be sent.

CDO should use SSH when communicating with the mail server.

Indicates whether there is an active MAPI connection to the messaging system. It can be set to PV_YES to attempt such a connection and PV_NO to sever the current connection. Panther attempts to connect to a MAPI session when a message is being sent or when the PR_MAIL_CONNECTED property is set to PV_YES. It will stay connected until any of the PR_MAIL_PROFILE, PR_MAIL_PASSWORD or PR_MAPI_FLAGS properties are set; until PR_MAIL_CONNECTED is set to PV_NO; or until Panther exits. It will have value PV_NO when the PV_USE_CDO flag is set.

You can set default values for all mail communication for the following properties:

Default value for the From: line of mail messages.

Default value for the To: line of mail messages.

Default value for the CC: line of mail messages.

Default value for the BCC: line of mail messages.

Default value for the Reply-to: line of mail messages. Ignored when using MAPI.

Default value for the Subject: line of mail messages.

Default value for whether to ask for a receipt. This seemingly does not work for most Mail Transfer Agents (Outlook and Outlook Express in particular).

Defining Multiple Addresses

PR_MAIL_TO, PR_MAIL_CC and PR_MAIL_BCC can include several addresses. For example:

@id(PR_MAIL_SYSTEM)->mail_to = \
'John Doe <>, Jane Roe <>'

Such items will be split up internally, so

	vars first_to = @id(PR_MAIL_SYSTEM)->mail_to[1]

would return the value 'John Doe <>' after the above.

Creating and Sending Email

Creating a Mail Message Object

A new mail message object is created by calling sm_mail_new:

	int sm_mail_new (char *name);

sm_mail_new returns the object ID of a new message. If name is supplied, it can be used to set properties of the message. Before the message is sent, the following properties can be set:

Text of the Subject: line.

Text of the message. There are also several functions that also can be used to set the message text.

Information for the From: line of mail messages. Some Mail Transfer Agents ignore this property.

Information for the To: line of mail messages.

Information for the CC: line of mail messages.

Information for the BCC: line of mail messages.

Information for the Reply-to: line of mail messages. Ignored when using MAPI.

Whether to ask for a receipt when the mail is first read. This will be ignored by some Mail Transfer Agents (Outlook and Outlook Express in particular).

Name of the message.

When any of PR_MAIL_FROM, PR_MAIL_TO, PR_MAIL_CC, PR_MAIL_BCC, PR_MAIL_RECEIPT or PR_MAIL_SUBJECT are not set, the corresponding value from the PR_MAIL_SYSTEM object will be used when it is set. Setting a property to '' is treated as setting the value, i.e.,

	@id(my_first_message)->mail_bcc = ''

PR_MAIL_SUBJECT, PR_MAIL_FROM, PR_MAIL_TEXT, PR_MAIL_REPLYTO, PR_MAIL_RECEIPT and PR_NAME have only one occurrence; the other properties can occur several times.

Sending Mail

sm_mail_send sends the message identified by obj_id or name and deletes it. Returns 0 if successful or an error code from smuprapi.h.

	int sm_mail_send (int obj_id);
	int sm_n_mail_send (char *name);

Sending a Screen Image

sm_mail_widget can only be used in prodev and prorun. The screen image of a widget is converted to a JPEG file that is attached to the mail message. PR_APPLICATION will send the complete MDI frame. Returns 0 if successful or an error code from smuprapi.h, most likely PR_E_OBJECT or PR_E_OBJID.

	int sm_mail_widget (int obj_id, char *widget_name, char *attachment_name, int quality);
	int sm_n_mail_widget (char *name, char *widget_name, char *attachment_name, int quality);

Sending Mail Using a Field

sm_mail_text takes the message text from the specified field. If the field is not word wrapped, each occurrence will be placed on a new line.

	int sm_mail_text (int obj_id, char *field_name);
	int sm_n_mail_text (char *name, char *field_name);

Sending Mail from a Text File

sm_mail_file_text takes the message text from a text file.

	int sm_mail_file_text (int obj_id, char *file_name);
	int sm_n_mail_file_text (char *name, char *file_name);

Sending Simple Mail Messages

sm_mail_message mails a message containing text with to as the address.

	int sm_mail_message (char *to, char *subject, char *text);

The default values of PR_MAIL_FROM, PR_MAIL_CC, PR_MAIL_BCC and PR_MAIL_RECEIPT will be used of they are set.

Sending Attachments

The following functions attach a file to the message:

int sm_mail_attach (int obj_id, char *pathname, char *filename, int delete);
int sm_n_mail_attach (char *name, char *pathname, char *filename, int delete);

pathname is the path to the file. filename is an optional filename to use when the file is saved by the message recipient. If the null string or null pointer is passed, the filename will be taken from pathname. If delete is not zero, the file will be deleted when the message is sent or deleted.

File attachments can only be created with sm_mail_attach or sm_n_mail_attach. Once created, these properties can be accessed and set.

File path and name to be sent as the attachment.

File name to be sent with the attachment. If not set, the file name from PR_MAIL_ATTACHMENT_SOURCE will be used. Not used when sending mail using CDO

If set to PV_YES, the file that is to be attached will be deleted when the mail object is destroyed.

Identifies the encoding used for the attached file.

Indicates the application that generated the attachment. Typical values are "text/html"; "text/plain"; "image/jpeg" and "application/pdf".