ch6.htm

MAPI__SAPI__TAPI

    <td WIDTH="118"><tt><font FACE="Courier">Address</font></tt> </td>
    <td WIDTH="61">String</td>
    <td WIDTH="411">Provider-specific message delivery data. This can be used by the message 
    system to identify recipients who are not in an address list (one-off addresses). </td>
  </tr>
  <tr>
    <td WIDTH="118"><tt><font FACE="Courier">EIDSize</font></tt> </td>
    <td WIDTH="61">Long</td>
    <td WIDTH="411">The size (in bytes) of the opaque binary data in <tt><font FACE="Courier">EntryID</font></tt>. 
    </td>
  </tr>
  <tr>
    <td WIDTH="118"><tt><font FACE="Courier">EntryID</font></tt> </td>
    <td WIDTH="61">String</td>
    <td WIDTH="411">A binary string used by Mail to efficiently specify the recipient. Unlike 
    the Address field, this data is opaque and is not printable. Mail returns valid <tt><font
    FACE="Courier">EntryID</font></tt>s for recipients or originators included in the address 
    list. </td>
  </tr>
</table>
</center></div>

<hr>

<blockquote>
  <b><p>Listing 6.2. The <tt><font FACE="Courier">MAPIRecip</font></tt> user-defined type.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>'************************************************ <br>
  '&nbsp;&nbsp;&nbsp;MAPIRecip holds information about a message <br>
  '&nbsp;&nbsp;&nbsp;originator or recipient<br>
  '************************************************<br>
  <br>
  Type MapiRecip<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Reserved As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;RecipClass As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Name As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Address As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;EIDSize As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;EntryID As String<br>
  End Type</font></tt> </p>
</blockquote>

<hr>

<h4><tt><font FACE="Courier">MAPIFile</font></tt></h4>

<p>The last structure used by SMAPI is the <tt><font FACE="Courier">MAPIFile</font></tt> 
structure. This user-defined type holds all the information about a message attachment. 
Table 6.3 describes the structure, and Listing 6.3 shows the UDT definition.<br>
</p>

<p align="center"><b>Table 6.3. The <tt><font FACE="Courier">MAPIFile</font></tt> 
structure.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Field</i></td>
    <td WIDTH="80"><i>Type</i></td>
    <td WIDTH="382"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">Reserved</font></tt> </td>
    <td WIDTH="80">Long</td>
    <td WIDTH="382">Reserved for future use. This field must be 0. </td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">Flags</font></tt></td>
    <td WIDTH="80">Long</td>
    <td WIDTH="382">A bitmask of flags. Unused flags are reserved and must be 0. The following 
    flags are defined: <br>
    <tt><font FACE="Courier">MAPI_OLE<br>
    MAPI_OLE_STATIC<br>
    MAPI_OLE</font></tt> is set if the attachment is an OLE object. If <tt><font
    FACE="Courier">MAPI_OLE_STATIC</font></tt> is also set, the attachment is a static OLE 
    object rather than an embedded OLE object. </td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">Position</font></tt> </td>
    <td WIDTH="80">Long</td>
    <td WIDTH="382">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 <tt><font FACE="Courier">MapiMessage</font></tt> 
    type field <tt><font FACE="Courier">NoteText[Position]</font></tt>. 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. </td>
  </tr>
  <tr>
    <td WIDTH="128">Field</td>
    <td WIDTH="80">Type</td>
    <td WIDTH="382">Description </td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">PathName</font></tt> </td>
    <td WIDTH="80">String</td>
    <td WIDTH="382">The full pathname of the attached file. The file should be closed before 
    this call is made. </td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">FileName</font></tt> </td>
    <td WIDTH="80">String</td>
    <td WIDTH="382">The filename seen by the recipient. This name may differ from the filename 
    in <tt><font FACE="Courier">PathName</font></tt> if temporary files are being used. If <tt><font
    FACE="Courier">FileName</font></tt> is empty, the filename from <tt><font FACE="Courier">PathName</font></tt> 
    is used. If the attachment is an OLE object, <tt><font FACE="Courier">FileName</font></tt> 
    contains the class name of the object; for example, &quot;Microsoft Excel Worksheet.&quot; 
    </td>
  </tr>
  <tr>
    <td WIDTH="128"><tt><font FACE="Courier">FileType</font></tt> </td>
    <td WIDTH="80">Long</td>
    <td WIDTH="382">A reserved descriptor that is used to indicate to the recipient the type 
    of the attached file. An empty string indicates an unknown or operating system-determined 
    file type. Use 0 for this parameter at all times. </td>
  </tr>
