3.1.4.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.3.9.

dwFlags:  A DWORD value containing 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 describing a logical position in a specific address book container. This parameter is used to both specify input parameters from the client and return values from the NSPI server.

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:  An PropertyRowSet_r. On return, holds the rows for the table that the client is requesting.

Return Values: The server returns a long value specifying 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 documented in section 2.2.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 if 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 according to 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. See the product behavior note cited in section 5.1 for more information.

  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 (section 3.1.1.3.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.

  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.

  9. If the input parameter dwFlags contains the value NspiAddressCreationTemplates, the client is requesting the rows of an Address Creation Table (section 3.1.1.3.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 (section 3.1.1.2).

  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 codepage specified by the field CodePage in the input parameter pStat. See section 3.1.1.2.

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

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