Funzione ReadPort (winsplp.h)

Articolo
02/27/2024

La funzione di ReadPort monitoraggio della porta legge i dati da una porta della stampante.

Sintassi

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

Parametri

[in] hPort

Handle di porta fornito dal chiamante.

[out] pBuffer

Puntatore fornito dal chiamante a un buffer per ricevere i dati letti dalla porta.

cbBuffer

Dimensioni fornite dal chiamante, in byte, di pBuffer.

[out] pcbRead

Puntatore fornito dal chiamante a una posizione per ricevere il numero di byte letti correttamente dalla porta.

Valore restituito

Se l'operazione ha esito positivo, la funzione deve restituire TRUE. In caso contrario, deve restituire FALSE.

Commenti

I monitoraggi del linguaggio e le DLL del server di monitoraggio delle porte sono necessari per definire una ReadPort funzione e includere l'indirizzo della funzione in una struttura MONITOR2.

L'handle ricevuto come argomento hPort della funzione è l'handle di porta fornito dalla funzione OpenPort o OpenPortEx del monitoraggio.

In genere, la funzione di ReadPort monitoraggio del linguaggio chiama la funzione del ReadPort monitor della porta associata e restituisce il contenuto del buffer ottenuto al chiamante.

Inoltre, un monitoraggio del linguaggio potrebbe creare un thread separato che chiama la funzione del ReadPort monitor della porta per verificare la presenza di informazioni sullo stato non richieste. Se un'operazione di lettura ha esito positivo, le informazioni sullo stato devono essere restituite al spooler chiamando SetPort (descritto nella documentazione di Microsoft Windows SDK).

In genere, una DLL del server di monitoraggio porta chiama ReadFile (descritta nella documentazione di ReadPort Windows SDK) per ottenere dati dal driver della porta in modalità kernel. La funzione restituisce solo i dati al chiamante.

Anche se sia i monitoraggi del linguaggio che i monitoraggi delle porte devono definire ReadPort le funzioni e inserire gli indirizzi nelle strutture MONITOR2, la funzione di ReadPort monitoraggio del linguaggio non viene mai chiamata in realtà dallo spooler o da un'applicazione. La funzione è esclusivamente per l'uso interno del monitoraggio del linguaggio stesso.

Ad esempio, pjlmon.dll, il monitoraggio del linguaggio di esempio crea un thread separato che chiama il proprio ReadPort per watch per informazioni sullo stato della stampante non richieste e la funzione chiama la ReadPort funzione del ReadPort monitor della porta. Quando il monitoraggio delle porte restituisce i dati al monitoraggio del linguaggio, il monitoraggio del linguaggio analizza i dati ricevuti e chiama SetPort (descritto nella documentazione di Windows SDK) per inviare informazioni sullo stato al spooler.

La funzione deve restituire il numero di byte letti correttamente inserendo il numero nella posizione puntata da pcbRead. Il chiamante determina l'esito positivo o negativo dell'operazione di scrittura controllando ReadPort's il valore restituito, non il conteggio dei byte restituiti. Quindi un conteggio di byte restituito di zero non rappresenta una lettura non riuscita a meno che la funzione non restituisca FALSE.

Un certo tipo di meccanismo di timeout implementato dal sistema o di monitoraggio deve garantire che la funzione restituirà entro un periodo di tempo ragionevole, per evitare di stallare lo ReadPort spooler.

È accettabile che un monitoraggio del linguaggio chiami la routine di ReadPort un monitoraggio porta all'esterno di una coppia StartDocPort EndDocPort/. Tale chiamata potrebbe essere generata da un controllo thread per lo stato non richiesto. Tuttavia, alcuni monitoraggi delle porte potrebbero non riuscire in una chiamata di questo tipo, quindi il monitoraggio del linguaggio deve essere scritto per gestire questo errore.