CreatePrintAsyncNotifyChannel, fonction (prnasnot.h)

Article
03/04/2024

Crée un canal de communication entre un composant d’impression hébergé par un spouleur d’impression, tel qu’un pilote d’impression ou un moniteur de port, et une application qui reçoit des notifications du composant.

Syntaxe

HRESULT CreatePrintAsyncNotifyChannel(
  [in]  PCWSTR                            pszName,
  [in]  PrintAsyncNotificationType        *pNotificationType,
  [in]  PrintAsyncNotifyUserFilter        eUserFilter,
  [in]  PrintAsyncNotifyConversationStyle eConversationStyle,
  [in]  IPrintAsyncNotifyCallback         *pCallback,
  [out] IPrintAsyncNotifyChannel          **ppIAsynchNotification
);

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 à envoyer dans le canal.

[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 l’application d’écoute utilisera pour rappeler le composant hébergé par spouleur d’impression. Cette valeur doit être NULL si la directionnalité est kUniDirectional.

[out] ppIAsynchNotification

Pointeur vers le nouveau canal.

Valeur retournée

HRESULT	Gravité	Signification
S_OK	SUCCESS	La fonction s’est terminée avec succès.
CHANNEL_ALREADY_OPENED	ERROR	Le canal a déjà été ouvert.
MAX_CHANNEL_COUNT_EXCEEDED	ERROR	Nombre maximal d’applications d’écoute déjà inscrites pour le type de notification spécifié avec la file d’attente ou le serveur d’impression spécifié. La valeur maximale par défaut est 10 000.

Les valeurs renvoyées sont des codes d’erreur COM. Étant donné que cette fonction peut terminer l’opération correctement et retourner 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 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 
}

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.

Un composant peut ouvrir un canal uniquement s’il s’exécute dans le processus du spouleur d’impression. Par exemple, si une application charge un pilote d’imprimante, le pilote ne peut pas ouvrir un canal, mais un pilote d’imprimante chargé à l’intérieur du spouleur d’impression peut ouvrir un canal. Les applications d’écoute peuvent être à l’intérieur ou à l’extérieur du processus du spouleur d’impression.

Pour fermer un canal, appelez IPrintAsyncNotifyChannel ::CloseChannel ; toutefois, IPrintAsyncNotifyChannel ::CloseChannel ne peut pas être appelé immédiatement après l’appel à CreatePrintAsyncNotifyChannel.

Appelez IPrintAsyncNotifyChannel ::Release() uniquement :

s’il s’agit d’une correspondance explicite à un appel IPrintAsyncNotifyChannel ::AddRef() antérieur.
si le canal est un canal unidirectionnel et que vous abandonnez le pointeur reçu lors d’un appel réussi à CreatePrintAsyncNotifyChannel.
si, après avoir créé un canal bidirectionnel ou dans l’implémentation de IPrintNotifyAsyncCallback ::OnEventNotify et :
1. vous n’avez pas appelé IPrintAsyncNotifyChannel ::SendNotification ou IPrintAsyncNotifyChannel ::CloseChannel OU
2. vous n’avez pas retenté un appel à IPrintAsyncNotifyChannel ::SendNotification ou IPrintAsyncNotifyChannel ::CloseChannel qui a échoué OU
3. côté serveur, vous n’avez pas retenté un appel à IPrintAsyncNotifyChannel ::SendNotification qui a réussi avec la valeur de retour NO_LISTENER OR
4. côté client, vous n’avez pas retenté un appel à IPrintAsyncNotifyChannel ::SendNotification qui a réussi avec la valeur de retour CHANNEL_ACQUIRED.

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

Partager via