Interface TCPMON Xcv

Cette section décrit l’interface d’émetteur (Xcv) pour le moniteur de port TCP/IP standard (TCPMON). Cette interface, qui est implémentée à l’aide des appels de fonction XcvData et XcvDataPort , permet à ceux qui l’utilisent de configurer un port d’imprimante TCP/IP ou d’obtenir des informations sur la configuration d’un port d’imprimante TCP/IP. L’interface Xcv décrite dans cette section est spécifique aux ports TCP/IP. D’autres interfaces Xcv peuvent être disponibles pour d’autres types de ports.

Pour obtenir un handle vers une interface Xcv pour un ordinateur local ou un ordinateur distant, appelez la fonction OpenPrinter . L’exemple de code suivant montre comment obtenir un handle Xcv sur un port :

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a local TCPMON port
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a TCPMON port on <ServerName>
}

Dans l’exemple de code, ServerName et PortName représentent des chaînes de nom de port et de serveur. Une fois que vous avez obtenu le handle, vous pouvez interroger des informations spécifiques au moniteur de port TCPMON, ou vous pouvez modifier la configuration du port. Notez que l’accès dont vous avez besoin pour le moniteur de port doit être spécifié dans le membre DesiredAccess de la structure PRINTER_DEFAULTS ou passer la valeur NULL si aucune sécurité spéciale n’est requise. Pour certains appels à la fonction XcvData , par exemple lorsque les commandes AddPort et DeletePort sont spécifiées (voir Commandes TCPMON Xcv), SERVER_ACCESS_ADMINISTER privilège est requis. Pour plus d’informations sur la fonction OpenPrinter et les droits d’accès qui peuvent être demandés dans la structure PRINTER_DEFAULTS, consultez la documentation de la fonction OpenPrinter .

Si le port n’existe pas encore, le handle Xcv peut être obtenu à partir du serveur en spécifiant le nom du moniteur. (Dans le cas du port de surveillance de port TCP/IP standard, il s’agit du « port TCP/IP standard ». ) L’exemple de code suivant montre comment obtenir un handle de données Xcv sur un moniteur de port :

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor <MonitorName>
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor 
 // <MonitorName> on the server <ServerName>
}

Dans l’exemple de code, ServerName et PortName représentent des chaînes de nom de port et de serveur. Une fois que vous avez obtenu le handle de données Xcv, vous pouvez émettre des instructions et des demandes au moniteur en appelant la fonction XcvData .

Notez que la valeur de retour de la fonction XcvData indique uniquement si les données ont été correctement envoyées au moniteur de port. Une valeur de retour TRUE n’indique pas que l’opération a réussi. Pour déterminer si l’opération a réussi, inspectez la valeur dans *pdwStatus. Ces valeurs status sont résumées dans le tableau suivant :

Valeur d’état	Signification
NO_ERROR	L'opération a réussi.
ERROR_ACCESS_DENIED	L’utilisateur ne dispose pas de privilèges suffisants. La commande nécessite SERVER_ACCESS_ADMINISTER privilège.
ERROR_INSUFFICIENT_BUFFER	Une mémoire tampon de sortie est requise, mais elle est plus petite que nécessaire.
ERROR_INVALID_DATA	Une mémoire tampon d’entrée est requise, mais le pointeur vers celle-ci est NULL ou la taille de la mémoire tampon d’entrée est inférieure à celle requise.
ERROR_INVALID_HANDLE	Le handle de données Xcv n’est pas valide.
ERROR_INVALID_LEVEL	La structure de données d’entrée ou de sortie n’est pas la version correcte.
ERROR_INVALID_PARAMETER	Une mémoire tampon de sortie est requise, mais elle est NULL, ou le paramètre de sortie requis est NULL et la mémoire tampon de sortie est trop petite, ou le moniteur de port TCP/IP standard ne comprend pas la commande en cours d’émission.