Интерфейс TCPMON Xcv

В этом разделе описывается интерфейс приемопередата (Xcv) для стандартного монитора портов TCP/IP (TCPMON). Этот интерфейс, реализованный с помощью вызовов функций XcvData и XcvDataPort , позволяет пользователям, использующим его, настраивать порт принтера TCP/IP или получать сведения о конфигурации порта принтера TCP/IP. Интерфейс Xcv, описанный в этом разделе, предназначен для портов TCP/IP. Другие интерфейсы Xcv могут быть доступны для других типов портов.

Чтобы получить дескриптор интерфейса Xcv для локального или удаленного компьютера, вызовите функцию OpenPrinter . В следующем примере кода показано, как получить дескриптор Xcv к порту:

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>
}

В примере кода ServerName и PortName представляют строки имени сервера и порта. Получив дескриптор, можно запросить сведения, относящиеся к монитору портов TCPMON, или изменить конфигурацию порта. Обратите внимание, что доступ, необходимый для монитора портов, должен быть указан в элементе DesiredAccess структуры PRINTER_DEFAULTS или передавать значение NULL , если специальные средства безопасности не требуются. Для некоторых вызовов функции XcvData , например при указании команд AddPort и DeletePort (см. раздел Команды TCPMON Xcv), требуется SERVER_ACCESS_ADMINISTER привилегий. Дополнительные сведения о функции OpenPrinter и правах доступа, которые могут быть запрошены в структуре PRINTER_DEFAULTS, см. в документации по функции OpenPrinter .

Если порт еще не существует, дескриптор Xcv можно получить с сервера, указав имя монитора. (В случае стандартного порта tcp/IP монитора это "Стандартный tcp/IP-порт".) В следующем примере кода показано, как получить дескриптор данных Xcv в монитор порта:

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>
}

В примере кода ServerName и PortName представляют строки имени сервера и порта. Получив дескриптор данных Xcv, вы можете выдавать инструкции и запросы к монитору, вызвав функцию XcvData .

Обратите внимание, что возвращаемое значение функции XcvData указывает только, правильно ли были отправлены данные в монитор портов. Возвращаемое значение TRUE не указывает, что операция прошла успешно. Чтобы определить, была ли операция успешной, проверьте значение в *pdwStatus. Эти значения состояния приведены в следующей таблице:

Значение состояния	Значение
NO_ERROR	Операция выполнена успешно.
ERROR_ACCESS_DENIED	У пользователя недостаточно привилегий. Для выполнения команды требуются права SERVER_ACCESS_ADMINISTER.
ERROR_INSUFFICIENT_BUFFER	Выходной буфер является обязательным, но меньше требуемого.
ERROR_INVALID_DATA	Входной буфер является обязательным, но указатель на него имеет значение NULL или размер входного буфера меньше требуемого.
ERROR_INVALID_HANDLE	Недопустимый дескриптор данных Xcv.
ERROR_INVALID_LEVEL	Структура входных или выходных данных не является правильной версией.
ERROR_INVALID_PARAMETER	Выходной буфер является обязательным, но он имеет значение NULL, либо обязательный выходной параметр равен NULL , а выходной буфер слишком мал, либо стандартный монитор портов TCP/IP не понимает выполняемую команду.