Freigeben über

RegisterForPrintAsyncNotifications-Funktion (prnasnot.h)

Ermöglicht einer Anwendung die Registrierung für Benachrichtigungen von Druckkomponenten, die von Print Spooler gehostet werden, z. B. Druckertreiber, Druckprozessoren und Portmonitoren.

Syntax

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

Parameter

[in] pszName

Ein Zeiger auf den Namen eines Druckservers oder einer Druckwarteschlange.

[in] pNotificationType

Ein Zeiger auf die GUID des Datenschemas für den Typ der Benachrichtigungen, die die Anwendung empfangen muss.

[in] eUserFilter

Ein Wert, der angibt, ob Benachrichtigungen gesendet werden:

  • Nur Anwendungen, die als derselbe Benutzer wie der vom Print Spooler gehostete Plug-In-Absender ausgeführt werden.
  • Eine breitere Palette von Lauschanwendungen.

[in] eConversationStyle

Ein Wert, der angibt, ob die Kommunikation bidirektional oder unidirektional ist.

[in] pCallback

Ein Zeiger auf ein Objekt, das von der von Print Spooler gehosteten Komponente verwendet wird, um die Anwendung zurückzurufen. Dies sollte niemals NULL sein.

[out] phNotify

Ein Zeiger auf eine Struktur, die die Registrierung darstellt.

Rückgabewert

HRESULT Schweregrad Bedeutung
S_OK SUCCESS Die Funktion wurde erfolgreich abgeschlossen.
ALREADY_REGISTERED ERROR Das Registrierungsobjekt wurde bereits registriert.
LOCAL_ONLY_REGISTRATION SUCCESS Die Registrierung für lokale Benachrichtigungen war erfolgreich. Die Registrierung für Remotebenachrichtigungen war nicht.
MAX_REGISTRATION_COUNT_EXCEEDED ERROR Die maximale Anzahl von Registrierungen wurde erreicht. Anmeldungen sind nicht mehr zulässig.
REMOTE_ONLY_REGISTRATION SUCCESS Die Registrierung für Remotebenachrichtigungen war erfolgreich. Die Registrierung für lokale Benachrichtigungen war nicht.
 

Die Rückgabewerte sind COM-Fehlercodes. Da diese Funktion den Vorgang möglicherweise erfolgreich abgeschlossen hat und dennoch ein anderes HRESULT als S_OK gibt, sollten Sie das Makro SUCCEEDED oder FAILED verwenden, um den Erfolg des Aufrufs zu bestimmen. Verwenden Sie das Makro HRESULT_CODE, um das spezifische HRESULT abzurufen, das von der Funktion zurückgegeben wurde.

Das folgende Codebeispiel zeigt, wie diese Makros zum Auswerten des Rückgabewerts verwendet werden können.

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

Weitere Informationen zu COM-Fehlercodes finden Sie unter Fehlerbehandlung.

Weitere mögliche Rückgabewerte finden Sie unter PrintAsyncNotifyError .

Hinweise

Hinweis Dies ist eine blockierende oder synchrone Funktion und wird möglicherweise nicht sofort zurückgegeben. Wie schnell diese Funktion zurückgibt, hängt von Laufzeitfaktoren wie Netzwerk-status, Druckserverkonfiguration und Druckertreiberimplementierung ab – Faktoren, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Wenn Sie diese Funktion über einen Thread aufrufen, der die Interaktion mit der Benutzeroberfläche verwaltet, kann die Anwendung nicht reagieren.
 
Um Benachrichtigungen über einen unidirektionalen Kanal zu beenden, übergibt die lauschende Anwendung den pRegistrationHandler-Wert , der von RegisterForPrintAsyncNotifications zurückgegeben wird, an UnRegisterForPrintAsyncNotifications. Rufen Sie für einen bidirektionalen Kanal UnRegisterForPrintAsyncNotifications auf, um Benachrichtigungen in allen neuen Kanälen zu blockieren, die nach diesem Aufruf erstellt wurden. Um Benachrichtigungen auf vorhandenen bidirektionalen Kanälen zu blockieren, muss die lauschende Anwendung den Kanal mit IPrintAsyncNotifyChannel::CloseChannel schließen.

Als Ergebnis eines RegisterForPrintAsyncNotifications-Aufrufs wird die IUnknown::AddRef-Methode für das pCallback-Objekt aufgerufen. Beim Aufrufen von UnRegisterForPrintAsyncNotifications wird das pCallback-Objekt freigegeben. Die Verweisanzahl des pCallback-Objekts wird ebenfalls erhöht, wenn ein Kanal erstellt und beim Schließen des Kanals dekrementiert wird.

Der pSchema-Parameter ist ein GUID-Zeiger, den der Spooler akzeptiert und zum Filtern der Listenerclients verwendet. Jeder Client des asynchronen Benachrichtigungsmechanismus für Spooler kann einen eigenen Benachrichtigungstyp definieren. Obwohl der Spooler den gesendeten Benachrichtigungstyp nicht kennt, filtert er dennoch die Listenerclients basierend auf dem Benachrichtigungstyp. Das Benachrichtigungsschema, auf das pSchema verweist, ist das Schema, das vom Benachrichtigungsobjekt verwendet wird, das IPrintAsyncNotifyDataObject verfügbar macht. Clients der Spooler-Benachrichtigungspipeline können ihr eigenes Datenschema definieren und jeden Datentyp hin- und her senden, und die GUID, auf die von pSchema verwiesen wird, ist für dieses Datenschema eindeutig.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile prnasnot.h
Bibliothek WinSpool.lib
DLL Spoolss.dll

Weitere Informationen

Clientidentitätswechsel

Druckspooler-API-Funktionen

Drucken

  • Last updated on