CreatePrintAsyncNotifyChannel function (prnasnot.h)

  • Article

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

HRESULT Severity Meaning
S_OK SUCCESS The function completed successfully.
CHANNEL_ALREADY_OPENED ERROR The channel has already been opened.
MAX_CHANNEL_COUNT_EXCEEDED ERROR The maximum number of listening applications have already registered for the specified type of notification with the specified queue or print server. The default maximum is 10,000.
 

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

Note  This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation—factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.
 
A component can open a channel only if it runs in the Print Spooler's process. For example, if an application loads a printer driver, the driver cannot open a channel, but a printer driver loaded inside the Print Spooler can open a channel. Listening applications can either be inside or outside the Print Spooler's process.

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

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
Library Winspool.lib
DLL Spoolss.dll

See also

Client Impersonation

Print Spooler API Functions

Printing