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
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 |