Função ReadPort (winsplp.h)

Artigo
08/08/2023

A função de um monitor de ReadPort porta lê dados de uma porta de impressora.

Sintaxe

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

Parâmetros

[in] hPort

Identificador de porta fornecido pelo chamador.

[out] pBuffer

Ponteiro fornecido pelo chamador para um buffer para receber dados lidos da porta.

cbBuffer

Tamanho fornecido pelo chamador, em bytes, de pBuffer.

[out] pcbRead

Ponteiro fornecido pelo chamador para um local para receber o número de bytes lidos com êxito da porta.

Retornar valor

Se a operação for bem-sucedida, a função deverá retornar TRUE. Caso contrário, ele deverá retornar FALSE.

Comentários

Monitores de linguagem e DLLs de servidor de monitor de porta são necessários para definir uma ReadPort função e incluir o endereço da função em uma estrutura MONITOR2 .

O identificador recebido como o argumento hPort da função é o identificador de porta fornecido pela função OpenPort ou OpenPortEx do monitor.

Normalmente, a função de um monitor de ReadPort linguagem chama a função do monitor de ReadPort porta associada e retorna o conteúdo do buffer obtido para o chamador.

Além disso, um monitor de linguagem pode criar um thread separado que chama a função do monitor de ReadPort porta para marcar para obter informações de status não solicitadas. Se essa operação de leitura for bem-sucedida, as informações de status deverão ser retornadas ao spooler chamando SetPort (descrito na documentação do SDK do Microsoft Windows).

Normalmente, a função da DLL de ReadPort um servidor de monitor de porta chama ReadFile (descrito na documentação do SDK do Windows) para obter dados do driver de porta no modo kernel. A função apenas retorna os dados para o chamador.

Embora monitores de linguagem e monitores de porta precisem definir ReadPort funções e colocar seus endereços em estruturas MONITOR2, a função de um monitor de ReadPort linguagem nunca é realmente chamada pelo spooler ou por um aplicativo. A função é exclusivamente para o uso interno do próprio monitor de linguagem.

Por exemplo, pjlmon.dll, o monitor de idioma de exemplo, cria um thread separado que chama seu próprio ReadPort para watch para informações de status de impressora não solicitadas e a ReadPort função chama a função do monitor de ReadPort porta. Quando o monitor de porta retorna dados para o monitor de idioma, o monitor de idioma analisa os dados recebidos e chama SetPort (descrito na documentação do SDK do Windows) para enviar status informações ao spooler.

A função deve retornar o número de bytes lidos com êxito colocando o número no local apontado por pcbRead. O chamador determina o êxito ou a falha da operação de gravação verificando ReadPort's o valor retornado, não a contagem de bytes retornada. Portanto, uma contagem de bytes retornada de zero não representa uma leitura com falha, a menos que a função retorne FALSE.

Algum tipo de mecanismo de tempo limite implementado pelo sistema ou implementado pelo monitor deve garantir que a ReadPort função retorne dentro de um período razoável, para evitar a interrupção do spooler.

É aceitável que um monitor de idioma chame a rotina de ReadPort um monitor de porta fora de um par StartDocPort/EndDocPort . (Essa chamada pode ser gerada por uma verificação de thread para status não solicitados.) No entanto, alguns monitores de porta podem falhar em tal chamada, portanto, o monitor de idioma deve ser gravado para lidar com essa falha.