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

Статья
03/13/2023

Функция XcvDataPort сервера мониторинга портов dll получает сведения из библиотеки 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 (описано в документации по Microsoft Windows SDK). Этот дескриптор создается и возвращается функцией XcvOpenPort .

[in] pszDataName

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

[in] pInputData

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

cbInputData

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

[out] pOutputData

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

cbOutputData

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

[out] pcbOutputNeeded

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

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

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

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

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

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

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

Как правило, функция записывается для распознавания дополнительных настраиваемых строк, которые отправляются библиотекой DLL пользовательского интерфейса из функций AddPortUI, ConfigurePortUI и DeletePortUI . Эти строки могут представлять команды, которые запрашивают текущие значения конфигурации из библиотеки DLL сервера или предоставляют новые значения. Например, функция XcvDataPort может распознать строку GetTransmissionRetryTimeout, которую библиотека DLL пользовательского интерфейса может отправить в библиотеку DLL сервера для запроса сохраненного значения времени ожидания повтора передачи. Вы также можете определить набор строк, которые должны быть отправлены перед отправкой addPort или DeletePort, где строки используются для предоставления сведений, определяющих порт для добавления или удаления.

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

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

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

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

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	winsplp.h (включая Winsplp.h)
Библиотека	NtosKrnl.exe