3.1.1.4.4 IRPCAsyncNotify_GetNotificationSendResponse (Opnum 4)

The IRPCAsyncNotify_GetNotificationSendResponse method sends a client response to the server and returns the next notification sent by way of the same channel when it becomes available. This method MUST be used only with bidirectional communication mode.

 HRESULT IRPCAsyncNotify_GetNotificationSendResponse(
   [in, out] PNOTIFYOBJECT* pChannel,
   [in, unique] PrintAsyncNotificationType* pInNotificationType,
   [in] unsigned long InSize,
   [in, size_is(InSize), unique] byte* pInNotificationData,
   [out] PrintAsyncNotificationType** ppOutNotificationType,
   [out] unsigned long* pOutSize,
   [out, size_is( , *pOutSize)] byte** ppOutNotificationData
 );

pChannel: A pointer to a notification channel that MUST NOT be closed or zero, and which MUST have been returned by the server in the ppChannelCtxt output parameter of a prior call to IRPCAsyncNotify_GetNewChannel. If the server closes the notification channel, it MUST set the pChannel value to NULL upon return from this method. If the notification channel was acquired by a different client, the server MUST set the pChannel value to NULL upon return from this method.

pInNotificationType: A NULL value or a pointer to a PrintAsyncNotificationType structure that specifies the notification type identifier of the notification type in which the registered client is interested.

On the first call to this method, the value of pInNotificationType MUST be NULL. On subsequent calls to this method, the value of pInNotificationType MUST be a pointer to a PrintAsyncNotificationType structure that specifies the notification type identifier for which the client has registered.

InSize: The size, in bytes, of the input data that the pInNotificationData parameter points to. The server SHOULD impose an upper limit of 0x00A00000 on this value. If the client exceeds the server-imposed limit, the server MUST return an error result.

pInNotificationData: A pointer to input data holding the client's response to the previous notification that was received on the same bidirectional notification channel.

On the first call to this method for a given channel, the client SHOULD provide zero bytes of response data and the server MUST ignore any response data sent. On subsequent calls to this method, the response format MUST conform to the requirements of the notification channel's notification type, and those notification type requirements determine whether or a not a zero-byte response is acceptable.

If the value of InSize is not 0x00000000, pInNotificationData MUST NOT be NULL.

ppOutNotificationType: A pointer to the returned pointer to the notification type identifier of the server-to-client notification. If the notification channel was acquired by a different client, the value MUST be NOTIFICATION_RELEASE (section 2.2.1). If the server needs to close the notification channel without sending a final response, the value SHOULD be NOTIFICATION_RELEASE. In all other cases, the value MUST be the same as the notification type identifier of the notification type for which the client has registered.

pOutSize: A pointer to the returned 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. If the notification channel was acquired by a different client, the server SHOULD set the value of pOutSize to 0x00000000. If the value of ppOutNotificationType points to NOTIFICATION_RELEASE, the server SHOULD set the value of pOutSize to 0x00000000.

ppOutNotificationData: A pointer to the returned pointer to server-to-client notification data in a format that MUST conform to the notification channel's notification type. If the notification channel was acquired by a different client, the server SHOULD set the value of ppOutNotificationData to NULL. If the value of ppOutNotificationType points to NOTIFICATION_RELEASE, the client MUST ignore the content of ppOutNotificationData.

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 MUST consider all error return values fatal and report them to the higher-level caller.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

If a failure is indicated by an error return or an exception, the client SHOULD close the channel.

The first call to this method on the newly opened notification channel serves as a mediator among all the clients that registered themselves for the given notification type. This MUST be done by blocking all calls from clients until a matching server-side event occurs, including the following:

• The channel issues a notification.

• An abnormal condition occurs, such as an initiated server shutdown sequence.

• The server receives a client request to close the channel.

The server MUST do the following.

• Choose the first client that sent a response, whether by calling this method or by calling IRPCAsyncNotify_CloseChannel with a notification type identifier other than NOTIFICATION_RELEASE, and assign the opened notification channel to that client.

• For all other clients, set the value of the ppOutNotificationType output parameter to NOTIFICATION_RELEASE and the value of the pChannel parameter to NULL.

• Return an HRESULT success value [MS-ERREF] to all the other clients that have outstanding blocked calls to this method.

All subsequent calls to this method MUST take the response provided by the client that was assigned to the notification channel and pass it to the server-resident notification source that opened the notification channel. The call MUST return when a subsequent notification is sent from a notification source using the bidirectional notification channel; the channel is closed; or an abnormal event happens, such as the print spooler server terminating its execution.

The server MUST NOT indicate success to a client call to this method if a prior call to IRPCAsyncNotify_CloseChannel succeeded specifying the same notification channel.

A client MUST NOT call IRPCAsyncNotify_GetNotificationSendResponse following a prior successful return from IRPCAsyncNotify_GetNotificationSendResponse with a NULL output value of the pChannel parameter or following a prior successful return from IRPCAsyncNotify_CloseChannel.

A client SHOULD call IRPCAsyncNotify_GetNotificationSendResponse or IRPCAsyncNotify_CloseChannel following a prior successful return from IRPCAsyncNotify_GetNotificationSendResponse with a non-NULL output value of the pChannel parameter.