3.1.4.1.4 NspiUpdateStat (Opnum 2)

  • Article

The NspiUpdateStat method updates the STAT block that represents position in a table to reflect positioning changes requested by the client.

 long NspiUpdateStat(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in, out] STAT* pStat,
   [in, out, unique] long* plDelta
 );

hRpc: An RPC context handle, as specified in section 2.2.10.

Reserved: A DWORD [MS-DTYP] value. Reserved for future use. Ignored by the server.

pStat: A pointer to a STAT block describing a logical position in a specific address book container. This parameter is used to specify both input parameters from the client and return values from the server.

plDelta: The value NULL or a pointer to a LONG [MS-DTYP] value that, on return, indicates movement within the address book container specified by the input parameter pStat. The server MUST ignore the value specified by this parameter in the request if it is not NULL.

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 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 whether the server changes its state.

  2. If the server returns any return value other than "Success", the server MUST NOT modify the output parameter pStat.

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

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

  5. The server locates the initial position row in the table specified by the ContainerID field of the input parameter pStat as follows:

    • If the row specified by the CurrentRec field of the input parameter pStat is not MID_CURRENT, the server locates that row as the initial position row using the absolute position, as specified in section 3.1.4.5.1. If the row cannot be found, the server MUST return the error "NotFound".

    • If the row specified by the CurrentRec field of the input parameter pStat is MID_CURRENT, the server locates the initial position row using the fractional position specified in the NumPos field of the input parameter pStat as specified in section 3.1.4.5.2.

  6. After locating the initial position row in the current table, the server locates the final position row by moving forward or backward in the table from the current position row as specified in the Delta field of the input parameter pStat, with the constraints specified in section 3.1.4.5 with respect to movement beyond the beginning or end of a table.

  7. If the input parameter plDelta is not null, the server MUST set it to the actual number of rows between the initial position row and the final position row. If the input parameter plDelta is null, the server MUST set the output parameter plDelta to null.

  8. The server MUST set the CurrentRec field of the parameter pStat to the Minimal Entry ID of the current row in the current address book container.

  9. The server MUST set the NumPos field of the parameter pStat to the approximate numeric position of the current row of the current address book container according to section 3.1.4.5.2.

  10. The server MUST set the TotalRecs field of the parameter pStat to the number of rows in the current address book container according to section 3.1.4.5.2.

  11. The server MUST leave all other fields of the parameter pStat unchanged.

  12. If no error condition has been specified by the previous constraints, the server MUST return "Success".