Функция AddPrinter

Статья
06/12/2023

Функция AddPrinter добавляет принтер в список поддерживаемых принтеров для указанного сервера.

Синтаксис

HANDLE AddPrinter(
  _In_ LPTSTR *pName,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter
);

Параметры

pName [in]: Указатель на строку, завершающуюся значением NULL, которая указывает имя сервера, на котором должен быть установлен принтер. Если эта строка имеет значение NULL, принтер устанавливается локально.
Level [in]: Версия структуры, на которую указывает pPrinter . Это значение должно быть равно 2.
pPrinter [in]: Указатель на структуру PRINTER_INFO_2 , содержащую сведения о принтере. Перед вызовом AddPrinter необходимо указать значения, отличные от NULL, для элементов pPrinterName, pPortName, pDriverName и pPrintProcessor этой структуры.

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

Если функция выполняется успешно, возвращаемое значение является дескриптором (не потокобезопасный) для нового объекта принтера. Завершив работу с дескриптором, передайте его в функцию ClosePrinter , чтобы закрыть его.

Если функция завершается сбоем, возвращается значение NULL.

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

Вызывающий объект должен иметь SeLoadDriverPrivilege.

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

Ниже приведены элементы структуры PRINTER_INFO_2 , которые можно задать перед вызовом функции AddPrinter :

Атрибуты
pPrintProcessor
DefaultPriority
Приоритет
pComment
pSecurityDescriptor
pDatatype
pSepFile
pDevMode
pShareName
pLocation
StartTime
pParameters
UntilTime

Элементы Status, cJobs и AveragePPM структуры PRINTER_INFO_2 зарезервированы для использования функцией GetPrinter . Их не следует задавать перед вызовом AddPrinter.

Если pSecurityDescriptor имеет значение NULL, система назначает принтеру дескриптор безопасности по умолчанию. Дескриптор безопасности по умолчанию имеет следующие разрешения.

Значение	Описание
Администраторы и опытные пользователи.	Полный доступ к очереди печати. Это означает, что члены этих групп могут печатать, управлять очередью (может удалять очередь, изменять любые параметры очереди, включая дескриптор безопасности), а также управлять заданиями печати всех пользователей (удаление, приостановка, возобновление, перезапуск заданий). Обратите внимание, что опытные пользователи не существуют до Windows XP Professional.
Создатель/владелец	Может управлять собственными заданиями. Это означает, что пользователь, отправивший задания, может управлять (удалять, приостанавливать, возобновлять, перезапускать) своими заданиями.
Все	Выполнение и стандартное управление чтением. Это означает, что члены группы "Все" могут печатать и считывать свойства очереди печати.

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

Функция AddPrinter возвращает ошибку, если объект принтера с тем же именем уже существует, если этот объект не помечен как ожидающий удаления. В этом случае существующий принтер не удаляется, а параметры создания AddPrinter используются для изменения существующих параметров принтера (как если бы приложение использовало функцию SetPrinter ).

Используйте функцию EnumPrintProcessors для перечисления набора процессоров печати, установленных на сервере. Используйте функцию EnumPrintProcessorDatatypes для перечисления набора типов данных, поддерживаемых обработчиком печати. Используйте функцию EnumPorts для перечисления набора доступных портов. Используйте функцию EnumPrinterDrivers для перечисления установленных драйверов принтера.

Вызывающий объект функции AddPrinter должен иметь SERVER_ACCESS_ADMINISTER доступ к серверу, на котором должен быть создан принтер. Дескриптор, возвращаемый функцией, будет иметь PRINTER_ALL_ACCESS разрешение и может использоваться для выполнения административных операций на принтере.

Если функции DrvPrinterEvent передается флаг PRINTER_EVENT_FLAG_NO_UI, драйвер не должен использовать вызов пользовательского интерфейса во время DrvPrinterEvent. Для выполнения заданий, связанных с пользовательским интерфейсом, установщик должен либо использовать запись VendorSetup в INF-файле принтера, либо для Plug and Play устройств установщик может использовать совместное установщик для конкретного устройства. Дополнительные сведения о VendorSetup см. в разделе Microsoft Windows Driver Development Kit (DDK).

Брандмауэр подключения к Интернету (ICF) по умолчанию блокирует порты принтеров, но при запуске AddPrinter включено исключение для общего доступа к файлам и печати.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Заголовок	Winspool.h (включая Windows.h)
Библиотека	Winspool.lib
DLL	Winspool.drv
Имя в кодировке Юникод и ANSI	AddPrinterW (Юникод) и AddPrinterA (ANSI)

См. также раздел

Вывод на печать
Функции API очереди печати принтера
ClosePrinter
DeletePrinter
EnumPorts
EnumPrinterDrivers
EnumPrintProcessors
EnumPrintProcessorDatatypes
GetPrinter
PRINTER_INFO_2
Свойства PrinterProperties
SetPrinter