3.1.1.4.6 IRPCAsyncNotify_CloseChannel (Opnum 6)

The IRPCAsyncNotify_CloseChannel method sends a final response on the notification channel and closes it. This method MUST NOT be used with unidirectional communication mode.

 HRESULT IRPCAsyncNotify_CloseChannel(
   [in, out] PNOTIFYOBJECT* pChannel,
   [in] PrintAsyncNotificationType* pInNotificationType,
   [in] unsigned long InSize,
   [in, size_is(InSize), unique] byte* pReason
 );

pChannel: MUST be a pointer to a notification channel that MUST NOT be closed or zero and that MUST have been returned by the server in the ppChannelCtxt output parameter of a prior call to IRPCAsyncNotify_GetNewChannel. Upon receipt, the server MUST set the pChannel value to NULL.

pInNotificationType: MUST be a pointer to a PrintAsyncNotificationType value. If the client needs to close the notification channels without sending a final response, then this value SHOULD point to NOTIFICATION_RELEASE. In all other cases, this value MUST point to the notification type identifier of the notification type for which the client has registered.

InSize: The server SHOULD impose an upper limit on this value that is smaller than the maximum unsigned 32-bit integer. That limit SHOULD be 0x00A00000. If the client exceeds the server-imposed limit, the server MUST return an error result.

If pInNotificationType is NOTIFICATION_RELEASE, then InSize SHOULD be 0x00000000.

pReason: MUST be a pointer to a sequence of bytes conveying final client-to-server response data. The number of bytes MUST be provided in the InSize parameter. If InSize is not 0x00000000, then pReason MUST NOT be NULL.

If pInNotificationType is NOTIFICATION_RELEASE, then the client SHOULD provide zero bytes of response data and the server MUST ignore any response data pointed to by pReason. If pInNotificationType is not NOTIFICATION_RELEASE, then the response format MUST conform to the requirements of the notification channel's notification type and those notification type requirements determine whether or not a zero-byte response is acceptable.

Return Values: This method MUST return zero or an HRESULT success value ([MS-ERREF] section 2.1.1) to indicate success, or an HRESULT error value to indicate failure.

Protocol-specific success values are defined in the following table.

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 client call to IRPCAsyncNotify_GetNotificationSendResponse is blocked on the server, waiting for a notification to become available on a notification channel, then the server MUST process a client call to this method on the same notification channel without waiting for a notification.

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