3.1.4.2.114 ApiGetBatchNotification (Opnum 115)

(Protocol Version 3) The ApiGetBatchNotification method instructs the server to retrieve the first queued batch update event indication from the designated batch update notification_port. The server MUST NOT complete this method until an indication has been queued to the port or the port has been closed through a separate call to the ApiCloseBatchPort method.

Upon successful completion of this method, the server MUST write a CLUSTER_REG_BATCH_UPDATE structure, as specified in section 2.2.3.17, indicating the modifications that have been made to the cluster registry. This information essentially mirrors the CLUSTER_REG_BATCH_UPDATE structure provided to the ApiExecuteBatch method with the modification that a CLUSREG_VALUE_DELETED command precedes every CLUSREG_SET_VALUE and CLUSREG_DELETE_VALUE command in the returned notification data if the value has existing data. The Name field identifies the name of the value that was modified, and the Data field contains the value data that existed prior to executing the aforementioned value command.

For example, the client calls ApiExecuteBatch with the following series of commands for a value named "NotifyTest" that does not already exist in the registry:

• Delete Value

• Set Value to "hello world"

• Set Value to "hello universe"

• Delete Value

The series of change notifications that the server returns to the client through this method are as follows:

• Delete Value

• Set Value to "hello world"

• Value Deleted with the data set to "hello world"

• Set Value to "hello universe"

• Value Deleted with the data set to "hello universe"

• Delete Value

The following diagrams illustrate the preceding command and notification sequence.

Figure 3: Client-issued registry update

Figure 4: Corresponding change notifications returned by server

The server SHOULD accept an ApiGetBatchNotification request if the client's access level is at least "Read" (section 3.1.4).

 error_status_t ApiGetBatchNotification(
   [in] HBATCH_PORT_RPC hBatchNotify,
   [out] DWORD * cbData,
   [out, size_is(,*cbData)] UCHAR ** lpData
 );

hBatchNotify: A pointer to an HBATCH_PORT_RPC context handle that was obtained in a previous ApiCreateBatchPort method call.

cbData: A pointer to a 32-bit integer. Upon successful completion of this method, the server MUST write the size, in bytes, of the lpData buffer to the integer location indicated by cbData.

lpData: The address of a pointer where the server MUST write, upon successful completion of this method, a CLUSTER_REG_BATCH_UPDATE structure as previously described.

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

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hBatchNotify parameter does not represent a valid HBATCH_PORT_RPC context handle.
0x00000103 ERROR_NO_MORE_ITEMS	The port referenced by the hBatchNotify parameter has been closed by a separate call to the ApiCloseBatchPort method.

For any other condition, this method MUST return a value that is not one of those 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.