Función ReadPort (winsplp.h)

Artículo
08/08/2023

Una función del monitor de ReadPort puerto lee los datos de un puerto de impresora.

Sintaxis

BOOL ReadPort(
  _In_  HANDLE  hPort,
  _Out_ LPBYTE  pBuffer,
        DWORD   cbBuffer,
  _Out_ LPDWORD pcbRead
);

Parámetros

[in] hPort

Identificador de puerto proporcionado por el autor de la llamada.

[out] pBuffer

Puntero proporcionado por el autor de la llamada a un búfer para recibir datos leídos del puerto.

cbBuffer

Tamaño proporcionado por el autor de la llamada, en bytes, de pBuffer.

[out] pcbRead

Puntero proporcionado por el autor de la llamada a una ubicación para recibir el número de bytes leídos correctamente desde el puerto.

Valor devuelto

Si la operación se realiza correctamente, la función debe devolver TRUE. De lo contrario, debe devolver FALSE.

Comentarios

Los monitores de lenguaje y los archivos DLL del servidor de supervisión de puertos son necesarios para definir una ReadPort función e incluir la dirección de la función en una estructura de MONITOR2 .

El identificador recibido como argumento hPort de la función es el identificador de puerto que proporcionó la función OpenPort o OpenPortEx del monitor.

Normalmente, la función de un monitor de ReadPort lenguaje llama a la función del monitor de ReadPort puerto asociado y devuelve el contenido del búfer obtenido al autor de la llamada.

Además, un monitor de lenguaje puede crear un subproceso independiente que llame a la función del monitor de ReadPort puerto para comprobar si hay información de estado no solicitada. Si esta operación de lectura se realiza correctamente, la información de estado se debe devolver al colador llamando a SetPort (que se describe en la documentación de Microsoft Windows SDK).

Normalmente, una función del archivo DLL del ReadPort servidor de supervisión de puertos llama a ReadFile (que se describe en la documentación de Windows SDK) para obtener datos del controlador de puerto en modo kernel. La función simplemente devuelve los datos al autor de la llamada.

Aunque tanto los monitores de lenguaje como los monitores de puerto deben definir ReadPort funciones y colocar sus direcciones en estructuras de MONITOR2, la función de ReadPort un monitor de lenguaje nunca la llama realmente el administrador de colas o una aplicación. La función es únicamente para el uso interno del propio monitor de idioma.

Por ejemplo, pjlmon.dll, el monitor de lenguaje de ejemplo, crea un subproceso independiente que llama a su propio ReadPort para watch para obtener información de estado de la impresora no solicitada y la ReadPort función llama a la función del monitor de ReadPort puerto. Cuando el monitor de puerto devuelve datos al monitor de idioma, el monitor de idioma analiza los datos recibidos y llama a SetPort (descrito en la documentación de Windows SDK) para enviar información de estado al administrador de colas.

La función debe devolver el número de bytes leídos correctamente colocando el número en la ubicación a la que apunta pcbRead. El autor de la llamada determina el éxito o error de la operación de escritura comprobando ReadPort's el valor devuelto, no el recuento de bytes devuelto. Por lo tanto, un recuento de bytes devuelto de cero no representa una lectura errónea a menos que la función devuelva FALSE.

Algún tipo de mecanismo de tiempo de espera implementado por el sistema o implementado por el monitor debe asegurarse de que la ReadPort función devolverá dentro de un período de tiempo razonable, para evitar que se detenga el colador.

Es aceptable que un monitor de idioma llame a la rutina de un monitor de ReadPort puerto fuera de un par StartDocPort/EndDocPort . (Es posible que una llamada de este tipo se genere mediante una comprobación del subproceso de estado no solicitado). Sin embargo, algunos monitores de puerto pueden producir un error en esta llamada, por lo que el monitor de idioma debe escribirse para controlar este error.