Partager via

3.1.1.4.5 IRPCAsyncNotify_GetNotification (Opnum 5)

  • Article

The IRPCAsyncNotify_GetNotification method returns notification data from the print server. This method MUST NOT be used with bidirectional communication mode.

 HRESULT IRPCAsyncNotify_GetNotification(
   [in] PRPCREMOTEOBJECT pRemoteObj,
   [out] PrintAsyncNotificationType** ppOutNotificationType,
   [out] unsigned long* pOutSize,
   [out, size_is(, *pOutSize)] byte** ppOutNotificationData
 );

pRemoteObj: MUST be the remote object context handle. This remote object MUST have been registered for unidirectional communication mode by a prior successful call to IRPCAsyncNotify_RegisterClient (section 3.1.1.4.1).

ppOutNotificationType: MUST return a pointer to the notification type identifier of the server-to-client notification. If the registered remote object has been deleted, the value MUST be NOTIFICATION_RELEASE (section 2.2.1). In all other cases the value MUST be the same as the notification type identifier of the notification type for which the print client has registered.

pOutSize: MUST be the length of server-to-client notification data, in number of bytes. The client MAY impose an upper limit on this value that is smaller than the maximum unsigned 32-bit integer.

ppOutNotificationData: MUST be a pointer to server-to-client notification data in a format that MUST conform to the channel's notification type.

Return Values: This method MUST return zero to indicate success, or an HRESULT error value ([MS-ERREF] section 2.1.1) to indicate failure. Protocol-specific error values are defined in the following table. The client SHOULD treat all error return values the same, except where noted.

Return value

Description

0x8004000C

The server has not yet returned from a previous call to this method with the same remote object.

If this error value is returned, the client SHOULD NOT retry this call before the previous call to this method with the specified remote object has completed.

0x8007000E

The server does not have enough memory to complete the request.

0x8007071A

Incoming notifications have been terminated. Upon completion of this call with this return value, the server MUST fail subsequent calls to this method with the same remote object.

If this error value is returned, the client SHOULD NOT retry this call.

Exceptions Thrown: An exception code of 0x08004000C or 0x8007071A SHOULD be thrown by the server under the circumstances described in the preceding table for the corresponding return values. The client MUST treat these exception codes exactly as it would treat the same return values. No additional exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Unless specified otherwise, if a failure is indicated by an error return or an exception, the client SHOULD retry this method call by performing the following steps:

  1. Call IRPCRemoteObject_Create (section 3.1.2.4.1) to generate a new PRPCREMOTEOBJECT (section 2.2.4).

  2. Call IRPCAsyncNotify_RegisterClient with the new PRPCREMOTEOBJECT.

  3. Call IRPCAsyncNotify_GetNotification with the new PRPCREMOTEOBJECT.

Retries SHOULD be separated by time intervals decaying from 1 second to 1 minute to reduce a potential burden on the server. Retries SHOULD terminate when the above sequence succeeds or the client determines that it is no longer interested in notifications for the particular combination of notification type, print queue name, conversation style, and user identity filter that were originally specified in the call to IRPCAsyncNotify_RegisterClient.

The IRPCAsyncNotify_GetNotification method MUST return data from the server that matches the registration for the given remote object.

A server MUST NOT do the following:

  • Indicate success to a client call of IRPCAsyncNotify_GetNotification unless a prior call to IRPCAsyncNotify_RegisterClient succeeded using the same PRPCREMOTEOBJECT value.

  • Indicate success to a client call of IRPCAsyncNotify_GetNotification following a prior successful call to IRPCAsyncNotify_UnregisterClient using the same PRPCREMOTEOBJECT value.

  • Complete a call to IRPCAsyncNotify_GetNotification until the Unidirectional Notification Queue associated with the Client Registration (Abstract Data Model (section 3.1.1.1)) contains an unreturned notification, or an abnormal condition occurs. An example of an abnormal condition is an initiated server shutdown sequence or remote object unregistration. An abnormal condition will result in a failure error code returned prior to the server having data.

A server SHOULD do the following:

  • Discard unidirectional notifications in the absence of corresponding registered clients.

  • Buffer unidirectional notifications, up to some implementation-defined limit,<10> for each registered client that does not have pending IRPCAsyncNotify_GetNotification calls.

If a client wants to receive further notifications from the server, the client SHOULD call IRPCAsyncNotify_GetNotification in response to a prior successful return from IRPCAsyncNotify_GetNotification. When the client no longer wants to receive notifications from the server, it SHOULD call IRPCAsyncNotify_UnregisterClient, either before or after the return from IRPCAsyncNotify_GetNotification.

A client MUST NOT do the following:

  • Call IRPCAsyncNotify_GetNotification unless a prior call to IRPCAsyncNotify_RegisterClient succeeded, using the same PRPCREMOTEOBJECT value.

  • Call IRPCAsyncNotify_GetNotification following a prior call to IRPCAsyncNotify_UnregisterClient by using the same PRPCREMOTEOBJECT value.