Функция XcvDataPort (winsplp.h)

Статья
02/07/2025

Функция dll сервера мониторинга портов XcvDataPort получает сведения из библиотеки ПОЛЬЗОВАТЕЛЬСКОго интерфейса монитора портов и возвращает сведения в библиотеку DLL пользовательского интерфейса монитора портов.

Синтаксис

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

Параметры

[in] hXcv

Вызывающий дескриптор принтера, полученный путем вызова OpenPrinter (описано в документации по пакету SDK для Microsoft Windows). Этот дескриптор создается и возвращается функцией XcvOpenPort.

[in] pszDataName

Вызывающий указатель на строку, представляющую имя запрашиваемых данных. Дополнительные сведения см. в следующем разделе "Примечания".

[in] pInputData

Вызывающий указатель на буфер, содержащий входные данные.

cbInputData

Указанный вызывающим объектом размер в байтах буфера, на который указывает pInputData.

[out] pOutputData

Вызывающий указатель на буфер для получения выходных данных.

cbOutputData

Указанный вызывающим объектом размер в байтах буфера, на который указывает pOutputData.

[out] pcbOutputNeeded

Вызывающий указатель на расположение для получения минимального размера в байтах, необходимого для буфера, на который указывает pOutputData.

Возвращаемое значение

Если операция выполнена успешно, эта функция должна возвращать ERROR_SUCCESS. В противном случае он должен вернуть код ошибки Win32 с префиксом ERROR_. Библиотека DLL пользовательского интерфейса монитора печати получает это значение в расположении pdwStatus pdwStatus, указанном для XcvData.

Замечания

Библиотеки DLL сервера мониторинга портов требуются для определения функции XcvDataPort, чтобы они могли получать сведения из библиотеки DLL пользовательского интерфейса монитора портов и возвращать данные в библиотеку DLL пользовательского интерфейса монитора портов. Адрес функции должен быть включен в структуру MONITOR2.

Функция XcvDataPort вызывается функцией spooler XcvData. Параметры функции для XcvDataPort и XcvData почти идентичны. (XcvData имеет дополнительный параметр, pdwStatus, который отсутствует в XcvDataPort.)

Строка, на которую указывает pszDataName указывает выполняемую операцию. Функция должна распознать следующие строки имени данных:

Строка имени данных	Операция
L"AddPort"	Все сведения, необходимые для добавления порта, отправлены. Функция должна выполнять операции, необходимые для добавления указанного порта, включая запись имени порта в реестре в разделе "Порты". Параметр pInputData указывает на строку имени порта, завершаемой значением NULL. Если функция возвращает ERROR_SUCCESS, средство spooler помечает порт как добавленный. Эта строка указана библиотекой DLL пользовательского интерфейса монитора печати из функции AddPortUI.
L"DeletePort"	Отправлены все сведения, необходимые для удаления порта. Функция должна выполнять операции, необходимые для удаления указанного порта, включая удаление имени порта из раздела портов реестра. Параметр pInputData указывает на строку имени порта, завершаемой значением NULL. Если функция возвращает ERROR_SUCCESS, средство spooler помечает порт как удаленный. Эта строка указывается библиотекой DLL пользовательского интерфейса монитора печати из функции DeletePortUI.
L"MonitorUI"	Функция должна использовать pOutputData для возврата имени библиотеки DLL пользовательского интерфейса монитора портов. Эта строка указывается в средстве spooler печати, когда приложение вызывает функцию microsoft Windows SDK AddPort.

Как правило, функция записывается для распознавания дополнительных настраиваемых строк, отправляемых библиотекой DLL пользовательского интерфейса из его AddPortUI, ConfigurePortUIи функции DeletePortUI. Эти строки могут представлять команды, запрашивающие текущие значения конфигурации из библиотеки DLL сервера или предоставляющие новые значения. Например, функция XcvDataPort может распознать строку GetTransmissionRetryTimeout, которую БИБЛИОТЕКА пользовательского интерфейса может отправить в библиотеку DLL сервера, чтобы запросить значение времени ожидания повтора передачи в данный момент. Кроме того, можно определить набор строк, которые необходимо отправить до отправки "AddPort" или "DeletePort", где строки используются для предоставления сведений, определяющих порт для добавления или удаления.

Для заданного pszDataName строкового и входного буфера XcvDataPort можно сначала вызвать с cbOutputData значение нулю. Функция должна возвращать требуемый размер буфера в pcbOutputNeed, а также возвращаемое значение ERROR_INSUFFICIENT_BUFFER. Вызывающий объект может использовать значение, полученное в pcbOutputNeed для выделения выходного буфера соответствующего размера, а затем снова вызвать XcvDataPort, на этот раз указав выделенный размер буфера в cbOutputData.

Функция XcvDataPort должна проверять все входные аргументы. В частности, функция должна:

Проверьте содержимое строки, на которую указывает параметр pszDataName. Если эта строка представляет собой административную операцию (как правило, добавление, удаление или настройку порта), функция XcvDataPort должна сравнить предоставленную маску доступа, полученную ранее функцией XcvOpenPort с SERVER_ACCESS_ADMINISTER. Если сравнение завершается ошибкой, XcvDataPort должен вернуть ERROR_ACCESS_DENIED.
Проверьте содержимое буфера, на который указывает параметр pInputData. Когда spooler вызывает функцию XcvOpenPort, она не выполняет проверку содержимого этого буфера. Монитор не может делать никаких предположений о действительности этих данных, которые могут поступать из вредоносного приложения.

Если вы пишете монитор портов, который будет взаимодействовать с TCPMON, см. интерфейсе TCPMON Xcv.