Was this page helpful?
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

4.1 Call Sequence To Retrieve Address Book Properties

This section describes the call sequence for obtaining two string properties — PidTagDisplayName (section and PidTagGivenName (section — for a mail user whose DN is "/o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/CN=Recipients/CN=user1." The following figure shows the call sequence between the client and the server.


Figure 1: Call sequence between client and server

Note This figure shows relevant information only, not all of the possible parameters. For more details about the parameters, see [MS-NSPI] and [MS-OXNSPI].

  1. The client initiates a session to the NSPI server by calling the NspiBind method. The messaging client sends in the following values to the server:

  2.  dwFlags
                  0x00000000            DWORD
                  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
           < a pointer to an array of 16 unsigned chars to be returned by the server>
  3. The server responds to the NspiBind method call with the return code "Success" and a valid server GUID. Typical parameters are as follows:

  4.  pServerGuid
                   [0x0]     0xab 0xbc 0x8b 0x86 0x79 0x33 0xc4         0x48 0xa1 0xef
                   [0xa]     0x1b 0x53 0xe6 0x3b 0xdc 0x46
                   < a token that will be used by the NspiUnbind call>
  5. The client requests the Minimal Entry ID for the DN "/o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/CN=Recipients/CN=user1" by calling the NspiDNToMId method with the following parameters:

  6.  _pNames
                   Count        0x00000001                DWORD
                   Strings                                char **
                                [0x0]                     char *
                   "/o=First Organization/ou=Exchange Administrative Group
            <a pointer to a valid memory location of type PropertyTagArray_r ** for server to return Mid>
  7. The server responds with return code of Success with a value of 0x00001927 for a Minimal Entry ID as follows:

  8.               Count         0x00000001                 DWORD
                  Strings                                  char **
                                [0x0]                      char *
                                     "/o=First Organization/ou=Exchange Administrative
                                     Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=user1"
                  cValues       0x00000001                 DWORD
                  aulPropTag                               DWORD[]
                                0x00001927                 DWORD
  9. The client requests two string properties — PidTagDisplayName (section and PidTagGivenName (section — by calling the NspiGetProps method with the following parameters:

  10. Note The Minimal Entry ID value of 0x00001927 that was obtained in step 4 is used as the CurrentRec field of the pStat parameter.

  11.  hRpc         < a valid RPC handle>                void *
     dwFlags      0x00000000               DWORD
                  hIndex                   0x00000000          unsigned long
                  ContainerID              0x00000000          unsigned long
                  CurrentRec               0x00001927          unsigned long
                  Delta                    0x00000000          long
                  NumPos                   0x00000000          unsigned long
                  TotalRecs                0x00000000          unsigned long
                  CodePage                 0x000004b0          unsigned long
                  TemplateLocale           0x00000409          unsigned long
                  SortLocale               0x00000409          unsigned long
     pPropTags            _SPropTagArray_r *
                          cValues          0x00000002          DWORD
                          aulPropTag=<a pointer to an array of proptags>
              aulPropTag                                       unsigned long []
                          [0x0]            PidTagDisplayName   unsigned long
                          [0x1]            PidTagGivenName     unsigned long
     ppRow                _SRow_r * *
              < memory location for server return values>
  12. The server responds to the NspiGetProps method call with the return code of Success. In this example, the server has returned the string value "user1" for both of the requested properties, and the return values are represented as follows:

  13.  dwFlags      0x00000000               DWORD
                  hIndex                   0x00000000           unsigned long
                  ContainerID              0x00000000           unsigned long
                  CurrentRec               0x00001927           unsigned long
                  Delta                    0x00000000           long
                  NumPos                   0x00000000           unsigned long
                  TotalRecs                0x00000000           unsigned long
                  CodePage                 0x000004b0           unsigned long
                  TemplateLocale           0x00000409           unsigned long
                  SortLocale               0x00000409           unsigned long
     pPropTags            _SPropTagArray_r *
                          cValues          0x00000002           DWORD
                          aulPropTag=<a pointer to an array of proptags>
                  aulPropTag                                    unsigned long []
                         [0x0]             PidTagDisplayName    unsigned long
                         [0x1]             PidTagGivenName      unsigned long
     ppRows      _SRowSet_r * *
                         cRows             0x00000001           DWORD
                         aRow=<a pointer to an array of rows>
  14. In this example, the server has returned a total of 0x1 row denoted as [0x0] that is represented as follows:

  15.  aRow       [0x0]     _SRow_r  *
                          cValues          0x00000002            DWORD
                          lpProps=<a pointer to an array of columns>
  16. In this example, the server has returned a column set of two properties, and each column will be represented as follows:

  17.  [0x0]     _SPropValue_r
                          ulPropTag        PidTagDisplayName      unsigned long
                                     lpszA =  "user1"char *
                          ulPropTag        PidTagGivenName        unsigned long
                                     lpszA =  "user1" char *
  18. Note The client can invoke additional NSPI calls to access other information from the server before calling the NSPIUnbind method.

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

  20.  contextHandle        NSPI_HANDLE  *
                  <a token which was sent by the server in the NspiBind call >
                         0x00000000                                unsigned long
  21. The server responds with the return code 0x00000001 and destroys the token that the client passed in.

© 2016 Microsoft