A handle is a short, signed integer. A valid handle is a non-negative integer. In the current release of MAPI, 0 (zero) is a valid session handle. A negative value for a handle indicates an error. The errors returned are the negative values of the MAPI errors documented in the Microsoft Mail Technical Reference. For example, the MAPI error MAPI_E_INVALID_RECIPS is returned as –25. SUCCESS_SUCCESS is returned as 0 (zero).
The MapiFile data type is not supported in WordBasic. To retrieve the information about the file attachments of a message, use the MAPIQueryAttachments helper function. To add file attachments, use MAPISetAttachment.
The MapiMessage data type is broken into its component data types. After MAPIReadMail returns successfully, use MAPIQuerySubject, MAPIQueryOriginator, and MAPIQueryDateReceived to retrieve envelope information about a message. Use MAPIQueryNoteText to retrieve the text of the message. Use successive calls to MAPIQueryNoteText to retrieve the text in usable chunks, since the message text can be longer than 65,280 characters, the maximum length of a WordBasic string.
Several functions use or return a handle to a MapiRecip data type, which contains the recipient list of a message. To add addresses to new messages, follow this general procedure:
1. Use MAPIAddress to allow the user to specify a recipient list.
2. Use MAPIQueryRecipientList to retrieve information about recipients in the recipient list.
3. Use MAPIResolveName to resolve ambiguous names in a recipient list.
4. Finally, use MAPISetRecipient to add recipients to the current outbound message.
See "MAPIQueryRecipientList" later in this appendix for an example of addressing messages and resolving names.
Other helper functions, which you will probably use infrequently, provide greater detail and additional functionality. MAPISetRecipientList adds a complete recipient list to the current outbound message, but the function is useful only if the list does not contain any unresolved names. MAPIQueryRecipientListCount returns the number of names in a recipient list, and MAPIQueryRecipientListElement retrieves information about a specific recipient in the list.