Função XcvDataPort (winsplp.h)

Artigo
03/13/2023

Uma função XcvDataPort do servidor de monitor de porta recebe informações e retorna informações para a DLL da interface do usuário do monitor de porta.

Sintaxe

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

Parâmetros

[in] hXcv

Identificador de impressora fornecido pelo chamador, obtido chamando OpenPrinter (descrito na documentação do SDK do Microsoft Windows). Esse identificador é criado e retornado pela função XcvOpenPort .

[in] pszDataName

Ponteiro fornecido pelo chamador para uma cadeia de caracteres que representa o nome dos dados que estão sendo solicitados. Para obter mais informações, consulte a seção Comentários a seguir.

[in] pInputData

Ponteiro fornecido pelo chamador para um buffer que contém dados de entrada.

cbInputData

Tamanho fornecido pelo chamador, em bytes, do buffer apontado por pInputData.

[out] pOutputData

Ponteiro fornecido pelo chamador para um buffer para receber dados de saída.

cbOutputData

Tamanho fornecido pelo chamador, em bytes, do buffer apontado por pOutputData.

[out] pcbOutputNeeded

Ponteiro fornecido pelo chamador para um local para receber o tamanho mínimo, em bytes, necessário para o buffer apontado por pOutputData.

Retornar valor

Se a operação for bem-sucedida, essa função deverá retornar ERROR_SUCCESS. Caso contrário, ele deverá retornar um código de erro Win32 prefixado por ERROR_. A DLL da interface do usuário do monitor de impressão recebe esse valor no local pdwStatus especificado para XcvData.

Comentários

As DLLs do servidor de monitor de porta são necessárias para definir uma função XcvDataPort para que possam receber informações e retornar informações para uma DLL de interface do usuário do monitor de porta. O endereço da função deve ser incluído em uma estrutura MONITOR2 .

A função XcvDataPort é chamada pela função XcvData do spooler. Os parâmetros de função para XcvDataPort e XcvData são quase idênticos. (XcvData tem um parâmetro adicional, pdwStatus, que não está presente em XcvDataPort.)

A cadeia de caracteres apontada por pszDataName especifica a operação a ser executada. A função deve reconhecer as seguintes cadeias de caracteres de nome de dados:

Cadeia de caracteres de nome de dados	Operação
L"AddPort"	Todas as informações necessárias para adicionar uma porta foram enviadas. A função deve executar as operações necessárias para adicionar a porta especificada, incluindo a gravação do nome da porta no registro na chave Portas. O parâmetro pInputData aponta para uma cadeia de caracteres de nome de porta terminada em NULL. Se a função retornar ERROR_SUCCESS, o spooler marcará a porta como adicionada. Essa cadeia de caracteres é especificada pela DLL da interface do usuário do monitor de impressão, de dentro de sua função AddPortUI .
L"DeletePort"	Todas as informações necessárias para excluir uma porta foram enviadas. A função deve executar as operações necessárias para excluir a porta especificada, incluindo a remoção do nome da porta da chave portas do registro. O parâmetro pInputData aponta para uma cadeia de caracteres de nome de porta terminada em NULL. Se a função retornar ERROR_SUCCESS, o spooler marcará a porta como excluída. Essa cadeia de caracteres é especificada pela DLL da interface do usuário do monitor de impressão, de dentro de sua função DeletePortUI .
L"MonitorUI"	A função deve usar pOutputData para retornar o nome da DLL da interface do usuário do monitor de porta associada. Essa cadeia de caracteres é especificada pelo spooler de impressão, quando um aplicativo chama a função SDK do Microsoft Windows AddPort.

Normalmente, a função é gravada para reconhecer cadeias de caracteres adicionais e personalizadas que são enviadas pela DLL da interface do usuário de dentro de suas funções AddPortUI, ConfigurePortUI e DeletePortUI . Essas cadeias de caracteres podem representar comandos que solicitam valores de configuração atuais da DLL do servidor ou que fornecem novos valores. Por exemplo, sua função XcvDataPort pode reconhecer a cadeia de caracteres "GetTransmissionRetryTimeout", que a DLL da interface do usuário pode enviar à DLL do servidor para solicitar o valor de tempo limite de repetição de transmissão armazenado no momento. Ou você pode definir um conjunto de cadeias de caracteres que devem ser enviadas antes que "AddPort" ou "DeletePort" seja enviado, para onde as cadeias de caracteres são usadas para fornecer informações que identifiquem a porta a ser adicionada ou excluída.

Para uma determinada cadeia de caracteres pszDataName e um buffer de entrada, XcvDataPort pode primeiro ser chamado com um valor cbOutputData igual a zero. A função deve retornar um tamanho de buffer necessário em pcbOutputNeeded, juntamente com um valor retornado de ERROR_INSUFFICIENT_BUFFER. O chamador pode usar o valor recebido em pcbOutputNeeded para alocar um buffer de saída de tamanho adequado e, em seguida, pode chamar XcvDataPort novamente, desta vez especificando o tamanho do buffer alocado em cbOutputData.

A função XcvDataPort deve validar todos os argumentos de entrada. Especificamente, a função deve:

Valide o conteúdo da cadeia de caracteres apontada pelo parâmetro pszDataName . Se essa cadeia de caracteres representar uma operação administrativa (normalmente adicionando, excluindo ou configurando uma porta), a função XcvDataPort deverá comparar a máscara de acesso concedida que foi recebida anteriormente pela função XcvOpenPort com SERVER_ACCESS_ADMINISTER. Se a comparação falhar, XcvDataPort deverá retornar ERROR_ACCESS_DENIED.
Valide o conteúdo do buffer apontado pelo parâmetro pInputData . Quando o spooler chama a função XcvOpenPort , ele não executa nenhuma validação no conteúdo desse buffer. O monitor não pode fazer suposições sobre a validade desses dados, que podem vir de um aplicativo mal-intencionado.

Se você estiver escrevendo um monitor de porta que se comunicará com TCPMON, consulte Interface Xcv TCPMON.