Función DocumentProperties

La función DocumentProperties recupera o modifica la información de inicialización de la impresora o muestra una hoja de propiedades de configuración de impresora para la impresora especificada.

Sintaxis

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

Parámetros

hWnd [in]

Identificador de la ventana primaria de la hoja de propiedades de configuración de impresora.

hPrinter [in]

Identificador de un objeto de impresora. Use la función OpenPrinter o AddPrinter para recuperar un identificador de impresora.

pDeviceName [in]

Puntero a una cadena terminada en null que especifica el nombre del dispositivo para el que se muestra la hoja de propiedades de configuración de impresora.

pDevModeOutput [out]

Puntero a una estructura DEVMODE que recibe los datos de configuración de la impresora especificados por el usuario.

pDevModeInput [in]

Puntero a una estructura DEVMODE que el sistema operativo usa para inicializar los controles de hoja de propiedades.

Este parámetro solo se usa si la marca DM_IN_BUFFER se establece en el parámetro fMode . Si no se establece DM_IN_BUFFER, el sistema operativo usa el DEVMODE predeterminado de la impresora.

fMode [in]

Las operaciones que realiza la función. Si este parámetro es cero, la función DocumentProperties devuelve el número de bytes requeridos por la estructura de datos DEVMODE del controlador de impresora. De lo contrario, utilice una o varias de las constantes siguientes para construir un valor para este parámetro; Sin embargo, tenga en cuenta que, para cambiar la configuración de impresión, una aplicación debe especificar al menos un valor de entrada y un valor de salida.

Valor	Significado
DM_IN_BUFFER	Valor de entrada. Antes de preguntar, copiar o actualizar, la función combina la configuración de impresión actual del controlador de impresora con la configuración de la estructura DEVMODE especificada por el parámetro pDevModeInput . La función actualiza la estructura solo para los miembros especificados por el miembro dmFields de la estructura DEVMODE. Este valor también se define como DM_MODIFY. En los casos de conflicto durante la combinación, la configuración de la estructura DEVMODE especificada por pDevModeInput invalida la configuración de impresión actual del controlador de impresora.
DM_IN_PROMPT	Valor de entrada. La función presenta la hoja de propiedades Print Setup del controlador de impresora y, a continuación, cambia la configuración de la estructura de datos DEVMODE de la impresora a los valores especificados por el usuario. Este valor también se define como DM_PROMPT.
DM_OUT_BUFFER	Valor de salida. La función escribe la configuración de impresión actual del controlador de impresora, incluidos los datos privados, en la estructura de datos DEVMODE especificada por el parámetro pDevModeOutput . El autor de la llamada debe asignar un búfer lo suficientemente grande como para contener la información. Si el bit DM_OUT_BUFFER establece está claro, el parámetro pDevModeOutput puede ser NULL. Este valor también se define como DM_COPY.

Valor devuelto

Si el parámetro fMode es cero, el valor devuelto es el tamaño del búfer necesario para contener los datos de inicialización del controlador de impresora. Tenga en cuenta que este búfer puede ser mayor que una estructura DEVMODE si el controlador de impresora anexa datos privados a la estructura.

Si la función muestra la hoja de propiedades, el valor devuelto es IDOK o IDCANCEL, en función del botón que seleccione el usuario.

Si la función no muestra la hoja de propiedades y se realiza correctamente, el valor devuelto es IDOK.

Si se produce un error en la función, el valor devuelto es menor que cero.

Comentarios

Nota

Se trata de una función de bloqueo o sincrónica y podría no devolverse inmediatamente. La rapidez con la que devuelve esta función depende de factores en tiempo de ejecución, como el estado de red, la configuración del servidor de impresión y los factores de implementación de controladores de impresora que son difíciles de predecir al escribir una aplicación. Llamar a esta función desde un subproceso que administra la interacción con la interfaz de usuario podría hacer que la aplicación parezca que no responde.

La cadena a la que apunta el parámetro pDeviceName se puede obtener llamando a la función GetPrinter .

La estructura DEVMODE usada realmente por un controlador de impresora contiene la parte independiente del dispositivo (como se define anteriormente) seguida de una parte específica del controlador que varía en tamaño y contenido con cada controlador y versión del controlador. Debido a esta dependencia del controlador, es muy importante que las aplicaciones consulten al controlador el tamaño correcto de la estructura DEVMODE antes de asignar un búfer para él.

Para realizar cambios en la configuración de impresión que son locales en una aplicación, una aplicación debe seguir estos pasos:

1. Obtenga el número de bytes necesarios para la estructura DEVMODE completa llamando a DocumentProperties y especificando cero en el parámetro fMode .
2. Asigne memoria para la estructura DEVMODE completa.
3. Obtenga la configuración de impresora actual llamando a DocumentProperties. Pase un puntero a la estructura DEVMODE asignada en el paso 2 como parámetro pDevModeOutput y especifique el valor DM_OUT_BUFFER .
4. Modifique los miembros adecuados de la estructura DEVMODE devuelta e indique qué miembros se cambiaron estableciendo los bits correspondientes en el miembro dmFields del DEVMODE.
5. Llame a DocumentProperties y vuelva a pasar la estructura DEVMODE modificada como parámetros pDevModeInput y pDevModeOutput y especifique los valores de DM_IN_BUFFER y DM_OUT_BUFFER (que se combinan con el operador OR). La estructura DEVMODE devuelta por la tercera llamada a DocumentProperties se puede usar como argumento en una llamada a la función CreateDC .

Para crear un identificador en un contexto de dispositivo de impresora mediante la configuración de impresora actual, solo tiene que llamar a DocumentProperties dos veces, como se ha descrito anteriormente. La primera llamada obtiene el tamaño del DEVMODE completo y la segunda llamada inicializa el DEVMODE con la configuración de impresora actual. Pase el DEVMODE inicializado a CreateDC para obtener el identificador en el contexto del dispositivo de impresora.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	Winspool.h (incluye Windows.h)
Biblioteca	Winspool.lib
Archivo DLL	Winspool.drv
Nombres Unicode y ANSI	DocumentPropertiesW (Unicode) y DocumentPropertiesA (ANSI)

Consulte también

Impresión

Funciones de la API del administrador de trabajos de impresión

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter