CreatePrintAsyncNotifyChannel function (prnasnot.h)

Creates a communication channel between a Print Spooler-hosted printing component, such as a print driver or port monitor, and an application that receives notifications from the component.

Syntax

HRESULT CreatePrintAsyncNotifyChannel(
  [in]  PCWSTR                            pszName,
  [in]  PrintAsyncNotificationType        *pNotificationType,
  [in]  PrintAsyncNotifyUserFilter        eUserFilter,
  [in]  PrintAsyncNotifyConversationStyle eConversationStyle,
  [in]  IPrintAsyncNotifyCallback         *pCallback,
  [out] IPrintAsyncNotifyChannel          **ppIAsynchNotification
);

Parameters

[in] pszName

A pointer to the name of a print server or print queue.

[in] pNotificationType

A pointer to the GUID of the data schema for the type of notifications to be sent in the channel.

[in] eUserFilter

A value specifying whether notifications will be sent to:

• Only applications that are running as the same user as the Print Spooler-hosted plug-in sender.
• A broader set of listening applications.

[in] eConversationStyle

A value specifying whether communication is bidirectional or unidirectional.

[in] pCallback

A pointer to an object that the listening application will use to call back the Print Spooler-hosted component. This should be NULL if directionality is kUniDirectional.

[out] ppIAsynchNotification

A pointer to the new channel.

Return value

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 to evaluate the return value.

if (SUCCEEDED(hr)){
  //Call was successful 
}

if (FAILED(hr)) {
  // Call failed 
}

if (FAILED(hr)) {
  // Call failed 
  switch (HRESULT_CODE(hr)){
    case CHANNEL_ALREADY_OPENED:
      // Some action 
      break;
    case MAX_CHANNEL_COUNT_EXCEEDED:
      // Some action 
      break;
    default:
      //Default action 
      break;
  }
} else {
  //call succeeded 
}

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

See PrintAsyncNotifyError for other possible return values.

Remarks

To close a channel, call IPrintAsyncNotifyChannel::CloseChannel; however, IPrintAsyncNotifyChannel::CloseChannel cannot be called immediately after the call to CreatePrintAsyncNotifyChannel.

Call IPrintAsyncNotifyChannel::Release() only:

1. if it is an explicit match to an earlier IPrintAsyncNotifyChannel::AddRef() call.
2. if the channel is a UniDirectional channel and you are abandoning the pointer received in a successful call to CreatePrintAsyncNotifyChannel.
3. if, after you created a BiDirectional channel or in the implementation of IPrintNotifyAsyncCallback::OnEventNotify and:
   1. you did not call IPrintAsyncNotifyChannel::SendNotification or IPrintAsyncNotifyChannel::CloseChannel OR
   2. you did not retry a call to IPrintAsyncNotifyChannel::SendNotification or IPrintAsyncNotifyChannel::CloseChannel that failed OR
   3. on the server side, you didn't retry a call to IPrintAsyncNotifyChannel::SendNotification that succeeded with the return value NO_LISTENER OR
   4. on the client side, you didn't retry a call to IPrintAsyncNotifyChannel::SendNotification that succeeded with return value CHANNEL_ACQUIRED.

Requirements

See also

Client Impersonation

Print Spooler API Functions

Printing