SocMapi.DLL
Easy Xbase++
accessible interface to Windows MAPI
- Version 1.02 -
This is
freeware and can be freely distributed. It is offered ôas isö, the author does
not take any responsibility. Comments welcome to AndiEnzinger@compuserve.com
This dll
offers easy access to most commonly needed Windows MAPI functions (Windows
Messaging API) for Xbase++ programmers. It has been tested to work with
MS-Outlook, MS-Outlook Express in Windows 98 / Windows 2000 / Windows XP
environments. However it should work with any e-mail program, which is
registered as main e-mail program for windows.
This
version offers a set of functions for sending mails and poll the inbox for received
mails. Since Xbase++ does not easily let the programmer exchange Structures or
pointers with APIs, all parameters are to be passed as integers or strings,
resp. reference to string buffers. The send-mail functions include popping up
the e-mail editor with preset addresses, subject, message text and attachments,
or directly store a mail to the outbox. The inbox-poll functions give access to
message items like ôsubject, message, receipt date, recipientsö and also lets
access file attachments. Messages can be marked as read after polling, or
deleted from the inbox if applicable.
This
attached file is Xbase++ sample code and demonstrates the usage of the
interface functions. An overview of the interface functions is at the end of
this document. Here is a short outline what MAPIDEMO.PRG does:
1. INIT
PROCEDURE SocMapiI()
Is invoked
automatically at startup. It loads the SocMapi.dll library and initialises
handles to all exported dll functions. Which then can be accessed with
DllEcecuteCall(). It then calls SocMapiInit(),which initialises the Windows MAPI (generally
MAPI32.DLL). An according call to SocMapiDeInit() at program shutdown is not necessary.
2. PROCEDURE
Main()
Calls SocMapiLogon(), which opens a MAPI session. The
MAPI session can be left logon, until all MAPI activities are done but should
be at least logged off with SocMapiLogoff() at program shutdown. Only one MAPI Session at
a time is supported.
3. PROCEDURE
DemoSendMail()
Demonstrates
the SendMail functions. SocMapiSendMail()opens the mail editor with preset data, SocMapiPostMail() directly stores a mail to the
outbox. Both functions receive 5 parameters:
-
cAdresses: Is a string with one or several e-mail
addresses, delimited with a semicolon ô;ö. CC or BCC addresses are indicated
with the prefix ôCC:öá resp. ôBCC:ö. (Up
to 256 adresses can be passed theoretically. Has not been tested yet)
-
cSubject: Is a string with the Message Subject.
-
cMessage: Is a string with the Message Text.
-
cAttachments: Is a string with the full path names of the
attachments. Several attachments are delimited with a semicolon ô;ö.
(theoretically up to 256 attachments û not yet tested.)
-
nFlags: Is an integer with the message flags. Combine
several flags by adding them. However for sending mails actually only the flag:
FLAG_RECEIPT_REQUESTED is useful. Valid Flags are #defined in MAPIDEMO.PRG. In
case no Flags are set, make sure to use NOFLAG. DonÆt leave that parameter
uninitialised.
Both functions
don┤t necessarily require a logged on MAPI session. In case no Session is
available, (no call to SocMapiLogon() has been done) a temporary session is
established, which automatically terminates after function call is completed.
The e-mail
editor dialog will popup as modal window. That is, the program execution of the
current thread stops and continues once the mail dialog has ended. Several
calls to SocMapiSendMail in parallel threads are possible, provided the mail
program supports several editor windows per MAPI Session. It appears that
Outlook express does support that, whereas Outlook seems to require one session
per dialog. (Several sessions are not supported by this interface).
4. PROCEDURE
DemoProcessInbox()
Demonstrates the Inbox poll functions. The principle
can be understood similar to the handling of a Database.
1)
Open the mail programÆs Inbox (InboxOpen())
2)
Go to first message (InboxGoTop()), which sets kind of
a ôRecord pointerö to the first message.
3)
Retrieve all items from the current message and
display them on the screen.
4)
Mark current message as read.
5)
Skip to next message (InboxSkip()) and repeat from 3.
Optionally pass a #define Flag to delete the message before skipping.
6)
Close the Inbox (InboxClose()), which frees allocated
memory.
The Demo procedure
calls AskFlag( nFlagID ). It returns 1 if a Flag is set and 0 if not
set. A message has three different flags, according Flag-IDÆs are #defined in
MAPIDEMO.PRG.
A message might contain several attachments. The
number of attachments can be determined by a Call to CountAttachments(). If this
number is not zero, the attachments can be stored to file with a call to SaveAttachments().
This stores all attachments to the Windows temp folder. The path to each
of those files then can be determined by repeated calls to GetMessageItem( nID, nItemPos ).
5. FUNCTION
GetMessageItem( nID, nItemPos )
This function is called repeatedly and returns the requested
Item indicated by nID for the current message. Valid nID┤s are #define┤d in
MAPIDEMO.PRG.
It calls AskBufferSize( nID, nItemPos ),á itÆs purpose is to determine the buffer size
necessary to hold the content of the desired message item. The size then is
used to initialise a buffer string accordingly. A reference to the large enough
buffer then is given to StuffBuffer( nID, nItemPos, @cBuffer, nBufSize ), which
fills the buffer with the desired content.
nID here is a #define constant, that indicates the
desired message item e.g. ID_SUBJECT, ID_MESSAGE, ... )
nItemPos needs to be passed, in case several items of one
type are within one message. That is the case for ID_RECIPIENTS and
ID_ATTACHMENTS. The number of Recipients resp. Attachments in one message can
be determined by a call to CountRecipients() resp.á CountAttachments(). The
returned number should be used to do a repeated call to GetMessageItem( nID, nItemPos ) within a
For/Next loop.
@cBuffer is the String buffer passed as reference to the
function, which is filled with the Item content.
@nBufSize is passed, to make sure that the buffer size is
not exceeded when the function stuffs the buffer.
Please
see MAPIDEMO.PRG for details on parameters and return values.
SocMapiIsInitááááááááááááááá Determines if MAPI is already
initialized
SocMapiInitáááááááááááááááááá Initializes MAPI
SocMapiDeInitáááááááááááááá DeInitializes MAPI
SocMapiIsLoggedOnáááááááááá Dertermines
if already logged onto a MAPI session.
SocMapiLogonááááááááááááá Loggs onto a
MAPI session
SocMapiLogoffááááááááááááá Loggs
off from a MAPI session
SocMapiSendMailáááááááááá Opens the
mail editor with some preset Data
SocMapiPostMailáááááááááá Directly
puts a mail in the outbox (without a Dialog)
InboxOpenááááááááááááááááááá Initializes
for further actions with the Inbox
InboxCloseááááááááááááááááááá Frees
memory that has been allocated with the inbox functions
InboxGoTopáááááááááááááááááá Positions the "Record pointer" to the first message in the inbox and reads it.
InboxSkipááááááááááááááááááááá Skips
to the next message in the inbox and reads it.
AskFlagááááááááááááááááááááááá Determines
the Flags of a message (unread, Receipt requested, sent)
AskBufferSizeáááááááááááááá Determines,
how much buffer must be allocated for the following "StuffBuffer"
call.
StuffBufferááááááááááááááááááá Stuffs
the buffer with a string for the desired message-element.
CountRecipientsáááááááááá Counts
the number of recipients for the current message.
CountAttachmentsáááááááááá counts
the number of attachments for the current message.
SaveAttachmentsáááááááááá Stores
all attachments of a message to temporary files.
MarkAsReadáááááááááááááááá Marks
current message as read