Функция SetJob

Статья
06/12/2023

Функция SetJob приостанавливает, возобновляет, отменяет или перезапускает задание печати на указанном принтере. Функцию SetJob также можно использовать для задания параметров задания печати, таких как приоритет задания печати и имя документа.

Функцию SetJob можно использовать для предоставления команды заданию печати, для задания параметров задания печати или для выполнения обоих действий в одном вызове. Значение параметра Command не влияет на то, как функция использует параметры Level и pJob . Кроме того, можно использовать SetJob с JOB_INFO_3 для связывания набора заданий печати. Дополнительные сведения см. в разделе "Примечания".

Синтаксис

BOOL SetJob(
  _In_ HANDLE hPrinter,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pJob,
  _In_ DWORD  Command
);

Параметры

hPrinter [in]

Дескриптор интересующего объекта принтера. Используйте функцию OpenPrinter, OpenPrinter2 или AddPrinter , чтобы получить дескриптор принтера.

JobId [in]

Идентификатор, указывающий задание печати. Идентификатор задания печати можно получить, вызвав функцию AddJob или функцию StartDoc .

Если параметр Level имеет значение 3, параметр JobId должен соответствовать элементу JobIdструктуры JOB_INFO_3, на которую указывает pJob.

Level [in]

Тип структуры сведений о задании, на которую указывает параметр pJob .

Все версии Windows. Для параметра Level можно задать значение 0, 1 или 2. Если для параметра Level задано значение 0, значение pJob должно иметь значение NULL. Используйте эти значения, если вы не задаете параметры задания печати.

Можно также задать для параметра Level значение 3.

Начиная с Windows Vista: вы также можете задать для параметра Level значение 4.

pJob [in]

Указатель на структуру, которая задает параметры задания печати.

Все версии Windows: pJob может указывать на структуру JOB_INFO_1 или JOB_INFO_2 .

pJob также может указывать на JOB_INFO_3 структуру. Необходимо иметь разрешение JOB_ACCESS_ADMINISTER на доступ для заданий, указанных членами JobId и NextJobId структуры JOB_INFO_3 .

Начиная с Windows Vista: pJob также может указывать на JOB_INFO_4 структуру.

Если параметр Level имеет значение 0, значение pJob должно иметь значение NULL.

Команда [in]

Выполняемая операция задания печати. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
JOB_CONTROL_CANCEL	Не используйте. Чтобы удалить задание печати, используйте JOB_CONTROL_DELETE.
JOB_CONTROL_PAUSE	Приостановить задание печати.
JOB_CONTROL_RESTART	Перезапустите задание печати. Задание может быть перезапущено только в том случае, если оно было на печать.
JOB_CONTROL_RESUME	Возобновление приостановленного задания печати.
JOB_CONTROL_DELETE	Удалите задание печати.
JOB_CONTROL_SENT_TO_PRINTER	Используется мониторами портов для завершения задания печати.
JOB_CONTROL_LAST_PAGE_EJECTED	Используется языковыми мониторами для завершения задания печати.
JOB_CONTROL_RETAIN	Windows Vista и более поздних версий: после печати задание хранится в очереди.
JOB_CONTROL_RELEASE	Windows Vista и более поздних версий: отпустите задание печати.

Вы можете использовать тот же вызов функции SetJob , чтобы задать параметры задания печати и передать команду заданию печати. Таким образом, если заданы параметры задания печати, команде не обязательно должно быть 0, хотя это может быть значение .

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

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

Если функция выполняется неудачно, возвращается нулевое значение.

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

С помощью функции SetJob можно задать различные параметры задания печати, указав указатель на структуру JOB_INFO_1, JOB_INFO_2, JOB_INFO_3 или JOB_INFO_4, содержащую необходимые данные.

Чтобы удалить или удалить все задания печати для конкретного принтера, вызовите функцию SetPrinter с параметром Command , для которой задано значение PRINTER_CONTROL_PURGE.

Следующие элементы структуры JOB_INFO_1, JOB_INFO_2 или JOB_INFO_4 игнорируются при вызове SetJob: JobId, pPrinterName, pMachineName, pUserName, pDrivername, Size, Submitted, Time и TotalPages.

Чтобы изменить позицию задания печати в очереди печати, необходимо иметь разрешение PRINTER_ACCESS_ADMINISTER на доступ к принтеру.

Если вы не хотите задавать позицию задания печати в очереди печати, необходимо задать для элемента Position структуры JOB_INFO_1, JOB_INFO_2 или JOB_INFO_4значение JOB_POSITION_UNSPECIFIED.

Используйте функцию SetJob со структурой JOB_INFO_3 для связывания набора заданий печати (также известной как цепочка). Это полезно в ситуациях, когда один документ состоит из нескольких частей, которые требуется отрисовать отдельно. Чтобы распечатать задания A, B, C и D по порядку, вызовите SetJob с JOB_INFO_4 для связывания A с B, B — C и C — D.

Если вы связываете задания печати, обратите внимание на следующее:

Задания можно добавлять в начало или конец цепочки.
Все задания в цепочке должны иметь одинаковый тип данных.
Цепочка должна быть полностью связана перед началом очереди. В противном случае диспетчер очереди печати может печатать и удалять хранимые задания, прежде чем связать их все. Существует два способа удержать цепочку от преждевременной печати:
- Приостановите первое задание в цепочке, пока цепочка не будет полностью связана. Приостановленное состояние первого задания управляет состоянием всех заданий в цепочке.
- Оставьте первое задание неполным, то есть не вызывайте EndDoc или ScheduleJob для первого задания. Однако, если включен параметр "печать при печати" (по умолчанию), этот метод блокирует порт во время построения цепочки, что также предотвращает печать не связанных заданий.
Приложение должно обрабатывать ситуацию, когда пользователь удаляет задание в цепочке до завершения печати цепочки. GetLastError возвращает INVALID_PARAMETER , если идентификатор задания не существует.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
AddJob
GetJob
OpenPrinter
SetPrinter
JOB_INFO_1
JOB_INFO_2
JOB_INFO_3
JOB_INFO_4