Contents
The Messaging Application Program Interface for C

Contents

Function	Description

MAPIAddress	Addresses a Mail message.

MAPIDeleteMail	Deletes a Mail message.

MAPIDetails	Displays a recipient details dialog box.

MAPIFindNext	Returns the ID of the next (or first) Mail message of a specified type.

MAPIFreeBuffer	Frees memory allocated by the messaging system.

MAPILogoff	Ends a session with the messaging system.

MAPILogon	Begins a session with the messaging system.

MAPIReadMail	Reads a Mail message.

MAPIResolveName	Displays a dialog box to resolve an ambiguous recipient name.

MAPISaveMail	Saves a Mail message.

MAPISendDocuments	Sends a standard Mail message using a dialog box.

MAPISendMail	Sends a Mail message, allowing greater flexibility in message generation.

Structure	Purpose

MapiFileDesc	Contains file attachment information.

MapiMessage	Contains message information.

MapiRecipDesc	Contains recipient information.


MAPI Overview
Overview

The simple Messaging Application Program Interface (MAPI) is a set of messaging functions that help you create mail-enabled applications, and is a subset of the powerful function group called MAPI. With simple MAPI functions,  you can easily add messaging to any Windows application. Some MAPI functions include a user interface (a dialog box), but you can also call MAPI functions without generating a user interface.

The files supplied for use with the MAPI C functions are described in the README.TXT file on the Messaging Application Development Tools disk.

As an example of what you can do with MAPI, consider this scenario: An operator using a network management application has generated a network usage report. You have used the macro language of the network management program to call the MAPISendDocuments function when the operator selects the Send command from a menu. Rather than using the Clipboard to paste the report into an electronic mail message and then mail it, the operator can now mail the report directly to a supervisor without leaving the network management program.

In this case, one function call is all that's required. The MAPISendDocuments function creates and initializes a message and supplies all of the standard Mail dialog boxes for the user to send messages. You can compile the function into the native code of your application, or, if your application includes a macro facility that can dynamically link to a code library (a DLL), you can integrate the DLL as an added macro command.

All of the MAPI functions are designed to be called from C, C++, or Microsoft Visual Basic programs, but you can also call them from high-level languages such as Actor and Object Vision or from applications with macro languages that can call a DLL, such as Microsoft Excel or Microsoft Word.

See Also

Adding the Send Command to an Application's File Menu

C Environment Considerations

MAPISendDocuments


MapiFileDesc

typedef struct {

 ULONG ulReserved;	// Reserved for future use. Must be 0.
 ULONG flFlags;	// Flags.
 ULONG nPosition;	// Attachment position in message body.
 LPSTR lpszPathName;	// Full path name of attached file.
 LPSTR lpszFileName;	// Original filename (optional).
 LPVOID lpFileType;	// Attachment file type (reserved).
} MapiFileDesc, *lpMapiFileDesc;

Description

The MapiFileDesc structure contains information about a file attachment. Simple MAPI supports the following kinds of attachments:

Data files

Embedded OLE objects

Static OLE objects

The flFlags field determines the kind of attachment. OLE (Object Linking and Embedding) object files are file representations of OLE object streams. You can recreate an OLE object from the file by calling the OleLoadFromStream function with an OLESTREAM object that reads the file contents. (For details, see the Microsoft Windows SDK documentation.) If an OLE file attachment is included in an outbound message, the OLE object stream should be written directly to the file used as the attachment.

Field	Description

ulReserved	Reserved for future use. This field must be 0.

flFlags	A bitmask of flags. Unused flags are reserved and must be 0. The following flags are defined in MAPI.H:

#define MAPI_OLE 0x0000001
#define MAPI_OLE_STATIC 0x00000002

MAPI_OLE is set if the attachment is an OLE object. If  MAPI_OLE_STATIC is also set, the attachment is a static OLE object rather than an embedded OLE object.

nPosition	An integer describing where the attachment should be placed in the message body. Attachments replace the character found at a certain position in the message body; in other words, attachments replace the MapiMessage structure field lpszNoteText[nPosition]. Applications may not place two attachments in the same location within a message, and attachments may not be placed beyond the end of the message body.

lpszPathName	A pointer to the full path name of the attached file. The file should be closed before this call is made.

lpszFileName	A pointer to the filename seen by the recipient. This name may differ from the filename in lpszPathName if temporary files are being used. If lpszFileName is empty or NULL, the filename from lpszPathName is used.  If the attachment is an OLE object, lpszFileName contains the class name of the object; for example, Microsoft Excel Worksheet.

lpFileType	A pointer to a reserved descriptor that is used to indicate to the recipient the type of the attached file. A pointer value of NULL indicates an unknown or operating system-determined file type. With this release, you must use NULL for this parameter.

Comments

MAPIReadMail does not return an attachment with nPosition equal to -1 unless the MAPI_BODY_AS_FILE flag is set.

With Microsoft Mail version 3.0b, if you send an attachment with nPosition equal to -1, the attachment is placed at the beginning of the message, with a space on either side of the attachment.

All pointers are far pointers.

See Also

MapiMessage, MAPIReadMail, MapiRecipDesc


MapiMessage

typedef struct {

 ULONG ulReserved;	// Reserved for future use. Must be 0.
 LPSTR lpszSubject;	// Message subject.
 LPSTR lpszNoteText;	// Message text.
 LPSTR lpszMessageType;	// Message class.
 LPSTR lpszDateReceived;	// In YYYY/MM/DD HH:MM format.
 LPSTR lpszConversationID;	// Conversation thread ID.
 ULONG flFlags;	// Unread, return receipt.
 lpMapiRecipDesc lpOriginator;	// Originator descriptor.
 ULONG nRecipCount;	// Number of recipients.
 lpMapiRecipDesc lpRecips;	// Recipient descriptors.
 ULONG nFileCount;	// Number of file attachments.
 lpMapiFileDesc lpFiles;	// Attachment descriptors.
} MapiMessage, *lpMapiMessage;

Description

The MapiMessage structure contains information about a message.

Field	Description

ulReserved	Reserved for future use. This field must be 0.

lpszSubject	A pointer to the subject text string, limited to 256 characters or less. (Messages saved using MAPISaveMail are not limited to 256 characters.) A pointer value of NULL or an empty string indicates no subject text.

lpszNoteText	A pointer to a string containing text in the message. A pointer value of NULL or an empty string indicates no text. For inbound messages, each paragraph is terminated with a carriage return-line feed pair (0x0d0a). For outbound messages, paragraphs can be delimited with a carriage return, line feed, or a carriage return-line feed pair (0x0d, 0x0a, or 0x0d0a).

lpszMessageType	A pointer to a message type string used by applications other than interpersonal electronic mail. A null pointer or empty string indicates an interpersonal message (IPM) type.