</table>
</center></div>

<hr>

<blockquote>
  <b><p>Listing 6.3. The <tt><font FACE="Courier">MAPIFile</font></tt> user-defined type.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>'****************************************************** <br>
  '&nbsp;&nbsp;&nbsp;MapiFile holds information about file attachments <br>
  '******************************************************<br>
  <br>
  Type MapiFile<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Reserved As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Flags As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Position As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;PathName As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;FileName As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;FileType As Long<br>
  End Type</font></tt> </p>
</blockquote>

<hr>

<p>These are the only three structures needed to establish MAPI services with the VBAMAPI 
DLLs. The next section describes each of the API calls and constants and shows you 
examples of how to use them. </p>

<h3><a NAME="TheAPIFunctions">The API Functions</a></h3>

<p>There are eleven SMAPI API calls. This set of calls provides access to the core MAPI 
services including 

<ul>
  <li><font COLOR="#000000">Logging on and logging off MAPI sessions</font> </li>
  <li><font COLOR="#000000">Gaining access to the MAPI address book</font> </li>
  <li><font COLOR="#000000">Reading, sending, saving, and deleting MAPI Messages</font> </li>
  <li><font COLOR="#000000">Performing address validations and lookups</font> </li>
  <li><font COLOR="#000000">Handling binary message attachments</font> </li>
</ul>

<p>The next several sections describe each of the API calls and provide Visual Basic 4.0 
examples of how to use them. </p>

<p>If you haven't already done so, start Visual Basic 4.0 and load the <tt><font
FACE="Courier">VBAMAP32.BAS</font></tt> module into your project. Listing 6.4 shows the 
complete set of API calls for SMAPI. You do not have to type this information into your 
project. You can find this module in the <tt><font FACE="Courier">Chap06</font></tt> 
directory that was created when you installed the source code from the CD-ROM. </p>

<hr>

<blockquote>
  <b><p>Listing 6.4. The Simple MAPI API call declarations.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>'***************************<br>
  '&nbsp;&nbsp;&nbsp;FUncTION Declarations<br>
  '***************************<br>
  <br>
  Declare Function MAPILogon Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPILogon&quot; 
  (ByVal UIParam&amp;, &Acirc;ByVal User$, ByVal Password$, ByVal Flags&amp;, ByVal 
  Reserved&amp;, Session&amp;) As Long<br>
  <br>
  Declare Function MAPILogoff Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPILogoff&quot; 
  (ByVal Session&amp;, &Acirc;ByVal UIParam&amp;, ByVal Flags&amp;, ByVal Reserved&amp;) As 
  Long<br>
  <br>
  Declare Function MAPIDetails Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPIDetails&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, Recipient As MapiRecip, ByVal Flags&amp;, 
  ByVal Reserved&amp;) &Acirc;As Long<br>
  <br>
  Declare Function MAPIResolveName Lib &quot;VBAMAP32.DLL&quot; Alias 
  &quot;BMAPIResolveName&quot; (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, ByVal 
  UserName$, ByVal Flags&amp;, ByVal Reserved&amp;, &Acirc;Recipient As MapiRecip) As Long<br>
  <br>
  Declare Function MAPISendDocuments Lib &quot;VBAMAP32.DLL&quot; Alias 
  &quot;BMAPISendDocuments&quot; &Acirc;(ByVal UIParam&amp;, ByVal DelimStr$, ByVal 
  FilePaths$, ByVal FileNames$, ByVal &Acirc;Reserved&amp;) As Long<br>
  <br>
  Declare Function MAPIFindNext Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPIFindNext&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, ByVal MsgType$, ByVal SeedMsgID$, ByVal 
  Flag&amp;, ByVal &Acirc;Reserved&amp;, MsgID$) As Long<br>
  <br>
  Declare Function MAPIDeleteMail Lib &quot;VBAMAP32.DLL&quot; Alias 
  &quot;BMAPIDeleteMail&quot; (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, ByVal MsgID$, 
  ByVal Flags&amp;, ByVal Reserved&amp;) As Long<br>
  <br>
  Declare Function MAPIAddress Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPIAddress&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, ByVal Caption$, ByVal EditFields&amp;, 
  ByVal Label$, &Acirc;RecipCount&amp;, Recipients() As MapiRecip, ByVal Flags&amp;, ByVal 
  Reserved&amp;) As Long<br>
  <br>
  Declare Function MAPISaveMail Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPISaveMail&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, Message As MapiMessage, Recipient As 
  MapiRecip, File As &Acirc;MapiFile, ByVal Reserved&amp;, MsgID$) As Long<br>
  <br>
  Declare Function MAPISendMail Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPISendMail&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, Message As MapiMessage, Recipient As 
  MapiRecip, File As &Acirc;MapiFile, ByVal Flags&amp;, ByVal Reserved&amp;) As Long<br>
  <br>
  Declare Function MAPIReadMail Lib &quot;VBAMAP32.DLL&quot; Alias &quot;BMAPIReadMail&quot; 
  (ByVal &Acirc;Session&amp;, ByVal UIParam&amp;, ByVal MsgID$, ByVal Flags&amp;, ByVal 
  Reserved&amp;, Message As &Acirc;MapiMessage, Originator As MapiRecip, recips() As 
  MapiRecip, files() As MapiFile) &Acirc;As Long</font></tt> </p>
