3.1.4.19 NspiResolveNamesW (Opnum 20)

  • Article

The NspiResolveNamesW method takes a set of string values in the Unicode 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 NspiResolveNamesW(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in] STAT* pStat,
   [in, unique] PropertyTagArray_r* pPropTags,
   [in] WStringsArray_r* paWStr,
   [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 containing a list of the proptags of the columns that the client requests to be returned for each row returned.

paWStr: A WStringsArray_r value. Specifies the values on which the client is requesting that the server perform ANR. 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 paWStr

ppRows: A reference to a PropertyRowSet_r. 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 Security (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 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 NspiResolveNamesW parameter hRpc is used as the NspiQueryRows parameter hRpc.

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

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

    4. The number of valid MIds constructed for the NspiResolveNamesW 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 NspiResolveNamesW 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 NspiResolveNamesW 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 NspiResolveNamesW parameter pPropTags is used as the NspiQueryRows parameter pPropTags.

      The additional constraint applies:

    • If the NspiQueryRows returns Success or ErrorsReturned, the server 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 NspiResolveNamesW 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.