lpszDateReceived	A pointer to a string indicating the date a message is received. The format is YYYY/MM/DD HH:MM; hours are measured on a 24-hour clock.

lpszConversationID	A pointer to a string indicating the conversation thread ID to which this message belongs.

flFlags	A bitmask of flags. Unused flags are reserved. Unused flags must be 0 for outbound messages and are ignored for inbound messages. The following flags are defined in MAPI.H:

#define MAPI_UNREAD 0x00000001
#define MAPI_RECEIPT_REQUESTED 0x00000002
#define MAPI_SENT 0x00000004

lpOriginator	A pointer to a MapiFileDesc structure containing information on the message originator.

nRecipCount	A count of the recipient descriptor structures pointed to by lpRecips. A value of 0 indicates that no recipients are included.

lpRecips	A pointer to an array of recipient descriptor structures.

nFileCount	A count of the file attachment descriptor structures pointed to by lpFiles. A value of 0 indicates that no file attachments are included.

lpFiles	A pointer to an array of file attachment descriptors.

Comments

All pointers are far pointers.

Microsoft Mail supports message types (the lpszMessageType parameter) that begin with IPM or IPC. Messages of type IPM. (interpersonal mail) are visible in the Inbox when delivered. Messages of type IPC.(interprocess communication) do not appear in the Inbox when delivered. For more information about message types, see the programmer's reference manual that accompanies this product.

See Also

MapiFileDesc, MapiRecipDesc


MapiRecipDesc

typedef struct {

 ULONG ulReserved;	// Reserved for future use.
 ULONG ulRecipClass;	// Recipient class.
// MAPI_TO, MAPI_CC,
// MAPI_BCC, MAPI_ORIG
 LPSTR lpszName;	// Recipient name.
 LPSTR lpszAddress;	// Recipient address (optional).
 ULONG ulEIDSize;	// Size (in bytes) of lpEntryID.
 LPVOID lpEntryID;	// System-specific recipient reference.
} MapiRecipDesc, *lpMapiRecipDesc;

#define MAPI_ORIG 0	// Recipient is message originator
#define MAPI_TO 1	// Recipient is a primary recipient
#define MAPI_CC 2	// Recipient is a copy recipient
#define MAPI_BCC 3	// Recipient is blind copy recipient

Description

The MapiRecipDesc structure contains information about a message originator or recipient.

Field	Description

ulReserved	Reserved for future use. This field must be 0.

ulRecipClass	Specifies the recipient's role in the message. It can also contain information about the originator of an inbound message.

lpszName	The name of the recipient that is displayed by Mail.

lpszAddress	Provider-specific message delivery data. The message system can use this to identify recipients who are not in an address list (one-off addresses).

ulEIDSize	The size (in bytes) of the opaque binary data in lpEntryID.

lpEntryID	Binary data that Mail uses to efficiently specify the recipient. Unlike the lpszAddress field, this data is opaque and is not printable. Mail returns valid lpEntryIDs for recipients or originators included in the address list.

Comment

All pointers are far pointers.

See Also

MapiFileDesc, MapiMessage


C Environment Considerations

In the Windows environment, compile your source code with MAPI.H, which contains data type, constant, and function definitions.

To determine whether MAPI is available at run time, check for the MAPI variable in the [MAIL] section of WIN.INI. If this variable is present and nonzero, it indicates that a MAPI.DLL library is available. If the MAPI variable is not found or is 0, then you cannot call the MAPI functions, and you should not enable applications for mail.

When calling a MAPI function, load MAPI.DLL and use the GetProcAddress function to acquire an entry point. The function calling conventions should be FAR PASCAL.


MAPIAddress

ULONG MAPIAddress(lhSession, ulUIParam, lpszCaption, nEditFields, lpszLabels,nRecips, lpRecips, flFlags, ulReserved, lpnNewRecips, lppNewRecips)

LHANDLE  lhSession;
ULONG  ulUIParam;
LPSTR   lpszCaption;
ULONG  nEditFields;
LPSTR  lpszLabels;
ULONG  nRecips;
lpMapiRecipDesc  lpRecips;
ULONG  flFlags;
ULONG  ulReserved;
ULONG  lpnNewRecips;
lpMapiRecipDesc  lppNewRecips;

Description

This function allows users to create or modify a set of address list entries using a standard address list dialog box. The dialog box cannot be suppressed, but function parameters allow the caller to set characteristics of the dialog box.

The call is made with an initial, and possibly empty, set of recipients. The address list dialog box shows the contents of the recipient set and allows users to choose new entries to add to the set. The final set of recipients is returned to the caller.

The returned recipient set is allocated by Mail and must be freed using MAPIFreeBuffer supplied with the base pointer of the returned recipient array.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. The session handle is returned by MAPILogon and invalidated by MAPILogoff. If the value is 0, Mail initiates a session from a system default session (if one exists) or presents a sign-in dialog box. In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszCaption 	The caption of the address list dialog box. If this parameter is null or an empty string, the default value Address Book is used.

nEditFields	The number of edit controls that should be present in the address list. The values 0 to 4 are valid. If nEditFields is 0, only address-list browsing is allowed. nEditFields values of 1 to 3 control the number of edit controls present. Entries selected for the different controls are differentiated by the nRecipClass parameter in the returned recipient structure. If nEditFields is 4, each recipient class supported by the underlying messaging system has an edit control.

If the number of recipient classes in lpRecips is greater than the value of nEditFields, the number of classes in lpRecips is used instead of nEditFields. If nEditFields is 1 and more than one kind of entry exists in lpRecips, then lpszLabels is ignored.

lpszLabels	A string used as an edit control label in the address list dialog box. This argument is ignored and should be null or an empty string except when nEditFields is 1.

If a default control label To: is desired, lpszLabels should be NULL or an empty string.

nRecips	The number of entries in lpRecips. If nRecips is 0, lpRecips is ignored.

lpRecips	A pointer to the initial array of recipient entries to be used to populate edit controls in the Address Book dialog box. Recipient entries need not be grouped by recipient class. If the value of the greatest recipient class present is greater than the nEditFields parameter, nEditFields and lpszLabels are ignored.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_LOGON_UI 0x00000001
// Display logon UI
#define MAPI_NEW_SESSION 0x00000002
// Don't get default if available

