Share via

3.1.4.1.16 NspiResolveNames (Opnum 19)

  • Article

The NspiResolveNames method takes a set of string values in an 8-bit character set and performs ANR (as specified in section 3.1.4.7 on those strings. The server reports the Minimal Entry ID that is the result of the ANR process. Certain property values are returned for any valid Minimal Entry IDs 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.2.10.

Reserved: A DWORD [MS-DTYP] reserved for future use.

pStat: A reference to a STAT block that describes 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 section 3.1.4.3.

ppMIds: A PropertyTagArray_r value. On return, contains a list of Minimal Entry IDs that match the array of strings, as specified in the input parameter paStr.

ppRows: A reference to a PropertyRowSet_r structure (section 2.2.4), which contains the address book container rows that the server returns in response to the request.

Return Values: The server returns a long value that specifies 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 specified in section 2.2.1.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 Reserved contains any value other than 0, the server MUST return one of the return values specified in section 2.2.1.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.

  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 Minimal Entry IDs specified in section 2.2.1.9 to return to the client. These Minimal Entry IDs are those that result from applying the ANR process, as specified in section 3.1.4.7, to the strings in the input parameter paStr. The server MUST return this list of Minimal Entry IDs in the output parameter ppMIds.

  7. Subject to the prior constraints, the server MUST construct a PropertyRowSet_r structure to return to the client.

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