Interface TCPMON Xcv

Esta seção descreve a interface transceive (Xcv) para o TCPMON (monitor de porta TCP/IP) padrão. Essa interface, que é implementada usando chamadas de função XcvData e XcvDataPort , permite que aqueles que a usam configurem uma porta de impressora TCP/IP ou obtenham informações sobre uma configuração de porta de impressora TCP/IP. A interface Xcv descrita nesta seção é específica para portas TCP/IP. Outras interfaces Xcv podem estar disponíveis para outros tipos de porta.

Para obter um identificador para uma interface Xcv para um computador local ou um computador remoto, chame a função OpenPrinter . O exemplo de código a seguir ilustra como obter um identificador Xcv para uma porta:

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a local TCPMON port
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a TCPMON port on <ServerName>
}

No exemplo de código, ServerName e PortName representam cadeias de caracteres de nome de servidor e porta. Depois de obter o identificador, você pode consultar informações específicas do monitor de porta TCPMON ou alterar a configuração da porta. Observe que o acesso necessário para o monitor de porta deve ser especificado no membro DesiredAccess da estrutura PRINTER_DEFAULTS ou passar NULL se nenhuma segurança especial for necessária. Para determinadas chamadas para a função XcvData , como quando os comandos AddPort e DeletePort são especificados (consulte Comandos Xcv TCPMON), SERVER_ACCESS_ADMINISTER privilégio é necessário. Para obter detalhes sobre a função OpenPrinter e os direitos de acesso que podem ser solicitados na estrutura PRINTER_DEFAULTS, consulte a documentação da função OpenPrinter .

Se a porta ainda não existir, o identificador Xcv poderá ser obtido do servidor especificando o nome do monitor. (No caso da porta padrão do monitor de porta TCP/IP, essa é a "Porta TCP/IP Padrão".) O exemplo de código a seguir ilustra como obter um identificador de dados Xcv para um monitor de porta:

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor <MonitorName>
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor 
 // <MonitorName> on the server <ServerName>
}

No exemplo de código, ServerName e PortName representam cadeias de caracteres de nome de servidor e porta. Depois de obter o identificador de dados Xcv, você pode emitir instruções e solicitações para o monitor chamando a função XcvData .

Observe que o valor retornado da função XcvData indica apenas se os dados foram enviados corretamente para o monitor de porta. Um valor retornado de TRUE não indica que a operação foi bem-sucedida. Para determinar se a operação foi bem-sucedida, inspecione o valor em *pdwStatus. Esses valores status são resumidos na tabela a seguir:

Valor de status	Significado
NO_ERROR	A operação foi bem-sucedida.
ERROR_ACCESS_DENIED	O usuário não tem privilégios suficientes. O comando requer SERVER_ACCESS_ADMINISTER privilégio.
ERROR_INSUFFICIENT_BUFFER	Um buffer de saída é necessário, mas é menor do que o necessário.
ERROR_INVALID_DATA	Um buffer de entrada é necessário, mas o ponteiro para ele é NULL ou o tamanho do buffer de entrada é menor do que o necessário.
ERROR_INVALID_HANDLE	O identificador de dados Xcv é inválido.
ERROR_INVALID_LEVEL	A estrutura de dados de entrada ou saída não é a versão correta.
ERROR_INVALID_PARAMETER	Um buffer de saída é necessário, mas é NULL ou o parâmetro necessário de saída é NULL e o buffer de saída é muito pequeno ou o monitor de porta TCP/IP padrão não entende o comando que está sendo emitido.