3.1.4.16 NspiGetNamesFromIDs (Opnum 17)

  • Article

The NspiGetNamesFromIDs method returns a list of property names for a set of proptags. 

 long NspiGetNamesFromIDs(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in, unique] FlatUID_r* lpguid,
   [in, unique] PropertyTagArray_r* pPropTags,
   [out] PropertyTagArray_r** ppReturnedPropTags,
   [out] PropertyNameSet_r** ppNames
 );

hRpc: An RPC context handle as specified in section 2.3.9.

Reserved: A DWORD value reserved for future use. Ignored by the server.

lpguid: The value NULL or a FlatUID_r value. Specifies the property set about which the client is requesting information.

pPropTags: The value NULL or a PropertyTagArray_r value. Specifies the specific Property IDs about which the client is requesting information.

ppReturnedPropTags: Contains an SPropTagArray. On return, it contains a list of all the proptags in the property set specified in the input parameter lpguid. If lpguid is NULL, this value MUST be NULL.

ppNames:  A PropertyNameSet_r value. On return, it contains a list of property names satisfying the client's 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 server returns any return value other than Success, the server MUST return a NULL for the output parameters ppReturnedPropTags and ppNames.

  2. 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. See the product behavior note cited in section 5.1 for more information.

  3. If the input parameter pPropTags has the value NULL and the input parameter lpGuid has the value PS_MAPI, as defined in [MS-OXCDATA], the server MUST return the value NotSupported.

  4. The server constructs a list of property sets as follows:

    1. If the input parameter lpGuid is not NULL, the list of property sets contains only the property set specified by the value of lpGuid.

    2. If the input parameter lpGuid is NULL, the list of property sets contains all property sets supported by the NSPI server.

  5. The server constructs a list of proptags as follows:

    1. If the input parameter pPropTags is not NULL, the list of proptags contains the proptags specified by the value of pPropTags. The list is ordered in one-to-one order preserving correspondence with the proptags specified by the input parameter pPropTags.

    2. If the input parameter pPropTags is NULL, the list of proptags contains all the proptags supported by the NSPI server. The ordering of the list is not specified.

  6. If the input parameter pPropTags has the value NULL and the input parameter lpGuid has the value NULL, the server MUST NOT return any names from the property set PS_MAPI as defined in [MS-OXCDATA].

  7. The server constructs a list of PropertyName_r structures. This list MUST be in a one-to-one order preserving correspondence with the constructed list of proptags. The values in this list are constructed as follows:

    1. If the proptag in the constructed list of proptags is not a member of one of the property sets in the constructed list of property sets, the server MUST map that proptag to a PropertyName_r structure with the lpGuid field set to the property set value NULL and the lID field set to the value 0.

    2. If the server is able to identify a proptag as being a member of a property set in the constructed list of property sets, it maps the proptag to a PropertyName_r structure with the lpGuid field set to the property set the proptag is a member of and the lID field set to the value of the proptag.

    3. If the server is otherwise unable to map a proptag to a PropertyName_r structure, the server MUST map that property to a PropertyName_r structure with the lpGuid field set to the property set value NULL and the lID field set to the value 0.

  8. The server MUST return the constructed list of PropertyName_r structures in the output parameter ppNames.

  9. If the value of the input parameter pPropTags is NULL, the server constructs a list of proptags from the elements of the list of PropertyName_r structures in the parameter ppNames. The proptags in the list of proptags are in a one-to-one order preserving correspondence with the list of PropertyName_r structures in ppNames. The server MUST return this list in the output parameter ppReturnedPropTags.

  10. If the value of the input parameter pPropTags is not NULL, the server MUST set the value of the output parameter ppReturnedPropTags to NULL.

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