Set MAPI_LOGON_UI if the function should display a sign-in dialog box (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not signed in. If the session passed in lhSession is not NULL, this flag is ignored.

Set MAPI_NEW_SESSION if you want to establish a session other than a current session. For instance, if a mail client is already running, another MAPI electronic mail client can piggyback on the session created by the Mail client application. Do not set this flag if you want the default session (if it still exists). If the session passed in lhSession is not NULL, this flag is ignored.

ulReserved	Reserved for future use. This parameter must be 0.

lpnNewRecips	An address to contain the number of entries in lpNewRecips. The MAPIAddress function supplies this value. If nNewRecips is 0, lpRecips should be ignored.

lppNewRecips	A pointer to the final array of recipient entries after potential selection of additional entries from the address list dialog box. This array is allocated by MAPIAddress and must be freed using MAPIFreeBuffer. Recipients in this array are grouped by recipient class in the following order: MAPI_TO, MAPI_CC, MAPI_BCC.

Return Value	Meaning

(If any error occurs, no memory was allocated and you do not need to deallocate the memory with MAPIFreeBuffer.)

MAPI_E_FAILURE	Unspecified error(s) occurred while addressing the mail. No list of entries was returned.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No list of entries was returned.

MAPI_E_INVALID_

EDITFIELDS	The value of nEditFields is outside the range of 0 to 4. No list of entries was returned.

MAPI_E_INVALID_

MESSAGE	An invalid message ID was used for the lpszMessageID parameter. No list of entries was returned.

MAPI_E_INVALID_

RECIPIENTS	One or more of the recipients in the address list is not valid. No list of entries was returned.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No list of entries was returned.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. No list of entries was returned.

MAPI_E_NOT_SUPPORTED	The operation was unsupported by the underlying mail system.

MAPI_E_USER_ABORT	The user canceled the process. No list of entries was returned.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIFreeBuffer, MAPILogoff, MAPILogon


MAPIDeleteMail

ULONG MAPIDeleteMail(lhSession, ulUIParam, lpszMessageID, flFlags, ulReserved)

LHANDLE  lhSession;
ULONG  ulUIParam;
LPSTR  lpszMessageID;
ULONG  flFlags;
ULONG  ulReserved;

Description

This function deletes a message from the message store. You should use MAPILogon to establish a valid MAPI session, and then MAPIFindNext before calling MAPIDeleteMail to verify that the correct message has been selected for deletion.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. The session handle is returned by MAPILogon and invalidated by MAPILogoff. If the value is 0, Mail establishes a session from a system default session (if one exists) or by presenting a sign-in dialog box. In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszMessageID 	The string identifier for this message returned by MAPIFindNext or MAPISaveMail. Applications should assume that this identifier is invalid after MAPIDeleteMail returns successfully.

flFlags	A bitmask of flags. All flags are reserved and should be set to 0.

ulReserved	Reserved for future use. This parameter must be 0.

Return Value	Meaning

MAPI_E_FAILURE	Unspecified error(s) occurred while deleting the mail. No mail was deleted.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No mail was deleted.

MAPI_E_INVALID_

MESSAGE	An invalid message ID was used for the lpszMessageID parameter. No mail was deleted.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No mail was deleted.

MAPI_E_USER_ABORT	The user canceled the process. No mail was deleted.

SUCCESS_SUCCESS	The function returned successfully. On all other return codes, no mail was deleted.

See Also

MAPIFindNext, MAPILogoff, MAPILogon, MAPISaveMail


MAPIDetails

ULONG MAPIDetails(lhSession, ulUIParam, lpRecip, flFlags, ulReserved)

LHANDLE  lhSession;
ULONG  ulUIParam;
lpMapiRecipDesc  lpRecip;
ULONG  flFlags;
ULONG  ulReserved;

Description

This function presents a dialog box that provides the details of a given address list entry. The dialog box cannot be suppressed. At the option of the caller, the entry can be either modifiable or static. MAPIDetails functions properly only for address list entries resolved as a result of being recipients of read mail, returned by MAPIAddress, or returned by MAPIResolveName.

The amount of information presented in the details dialog box is determined by the directory to which the entry belongs. At a minimum, it contains the display name and address of the recipient.

An entry is resolved if the ulEIDSize field of the MapiRecipDesc structure is nonzero.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. Session handles are returned by MAPILogon and invalidated by MAPILogoff. If the value is 0, Mail sets up a session from a system default session (if one exists) or by presenting a sign-in dialog box.  In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpRecip	A pointer to a recipient descriptor containing the entry whose details are to be displayed. All fields of the MapiRecipDesc structure except ulEIDSize and lpEID are ignored. If the field ulEIDSize is zero, MAPI_E_AMBIG_RECIP is returned.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_LOGON_UI 0x00000001
// Display logon UI
#define MAPI_NEW_SESSION 0x00000002
// Don't get default if available
#define MAPI_AB_NOMODIFY 0x00000400
// Don't modify PAB entries

Set MAPI_LOGON_UI if the function should display a sign-in dialog box (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not signed in.

Set MAPI_NEW_SESSION if you want to establish a session other than a current one. For instance, if a mail client is already running, another MAPI electronic mail client can piggyback on the session created by the mail client application. Do not set if you want the default session (if it still exists). If the session passed in lhSession is not NULL, this flag is ignored.

Set MAPI_AB_NOMODIFY if the details of the entry should not be modifiable even if the entry belongs to the personal address book.

ulReserved	Reserved for future use. This parameter must be 0.

Return Value	Meaning

MAPI_E_AMBIG_RECIP	The ulEIDSize parameter is zero. No dialog box was displayed.

MAPI_E_BAD_RECIP	One or more recipients were unknown. No dialog box was displayed.

MAPI_E_FAILURE	Unspecified error(s) occurred while matching the message type. The call failed before message type matching could take place.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No dialog box was displayed.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. No details dialog box was displayed.

MAPI_E_NOT_SUPPORTED	The operation was unsupported by the underlying mail system.

MAPI_E_USER_ABORT	The user canceled the process. No dialog box was displayed.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIAddress, MAPILogoff, MAPILogon, MapiRecipDesc , MAPIResolveName


MAPIFindNext

ULONG MAPIFindNext(lhSession, ulUIParam, lpszMessageType, lpszSeedMessageID, flFlags, ulReserved, lpszMessageID)

LHANDLE  lhSession;
ULONG  ulUIParam;
LPSTR  lpszMessageType;
LPSTR  lpszSeedMessageID;
ULONG  flFlags;
ULONG  ulReserved;
ULONG  lpszMessageID;

Description

This function allows an application to enumerate messages of a given type. It returns message identifiers that can be used in subsequent MAPI function calls to retrieve and delete messages. MAPIFindNext is designed for processing incoming mail, not for managing received mail. MAPIFindNext looks for messages in the folder in which new messages of the specified type are delivered. MAPIFindNext calls can be made only in the context of a valid MAPI session established with MAPILogon.

When provided with a null lpszSeedMessageID, MAPIFindNext returns the ID of the first message of type lpszMessageType. When provided a non-null or non-empty lpszSeedMessageID, MAPIFindNext returns the next matching message of the type specified with lpszMessageType. Repeated calls to MAPIFindNext ultimately result in a return of MAPI_E_NO_MESSAGES,  which means that the enumeration of the matching message types is complete.

Message identifiers are not guaranteed to remain valid, because other applications could move or delete messages. Applications must be able to handle failed calls to MAPIFindNext, MAPIDeleteMail, and MAPIReadMail for invalid message IDs. The ordering of messages is system-specific. Message ID strings must be allocated by the caller and must be at least 64 characters long.

Message type matching is done against message class strings. All messages types whose names match (up to the length specified in the lpszMessageType parameter) are returned. If the lpszMessageType parameter begins with the letters IPM, matching is performed in the Inbox. Otherwise, matching is performed in the hidden application Mail folder. If the message type is null or an empty string, all messages in the Inbox are included in the list.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. Session handles are returned by MAPILogon and invalidated by MAPILogoff. If the value is 0, MAPIFindNext returns MAPI_E_INVALID_SESSION. In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box  (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszMessageType	A pointer to a string that is the message type. To specify an interpersonal mail message, specify a pointer value of NULL or a pointer to the empty string, "".

lpszSeedMessageID	A pointer to a string that is the message identifier seed for the request. If the identifier is NULL or an empty string, the first message matching the type specified in the lpszMessageType parameter is returned. Message IDs are system-specific and opaque. Message IDs may be invalidated at any time if another application moves or deletes a message.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_UNREAD_ONLY 0x00000020
// Only unread messages
#define MAPI_GUARANTEE_FIFO 0x00000100
// Guarantee FIFO MAPIFindNext

Set MAPI_UNREAD_ONLY if the function should enumerate only unread messages. When this flag is not set, all messages of the given type are returned.

Set MAPI_GUARANTEE_FIFO if you want the message IDs returned in the order the messages were received. MAPIFindNext calls may take longer if this flag is set.

ulReserved	Reserved for future use. This parameter must be 0.

lpszMessageID	A pointer to a caller-allocated string that is the message identifier. Message IDs are system-specific, nonprintable, and opaque. Message ID strings must be able to accommodate at least 64 characters. Message IDs may be invalidated at any time if another application deletes or moves a message.

Return Value	Meaning

MAPI_E_FAILURE	Unspecified error(s) occurred while matching the message type. The call failed before message type matching could take place.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No mail was found.

MAPI_E_INVALID_MESSAGE	An invalid message ID was used for the lpszSeedMessageID parameter. No mail was found.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No mail was found.

MAPI_E_NO_MESSAGES	The MAPIFindNext function can't find a matching message.

MAPI_E_USER_ABORT	The user canceled the process. No mail was found.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIDeleteMail, MAPILogoff, MAPILogon, MAPIReadMail


MAPIFreeBuffer

ULONG MAPIFreeBuffer(lpMemory)

LPVOID  lpMemory;

Description

This function frees memory allocated by the messaging system. After the call, the pointer lpMemory is invalid and should not be referenced. When any MAPI function allocates and returns a buffer to an application, the application should free that memory with this call when finished. MAPIFreeBuffer's behavior is undefined when called with a pointer to a memory block not allocated by the messaging system.

When a MAPI function returns a complex structure containing several levels of pointers, the application can free the entire structure by calling this function with the base pointer returned by MAPIReadMail, MAPIAddress, or MAPIResolveName. (These are the three MAPI functions that allocate memory for messaging system purposes.)

Buffers are not automatically released when MAPILogoff is called.

Parameter	Description

lpMemory	A pointer to memory allocated by the messaging system. Such pointers are returned by MAPIReadMail, MAPIAddress, and MAPIResolveName.

Return Value	Meaning

SUCCESS_SUCCESS	Successful return. All other (unsuccessful) returns will return the original pointer.

See Also

MAPIAddress, MAPILogoff, MAPIReadMail, MAPIResolveName


MAPILogoff

ULONG MAPILogoff(lhSession, ulUIParam, flFlags, ulReserved)

LHANDLE  lhSession;
ULONG  ulUIParam;
ULONG  flFlags;
ULONG  ulReserved;

Description

This function ends a session with the messaging system.

Parameter	Description

lhSession	An opaque session handle that represents a session with Mail. Session handles are returned by MAPILogon and invalidated by MAPILogoff.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

flFlags	Reserved for future use. This parameter must be 0.

ulReserved	Reserved for future use. This parameter must be 0.

Return Value	Meaning

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. The session was not terminated.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. The session was not terminated.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPILogon


MAPILogon

ULONG MAPILogon(ulUIParam, lpszName, lpszPassword, flFlags, ulReserved, lphSession)

ULONG  ulUIParam;
LPSTR  lpszName;
LPSTR  lpszPassword;
ULONG  flFlags;
ULONG  ulReserved;
LHANDLE lphSession;

Description

The MAPILogon function begins a session with the messaging system. You can sign in to Mail in two ways using simple MAPI mail calls:

•	Implicitly sign in.

Any MAPI function call made outside of an established MAPI session generates a sign-in dialog box, which can be suppressed by the calling application. In this case, when the call returns, the session is terminated and Mail returns to its state before the call was made. For example, a user signed off from Mail before the call would also be signed off after the call completed.

•	Explicitly sign in using the MAPILogon function (and signing off using MAPILogoff).

If you want to maintain a session over a number of simple MAPI calls, you can use the MAPILogon function to provide a session handle to Mail. This session handle can be used in subsequent MAPI calls to explicitly provide user credentials to the messaging system. A flag is available to display a sign-in dialog box if the credentials presented fail to validate the session. You can pass a null password, although it may not validate the mail session.

Parameter	Description

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to an ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszName	A pointer to a null-terminated client account-name string, limited to 256 characters or less. A pointer value of NULL or an empty string indicates that a sign-in dialog box with an empty name field should be generated (if the appropriate flag is set).

lpszPassword	A pointer to a null-terminated credential string, limited to 256 characters or less. A pointer value of NULL or an empty string indicates that a sign-in dialog box with an empty password field should be generated  (if the appropriate flag is set) or that Mail does not expect password credentials.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The flags are defined as follows:

#define MAPI_LOGON_UI 0x00000001
// Display logon dialog box
#define MAPI_NEW_SESSION 0x00000002
// Get default if available
#define MAPI_FORCE_DOWNLOAD 0x00001000
// Force message download from server

Set MAPI_LOGON_UI if the function should display a dialog box to prompt for name and password (if required). When this flag is not set, the MAPILogon function does not display a sign-in dialog box and returns an error if the user is not signed in.

Set MAPI_NEW_SESSION if you want to establish a session other than the current one. For instance, if a mail client is already running, another MAPI electronic mail client can piggyback on the session created by the mail client application. Do not set if you want the default session (if it still exists).

Set MAPI_FORCE_DOWNLOAD to force a download of all new messages from the mail server to a user's Inbox during the sign-in process. Use this flag so that an application can deal with the user's complete set of messages when it signs in. When set, a progress indicator popup is displayed and automatically removed when the process is complete. Use of this flag may increase processing time.

ulReserved	Reserved for future use. This parameter must be 0.

lphSession	Pointer to an opaque session handle whose value is set by Mail when the MAPILogon call is successful. The session handle can then be used in subsequent MAPI calls.

Return Value	Meaning

MAPI_E_FAILURE	Unspecified error(s) occurred while signing in. A session handle was not returned.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. A session handle was not returned.

MAPI_E_LOGON_FAILURE	There was no default sign in, and the user failed to successfully sign in when the sign-in dialog box was displayed. A session handle was not returned.

MAPI_E_TOO_MANY_

SESSIONS	The user had too many sessions open at once. A session handle was not returned.

MAPI_E_USER_ABORT	The user canceled the process. A session handle was not returned.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPILogoff


MAPIReadMail

ULONG MAPIReadMail(lhSession, ulUIParam, lpszMessageID, flFlags, ulReserved, lppMessage )

LHANDLE  lhSession;
ULONG  ulUIParam;
LPSTR  lpszMessageID;
ULONG  flFlags;
ULONG  ulReserved;
lpMapiMessage  lppMessage;

Description

This function reads a mail message. You should use MAPILogon to establish a valid MAPI session, and then use MAPIFindNext before calling MAPIReadMail to verify that the message to be read is the one desired.

The call returns one message, breaking the message content into the same parameters and structures used in the MAPISendMail function. MAPIReadMail fills a block of memory with the MAPIMessage structure containing message elements. File attachments are saved to temporary files, and the names are returned to the caller in the message structure. Recipients, attachments, and contents are copied from the message before the function returns to the caller, so that later changes to the files do not affect the contents of the message. Memory is allocated by MAPIReadMail and must be freed by using MAPIFreeBuffer.

A flag is provided to specify that only envelope information is to be returned from the call. Another flag (in the MapiMessage structure) specifies whether the message is marked as sent or unsent.

All strings are null-terminated and must be specified in the current character set or code page of the calling program's operating system process. In Microsoft Windows, the character set is ANSI.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. If the value is 0, MAPIReadMail returns MAPI_E_INVALID_SESSION.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszMessageID	A pointer to a caller-allocated string that is the message identifier of the message to be read. Message IDs are system-specific, nonprintable, and opaque. Message IDs can be obtained from the MAPIFindNext and MAPISaveMail functions.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_ENVELOPE_ONLY 0x00000040
// Only header information
#define MAPI_SUPPRESS_ATTACH 0x00000800
// Header and body, no files
#define MAPI_BODY_AS_FILE 0x00000200
// Save body as first attachment
#define MAPI_PEEK 0x00000080
// Don't mark message as read

Set MAPI_ENVELOPE_ONLY when you don't want the function to copy file attachments to temporary files or return the note text. All other message information (except for temporary filenames) is returned. Setting this flag usually reduces the processing time required for the function.

Set MAPI_SUPPRESS_ATTACH when you don't want MAPIReadMail to copy file attachments, but instead just return message text. This flag is ignored if MAPI_ONLY_ENVELOPE is set. The flag should reduce the time required by the MAPIReadMail function.

Set MAPI_BODY_AS_FILE when you want the message body written to a temporary file and added to the attachment list as the first attachment, instead of returning a pointer to the message body (the default behavior). The nPosition parameter of a body attachment is -1.

Set MAPI_PEEK when you don't want MAPIReadMail to mark the message as read. Any unsuccessful return leaves the message unread.

ulReserved	Reserved for future use. This parameter must be 0.

lppMessage	A long pointer to a pointer set by MAPIReadMail to a message structure containing the message contents. All fields in the message structure are allocated from a single block, so the caller can free the entire structure with a call to MAPIFreeBuffer.

When MAPIReadMail is called, all message attachments are written to temporary files. It is the caller's responsibility to delete these files when they are no longer needed. When MAPI_ENVELOPE_ONLY or MAPI_SUPPRESS_ATTACH is set, no temporary files are written and no temporary names are filled into the file attachment descriptors.

Return Value	Meaning

If an error occurs, no memory was allocated and you do not need to deallocate the memory with MAPIFreeBuffer.

MAPI_E_ATTACHMENT_

WRITE_FAILURE	An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_DISK_FULL	The disk is full.

MAPI_E_FAILURE	Unspecified error(s) occurred while reading the mail. No mail was read.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No mail was read.

MAPI_E_INVALID_MESSAGE	The message ID is invalid. The message ID may have been deleted or changed by another process.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No mail was read.

MAPI_E_NOT_SUPPORTED	The operation was unsupported by the underlying mail system.

MAPI_E_TOO_MANY_FILES	Too many file attachments were contained in the message. No mail was read.

MAPI_E_TOO_MANY_

RECIPIENTS	There were too many recipients of the message. No mail was read.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIFindNext, MAPIFreeBuffer, MAPILogon, MapiMessage, MAPISaveMail, MAPISendMail


MAPIResolveName

ULONG MAPIResolveName(lhSession, ulUIParam, lpszName, flFlags, ulReserved, lppRecip )

LHANDLE  lhSession;
ULONG  ulUIParam;
LPSTR  lpszName;
ULONG  flFlags;
ULONG  ulReserved;
lpRecipDesc  lppRecip;

Description

This function resolves a mail recipient's name (as entered by a user) to an unambiguous address list entry, optionally prompting the user to choose between ambiguous entries if necessary. A recipient descriptor is allocated and returned containing fully resolved information about the entry.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. The session handle is returned by MAPILogon and invalidated by MAPILogoff. If the value is 0, Mail initiates a session from a system default session (if one exists) or by presenting a sign-in dialog box. In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box  (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpszName	A pointer to a null-terminated string containing the name to be resolved.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_LOGON_UI 0x00000001
// Display logon UI
#define MAPI_NEW_SESSION 0x00000002
// Don't get default if available
#define MAPI_DIALOG 0x00000008
// Prompt to resolve ambig. names
#define MAPI_AB_NOMODIFY 0x00000400
// User can't modify PAB entries

Set MAPI_LOGON_UI if the function should display a sign-in dialog box (if required). When this flag isnot set, the function does not display a dialog box and returns an error if the user is not signed in.

Set MAPI_NEW_SESSION if you want to establish a session other than the current one. For instance, if a Mail client is already running, another MAPI electronic mail client can piggyback on the session created by the mail client application. Do not set if you want the default session (if it still exists). If the session passed in lhSession is not NULL, this flag is ignored.

Set MAPI_DIALOG if MAPIResolveName should attempt to resolve names by displaying a name resolution dialog box to the user. If this flag is not set, resolutions which do not result in a single name will return MAPI_E_AMBIG_RECIP.

Set MAPI_AB_NOMODIFY if the details of the entry should not be modifiable even if the entry belongs to the personal address book. (Part of the resolution dialog box could involve displaying details about the various entries that match the lpszName parameter. Set this flag if these details should not be modifiable.) This flag is ignored if MAPI_DIALOG is not set.

ulReserved	Reserved for future use. This parameter must be 0.

lppRecip	The address of a pointer to a recipient structure set by MAPIResolveName if the resolution results in a single match. The structure contains the recipient information of the resolved name. The descriptor can then be used in calls to MAPISendMail, MAPISaveMail, and MAPIAddress. This memory must be freed using MAPIFreeBuffer.

Return Value	Meaning

(If an error occurs, no memory was allocated and you do not need to deallocate the memory with MAPIFreeBuffer.)

MAPI_E_AMBIG_RECIP	One or more recipients was specified ambiguously, or the ulEIDSize parameter is zero. The name was not resolved.

MAPI_E_FAILURE	Unspecified error(s) occurred while addressing the mail. The name was not resolved.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. The name was not resolved.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. The name was not resolved.

MAPI_E_NO_RECIP	No name was specified in the lpszName parameter.

MAPI_E_NOT_SUPPORTED	The operation was unsupported by the underlying mail system.

MAPI_E_USER_ABORT	The user canceled the process. The name was not resolved.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIAddress, MAPIFreeBuffer, MAPILogoff, MAPILogon, MAPISaveMail, MAPISendMail


MAPISaveMail

ULONG MAPISaveMail( lhSession, ulUIParam, lpMessage, flFlags, ulReserved, lpszMessageID)

LHANDLE  lhSession;
ULONG  ulUIParam;
lpMapiMessage  lpMessage;
ULONG  flFlags;
ULONG  ulReserved;
LPSTR  lpszMessageID;

Description

This function saves a message, optionally replacing an existing message. You should use MAPILogon to establish a valid MAPI session, and then use MAPIFindNext before calling MAPISaveMail to verify that the message to be saved is the correct one. The elements of the message identified by the lpszMessageID parameter are replaced by the elements in the lpMessage parameter. If the lpszMessageID parameter is empty, a new message is created. All replaced messages are saved in their appropriate folders. New messages are saved in the folder appropriate for incoming messages of that class.

The new message ID is returned in the lpszMessageID parameter on completion of the call.

Parameter	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. Session handles are returned by MAPILogon and invalidated by MAPILogoff. If the value is 0 and lpszMessageID is NULL or an empty string, Mail establishes a session from a system default session (if one exists) or by presenting a sign-in dialog box. Otherwise, calls with lhSession equal to 0 return MAPI_E_INVALID_SESSION.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpMessage	A pointer to the MapiMessage structure containing the contents of the message to be saved. With MAPISaveMail calls, the lpOriginator field is ignored. The MAPI_SENT flag is ignored.

flFlags	A bitmask of flags. Unspecified flags should always be passed as 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_LOGON_UI 0x00000001
// Display logon UI
#define MAPI_NEW_SESSION 0x00000002
// Don't get default if available

Set MAPI_LOGON_UI if the function should display a sign-in dialog box (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not signed in.

Set MAPI_NEW_SESSION to establish a session other than the current one. For instance, if a mail client is already running, another MAPI electronic mail client can piggyback on the session created by the mail client application. Do not set this flag if you want the default session (if it still exists). If the session passed in lhSession is not NULL, this flag is ignored.

ulReserved	Reserved for future use. This parameter must be 0.

lpszMessageID 	A string identifier for this message. It is returned by the MAPIFindNext function or a previous call to MAPISaveMail. NULL is not a valid pointer value for this parameter. If a new message is to be created, this parameter should point to an empty string. Message ID strings must be allocated by the caller and must be able to hold at least 64 characters.

Return Value	Meaning

MAPI_E_DISK_FULL	The disk is full.

MAPI_E_FAILURE	Unspecified error(s) occurred while saving the mail. No mail was saved.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No mail was saved.

MAPI_E_INVALID_MESSAGE	An invalid message ID was used for the lpszMessageID parameter. No mail was saved.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No mail was saved.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. Mail wasn't saved.

MAPI_E_NOT_SUPPORTED	The operation was unsupported by the underlying mail system.

MAPI_E_USER_ABORT	The user canceled the process. No mail was saved.

SUCCESS_SUCCESS	The function returned successfully.

See Also

MAPIFindNext, MAPILogoff, MAPILogon


MAPISendDocuments

ULONG MAPISendDocuments(ulUIParam, lpszDelimChar, lpszFilePaths, lpszFileNames, ulReserved)

ULONG  ulUIParam;
LPSTR  lpszDelimChar;
LPSTR  lpszFilePaths;
LPSTR  lpszFileNames;
ULONG  ulReserved;

Description

The MAPISendDocuments function sends a standard mail message. Calling the function displays a Send Note dialog box, which prompts the user to send a Mail message with data file attachments. Attachments can include the active document or all the currently open documents in the Windows-based application that called MAPISendDocuments. The function is used primarily for calls from a macro or scripting language, often found in applications such as spreadsheets or word processors.

The user's default sign-in identification is used when sending the mail. If there is no default identification when this function is called, a standard sign-in dialog box appears. After the user provides a mailbox name and password, the Send Note dialog box appears.

The user's default messaging options are used as the default dialog box values. The function caller is responsible for deleting temporary files created when using this function.

Parameter	Description

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to an ULONG. A value of 0 specifies that the Send Note dialog box is application modal.

lpszDelimChar	A pointer to a character used to delimit the names in the lpszFilePaths and lpszFileNames parameters. This character should not be used in filenames on your operating system.

lpszFilePaths	A pointer to a null-terminated list of full paths (including drive letters) for the attached files. The list is formed by concatenating correctly formed file paths separated by the character specified in the lpszDelimChar parameter and followed by a null terminator. An example for a Windows or MS-DOS system is:

C:\TMP\TEMP1.DOC;C:\TMP\TEMP2.DOC

The files specified in this parameter are added to the message as file attachments.

If this parameter is null or contains an empty string, then the Send Note dialog box is displayed with no attached files.

lpszFileNames	A pointer to a null-terminated list of the original filenames (in 8.3 format) as they should appear in the message. When multiple names are specified, the list is formed by concatenating the filenames separated by the character specified in the lpszDelimChar parameter and followed by a null terminator. An example for Windows and MS-DOS systems is:

MEMO.DOC;EXPENSES.DOC

Note that the icon displayed for a file is based on the filename extension supplied in this parameter. For example, a filename with an .XLS extension appears with a Microsoft Excel icon. Mail also relies on the file extension when opening and saving a file. If an attached file has no extension, you should append the default extension for your application's document type.

ulReserved	Reserved for future use. This parameter must be 0.

Return Value	Meaning

MAPI_E_ATTACHMENT_

OPEN_FAILURE	One or more files in the lpszFilePaths parameter could not be located. No mail was sent.

MAPI_E_DISK_FULL	The disk is full.

MAPI_E_FAILURE	Unspecified error(s) occurred while sending the mail. It is not known if the mail was sent.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. No mail was sent.

MAPI_E_USER_ABORT	The user canceled the process (from the Send Note dialog box). No mail was sent.

SUCCESS_SUCCESS	The mail was successfully sent. The caller is responsible for deleting any temporary files referenced in the lpszFilePaths parameter.

See Also

Adding the Send Command to an Application's File Menu

MAPISendDocuments Example


MAPISendDocuments Example

The following example shows how the MAPISendDocuments function is called from a Microsoft Excel macro:

CALL ("MAPI.DLL", "MAPISendDocuments", "JJCCC", 0, ";", "c:\budget.xls;c:\demo.doc", "budget.xls;demo.doc", 0)


Adding the Send Command to an Applications File Menu
Adding the Send Command to an Application's File Menu

The Send Note dialog box is displayed by calling the MAPISendDocuments function.  It allows the sender to:

Address a message to one or more recipients (in the To box). Recipients can be individuals or groups. The Address button supplies additional information. The Check Names button finds names in the postoffice.

Indicate optional recipients in the Cc box.

Type a subject line.

Attach files to a message with the Attach button.

Comment on the attachments in the body of the message.

Set message options with the Options button.

Send a message with the Send button.

Adding the Send command to the application menu involves coding your application to work correctly with the standard mail interface.

To add the Send command to an application's File menu:

(Choose the step number for additional details about the step.)

1	Check for MAPI support, and then initialize the File menu.

2	Using Windows API function calls, insert the Send command in the File menu, immediately above the Exit command.

3	Process the menu command.

4	Save temporary files.

5	Link to and call the MAPISendDocuments function.

6	Delete the temporary files and unload the library.

7	Correct any errors.

Note

See Also

MAPISendDocuments


MAPISendDocuments Note
An application's packaging or documentation may specify that the application allows sending documents via Microsoft Mail or any other mail system that offers the MAPI Simple Mail Interface.

The application's documentation or online Help should include a brief description of what the Send command on the File menu does. However, the application's documentation need not describe details of the Send Note dialog box, because this form is described in the Microsoft Mail documentation.


MAPI can be used only with mail systems that support it. To check for this support, use the Windows GetProfileInt function at application startup to check for a variable called MAPI in the [MAIL] section of the WIN.INI file. If this variable is present and nonzero, it indicates that a MAPI.DLL library is available and the required support is present. If the MAPI variable isn't found in WIN.INI or is 0, the Send command should not be added to the File menu.


If your application has other commands that you want immediately above the Exit command, insert the Send command as far down the File menu as possible.

If the application displays status messages when menu commands are selected, the status line should display Send document when the Send command is selected.

If there are no open documents in the application, the Send command should be disabled or removed from the File menu.


If your application supports editing of only one document at a time (single document interaction, or SDI) or does not allow transmittal of all open documents, go to step 4.

If your application supports multiple document interaction (MDI), display a cascading menu that contains two commands upon selection of the Send command. The first command in the cascading menu should be the name (in the 8.3 name format) of the currently active document in the application; for example, EXPENSES.XLS. The second command should be All Open Documents. If the user selects the All Open Documents command, all open documents are attached to the message.


On the local disk, save each of the files the user has selected in temporary files. Do not alter the filename or file status (saved or unsaved) of the documents as displayed by the application. In other words, copy the document as it currently exists in the application without affecting any of the file's properties. Note that a new (untitled) document never previously saved can be attached by the user, and attaching a file to a Mail message does not result in a residual file on the disk. The temporary files must be closed before calling the MAPISendDocuments function.


Call the Windows API functions to load the MAPI.DLL file. Create a function pointer to the MAPISendDocuments function. Call the MAPISendDocuments function, and pass the list of temporary file paths (lpFilePaths) and the short names of the documents (lpFileNames) as parameters. For more information on these parameters, see the Parameters section of the MAPISendDocuments reference topic.


When the MAPISendDocuments function returns control to your application, delete the temporary files, and use the Windows FreeLibrary function to unload MAPI.DLL.


None of the return values returned by the MAPISendDocuments function requires the application to display an error message to the user. For more information, see the list of return values in the MAPISendDocuments reference topic. If MAPI.DLL can't be loaded correctly, the application displays the following error message:

The Send DLL cannot be loaded. Check your Mail installation.


MAPISendMail

ULONG MAPISendMail(lhSession, ulUIParam,  lpMessage, flFlags, ulReserved)

LHANDLE  lhSession;
ULONG  ulUIParam;
lpMapiMessage  lpMessage;
ULONG  flFlags;
ULONG  ulReserved;

Description

This function sends a standard mail message. It can, at the option of the caller, prompt for user input with a dialog box or proceed without any user interaction.

The caller can optionally provide a list of recipient names, subject text, file attachments, or message text. If required message elements are not provided, the function can prompt the user for them. If the caller provides recipient names, file attachments, or message text, the function 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 the function returns to the caller;  therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied.

All strings are null-terminated and must be specified in the current character set or code page of the calling program's operating system process. In Microsoft Windows and MS-DOS environments, the character set is ANSI. In OS/2 environments, the code page is CP-850. All pointers are far pointers.

Parameter 	Description

lhSession	An opaque session handle whose value represents a session with the messaging subsystem. If the value is 0, Mail sets up a session either from a system default session (if one exists) or by presenting a sign-in dialog box. In all cases, Mail returns to its state before the call.

ulUIParam	The parent window handle for the dialog box (of type HWND) cast to a ULONG. A value of 0 specifies that any dialog box displayed is application modal.

lpMessage	A pointer to the MapiMessage structure containing the contents of the message to be sent. If the MAPI_DIALOG flag is not set, the following fields must be set for successful message delivery:

lpMessage.nRecipCount

lpMessage.lpRecips

All other fields are optional. Unused pointers should be NULL. Unused integers should be 0. The following fields are ignored:

lpMessage.lpszDateReceived

lpMessage.lpszOriginator

lpMessage.flFlags -> MAPI_UNREAD

lpMessage.flFlags -> MAPI_SENT

Recipients (lpRecips)

If no recipients are specified, a pointer value of NULL should be assigned to the lpMessage.lpRecips field.

The recipient descriptor can include either the recipient's name or the recipient's name-address pair. If only a name is specified, the name is resolved to an address using implementation-defined address book search rules. If an address is also specified, a search for the name is not performed. The address is in an implementation-defined format and is assumed to have been obtained from the implementation some other way. When the address is specified, the name is used for display to the user and the address is used for delivery.

When the EntryID is used, no search is performed and the display name and address are ignored. (A name and address are associated with the EntryID within Mail.) EntryIDs are returned by the MAPIReadMail function.

Attachments (lpFiles)

The number of attachments per message may be limited in some systems. If the limit is exceeded, the error MAPI_E_TOO_MANY_FILES is returned. If 0 files are specified, a pointer value of NULL should be assigned to the lpMessage.lpFiles field.

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 body.

Subject (lpszSubject)

A pointer value of NULL indicates no subject text. Some implementations may truncate subject lines that are too long or contain carriage returns, line feeds, or other control characters.

Note Text (lpszNoteText)

A pointer value of NULL 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 may place limits on the size of the text. If this limit is exceeded, a return of MAPI_E_TEXT_TOO_LARGE is generated.

Message Type (lpszMessageType)

A pointer to a string that is the message type. This field is for use by applications other than interpersonal mail (electronic forms, game message transmittal, and so on). For an interpersonal mail message, specify a pointer value of NULL or a pointer to the empty string, "", for this field.

flFlags	A bitmask of flags. Unspecified flags should always be set to 0. Undocumented flags are reserved. The following flags are defined in MAPI.H:

#define MAPI_LOGON_UI 0x00000001
// Display logon UI
#define MAPI_NEW_SESSION 0x00000002
// Don't get default if available
#define MAPI_DIALOG 0x00000008
// Display a send note UI

Set MAPI_LOGON_UI if the function should display a dialog box to prompt for sign in (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not signed in.

Set MAPI_NEW_SESSION if you want to establish a session other than the current one. For instance, if a mail client is already running, another MAPI electronic mail client can piggyback on the session created by the mail client application. Do not set if you want the default session (if it still exists). If the session passed in lhSession is not NULL, this flag is ignored.

Set MAPI_DIALOG if the function should display a dialog box to prompt for recipients and other sending options. When this flag is not set, the function does not display a dialog box, but at least one recipient must be specified.

ulReserved	Reserved for future use. This parameter must be 0.

Return Value	Meaning

MAPI_E_AMBIG_RECIP	A recipient matched more than one of the recipient descriptor structures, and MAPI_DIALOG was
not set.

MAPI_E_ATTACHMENT_

NOT_FOUND	The specified attachment was not found. No mail was sent.

MAPI_E_BAD_RECIPTYPE	The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC.

MAPI_E_DISK_FULL	The disk is full.

MAPI_E_FAILURE	Unspecified error(s) occurred while sending the mail. No mail was sent.

MAPI_E_INSUFFICIENT_

MEMORY	There was insufficient memory to proceed. No mail was sent.

MAPI_E_INVALID_SESSION	An invalid session handle was used for the lhSession parameter. No mail was sent.

MAPI_E_LOGON_FAILURE	There was no default sign-in, and the user failed to successfully sign in when the sign-in dialog box was displayed. No mail was sent.

MAPI_E_TEXT_TOO_LARGE	The text in the message was too large to be sent. No mail was sent.

MAPI_E_TOO_MANY_FILES	There were too many file attachments. No mail was sent.

MAPI_E_TOO_MANY_

RECIPIENTS	There were too many message recipients specified. No mail was sent.

MAPI_E_TOO_MANY_

SESSIONS	The user had too many sessions open at once. No mail was sent.

MAPI_E_UNKNOWN_

RECIPIENT	The recipient did not appear in the address list. No mail was sent.

MAPI_E_USER_ABORT	The user canceled the process from the Send form. No mail was sent.

SUCCESS_SUCCESS	The function returned successfully. On all other return codes, no mail was sent.

See Also

MAPIReadMail, MAPISendMail Example


MAPISendMail Example

The following example shows the code used to send a message containing a file attachment,  and how to prompt for recipients, subject, and message text with a dialog box.

long err;
MapiFileDesc file = {0, 0, "c:\tmp\tmp.wk3", "budget17.wk3", NULL};
MapiMessage note = {0,NULL,NULL,NULL,NULL,NULL,0,NULL,0,NULL,1,&file};

err = MAPISendMail (0L,0L,&note,MAPI_DIALOG,0L);
if (err != SUCCESS_SUCCESS )
printf("Unable to send the message.\n");

The next example shows the code used to send a message to Sally Jones with a copy to the Marketing group. The message contains a spreadsheet attachment with a note, and doesn't require user interaction with a dialog box.

MapiRecipDesc recip[2];

MapiFileDesc file = {0, 0, "c:\budget17.wk3", "budget17.wk3", NULL};
MapiMessage note = {0,NULL,
"Attached is the budget proposal.\r\nSee you Monday.\r\n",
NULL,NULL,NULL,0,NULL,2,NULL,1,&file};

recip[0].ulReserved = 0;
recip[0].nRecipClass = MAPI_TO;
recip[0].lpszName = "Sally Jones";
recip[0].lpszAddress = NULL;
recip[0].ulEIDSize = 0;
recip[0].lpEntryID = NULL;

recip[1].ulReserved = 0;
recip[1].nRecipClass = MAPI_CC;
recip[1].lpszName = "Marketing";
recip[1].lpszAddress = NULL;
recip[1].ulEIDSize = 0;
recip[1].lpEntryID = NULL;

note.lpRecips = &recip;

err = MAPISendMail (0L,0L,&note,0L,0L);
if (err != SUCCESS_SUCCESS )
printf("Unable to send the message.\n");


The Send Note Dialog Box


Send Command Figure


Help Instructions

The following information is here to help you quickly find what you need in MAPI's online Help. For more information about Help, choose How to Use Help from the Help menu.

	The pointer becomes a hand when it is over a region that contains more information (a pop-up topic) or a jump to another topic. Choose this region to jump to the topic or view the pop-up topic.
	To jump to another topic, choose this highlighted text.
	To display a pop-up topic containing art, a definition, a note, or more information about this topic, choose this highlighted text. To clear a pop-up topic, click anywhere outside the popup or press ESCAPE.
	To return to the last screenload of information, click the Back button, or press B.
	To see a list of the function's return values, choose the Return Values button. This button is present only when the current topic has a Return Values section.
	To see a list of topics related to the current topic, choose the See Also button. This button is present only when the current topic has a See Also section.
	To display an example appropriate to the topic, choose the Example button. This button is present only when the current topic has an example.