3.1.4.1.3 NspiGetSpecialTable (Opnum 12)

  • Article

The NspiGetSpecialTable method returns the rows of a special table to the client. The special table can be an address book hierarchy table or an address creation table.

 long NspiGetSpecialTable(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD dwFlags,
   [in] STAT* pStat,
   [in, out] DWORD* lpVersion,
   [out] PropertyRowSet_r** ppRows
 );

hRpc: An RPC context handle, as specified in section 2.2.10.

dwFlags: A DWORD [MS-DTYP] value that contains a set of bit flags. The server MUST ignore values other than the bit flags NspiAddressCreationTemplates and NspiUnicodeStrings.

pStat: A pointer to a STAT block that describes a logical position in a specific address book container. This parameter is used to specify input parameters from the client.

lpVersion: A reference to a DWORD. On input, holds the value of the version number of the address book hierarchy table that the client has.

ppRows: A PropertyRowSet_r structure. On return, holds the rows for the table that the client is requesting.

Return Values: The server returns a LONG [MS-DTYP] value that specifies the return status of the method.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

Server Processing Rules: Upon receiving this message, the server MUST process the data from the message subject to the following constraints:

  1. If the input parameter dwFlags does not contain the value "NspiUnicodeStrings", and the input parameter dwFlags does not contain the value "NspiAddressCreationTemplates", and the CodePage field of the input parameter pStat contains the value CP_WINUNICODE, the server MUST return one of the return values specified in section 2.2.1.2.  No further constraints are applied to server processing of this method; in this case server behavior is undefined. Note especially that there is no constraint on the data the server returns in any output parameter other than the return value, nor is there any constraint on how or whether the server changes its state.

  2. If the server returns any return value other than "Success", the server MUST return a NULL for the output parameter ppRows.

  3. The server MAY make additional validations, as described in section 5. If the server chooses to limit the visibility of data based on these validations, the server MUST proceed as if that data did not exist in the address book.

  4. If the input parameter dwFlags contains both the value "NspiAddressCreationTemplates" and the value "NspiUnicodeStrings", the server MUST ignore the value "NspiUnicodeStrings" and proceed as if the parameter dwFlags contained only the value "NspiAddressCreationTemplates".

  5. If the input parameter dwFlags does not contain the value "NspiAddressCreationTemplates", the client is requesting the rows of the server's address book hierarchy table, as specified in section 3.1.4.4.3.1.

  6. If the client is requesting the rows of the server's address book hierarchy table and the server is not maintaining an address book hierarchy table, the server MUST return the error code "OutOfResources".

  7. If the client is requesting the rows of the server's address book hierarchy table, the input parameter lpVersion contains a version number. If the version number of the address book hierarchy table the server is holding matches this version number, the server MUST proceed as if the address book hierarchy table had no rows.<3>

  8. If the client is requesting the rows of the server's address book hierarchy table and the server returns the value "Success", the server MUST set the output parameter lpVersion to the version of the server's address book hierarchy table.<4>

  9. If the input parameter dwFlags contains the value "NspiAddressCreationTemplates", the client is requesting the rows of an address creation table, as specified in section 3.1.4.4.3.2.

  10. There is no constraint on the parameter lpVersion if the client is requesting the rows of an address creation table.

  11. If the client is requesting the rows of an address creation table, the TemplateLocale field of the input parameter pStat specifies the LCID for which the client requires an address creation table. If the server does not maintain an address creation table for that LCID, the server MUST proceed as if it maintained an address creation table with no rows for that LCID. That is, the server MUST NOT return an error code if it does not maintain an address creation table for that LCID.

  12. If the input parameter dwFlags contains the value "NspiUnicodeStrings" and the client is requesting the rows of the server's address book hierarchy table, the server MUST express string-valued properties in the table as Unicode values, as specified in section 3.1.4.3.

  13. If the input parameter dwFlags does not contain the value "NspiUnicodeStrings" and the client is requesting the rows of the server's hierarchy table, and the CodePage field of the input parameter pStat does not contain the value CP_WINUNICODE, the server MUST express string-valued properties as 8-bit strings in the code page specified by the field CodePage in the input parameter pStat. For more details, see section 3.1.4.3.

  14. The server MUST return the following properties for each container in the hierarchy, in the order listed:

    • PidTagEntryId ([MS-OXPROPS] section 2.684)

    • PidTagContainerFlags ([MS-OXPROPS] section 2.645)

    • PidTagDepth ([MS-OXPROPS] section 2.674)

    • PidTagAddressBookContainerId ([MS-OXPROPS] section 2.512)

    • PidTagDisplayName ([MS-OXPROPS] section 2.677)

    • PidTagAddressBookIsMaster ([MS-OXPROPS] section 2.545)

    • PidTagAddressBookParentEntryId ([MS-OXPROPS] section 2.559) (optional, and MUST be the seventh column if it is included)

  15. For every row returned, all of these properties except PidTagAddressBookParentEntryId MUST be present, and each of them MUST have a value prescribed under its definition.

  16. The PidTagEntryId property MUST be in the form of a PermanentEntryID structure, as section 2.2.9.3, with its PidTagDisplayType property having the value DT_CONTAINER, as specified in section 2.2.1.3, and its DN following the addresslist-dn format specification, as specified in [MS-OXOABK] section 2.2.1.1. When the object is the Global Address List (GAL) container, its DN MUST follow the gal-addrlist-dn format specification.

  17. Subject to the prior constraints, the server returns the rows of the table requested by the client in the output parameter ppRows.

  18. If no error condition has been specified by the previous constraints, the server MUST return the value "Success".