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

Статья
02/07/2025

Функция dll пользовательского интерфейса мониторинга портов AddPortUI добавляет порт принтера, а затем получает сведения о конфигурации порта от пользователя и отправляет его в библиотеку DLL сервера мониторинга портов.

Синтаксис

BOOL AddPortUI(
  [in, optional]  PCWSTR pszServer,
  [in]            HWND   hWnd,
                  PCWSTR pszMonitorNameIn,
  [out, optional] PWSTR  *ppszPortNameOut
);

Параметры

[in, optional] pszServer

Вызывающий указатель на строку, представляющую имя сервера или NULL, если принтер является локальным.

[in] hWnd

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

pszMonitorNameIn

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

[out, optional] ppszPortNameOut

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

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

Если операция выполнена успешно, функция должна вернуть TRUE. В противном случае необходимо вызвать SetLastError, чтобы указать код ошибки, и функция должна возвращать FALSE. Если операция отменена пользователем или не поддерживается, функция должна вызвать SetLastError(ERROR_CANCELLED), а затем вернуть FALSE.

Замечания

Библиотеки DLL мониторинга портов требуются для определения функции AddPortUI и включения адреса функции в структуру MONITORUI.

Spooler вызывает AddPortUI из функции AddPort. Первые три аргумента, полученные AddPortUI являются аргументами, полученными AddPort. (Функция AddPort описана в документации по пакету SDK для Microsoft Windows.)

Функция должна выполнять следующие операции:

Вызов OpenPrinter, указав имя принтера со следующим форматом:

\\ Имя сервера\,XcvMonitorMonitorName

где ServerName и MonitorName являются именами серверов и мониторов, полученных в качестве аргументов функции AddPortUI .

Для вызова OpenPrinter требуется структура PRINTER_DEFAULTS, описанная в документации по пакету SDK для Windows. Элемент DesiredAccess структуры должен иметь значение SERVER_ACCESS_ADMINISTER. Его элементы pDatatype и pDevMode могут быть null.

Этот вызов приводит к вызову функции XcvOpenPort сервера монитора печати.
Получите имя порта от пользователя, отображая диалоговое окно.
Вызовите XcvData, указав следующие входные аргументы:
- Дескриптор, полученный от OpenPrinter
- Имя порта, полученное от пользователя
- Настраиваемая строка имени данных, например PortExists
Этот вызов приводит к вызову функции XcvDataPort сервера, библиотеки DLL сервера. Функция XcvDataPort должна возвращать значение, указывающее, уже использовалось ли указанное имя порта. Если она имеется, библиотека DLL пользовательского интерфейса должна запросить другое имя от пользователя и снова вызвать XcvData.
После получения допустимого нового имени порта вызовите XcvData на этот раз, указав следующие входные аргументы.
- Дескриптор, полученный от OpenPrinter
- Проверенное имя порта, полученное от пользователя
- Строка имени данных "AddPort"
Этот вызов приводит к повторному вызову функции XcvData Port библиотеки DLL сервера.
Получите параметры конфигурации порта от пользователя, отображая диалоговое окно.
Вызов XcvData один или несколько раз, указав настраиваемые строки имен данных, чтобы отправить каждый параметр конфигурации в библиотеку DLL сервера. Каждый вызов XcvData приводит к вызову функции XcvDataPort сервера.
Вызов ClosePrinter, указав дескриптор, полученный от OpenPrinter. Это приводит к вызову функции XcvClosePort библиотеки DLL сервера.