3.1.4.1.7 NspiGetProps (Opnum 9)

  • Article

The NspiGetProps method returns an address book row that contains a set of the properties and values that exist on an object.

 long NspiGetProps(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD dwFlags,
   [in] STAT* pStat,
   [in, unique] PropertyTagArray_r* pPropTags,
   [out] PropertyRow_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 fEphID and fSkipObjects.

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.

pPropTags: The value NULL or a reference to a PropertyTagArray_r value. Contains list of the proptags of the properties that the client wants to be returned.

ppRows: A reference to a PropertyRow_r value. Contains the address book container row the server returns in response to the request.

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 CodePage field of the input parameter pStat is set to the value CP_WINUNICODE and the type of the proptags in the input parameter pPropTags is PtypString8, 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 if the server changes its state.

  2. If the server returns any return values other than "ErrorsReturned" (0x00040380) or "Success" (0x00000000), 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 server is unable to locate the address book container specified by the ContainerID field in the input parameter pStat, the server MUST return the value "InvalidBookmark" (0x80040405).<5>

  5. The server constructs a list of proptags for which it will return property values as follows:

    • If the input parameter pPropTags is not NULL, the client is requesting the server return only those properties and their values in the output parameter ppRows. The server MUST use this list.

    • If the input parameter pPropTags is NULL, the client is requesting that the server constructs a list of proptags on its behalf. The server MUST construct a proptag list that is exactly the same list that would be returned to the client in the pPropTags output parameter of the NspiGetPropList method, as specified in section 3.1.4.1.6, using the following parameters as inputs to the NspiGetPropList method:

      • The NspiGetProps parameter hRpc is used as the NspiGetPropList parameter hRpc.

      • The NspiGetProps parameter dwFlags is used as the NspiGetPropList parameter dwFlags.

      • The CurrentRec field of the NspiGetProps parameter pStat is used as the NspiGetPropList parameter dwMId.

      • The CodePage field of the NspiGetProps parameter pStat is used as the NspiGetPropList parameter CodePage.

    • If a call to the NspiGetPropList method with these parameters and relaxed constraints would return anything other than "Success", the server MUST return that error code as the return value for the NspiGetProps method.

  6. If the length of the list of proptags for which the server will return property values is excessive, the server MUST return the return value "TableTooBig", as specified in [MS-OXCDATA] section 2.4. The Exchange Server NSPI Protocol does not prescribe what constitutes an excessive length.

  7. If input parameter dwFlags contains the bit flag fEphID and the PidTagEntryId property is present in the list of proptags, the server MUST return the values of the PidTagEntryId property in the Ephemeral Entry ID format, as specified in section 2.2.9.2.

  8. If input parameter dwFlags does not contain the bit flag fEphID and the PidTagEntryId property is present in the list of proptags, the server MUST return the values of the PidTagEntryId property in the Permanent Entry ID format, as specified in section 2.2.9.3.

  9. The server MUST return string-valued properties in the code page specified in CodePage field of the input parameter pStat, as specified in section 3.1.4.3.

  10. If the server can locate the object specified in the CurrentRec field of the input parameter pStat, the server MUST return values associated with this object.

  11. If the server is unable to locate the object specified in the CurrentRec field of the input parameter pStat, the server MUST proceed as if the object was located but had no values for any properties.

  12. If a property in the proptag list has no value on the object specified by the CurrentRec field, the server MUST return the error code ErrorsReturned. The server MUST set the aulPropTag member corresponding to the proptag with no value with the proptag that has no value with the PtypErrorCode property type. Subject to the prior constraints, the server constructs a list of properties and their values as a single PropertyRow_r structure with a one-to-one order preserving correspondence between the values in the proptag list specified by input parameters and the returned properties and values in the RowSet. If there are duplicate properties in the proptag list, the server MUST create duplicate values in the parameter RowSet. The server MUST return this RowSet in the output parameter ppRows.

  13. If no other return values have been specified by these constraints, the server MUST return the return value "Success".