IPrintTicketProvider::BindPrinter method (prdrvcom.h)

Article
09/01/2022

The IPrintTicketProvider::BindPrinter method binds a printer or print queue to a specific version of the print ticket schema, which enables the core driver to associate a set of private namespace uniform resource identifiers (URIs) with a device.

Syntax

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
);

Parameters

[in] hPrinter

The spooler's print handle, which is supplied by the core driver. The provider should not close this handle at any time because the client of the provider is responsible for managing the lifetime of this handle. The provider can cache the print handle; all future calls are relative to the printer that is associated with this handle.

[in] version

The major version number of the print ticket or print ticket schema that the print ticket manager requests the OEM plug-in provider to support. Windows Vista supports only version 1. The provider should fail any attempt to bind to a version that it does not support or recognize.

[out] pOptions

A pointer to a variable that receives one of the following enumerated values:

PTSHIM_DEFAULT

The system places a binary encoding (a BLOB - binary large object) of the private portion of the DEVMODEW structure into the print ticket in a conversion of a DEVMODEW to a print ticket.
PTSHIM_NOSNAPSHOT

The system will not place a binary encoding (a BLOB) of the private portion of the DEVMODEW structure into the print ticket in a conversion of a DEVMODEW to a print ticket. Use this value if all of the public and private DEVMODEW members are fully represented in the print ticket.

[out] pDevModeFlags

A pointer to a DWORD-typed variable that receives a set of bit flags that indicate which public DEVMODEW members should not be processed by the print ticket shim in DEVMODEW-to-print ticket or print ticket-to-DEVMODEW conversions. A bit flag that is present in this parameter indicates either that the printer does not support the associated DEVMODEW member or that the provider handles that DEVMODEW characteristic. For example, if DM_MEDIATYPE is set in *pDevModeFlags, either the printer does not support multiple media types, or the provider is responsible for supporting multiple media types. (All of the DM_XXX bit flags are defined in wingdi.h and described in the Microsoft Windows SDK.) By default, the print ticket shim handles all of the members that are represented in the dmFlags member of the default DEVMODEW structure.

[out] cNamespaces

A pointer to a variable that receives the number of private namespace URIs that are used in the plug-in. This number represents the count of strings in the array that is pointed to by ppNamespaces.

[out] ppNamespaces

A pointer to a variable that receives the address of the first element of a BSTR array. The plug-in fills each array position with a namespace URI. For more information about this parameter, see the following Remarks section.

Return value

IPrintTicketProvider::BindPrinter should return one of the following values:

Return code	Description
S_OK	The operation succeeded.
E_VERSION_NOT_SUPPORTED	The plug-in does not support the version of the print schema that is specified in the version parameter.

Remarks

Binding to a device enables the provider to cache certain objects and handles that it will need for future print ticket or device capabilities services on that device. For example, the printer handle in the hPrinter parameter can be cached. The IPrintTicketProvider::BindPrinter method is guaranteed to be called only once.

The driver is responsible for allocating memory for the array that is pointed to by the ppNamespaces parameter and for the namespace URI strings. The array should be allocated by using the CoTaskMemAlloc function; the namespace strings should be allocated by using the SysAllocString function. Both functions are described in the Windows SDK documentation. The array that is pointed to by the ppNamespaces parameter is not required to contain the namespaces for the Print Schema Keywords or the Print Schema Framework.

An IPrintTicketProvider object does not have to be able to bind more than once. The print ticket manager always uses different IPrintTicketProvider object instances for binding to different devices. All resources that are acquired in a successful call to IPrintTicketProvider::BindPrinter should be released when the reference count of an IPrintTicketProvider object is zero. Note that the provider should not close the handle that was passed into the call to BindPrinter. The print ticket manager might create multiple providers for the same device, in different versions, if multiple versions are supported.

Requirements

Requirement	Value
Header	prdrvcom.h (include Prdrvcom.h)