3.1.4.2.141 ApiExecuteReadBatch (Opnum 145)

(Protocol Version 3) The ApiExecuteReadBatch method SHOULD<128> instruct the server to perform a series of cluster registry value read operations, relative to the designated key on the cluster registry.

The individual read operations are described by means of a CLUSTER_REG_BATCH_UPDATE structure. Each batch update command instructs the server as to how the registry is to be read. The server MUST maintain a current key pointer that is initially set to the designated key and is changed to the key identified in a CLUSREG_READ_KEY command when that command is executed.

The Name field for the CLUSREG_READ_KEY command is a path to the key to read, and is relative to the designated key. The key namespace is hierarchical, and each level in the hierarchy is separated by a Unicode backslash ("\"). The following are examples of properly formed key names: "test", "test\KeyToReadValuesOf".

The following table describes the different command types.

Command Type	Action	Name	Data	Effect on Key Pointer
CLUSREG_READ_KEY	Changes the current key to be relative to the previous current key.	A subkey path relative to the current key pointer.	Not used.	The key pointer is set to this key.
CLUSREG_READ_VALUE	Reads the named value relative to the current key pointer.	The name of the value to be read. This can be the null Unicode string (0x0000), indicating the default, unnamed value associated with the key.	Not used.	None.

On successful completion of this method, the server MUST set the lpOutData parameter to a buffer containing a CLUSTER_REG_BATCH_UPDATE structure. For each BATCH_UPDATE_COMMAND structure in the variable-length CLUSTER_REG_BATCH_UPDATE structure pointed to by lpInData, the server MUST include, in the same order, a CLUSTER_REG_BATCH_UPDATE structure in the lpOutData parameter. If the read operation is successful, a BATCH_UPDATE_COMMAND of command type CLUSREG_READ_VALUE is returned with its Data and ValueType fields filled out. If the read operation is not successful, a CLUSREG_READ_ERROR is returned with the ValueType field set to the status code corresponding to the failure, as would be returned by the server if the designed query were attempted via the ApiQueryValue (section 3.1.4.2.35) method.

The server SHOULD accept calls to ApiExecuteReadBatch if it is in the read state, and MUST accept calls to ApiExecuteReadBatch if it is in the read/write state, as specified in section 3.1.1.

The server MUST require that the client have a security access level of "Read", as specified in section 3.1.4.

 error_status_t ApiExecuteReadBatch(
   [in] HKEY_RPC hKey,
   [in] DWORD cbInData,
   [in, size_is(cbInData)] UCHAR const * lpInData,
   [out] DWORD * cbOutData,
   [out, size_is(,*cbOutData)] UCHAR ** lpOutData,
   [out] error_status_t *rpc_status
 );

hKey: The RPC context handle for a key that was previously obtained by a call to ApiGetRootKey, ApiCreateKey, or ApiOpenKey. The key represented by this parameter is the initial key from which all commands in the buffer of the lpInData parameter are executed.

cbInData: A 32-bit integer that provides the size, in bytes, of the buffer pointed to by the lpInData parameter.

lpInData: A pointer to a buffer containing a variable-length CLUSTER_REG_BATCH_UPDATE structure that contains a series of commands describing a set of values to read from the cluster registry.

cbOutData: A 32-bit integer that provides the size, in bytes, of the buffer pointed to by the lpOutData parameter.

lpOutData: A pointer to a pointer to a buffer containing a variable-length CLUSTER_REG_BATCH_UPDATE structure that contains the results of the read operations from the cluster registry.

rpc_status: A 32-bit integer indicating success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as described in [C706] Appendix E.

Return Values: The method MUST return the following error codes for the following conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The operation completed successfully.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hKey parameter does not represent a valid HKEY_RPC context handle.
0x00000057 ERROR_INVALID_PARAMETER	A CLUSREG_SET_VALUE or CLUSREG_DELETE_VALUE command was encountered in the input CLUSTER_REG_BATCH_UPDATE structure prior to a CLUSREG_CREATE_KEY command.

For any other condition, this method returns a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in section 3.2.4.6 as recoverable errors and initiate the reconnect procedure specified in section 3.2.4.6.