The Visual Basic MAPISendMail function sends a standard message.
Quick Info
Header file:
MAPIVB32.BAS
MAPISendMail(
Session as Long,. UIParam as Long, Message as MapiMessage, Recips as MapiRecip, Files as MapiFile, Flags as Long, Reserved as Long) as Long
Parameters
Session
[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.
UIParam
The parent window handle for the dialog box. A value of zero indicates that any dialog box displayed is application modal.
Message
[in] The message to be sent. An empty string indicates no text. Each paragraph should be terminated with either a carriage return (0x0d), a line feed (0x0a), or a carriage return–line feed pair (0x0d0a). The implementation wraps lines as appropriate. Implementations can place limits on the size of the text. The MAPI_E_TEXT_TOO_LARGE value is returned if this limit is exceeded. Client applications can set MAPI_RECEIPT_REQUESTED in the Flags member in the MapiMessage type pointed to by the Message parameter to prompt for a read report.
Recips
[in] The first element of an array of recipients. When the the value of the RecipCount member in the MapiRecip type pointed to by the Message parameter is zero, the Recips parameter is ignored. The Recips parameter can include either an entry identifier, the recipient's name, an address, or a name and address pair. Depending on the type and amount of information passed, MAPISendMail will perform varied levels of name resolution. If an entry identifier in the EntryID member for a particular recipient is specified, MAPISendMail performs no lookup and ignores the name and address. If only a name is specified, MAPISendMail resolves the name to a valid address using name resolution rules defined by Simple MAPI. If only an address is specified, MAPISendMail uses this address for both message delivery and for displaying the recipient name; no name resolution occurs. If both a name and address are specified, again MAPISendMail does not resolve the name. The specified name is used as the display name and not for resolution.
Files
[in] The first element of an array of attachment files written when the message is read. The number of attachments per message might be limited in some systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. When the value of the FileCount member in the MapiMessage type pointed to by the Message parameter is zero, the Files parameter is ignored. Attachment files are read and attached to the message before the call returns. Do not attempt to display attachments outside the range of the message text.
Flags
[in] Bitmask of option flags. The following flags can be set:
MAPI_DIALOG
A dialog box should be displayed to prompt the user for recipients and other sending options. Set the MAPI_LOGON_UI flag if MAPISendMail should display a dialog box to prompt the user to log on. When this flag is not set, MAPISendMail does not display a dialog box and returns a message if the user is not logged on.
MAPI_LOGON_UI
A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISaveMail ignores this flag if the MessageID parameter is empty.
MAPI_NEW_SESSION
An attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, MAPISendMail uses an existing shared session.
Reserved
Reserved; must be zero.
Return Values
MAPI_E_AMBIGUOUS_RECIPIENT
A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent.
MAPI_E_ATTACHMENT_NOT_FOUND
The specified attachment was not found. No message was sent.
MAPI_E_ATTACHMENT_OPEN_FAILURE
The specified attachment could not be opened. No message was sent.
MAPI_E_FAILURE
One or more unspecified errors occurred. No message was sent.
MAPI_E_INSUFFICIENT_MEMORY
There was insufficient memory to proceed. No message was sent.
MAPI_E_LOGIN_FAILURE
There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.
MAPI_E_TEXT_TOO_LARGE
The text in the message was too large. No message was sent.
MAPI_E_TOO_MANY_FILES
There were too many file attachments. No message was sent.
MAPI_E_TOO_MANY_RECIPIENTS
There were too many recipients. No message was sent.
MAPI_E_UNKNOWN_RECIPIENT
A recipient did not appear in the address list. No message was sent.
MAPI_E_USER_ABORT
The user canceled the process. No message was sent.
SUCCESS_SUCCESS
The call succeeded and the message was sent.
Remarks
The MAPISendMail function sends a standard message, with or without any user interaction. If recipient names, file attachments, or message text is provided, MAPISendMail can send the files or note without prompting users. If the optional parameters are specified and a dialog box is requested by use of the MAPI_DIALOG flag, the parameters provide the initial values for the dialog box.
File attachments are copied to the message before MAPISendMail returns; therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied.
MAPISendMail takes the recipients and file attachments from the Recips and Files parameters, which should each be the first element of dynamically allocated arrays of their respective types. These arrays are not redimensioned.
All strings must be specified in the current character set or code page of the client application's operating system process.
The declaration of this function for the 32-bit Visual Basic runtime is:
MAPISendMail(
ByVal Session&,
ByVal UIParam&, message As MAPIMessage, Recipient() As MapiRecip, File() As MapiFile,
ByVal Flags&,
ByVal Reserved&) As Long