RegisterForPrintAsyncNotifications function (prnasnot.h)

Enables an application to register for notifications from Print Spooler-hosted printing components such as printer drivers, print processors, and port monitors.

Syntax

HRESULT RegisterForPrintAsyncNotifications(
  [in]  PCWSTR                            pszName,
  [in]  PrintAsyncNotificationType        *pNotificationType,
  [in]  PrintAsyncNotifyUserFilter        eUserFilter,
  [in]  PrintAsyncNotifyConversationStyle eConversationStyle,
  [in]  IPrintAsyncNotifyCallback         *pCallback,
  [out] HANDLE                            *phNotify
);

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 that the application must receive.

[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 Print Spooler-hosted component will use to call back the application. This should never be NULL.

[out] phNotify

A pointer to a structure that represents the registration.

Return value

HRESULT Severity Meaning
S_OK SUCCESS The function completed successfully.
ALREADY_REGISTERED ERROR The registration object has already been registered.
LOCAL_ONLY_REGISTRATION SUCCESS Registration for local notification was successful. Registration for remote notifications was not.
MAX_REGISTRATION_COUNT_EXCEEDED ERROR The maximum number of registrations has been reached. No more registrations are permitted.
REMOTE_ONLY_REGISTRATION SUCCESS Registration for remote notifications was successful. Registration for local notifications was not.
 

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 succeeded, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case S_OK:
      // Some action 
      break;
      case LOCAL_ONLY_REGISTRATION:
      // Some action 
      break;
    case REMOTE_ONLY_REGISTRATION:
      // Some action 
      break;
    default:
      // Default action 
      break;
  }
} else {
  // Call failed, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case ALREADY_REGISTERED:
      // Some action 
      break;
    case MAX_REGISTRATION_COUNT_EXCEEDED:
      // Some action 
      break;
    default:
      // Default action 
      break;
  }
}

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.
 
To stop notifications through a unidirectional channel, the listening application passes the pRegistrationHandler value returned by RegisterForPrintAsyncNotifications to UnRegisterForPrintAsyncNotifications. For a bidirectional channel, call UnRegisterForPrintAsyncNotifications to block notifications in any new channels that were created after that call. To block notifications on existing bidirectional channels, the listening application must close the channel with IPrintAsyncNotifyChannel::CloseChannel.

As a result of a RegisterForPrintAsyncNotifications call, the IUnknown::AddRef method is called for the pCallback object. Calling UnRegisterForPrintAsyncNotifications will release the pCallback object. The reference count of pCallback object will be also incremented when a channel is created and decremented when the channel is closed.

The pSchema parameter is a GUID pointer that the spooler accepts and uses to filter the listener clients. Any client of the spooler asynchronous notification mechanism can define its own notification type. Even though the spooler is unaware of the notification type that is sent, it still filters the listener clients based on the notification type. The notification schema that pSchema references is the schema that is used by the notification object that exposes IPrintAsyncNotifyDataObject. Clients of the spooler notification pipe can define their own data schema and can send any data type back and forth and the GUID referenced by pSchema is unique to that data schema.

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