RegisterForPrintAsyncNotifications, fonction (prnasnot.h)

Permet à une application de s’inscrire aux notifications des composants d’impression hébergés par un spouleur d’impression, tels que les pilotes d’imprimante, les processeurs d’impression et les moniteurs de port.

Syntaxe

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

Paramètres

[in] pszName

Pointeur vers le nom d’un serveur d’impression ou d’une file d’attente d’impression.

[in] pNotificationType

Pointeur vers le GUID du schéma de données pour le type de notifications que l’application doit recevoir.

[in] eUserFilter

Valeur spécifiant si les notifications seront envoyées à :

• Seules les applications qui s’exécutent comme le même utilisateur que l’expéditeur du plug-in hébergé par le spouleur d’impression.
• Un ensemble plus large d’applications d’écoute.

[in] eConversationStyle

Valeur spécifiant si la communication est bidirectionnelle ou unidirectionnelle.

[in] pCallback

Pointeur vers un objet que le composant print hébergé par un spouleur utilisera pour rappeler l’application. Cela ne doit jamais être NULL.

[out] phNotify

Pointeur vers une structure qui représente l’inscription.

Valeur retournée

HRESULT	Gravité	Signification
S_OK	SUCCESS	La fonction s’est terminée avec succès.
ALREADY_REGISTERED	ERROR	L’objet d’inscription a déjà été inscrit.
LOCAL_ONLY_REGISTRATION	SUCCESS	L’inscription pour la notification locale a réussi. L’inscription pour les notifications à distance n’était pas.
MAX_REGISTRATION_COUNT_EXCEEDED	ERROR	Le nombre maximal d’inscriptions a été atteint. Plus aucune inscription n’est autorisée.
REMOTE_ONLY_REGISTRATION	SUCCESS	L’inscription pour les notifications à distance a réussi. L’inscription pour les notifications locales n’a pas été.

 

Les valeurs renvoyées sont des codes d’erreur COM. Étant donné que cette fonction peut terminer l’opération correctement tout en renvoyant un HRESULT autre que S_OK vous devez utiliser la macro SUCCEEDED ou FAILED pour déterminer la réussite de l’appel. Pour obtenir le HRESULT spécifique retourné par la fonction, utilisez la macro HRESULT_CODE.

L’exemple de code suivant montre comment ces macros peuvent être utilisées pour évaluer la valeur de retour.

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

Pour plus d’informations sur les codes d’erreur COM, consultez Gestion des erreurs.

Consultez PrintAsyncNotifyError pour connaître les autres valeurs de retour possibles.

Remarques

Note Il s’agit d’une fonction bloquante ou synchrone qui peut ne pas être retournée immédiatement. La rapidité avec laquelle cette fonction retourne dépend de facteurs d’exécution tels que l’status réseau, la configuration du serveur d’impression et l’implémentation du pilote d’imprimante, facteurs difficiles à prédire lors de l’écriture d’une application. L’appel de cette fonction à partir d’un thread qui gère l’interaction avec l’interface utilisateur peut donner l’impression que l’application ne répond pas.

 

Pour arrêter les notifications via un canal unidirectionnel, l’application d’écoute transmet la valeur pRegistrationHandler retournée par RegisterForPrintAsyncNotifications à UnRegisterForPrintAsyncNotifications. Pour un canal bidirectionnel, appelez UnRegisterForPrintAsyncNotifications pour bloquer les notifications dans tous les nouveaux canaux créés après cet appel. Pour bloquer les notifications sur les canaux bidirectionnels existants, l’application d’écoute doit fermer le canal avec IPrintAsyncNotifyChannel ::CloseChannel.

À la suite d’un appel RegisterForPrintAsyncNotifications , la méthode IUnknown ::AddRef est appelée pour l’objet pCallback . L’appel de UnRegisterForPrintAsyncNotifications libère l’objet pCallback . Le nombre de références de l’objet pCallback est également incrémenté lorsqu’un canal est créé et décrémenté lorsque le canal est fermé.

Le paramètre pSchema est un pointeur GUID que le spouleur accepte et utilise pour filtrer les clients de l’écouteur. Tout client du mécanisme de notification asynchrone du spouleur peut définir son propre type de notification. Même si le spouleur ne connaît pas le type de notification envoyé, il filtre toujours les clients de l’écouteur en fonction du type de notification. Le schéma de notification auquel pSchema fait référence est le schéma utilisé par l’objet de notification qui expose IPrintAsyncNotifyDataObject. Les clients du canal de notification du spouleur peuvent définir leur propre schéma de données et envoyer n’importe quel type de données, et le GUID référencé par pSchema est propre à ce schéma de données.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	prnasnot.h
Bibliothèque	WinSpool.lib
DLL	Spoolss.dll

Voir aussi

Emprunt d'identité de client

Fonctions API du spouleur d’impression

Impression