3.1.4.17 NspiGetIDsFromNames (Opnum 18)

  • Article

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

 long NspiGetIDsFromNames(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in] DWORD dwFlags,
   [in, range(0,100000)] DWORD cPropNames,
   [in, size_is(cPropNames)] PropertyName_r** pNames,
   [out] PropertyTagArray_r** ppPropTags
 );

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

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

dwFlags: A DWORD value. All clients MUST set this value to either 0 or the flag NspiVerifyNames.

cPropNames: A DWORD value containing the number property names supplied by the client. The value is limited to 100,000.

pNames: A reference to a PropertyName_r value. Contains a list of property names supplied by the client.

ppPropTags: A reference to a PropertyTagArray_r value. On successful return to the client, contains a list of proptags.

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 or ErrorsReturned, the server MUST return a NULL for the output parameters ppPropTags.

  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. The server constructs a list of proptags. This list MUST be in a one-to-one order preserving correspondence with the list of names specified in the input parameter pNames. The values in this list are constructed as follows:

    1. If the lpGuid field of the PropertyName_r structure that the pNames input parameter points to is NULL, the server MUST insert the proptag value 0x0000000A into the list.

    2. If the server is unable to locate a proptag corresponding to a property name, the server MUST insert the proptag value 0x0000000A into the list.

    3. If the server is able to locate a proptag corresponding to a property name, the server MUST insert the proptag thus mapped into the list. However, the Property Type of the proptag inserted into the list is modified to be UnspecifiedType, regardless of the original Property Type in the proptag thus mapped.

  4. If the proptag value 0x0000000A appears in the constructed list of proptags and the flag NspiVerifyNames appears in the input parameter dwFlags, the server MUST return the value AccessDenied.

  5. If the proptag value 0x0000000A appears in the constructed list of proptags and the flag NspiVerifyNames does not appear in the input parameter dwFlags, the server MUST return the value ErrorsReturned.

  6. Subject to the prior constraints, the server MUST return the constructed list of proptags in the output parameter ppPropTags.

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