Share via

4 Protocol Examples

This section shows the call sequence for obtaining the address book hierarchy table at the NSPI layer. It further shows how a messaging client can use this table to retrieve properties of the Address Book objects by using the NspiQueryRows method.

It is assumed that the messaging client has established an RPC connection to the server.

Note Only parts of the details of client request parameters and server response parameters are documented, to show only the relevant information.

NSPI session message sequence example. NspiBind requests are sent from client to server. NspiBind responses are sent from server to client.

Figure 2: NSPI session message sequence example

The client initiates a session to the server by calling the NspiBind method. Messaging clients send the following values to the server.

Note Only relevant information, and not all parameters, are shown.

dwFlags        0x00000000        unsigned long
pStat
    hIndex           0x00000000        unsigned long
    ContainerID      0x00000000        unsigned long
    CurrentRec       0x00000000        unsigned long
    Delta            0x00000000        long
    NumPos           0x00000000        unsigned long
    TotalRecs        0x00000000        unsigned long
    CodePage         0x000004e4        unsigned long
    TemplateLocale   0x00000409        unsigned long
    SortLocale       0x00000409        unsigned long
pServerGuid   
<pointer to an array of 16 unsigned char to be returned by the server>

The server responds to the NspiBind method call with return code "Success" and a valid server GUID. Typical parameters are as follows.

pServerGuid
   [0x0]0xab 0xbc 0x8b 0x86 0x79 0x33 0xc4 0x48 0xa1 0xef 
   [0xa]0x1b 0x53 0xe6 0x3b 0xdc 0x46
 
contextHandle
   <a token>

The client requests the address book hierarchy table from the server by calling the NspiGetSpecialTable method with dwFlags parameter typically set to the NspiUnicodeStrings bit flag. More importantly, the client does not set the NspiAddressCreationTemplates flag. Typical parameters are as follows.

dwFlags        0x00000004        unsigned long
pStat
     hIndex             0x00000000        unsigned long
     ContainerID        0x00000000        unsigned long
     CurrentRec         0x00000000        unsigned long
     Delta              0x00000000        long
     NumPos             0x00000000        unsigned long
     TotalRecs          0x00000000        unsigned long
     CodePage           0x000004e4        unsigned long
     TemplateLocale     0x00000409        unsigned long
     SortLocale         0x00000409        unsigned long
ppRows
<memory location that holds _PropertyRowSet_r** returned by the 
  server>

The server responds to the NspiGetSpecialTable method call with return code "Success", and the rows of the address book hierarchy table typically have the following columns set, as described in [MS-OXOABK]:

  • PidTagEntryId

  • PidTagContainerFlags

  • PidTagDepth

  • PidTagAddressBookContainerId

  • PidTagDisplayName

  • PidTagAddressBookIsMaster.

In this example, the server did not return the optional PidTagAddressBookParentEntryId property. Typical parameters are as follows.

Note Only relevant information, and not all return parameters, are shown.

ppRows_PropertyRowSet_r * *
      {
          cRows=0x00000007 
          aRow=<a pointer to an array of rows> 
      } 

In this example, the server has returned a total of seven rows, denoted as [0x0]...[0x6], and each row typically looks as follows.

aRow[0x0] ... [0x6]_PropertyRow_r  * 
     {
         Reserved=0x00000000 
         cValues=0x00000006 
         lpProps=<a pointer to an array of columns>
     }

In this example, the server has returned a column set of six properties, and each column looks as follows.

[0x0]_PropertyValue_r
      {
      ulPropTag=PidTagEntryId
        dwAlignPad=0x00000000 
        Value={...} 
      }
[0x1]_PropertyValue_r
     {
        ulPropTag=PidTagContainerFlags
        dwAlignPad=0x00000000 
        Value={...} 
     }
[0x2]_PropertyValue_r
     {
       ulPropTag=PidTagDepth
       dwAlignPad=0x00000000 
       Value={...} 
     }
[0x3]_PropertyValue_r 
     {
       ulPropTag=PidTagAddressBookContainerId
       dwAlignPad=0x00000000 
       Value={...} 
     }
