IPrintAsyncNotifyChannel::CloseChannel method (prnasnot.h)

Article
07/27/2022

Closes the channel.

Syntax

HRESULT CloseChannel(
  [in] IPrintAsyncNotifyDataObject *pData
);

Parameters

[in] pData

Pointer to a notification that specifies why the channel closed. This pointer can be NULL.

Return value

HRESULT	Severity	Meaning
S_OK	SUCCESS	The function completed successfully.
CHANNEL_ACQUIRED	ERROR or SUCCESS	Another listener on this channel has already responded. Only the first respondent can continue the communication with the sender. If this HRESULT has an ERROR severity, the calling function should handle the error condition.
CHANNEL_ALREADY_CLOSED	ERROR or SUCCESS	The channel has already closed. IPrintAsyncNotifyChannel::Release must not be called if this HRESULT is returned because the channel has already been closed and released. If this HRESULT has an ERROR severity, the calling function should handle the error condition.
CHANNEL_CLOSED_BY_ANOTHER_LISTENER	ERROR	A listening application, other than the caller, closed the communication channel.
CHANNEL_CLOSED_BY_SAME_LISTENER	ERROR	The caller has already closed the communication channel.
INVALID_NOTIFICATION_TYPE	ERROR	The specified notification type is invalid.

The return values are COM error codes. Because this function might complete the operation successfully yet return an HRESULT other than S_OK you should use the SUCCEEDED or FAILED macro to determine the success of the call. To get the specific HRESULT that was returned by the function, use the HRESULT_CODE macro. The following code example shows how these macros can be used.

See PrintAsyncNotifyError for other possible return values.

For more information about COM error codes, see Error Handling.

if (SUCCEEDED(hr)) {
  // Call succeeded, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case CHANNEL_ACQUIRED:
      // Some action 
      break;
    case CHANNEL_ALREADY_CLOSED:
      // Some action 
      break;
    default:
      // Default action 
      break;
  }
} else {
  // Call failed, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case CHANNEL_CLOSED_BY_ANOTHER_LISTENER:
      // Some action 
      break;
    case CHANNEL_CLOSED_BY_SAME_LISTENER:
      // Some action 
      break;
    case INVALID_NOTIFICATION_TYPE:
      // Some action 
      break;
    case CHANNEL_ACQUIRED:
      // This can be an error and a successful return
      //  some action 
      break;
    case CHANNEL_ALREADY_CLOSED:
      // This can be an error and a successful return
      //  some action 
      break;
    default:
      // Default action 
      break;
  }
}

Remarks

CloseChannel can be called by either side of the communication channel—the component that is hosted by the print spooler or the listening application.

If an IPrintAsyncNotifyChannel::SendNotification call is made while the print spooler is processing an earlier call to SendNotification, the print spooler will queue the notifications. Queued notifications are discarded if either the component that is hosted by the print spooler or the application calls CloseChannel.

CloseChannel cannot be called immediately after the call to CreatePrintAsyncNotifyChannel.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	prnasnot.h
DLL	Prnasnot.dll