ReadPort, fonction (winsplp.h)
La fonction ReadPort d’un moniteur de port lit les données d’un port d’imprimante.
Syntaxe
BOOL ReadPort(
_In_ HANDLE hPort,
_Out_ LPBYTE pBuffer,
DWORD cbBuffer,
_Out_ LPDWORD pcbRead
);
Paramètres
[in] hPort
Handle de port fourni par l’appelant.
[out] pBuffer
Pointeur fourni par l’appelant vers une mémoire tampon pour recevoir les données lues à partir du port.
cbBuffer
Taille fournie par l’appelant, en octets, de pBuffer .
[out] pcbRead
Pointeur fourni par l’appelant vers un emplacement pour recevoir le nombre d’octets lus correctement à partir du port.
Valeur de retour
Si l’opération réussit, la fonction doit retourner TRUE. Sinon, elle doit retourner FALSE.
Remarques
moniteurs de langage et les DLL du serveur de surveillance de port sont nécessaires pour définir une fonction ReadPort et inclure l’adresse de la fonction dans une structure MONITOR2.
Le handle reçu en tant qu’argument hPort de la fonction est le handle de port fourni par la fonction openPort ou OpenPortEx du moniteur.
En règle générale, la fonction ReadPort d’un moniteur de langage appelle la fonction ReadPort du moniteur de port associée et retourne le contenu de la mémoire tampon obtenue à l’appelant.
En outre, un moniteur de langue peut créer un thread distinct qui appelle la fonction ReadPort du moniteur de port pour rechercher les informations d’état non sollicitées. Si une telle opération de lecture réussit, les informations d’état doivent être retournées au spouleur en appelant SetPort (décrit dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows).
En règle générale, la fonction ReadPort d’un serveur moniteur de ports appelle readFile (décrite dans la documentation du Kit de développement logiciel (SDK) Windows) pour obtenir des données à partir du pilote de port en mode noyau. La fonction retourne simplement les données à l’appelant.
Même si les moniteurs de langage et les moniteurs de port doivent définir ReadPort fonctions et placer leurs adresses dans des structures MONITOR2, la fonction ReadPort d’un moniteur de langage n’est jamais réellement appelée par le spouleur ou une application. La fonction est uniquement destinée à l’utilisation interne du moniteur de langage lui-même.
Par exemple, pjlmon.dll, l’exemple de moniteur de langue, crée un thread distinct qui appelle son propre ReadPort pour surveiller les informations d’état de l’imprimante non sollicitée, et la fonction ReadPort appelle la fonction ReadPort du moniteur de port. Lorsque le moniteur de port retourne des données au moniteur de langue, le moniteur de langue analyse les données reçues et appelle SetPort (décrit dans la documentation du Kit de développement logiciel (SDK) Windows) pour envoyer des informations d’état au spouleur.
La fonction doit renvoyer le nombre d’octets lus avec succès en plaçant le nombre à l’emplacement vers lequel pointe . L’appelant détermine la réussite ou l’échec de l’opération d’écriture en vérifiant ReadPort's valeur de retour, et non le nombre d’octets retournés. Par conséquent, un nombre d’octets retourné de zéro ne représente pas une lecture ayant échoué, sauf si la fonction retourne FALSE.
Un certain type de mécanisme de délai d’attente implémenté par le système ou de surveillance doit s’assurer que la fonction ReadPort retournera dans un délai raisonnable, afin d’éviter de bloquer le spouleur.
Il est acceptable qu’un moniteur de langue appelle la routine de ReadPort d’un moniteur de port en dehors d’une paire StartDocPort/EndDocPort. (Un tel appel peut être généré par une vérification de thread pour l’état non sollicité.) Toutefois, certains moniteurs de port peuvent échouer à un tel appel, de sorte que le moniteur de langue doit être écrit pour gérer cette défaillance.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Bureau |
| d’en-tête | winsplp.h (include Winsplp.h) |
| bibliothèque | NtosKrnl.exe |