Método IPrintTicketProvider2::BindPrinter (prdrvcom.h)

Artículo
02/26/2024

El método IPrintTicketProvider2::BindPrinter enlaza una impresora o una cola de impresión a una versión específica del esquema de vales de impresión, lo que permite al controlador principal asociar un conjunto de identificadores uniformes de recursos (URI) de espacio de nombres privados con un dispositivo.

Sintaxis

HRESULT BindPrinter(
  [in]  IN HANDLE     hPrinter,
  [in]  IN INT        version,
  [out] OUT PSHIMOPTS pOptions,
  [out] OUT DWORD     *pDevModeFlags,
  [out] OUT INT       *cNamespaces,
  [out] OUT BSTR      **ppNamespaces
);

Parámetros

[in] hPrinter

Identificador de impresión del administrador de colas, proporcionado por el controlador principal. El proveedor no debe cerrar este identificador en ningún momento porque el cliente del proveedor es responsable de administrar la duración de este identificador. El proveedor puede almacenar en caché el identificador de impresión; todas las llamadas futuras son relativas a la impresora asociada a este identificador.

[in] version

Número de versión principal del esquema de vale de impresión o vale de impresión que el administrador de vales de impresión solicita al proveedor del complemento OEM que admita. Windows Vista solo admite la versión 1. El proveedor debe producir un error en cualquier intento de enlazar a una versión que no admita ni reconozca.

[out] pOptions

Puntero a una variable que recibe uno de los siguientes valores enumerados:

PTSHIM_DEFAULT

El sistema coloca una codificación binaria (un objeto BLOB - binario grande) de la parte privada de la estructura DEVMODEW en el vale de impresión en una conversión de un DEVMODEW a un vale de impresión.
PTSHIM_NOSNAPSHOT

El sistema no colocará una codificación binaria (un BLOB) de la parte privada de la estructura DEVMODEW en el vale de impresión en una conversión de un DEVMODEW a un vale de impresión. Utilice este valor si todos los miembros DEVMODEW públicos y privados están totalmente representados en el vale de impresión.

[out] pDevModeFlags

Puntero a una variable con tipo DWORD que recibe un conjunto de marcas de bits que indican qué miembros públicos de DEVMODEW no deben ser procesados por la corrección de compatibilidad del vale de impresión en deVMODEW-to-print ticket o conversiones de vale de impresión a DEVMODEW. Una marca de bits que está presente en este parámetro indica que la impresora no admite el miembro DEVMODEW asociado o que el proveedor controla esa característica DEVMODEW. Por ejemplo, si DM_MEDIATYPE se establece en *pDevModeFlags, la impresora no admite varios tipos de medios o el proveedor es responsable de admitir varios tipos de medios. (Todas las marcas de bits de DM_XXX se definen en wingdi.h y se describen en el Microsoft Windows SDK). De forma predeterminada, la corrección de compatibilidad del vale de impresión controla todos los miembros representados en el miembro dmFlags de la estructura DEVMODEW predeterminada.

[out] cNamespaces

Puntero a una variable que recibe el número de URI de espacio de nombres privados que se usan en el complemento. Este número representa el recuento de cadenas de la matriz a la que apunta ppNamespaces.

[out] ppNamespaces

Puntero a una variable que recibe la dirección del primer elemento de una matriz BSTR. El complemento rellena cada posición de matriz con un URI de espacio de nombres. Para obtener más información sobre este parámetro, vea la siguiente sección Comentarios.

Valor devuelto

IPrintTicketProvider2::BindPrinter debe devolver uno de los siguientes valores:

Código devuelto	Descripción
S_OK	La operación se realizó correctamente.
E_VERSION_NOT_SUPPORTED	El complemento no admite la versión del esquema de impresión especificado en el parámetro version .

Comentarios

El enlace a un dispositivo permite al proveedor almacenar en caché determinados objetos y identificadores que necesitará para futuros servicios de funcionalidades de impresión o incidencias de impresión en ese dispositivo. Por ejemplo, el identificador de impresora del parámetro hPrinter se puede almacenar en caché. Se garantiza que el método IPrintTicketProvider2::BindPrinter se llame solo una vez.

El controlador es responsable de asignar memoria para la matriz a la que apunta el parámetro ppNamespaces y para las cadenas de URI del espacio de nombres. La matriz debe asignarse mediante la función CoTaskMemAlloc ; las cadenas de espacio de nombres se deben asignar mediante la función SysAllocString . Ambas funciones se describen en la documentación de Windows SDK. La matriz a la que apunta el parámetro ppNamespaces no es necesaria para contener los espacios de nombres para las palabras clave de esquema de impresión o el marco de esquema de impresión.

Un objeto IPrintTicketProvider2 no tiene que ser capaz de enlazar más de una vez. El administrador de vales de impresión siempre usa diferentes instancias de objeto IPrintTicketProvider2 para enlazar a diferentes dispositivos. Todos los recursos que se adquieren en una llamada correcta a IPrintTicketProvider2::BindPrinter deben liberarse cuando el recuento de referencias de un objeto IPrintTicketProvider2 es cero. Tenga en cuenta que el proveedor no debe cerrar el identificador que se pasó a la llamada a BindPrinter. El administrador de vales de impresión puede crear varios proveedores para el mismo dispositivo, en versiones diferentes, si se admiten varias versiones.