| Application Development | |
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:
PR_MAIL_PROFILE
MAPI profile name for the MAPILogon function.
PR_MAIL_SERVER
PR_MAIL_PORT
PR_MAIL_USERNAME
PR_MAIL_PASSWORD
MAPILogon function and for CDO when the PR_MAIL_USERNAME property is set.
PR_MAIL_FLAGS
MAPI session or the CDO option to use. One or more can be used. Values are:
PV_MAPI_NEW_SESSION
PV_MAPI_LOGON_UI
PR_MAIL_PROFILE is set, it will be used as the default profile name.
PV_MAPI_PASSWORD_UI
MAPI session. This setting is ignored if PV_MAPI_LOGON_UI is also set.
PV_MAPI_USE_CDO
PV_MAPI_USE_CDO_SSH
PR_MAIL_CONNECTED
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:
PR_MAIL_FROM
From: line of mail messages.
PR_MAIL_TO
To: line of mail messages.
PR_MAIL_CC
CC: line of mail messages.
PR_MAIL_BCC
BCC: line of mail messages.
PR_MAIL_REPLYTO
PR_MAIL_SUBJECT
Subject: line of mail messages.
PR_MAIL_RECEIPT
PR_MAIL_TO, PR_MAIL_CC and PR_MAIL_BCC can include several addresses. For example:
@id(PR_MAIL_SYSTEM)->mail_to = \
'John Doe <j.doe@somewhere.com>, Jane Roe <j.roe@elsewhere.com>'
Such items will be split up internally, so
vars first_to = @id(PR_MAIL_SYSTEM)->mail_to[1]
would return the value 'John Doe <j.doe@somewhere.com>' after the above.
Creating and Sending Email | |
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:
PR_MAIL_SUBJECT
Subject: line.
PR_MAIL_TEXT
PR_MAIL_FROM
From: line of mail messages. Some Mail Transfer Agents ignore this property.
PR_MAIL_TO
To: line of mail messages.
PR_MAIL_CC
CC: line of mail messages.
PR_MAIL_BCC
BCC: line of mail messages.
PR_MAIL_REPLYTO
PR_MAIL_RECEIPT
PR_NAME
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.
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);
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);
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);
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);
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.
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.
PR_MAIL_ATTACHMENT_PATHNAME
PR_MAIL_ATTACHMENT_FILENAME
PR_MAIL_ATTACHMENT_SOURCE will be used. Not used when sending mail using CDO
PR_MAIL_ATTACHMENT_DELETE
PV_YES, the file that is to be attached will be deleted when the mail object is destroyed.
PR_MAIL_ATTACHMENT_ENCODING
PR_MAIL_ATTACHMENT_TAG