Функция DocumentProperties

Статья
06/12/2023

Функция DocumentProperties извлекает или изменяет сведения об инициализации принтера или отображает страницу свойств конфигурации принтера для указанного принтера.

Синтаксис

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Параметры

hWnd [in]

Дескриптор родительского окна страницы свойств конфигурации принтера.

hPrinter [in]

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

pDeviceName [in]

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

pDevModeOutput [out]

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

pDevModeInput [in]

Указатель на структуру DEVMODE , используемую операционной системой для инициализации элементов управления страницы свойств.

Этот параметр используется только в том случае, если флаг DM_IN_BUFFER задан в параметре fMode . Если DM_IN_BUFFER не задано, операционная система использует devmode принтера по умолчанию.

fMode [in]

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

Значение	Значение
DM_IN_BUFFER	Входное значение. Перед запросом, копированием или обновлением функция объединяет текущие параметры печати драйвера принтера с параметрами в структуре DEVMODE , заданной параметром pDevModeInput . Функция обновляет структуру только для элементов, указанных элементом dmFields структуры DEVMODE. Это значение также определяется как DM_MODIFY. В случае конфликта во время слияния параметры в структуре DEVMODE , заданной параметром pDevModeInput , переопределяют текущие параметры печати драйвера принтера.
DM_IN_PROMPT	Входное значение. Функция представляет страницу свойств настройки печати драйвера принтера, а затем изменяет параметры в структуре данных DEVMODE принтера на значения, заданные пользователем. Это значение также определяется как DM_PROMPT.
DM_OUT_BUFFER	Выходное значение. Функция записывает текущие параметры печати драйвера принтера, включая частные данные, в структуру данных DEVMODE , заданную параметром pDevModeOutput . Вызывающий объект должен выделить достаточно большой буфер для хранения информации. Если наборы битов DM_OUT_BUFFER ясны, параметр pDevModeOutput может иметь значение NULL. Это значение также определяется как DM_COPY.

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

Если параметр fMode равен нулю, возвращаемое значение — это размер буфера, необходимый для хранения данных инициализации драйвера принтера. Обратите внимание, что этот буфер может быть больше структуры DEVMODE , если драйвер принтера добавляет частные данные в структуру.

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

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

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

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

Строку, на которую указывает параметр pDeviceName , можно получить, вызвав функцию GetPrinter .

Структура DEVMODE , фактически используемая драйвером принтера, содержит независимую от устройства часть (как определено выше), за которой следует часть драйвера, которая зависит от размера и содержимого каждого драйвера и версии драйвера. Из-за этой зависимости от драйвера очень важно, чтобы приложения запрашивали у драйвера правильный размер структуры DEVMODE , прежде чем выделять для него буфер.

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

Получите количество байтов, необходимых для полной структуры DEVMODE , вызвав DocumentProperties и указав ноль в параметре fMode .
Выделение памяти для полной структуры DEVMODE .
Получите текущие параметры принтера, вызвав DocumentProperties. Передайте указатель на структуру DEVMODE, выделенную на шаге 2, в качестве параметра pDevModeOutput и укажите значение DM_OUT_BUFFER .
Измените соответствующие элементы возвращаемой структуры DEVMODE и укажите, какие элементы были изменены, задав соответствующие биты в элементе dmFieldsDEVMODE.
Вызовите DocumentProperties и передайте измененную структуру DEVMODE обратно в качестве параметров pDevModeInput и pDevModeOutput и укажите значения DM_IN_BUFFER и DM_OUT_BUFFER (которые объединяются с помощью оператора OR). Структура DEVMODE, возвращаемая при третьем вызове DocumentProperties , может использоваться в качестве аргумента при вызове функции CreateDC .

Чтобы создать дескриптор контекста устройства принтера с помощью текущих параметров принтера, необходимо вызвать DocumentProperties только дважды, как описано выше. Первый вызов получает размер полной версии DEVMODE , а второй вызов инициализирует DEVMODE с текущими параметрами принтера. Передайте инициализированный DEVMODEв CreateDC , чтобы получить дескриптор в контексте устройства принтера.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
AdvancedDocumentProperties
CreateDC
DEVMODE
GetPrinter
OpenPrinter