MAPISendMail
(VB)
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