Fonction ReadPort (winsplp.h)

Article
02/27/2024

La fonction d’un moniteur de ReadPort 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 des 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 correctement lus à partir du port.

Valeur retournée

Si l’opération réussit, la fonction doit retourner TRUE. Sinon, elle doit retourner FALSE.

Remarques

Les moniteurs de langage et les DLL de serveur de surveillance de port sont nécessaires pour définir une ReadPort fonction 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 d’un moniteur de ReadPort langage appelle la fonction du moniteur de ReadPort port associé 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 du moniteur de ReadPort port pour case activée pour obtenir des informations de status non sollicitées. Si une telle opération de lecture réussit, les informations de status doivent être retournées au spouleur en appelant SetPort (décrit dans la documentation Microsoft Windows SDK).

En règle générale, la fonction d’une DLL de serveur de surveillance de ReadPort port appelle ReadFile (décrit dans la documentation 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 des fonctions et placer leurs adresses dans des structures MONITOR2, la fonction d’un moniteur de ReadPort 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 watch pour obtenir des informations de status d’imprimante non sollicitées, et la ReadPort fonction appelle la fonction du moniteur de ReadPort port. Lorsque le moniteur de port retourne des données au moniteur de langue, celui-ci analyse les données reçues et appelle SetPort (décrit dans la documentation SDK Windows) pour envoyer status informations au spouleur.

La fonction doit retourner le nombre d’octets correctement lus en plaçant le nombre à l’emplacement indiqué par pcbRead. L’appelant détermine la réussite ou l’échec de l’opération d’écriture en vérifiant ReadPort's la 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 un échec de lecture, sauf si la fonction retourne FALSE.

Une sorte de mécanisme de délai d’attente implémenté par le système ou implémenté par le moniteur doit garantir que la ReadPort fonction retourne dans un délai raisonnable, afin d’éviter de bloquer le spouleur.

Il est acceptable pour un moniteur de langue d’appeler la routine d’un moniteur de ReadPort port en dehors d’une paire StartDocPort/EndDocPort . (Un tel appel peut être généré par un thread qui recherche des status non sollicités.) Toutefois, certains moniteurs de port peuvent échouer à un tel appel, de sorte que le moniteur de langue doit être écrit pour gérer cet échec.