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.