3.1.4.18 NspiResolveNames (Opnum 19)

The NspiResolveNames method takes a set of string values in an 8-bit character set and performs ANR (as specified in 3.1.1.6) on those strings. The server reports the MId that are the result of the ANR process. Certain property values are returned for any valid MIds identified by the ANR process.

 long NspiResolveNames(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in] STAT* pStat,
   [in, unique] PropertyTagArray_r* pPropTags,
   [in] StringsArray_r* paStr,
   [out] PropertyTagArray_r** ppMIds,
   [out] PropertyRowSet_r** ppRows
 );

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

Reserved: A DWORD value reserved for future use.

pStat: A reference to a STAT block describing a logical position in a specific address book container.

pPropTags: The value NULL or a reference to a PropertyTagArray_r value containing a list of the proptags of the columns that the client requests to be returned for each row returned.

paStr: A StringsArray_r value. Specifies the values the client is requesting the server to do ANR on. The server MUST apply any necessary character set conversion as specified in String Handling (section 3.1.1.2).

ppMIds: A PropertyTagArray_r value. On return, contains a list of MIds matching the array of strings, as specified in the input parameter paStr.

ppRows: A reference to a PropertyRowSet_r value. Contains the address book container rows that 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 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 input parameter Reserved1 contains any value other than 0, 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.

  3. If the server returns any return value other than Success, the server MUST return the value NULL in the return parameters ppMIds and ppRows.

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

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

  6. The server constructs a list of the MIds defined in section 2.2.9 to return to the client. These MIds are those that result from applying the ANR process (see section 3.1.1.6) to the strings in the input parameter paStr. This list is in a one-to-one order preserving correspondence with the strings in the input parameter paStr. The server MUST return this list of MIds in the output parameter ppMIds.

  7. Subject to the prior constraints, the server MUST construct an PropertyRowSet_r to return to the client. This PropertyRowSet_r MUST be exactly the same PropertyRowSet_r that would be returned via the method NspiQueryRows with the following parameters:

    1. The NspiResolveNames parameter hRpc is used as the NspiQueryRows parameter hRpc.

    2. The value 0 is used as the NspiQueryRows parameter dwFlag.

    3. The NspiResolveNames parameter pStat is used as the NspiQueryRows parameter pStat.

    4. The number of valid MIds constructed for the NspiResolveNames output parameter ppMIds (that is, all those MIds not equal to MID_AMBIGUOUS or MID_UNRESOLVED) is used as the NspiQueryRows parameter dwETableCount.

    5. The list of valid MIds constructed for the NspiResolveNames output parameter ppMIds (that is, all those MIds not equal to MID_AMBIGUOUS or MID_UNRESOLVED) is used as the NspiQueryRows parameter lpETable. These MIds are expressed as a simple array of DWORD values rather than as a PropertyTagArray_r value.

    6. The number of valid MIds constructed for the NspiResolveNames output parameter ppMIds (that is, all those MIds not equal to MID_AMBIGUOUS or MID_UNRESOLVED) is used as the NspiQueryRows parameter Count.

    7. The NspiResolveNames parameter pPropTags is used as the NspiQueryRows parameter pPropTags.

      And the additional constraint:

    • If the NspiQueryRows returns Success or ErrorsReturned, the method MUST return the number of rows specified by the input parameter Count.

      If the method NspiQueryRows with the specified parameters and additional constraint would return any value other than Success or ErrorsReturned, the NspiResolveNames method MUST return that error code. If the NspiQueryRows would return either Success or ErrorsReturned, the server MUST return the constructed PropertyRowSet_r in the output parameter ppRows.

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