</blockquote>

<hr>

<p>There are also a number of <tt><font FACE="Courier">CONSTANT</font></tt> declarations 
needed to make the API calls easier to work with. Listing 6.5 shows the error constants 
and flag declarations used for SMAPI. </p>

<hr>

<blockquote>
  <b><p>Listing 6.5. The SMAPI constants.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>'**************************<br>
  '&nbsp;&nbsp;&nbsp;CONSTANT Declarations<br>
  '**************************<br>
  '<br>
  <br>
  Global Const SUccESS_SUccESS = 0<br>
  Global Const MAPI_USER_ABORT = 1<br>
  Global Const MAPI_E_FAILURE = 2<br>
  Global Const MAPI_E_LOGIN_FAILURE = 3<br>
  Global Const MAPI_E_DISK_FULL = 4<br>
  Global Const MAPI_E_INSUFFICIENT_MEMORY = 5<br>
  Global Const MAPI_E_BLK_TOO_SMALL = 6<br>
  Global Const MAPI_E_TOO_MANY_SESSIONS = 8<br>
  Global Const MAPI_E_TOO_MANY_FILES = 9<br>
  Global Const MAPI_E_TOO_MANY_RECIPIENTS = 10<br>
  Global Const MAPI_E_ATTAchMENT_NOT_FOUND = 11<br>
  Global Const MAPI_E_ATTAchMENT_OPEN_FAILURE = 12<br>
  Global Const MAPI_E_ATTAchMENT_WRITE_FAILURE = 13<br>
  Global Const MAPI_E_UNKNOWN_RECIPIENT = 14<br>
  Global Const MAPI_E_BAD_RECIPTYPE = 15<br>
  Global Const MAPI_E_NO_MESSAGES = 16<br>
  Global Const MAPI_E_INVALID_MESSAGE = 17<br>
  Global Const MAPI_E_TEXT_TOO_LARGE = 18<br>
  Global Const MAPI_E_INVALID_SESSION = 19<br>
  Global Const MAPI_E_TYPE_NOT_SUPPORTED = 20<br>
  Global Const MAPI_E_AMBIGUOUS_RECIPIENT = 21<br>
  Global Const MAPI_E_MESSAGE_IN_USE = 22<br>
  Global Const MAPI_E_NETWORK_FAILURE = 23<br>
  Global Const MAPI_E_INVALID_EDITFIELDS = 24<br>
  Global Const MAPI_E_INVALID_RECIPS = 25<br>
  Global Const MAPI_E_NOT_SUPPORTED = 26<br>
  <br>
  Global Const MAPI_E_NO_LIBRARY = 999<br>
  Global Const MAPI_E_INVALID_PARAMETER = 998<br>
  <br>
  Global Const MAPI_ORIG = 0<br>
  Global Const MAPI_TO = 1<br>
  Global Const MAPI_cc = 2<br>
  Global Const MAPI_Bcc = 3<br>
  <br>
  Global Const MAPI_UNREAD = 1<br>
  Global Const MAPI_RECEIPT_REQUESTED = 2<br>
  Global Const MAPI_SENT = 4<br>
  <br>
  <br>
  Listing 6.5. continued<br>
  '***********************<br>
  '&nbsp;&nbsp;&nbsp;FLAG Declarations<br>
  '***********************<br>
  <br>