Функция SetPrinter
Функция SetPrinter задает данные для указанного принтера или задает состояние указанного принтера путем приостановки печати, возобновления печати или очистки всех заданий печати.
Синтаксис
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Параметры
-
hPrinter [in]
-
Дескриптор принтера. Используйте функцию OpenPrinter, OpenPrinter2 или AddPrinter , чтобы получить дескриптор принтера.
-
Level [in]
-
Тип данных, которые функция сохраняет в буфере, на который указывает pPrinter. Если параметр Command не равен нулю, параметр Level должен быть равен нулю.
Это значение может быть 0, 2, 3, 4, 5, 6, 7, 8 или 9.
-
pPrinter [in]
-
Указатель на буфер, содержащий данные, заданные для принтера, или сведения для команды, указанной параметром Command . Тип данных в буфере определяется значением Level.
Level Структура - 0
Если параметр Command имеет значение PRINTER_CONTROL_SET_STATUS, pPrinter должен содержать значение DWORD , указывающее новое состояние принтера для задания. Список возможных значений состояния см. в разделе Элемент Statusструктуры PRINTER_INFO_2 . Обратите внимание, что PRINTER_STATUS_PAUSED и PRINTER_STATUS_PENDING_DELETION не являются допустимыми значениями состояния.
Если level равно 0, но параметр Command не PRINTER_CONTROL_SET_STATUS, pPrinter должен иметь значение NULL.- 2
Структура PRINTER_INFO_2 , содержащая подробные сведения о принтере. - 3
Структура PRINTER_INFO_3 , содержащая сведения о безопасности принтера. - 4
Структура PRINTER_INFO_4 , содержащая минимальные сведения о принтере, включая имя принтера, имя сервера и то, является ли принтер удаленным или локальным. - 5
Структура PRINTER_INFO_5 , содержащая сведения о принтере, такие как атрибуты принтера и параметры времени ожидания. - 6
Структура PRINTER_INFO_6 , указывающая значение состояния принтера. - 7
Структура PRINTER_INFO_7. Элемент dwAction этой структуры указывает, следует ли SetPrinter публиковать, отменять публикацию, переиздать или обновлять данные принтера в службе каталогов. - 8
Структура PRINTER_INFO_8 , указывающая глобальные параметры принтера по умолчанию. - 9
Структура PRINTER_INFO_9 , указывающая параметры принтера по умолчанию для каждого пользователя. -
Команда [in]
-
действие для выполнения.
Если параметр Level является ненулевым, задайте значение этого параметра равным нулю. В этом случае принтер сохраняет текущее состояние, а функция перенастраивает данные принтера в соответствии с параметрами Level и pPrinter .
Если параметр Level равен нулю, задайте для этого параметра одно из следующих значений.
Значение Значение - PRINTER_CONTROL_PAUSE
Приостановите работу принтера. - PRINTER_CONTROL_PURGE
Удалите все задания печати на принтере. - PRINTER_CONTROL_RESUME
Возобновление приостановленного принтера. - PRINTER_CONTROL_SET_STATUS
Задайте состояние принтера.
Присвойте параметру pPrinter указатель на значение DWORD , указывающее состояние нового принтера.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ненулевым.
Если функция выполняется неудачно, возвращается нулевое значение.
Если уровень равен 7 и действие публикации завершилось сбоем, SetPrinter возвращает ERROR_IO_PENDING и пытается выполнить действие в фоновом режиме. Если значение Level равно 7 и действие обновления завершилось сбоем, SetPrinter возвращает ERROR_FILE_NOT_FOUND.
Комментарии
Примечание
Это блокирующая или синхронная функция, возвращаемая не сразу. Скорость возврата этой функции зависит от факторов времени выполнения, таких как состояние сети, конфигурация сервера печати и факторы реализации драйвера принтера, которые трудно предсказать при написании приложения. Вызов этой функции из потока, который управляет взаимодействием с пользовательским интерфейсом, может привести к тому, что приложение не отвечает.
С помощью SetPrinter нельзя изменить принтер по умолчанию.
Чтобы изменить текущие параметры принтера, вызовите функцию GetPrinter , чтобы получить текущие параметры в структуру PRINTER_INFO_2 , при необходимости измените элементы этой структуры, а затем вызовите SetPrinter.
Функция SetPrinter игнорирует элементы pServerName, AveragePPM, Status и cJobs структуры PRINTER_INFO_2 .
Приостановка работы принтера приостанавливает планирование всех заданий печати для этого принтера, за исключением одного задания печати, которое может быть на печать в данный момент. Задания печати можно отправить на приостановленный принтер, но никакие задания не будут планироваться для печати на этом принтере, пока печать не будет возобновлена. Если принтер снят, все задания печати для этого принтера удаляются, за исключением текущего задания печати.
Если вы используете SetPrinter для изменения структуры DEVMODE по умолчанию для принтера (глобально задав значения по умолчанию принтера), необходимо сначала вызвать функцию DocumentProperties для проверки структуры DEVMODE .
Для PRINTER_INFO_2 и PRINTER_INFO_3 структур, содержащих указатель на дескриптор безопасности, функция может задать только те компоненты дескриптора безопасности, которые вызывающий объект имеет разрешение на изменение. Чтобы задать определенные компоненты дескриптора безопасности, необходимо указать необходимые права доступа при вызове функции OpenPrinter или OpenPrinter2 для получения дескриптора принтера. В следующей таблице показаны права доступа, необходимые для изменения различных компонентов дескриптора безопасности.
| Разрешение на доступ | Компонент дескриптора безопасности |
|---|---|
| WRITE_OWNER | Владелец Основная группа |
| WRITE_DAC | Дискреционный список управления доступом (DACL) |
| ACCESS_SYSTEM_SECURITY | Системный список управления доступом (SACL) |
Если дескриптор безопасности содержит компонент, который вызывающий объект не имеет права доступа для изменения, SetPrinter завершается ошибкой . Эти компоненты дескриптора безопасности, которые вы не хотите изменять, должны иметь значение NULL или не должны присутствовать соответствующим образом. Если вы не хотите изменять дескриптор безопасности и вызываете SetPrinter со структурой PRINTER_INFO_2 , задайте для элемента pSecurityDescriptor этой структуры значение NULL.
Брандмауэр подключения к Интернету (ICF) по умолчанию блокирует порты принтеров, но можно включить исключение для общего доступа к файлам и печати. Если метод SetPrinter вызывается администратором компьютера, он включает исключение. Если он вызывается неадминистратором и исключение еще не включено, вызов завершается ошибкой.
Вы можете использовать уровень 7 со структурой PRINTER_INFO_7 для публикации, отмены публикации или обновления данных службы каталогов для принтера. Данные службы каталогов для принтера включают все данные, хранящиеся в ключах SPLDS_*, путем вызова функции SetPrinterDataEx для принтера. Перед вызовом SetPrinter задайте для элемента pszObjectGUIDPRINTER_INFO_7значение NULL , а для элемента dwAction задайте одно из следующих значений.
| Значение | Описание |
|---|---|
|
DSPRINT_PUBLISH |
Публикует данные службы каталогов. |
|
DSPRINT_REPUBLISH |
Данные службы каталогов для принтера отменяются, а затем публикуются снова, обновляя все свойства опубликованного принтера. При повторной публикации также изменяется ИДЕНТИФИКАТОР GUID опубликованного принтера. Используйте это значение, если вы подозреваете, что опубликованные данные принтера повреждены. |
|
DSPRINT_UNPUBLISH |
Отменяет публикацию данных службы каталогов. |
|
DSPRINT_UPDATE |
Обновления данных службы каталогов. Это то же самое, что и DSPRINT_PUBLISH, за исключением того, что SetPrinter завершается сбоем с ERROR_FILE_NOT_FOUND , если принтер еще не опубликован. Используйте DSPRINT_UPDATE для обновления опубликованных свойств, но не принудительной публикации. Драйверы принтеров всегда должны использовать DSPRINT_UPDATE , а не DSPRINT_PUBLISH. |
DSPRINT_PENDING не является допустимым значением dwAction для SetPrinter.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента |
Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера |
Windows 2000 Server [только классические приложения] |
| Заголовок |
|
| Библиотека |
|
| DLL |
|
| Имя в кодировке Юникод и ANSI |
SetPrinterW (Юникод) и SetPrinterA (ANSI) |