[0x4]_PropertyValue_r
     {
       ulPropTag=PidTagDisplayName
       dwAlignPad=0x00000000 
       Value={...} 
     }
[0x5]_PropertyValue_r 
     {
       ulPropTag=PidTagAddressBookIsMaster
       dwAlignPad=0x00000000 
       Value={...} 
     }

Note The client can invoke additional NSPI calls to access other information from the server before calling the NspiUnbind method.

Messaging clients call the NspiQueryRows method to retrieve various properties of Address Book objects. The following example shows the client requesting the server a total of two rows that contain the following properties:

  • PidTagEntryId

  • PidTagDisplayName

  • PidTagSmtpAddress

  • PidTagTitle.

Also, the client is requesting the server to use the pStat structure for table information by setting lpETable NULL and setting relevant values in the pStat structure. Typical parameters are as follows.

Note Only relevant information, and not all return parameters, are shown.

pStat
     hIndex           0x00000000        unsigned long
     ContainerID      0x00000000        unsigned long
     CurrentRec       0x00000000        unsigned long
     Delta            0x00000000        long
     NumPos           0x00000000        unsigned long
     TotalRecs        0xffffffff        unsigned long
     CodePage         0x000004e4        unsigned long
     TemplateLocale   0x00000409        unsigned long
     SortLocale       0x00000409        unsigned long
dwETableCount0        0x00000000        unsigned long
lpETable              0x00000000        unsigned long *
Count                 0x00000002        unsigned long
Flags                 0x00000000        unsigned long
pPropTags_PropertyTagArray_r * 
     {
        cValues=0x00000004
        aulPropTag=<a pointer to an array of properties> 
     }
     aulPropTag<array of 4 PropTags>
      [0x0]PidTagEntryId        unsigned long
      [0x1]PidTagDisplayName    unsigned long
      [0x2]PidTagSmtpAddress    unsigned long
      [0x3]PidTagTitle          unsigned long

The server responds to the NspiQueryRows method call with return code "Success" and a row set. Typical return parameters are as follows.

Note Only relevant information, and not all parameters, are shown.

dwFlags    0x00000000unsigned long
pStat
     hIndex             0x00000000        unsigned long
     ContainerID        0x00000000        unsigned long
     CurrentRec         0x00001928        unsigned long
     Delta              0x00000000        long
     NumPos             0x00000002        unsigned long
     TotalRecs          0x00000016        unsigned long
     CodePage           0x000004e4        unsigned long
     TemplateLocale     0x00000409        unsigned long
     SortLocale         0x00000409        unsigned long
 
dwETableCount   0x00000000        unsigned long
lpETable        0x00000000        unsigned long *
Count           0x00000002        unsigned long
pPropTags_PropertyRowSet_r * *
{
          cRows=0x00000002 
          aRow=<a pointer to an array of rows> 
}

In this example, the server has returned a total of 0x2 rows denoted as [0x0]...[0x1] equal to the number of rows requested by the client. Each row typically looks as follows.

 aRow[0x0] ... [0x1]_PropertyRow_r  * 
 {
     Reserved=0x00000000 
     cValues=0x00000004 
     lpProps=<a pointer to an array of columns>
 }

In this example, the server has returned a column set of four properties equal to the number of properties requested by the client. Each column looks as follows.

 [0x0]_PropertyValue_r
      {
          ulPropTag= PidTagEntryId
          dwAlignPad=0x00000000 
          Value={...} 
     }
 [0x1]_PropertyValue_r
      {
         ulPropTag= PidTagDisplayName
         dwAlignPad=0x00000000 
         Value={...} 
      }
 [0x2]_PropertyValue_r
      {
         ulPropTag= PidTagSmtpAddress
         dwAlignPad=0x00000000 
         Value={...} 
      }
 [0x3]_PropertyValue_r 
      {
        ulPropTag= PidTagTitle
        dwAlignPad=0x00000000 
        Value={...} 
      }

The client terminates the connection by calling the NspiUnbind method with a token that the server returned in response to the NspiBind method call.

 contextHandleNSPI_HANDLE  *
 <a token>
 dwFlags    0x00000000    unsigned long

The server responds with return code 0x00000001 and destroys the token that the client passed.