3.1.4.7 NspiGetProps (Opnum 9)

  • Article

The NspiGetProps method returns an address book row containing 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.3.9.

dwFlags: A DWORD value, containing 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 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.

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, then the server MUST return one of the return values specified 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 values other than ErrorsReturned or 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 server is unable to locate the address book container specified by the ContainerID field in the input parameter pStat, the server MUST return the return value InvalidBookmark.

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

    1. 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.

    2. 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 method NspiGetPropList (section 3.1.4.6) using the following parameters as inputs to method NspiGetPropList:

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

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

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

      4. The field CodePage 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 TableBig. The NSPI Protocol does not prescribe what constitutes an excessive length.

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

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

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

  10. If the server is able to 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 Property Type PtypErrorCode. Subject to the prior constraints, the server constructs a list of properties and their values as a single PropertyRow_r 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.