Fonction XcvDataPort (winsplp.h)

Article
03/01/2024

La fonction XcvDataPort d’une DLL de serveur de surveillance de port reçoit des informations de la DLL d’interface utilisateur du moniteur de port et retourne des informations à.

Syntaxe

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

Paramètres

[in] hXcv

Handle d’imprimante fourni par l’appelant, obtenu en appelant OpenPrinter (décrit dans la documentation Microsoft Windows SDK). Ce handle est créé et retourné par la fonction XcvOpenPort .

[in] pszDataName

Pointeur fourni par l’appelant vers une chaîne représentant le nom des données demandées. Pour plus d'informations, consultez la section Notes qui suit.

[in] pInputData

Pointeur fourni par l’appelant vers une mémoire tampon contenant des données d’entrée.

cbInputData

Taille fournie par l’appelant, en octets, de la mémoire tampon pointée par pInputData.

[out] pOutputData

Pointeur fourni par l’appelant vers une mémoire tampon pour recevoir des données de sortie.

cbOutputData

Taille fournie par l’appelant, en octets, de la mémoire tampon pointée par pOutputData.

[out] pcbOutputNeeded

Pointeur fourni par l’appelant vers un emplacement pour recevoir la taille minimale, en octets, requise pour la mémoire tampon pointée par pOutputData.

Valeur retournée

Si l’opération réussit, cette fonction doit retourner ERROR_SUCCESS. Sinon, il doit retourner un code d’erreur Win32 préfixé ERROR_. La DLL d’interface utilisateur du moniteur d’impression reçoit cette valeur dans l’emplacement pdwStatus spécifié pour XcvData.

Remarques

Les DLL de serveur de surveillance de port sont nécessaires pour définir une fonction XcvDataPort afin qu’elles puissent recevoir des informations d’une DLL d’interface utilisateur du moniteur de port et les renvoyer. L’adresse de la fonction doit être incluse dans une structure MONITOR2 .

La fonction XcvDataPort est appelée par la fonction XcvData du spouleur. Les paramètres de fonction pour XcvDataPort et XcvData sont presque identiques. (XcvData a un paramètre supplémentaire, pdwStatus, qui n’est pas présent dans XcvDataPort.)

La chaîne pointée vers par pszDataName spécifie l’opération à effectuer. La fonction doit reconnaître les chaînes de noms de données suivantes :

Chaîne de nom de données	Opération
L"AddPort »	Toutes les informations nécessaires à l’ajout d’un port ont été envoyées. La fonction doit effectuer les opérations nécessaires pour ajouter le port spécifié, notamment en écrivant le nom du port dans le Registre sous la clé Ports. Le paramètre pInputData pointe vers une chaîne de nom de port terminée par NULL. Si la fonction retourne ERROR_SUCCESS, le spouleur marque le port comme ajouté. Cette chaîne est spécifiée par la DLL d’interface utilisateur du moniteur d’impression, à partir de sa fonction AddPortUI .
L"DeletePort »	Toutes les informations nécessaires à la suppression d’un port ont été envoyées. La fonction doit effectuer les opérations nécessaires pour supprimer le port spécifié, notamment en supprimant le nom du port de la clé Ports du Registre. Le paramètre pInputData pointe vers une chaîne de nom de port terminée par NULL. Si la fonction retourne ERROR_SUCCESS, le spouleur marque le port comme supprimé. Cette chaîne est spécifiée par la DLL d’interface utilisateur du moniteur d’impression, à partir de sa fonction DeletePortUI .
L"MonitorUI »	La fonction doit utiliser pOutputData pour renvoyer le nom de la DLL d’interface utilisateur du moniteur de port associée. Cette chaîne est spécifiée par le spouleur d’impression lorsqu’une application appelle la fonction AddPort Microsoft Windows SDK.

En règle générale, la fonction est écrite pour reconnaître des chaînes personnalisées supplémentaires envoyées par la DLL d’interface utilisateur à partir de ses fonctions AddPortUI, ConfigurePortUI et DeletePortUI . Ces chaînes peuvent représenter des commandes qui demandent des valeurs de configuration actuelles à la DLL du serveur ou qui fournissent de nouvelles valeurs. Par exemple, votre fonction XcvDataPort peut reconnaître la chaîne « GetTransmissionRetryTimeout », que votre DLL d’interface utilisateur peut envoyer à la DLL de votre serveur pour demander la valeur de délai d’attente de nouvelle tentative de transmission actuellement stockée. Vous pouvez également définir un ensemble de chaînes qui doivent être envoyées avant l’envoi de « AddPort » ou « DeletePort », où les chaînes sont utilisées pour fournir des informations identifiant le port à ajouter ou à supprimer.

Pour une chaîne pszDataName et une mémoire tampon d’entrée données, XcvDataPort peut d’abord être appelé avec une valeur cbOutputData de zéro. La fonction doit retourner une taille de mémoire tampon requise dans pcbOutputNeeded, ainsi qu’une valeur de retour de ERROR_INSUFFICIENT_BUFFER. L’appelant peut utiliser la valeur reçue dans pcbOutputNeeded pour allouer une mémoire tampon de sortie d’une taille adéquate, puis peut à nouveau appeler XcvDataPort , en spécifiant cette fois la taille de mémoire tampon allouée dans cbOutputData.

La fonction XcvDataPort doit valider tous les arguments d’entrée. Plus précisément, la fonction doit :

Validez le contenu de la chaîne pointée vers le paramètre pszDataName . Si cette chaîne représente une opération administrative (généralement l’ajout, la suppression ou la configuration d’un port), la fonction XcvDataPort doit comparer le masque d’accès accordé précédemment reçu par la fonction XcvOpenPort avec SERVER_ACCESS_ADMINISTER. Si la comparaison échoue, XcvDataPort doit retourner ERROR_ACCESS_DENIED.
Validez le contenu de la mémoire tampon pointée vers le paramètre pInputData . Lorsque le spouleur appelle la fonction XcvOpenPort , il n’effectue aucune validation sur le contenu de cette mémoire tampon. Le moniteur ne peut faire aucune hypothèse sur la validité de ces données, qui peuvent provenir d’une application malveillante.

Si vous écrivez un moniteur de port qui communiquera avec TCPMON, consultez Interface TCPMON Xcv.