3.1.4.9.4 RpcAsyncGetRemoteNotifications (Opnum 61)
A print client uses RpcAsyncGetRemoteNotifications to poll the print server for specified change notifications. A call to this method is suspended until the server has a new change notification for the client. Subsequently, the client calls this method again to poll for additional notifications from the server.
-
HRESULT RpcAsyncGetRemoteNotifications( [in] RMTNTFY_HANDLE hRpcHandle, [out] RpcPrintPropertiesCollection** ppNotifyData );
hRpcHandle: A remote notification handle that was opened by using RpcSyncRegisterForRemoteNotifications (section 3.1.4.9.1).
ppNotifyData: A pointer to a variable that receives a pointer to an RpcPrintPropertiesCollection (section 2.2.4) instance that contains the notification data.
Return Values: This method returns either an HRESULT success value ([MS-ERREF] section 2.1) to indicate successful completion or an HRESULT error value to indicate failure.
Exceptions Thrown: This method MUST NOT throw any exceptions other than those that are thrown by the underlying RPC protocol [MS-RPCE].
Parameter Validation Requirements: Upon receiving this method call, the server MUST verify that the hRpcHandle parameter is not NULL, and that it is associated with a valid notification object created by a call to RpcSyncRegisterForRemoteNotifications (section 3.1.4.9.1).
If parameter validation fails, the server MUST return immediately, with a failure indication in its response to the client.
Processing and Response Requirements: If parameter validation succeeds, the server MUST process the method call by:
Checking whether any change notification data is available on the notification object associated with this notification handle.
If the change notification data is not available, waiting until the specified printer object or server changes and notification data becomes available.
Returning a response that contains the status of the operation.
If the operation is successful, the server MUST process the message and compose a response to the client as follows:
Create an RpcPrintPropertiesCollection object as follows:
Store the notification data requested by the client in the "RemoteNotifyData Info" key in the RpcPrintPropertiesCollection object.
Store the notification synchronization value in the "RemoteNotifyData Color" key in the RpcPrintPropertiesCollection object. The latest synchronization value was sent by the client in a prior call to RpcSyncRefreshRemoteNotifications.
Store a value specifying the members that have changed in the "RemoteNotifyData Flags" key in the RpcPrintPropertiesCollection object.
Store this RpcPrintPropertiesCollection object in the ppNotifyData parameter.
Delete the notification data associated with the notification handle that has been successfully sent.