Metodo IPrintTicketProvider::BindPrinter (prdrvcom.h)

Articolo
02/29/2024

Il metodo IPrintTicketProvider::BindPrinter associa una stampante o una coda di stampa a una versione specifica dello schema del ticket di stampa, che consente al driver principale di associare un set di URI (Uniform Resource Identifier) dello spazio dei nomi privato a un dispositivo.

Sintassi

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

Parametri

[in] hPrinter

Handle di stampa dello spooler, fornito dal driver principale. Il provider non deve chiudere questo handle in qualsiasi momento perché il client del provider è responsabile della gestione della durata di questo handle. Il provider può memorizzare nella cache l'handle di stampa; tutte le chiamate future sono relative alla stampante associata a questo handle.

[in] version

Numero di versione principale del ticket di stampa o dello schema del ticket di stampa richiesto dal gestore ticket di stampa al provider di plug-in OEM. Windows Vista supporta solo la versione 1. Il provider deve non riuscire a eseguire il binding a una versione che non supporta o riconosce.

[out] pOptions

Puntatore a una variabile che riceve uno dei valori enumerati seguenti:

PTSHIM_DEFAULT

Il sistema inserisce una codifica binaria (un BLOB - oggetto binario di grandi dimensioni) della parte privata della struttura DEVMODEW nel ticket di stampa in una conversione di DEVMODEW in un ticket di stampa.
PTSHIM_NOSNAPSHOT

Il sistema non inserisce una codifica binaria (BLOB) della parte privata della struttura DEVMODEW nel ticket di stampa in una conversione di DEVMODEW in un ticket di stampa. Utilizzare questo valore se tutti i membri DEVMODEW pubblici e privati sono completamente rappresentati nel ticket di stampa.

[out] pDevModeFlags

Puntatore a una variabile tipizzata DWORD che riceve un set di flag di bit che indicano quali membri DEVMODEW pubblici non devono essere elaborati dallo shim del ticket di stampa in DEVMODEW-to-print ticket or print ticket-to-DEVMODEW conversioni. Un flag di bit presente in questo parametro indica che la stampante non supporta il membro DEVMODEW associato o che il provider gestisce la caratteristica DEVMODEW. Ad esempio, se DM_MEDIATYPE è impostato in *pDevModeFlags, la stampante non supporta più tipi di supporti o il provider è responsabile del supporto di più tipi di supporti. Tutti i flag di bit DM_XXX sono definiti in wingdi.h e descritti nella Microsoft Windows SDK. Per impostazione predefinita, lo shim del ticket di stampa gestisce tutti i membri rappresentati nel membro dmFlags della struttura DEVMODEW predefinita.

[out] cNamespaces

Puntatore a una variabile che riceve il numero di URI dello spazio dei nomi privati usati nel plug-in. Questo numero rappresenta il numero di stringhe nella matrice a cui punta ppNamespaces.

[out] ppNamespaces

Puntatore a una variabile che riceve l'indirizzo del primo elemento di una matrice BSTR. Il plug-in riempie ogni posizione della matrice con un URI dello spazio dei nomi. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

Valore restituito

IPrintTicketProvider::BindPrinter deve restituire uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	Operazione completata.
E_VERSION_NOT_SUPPORTED	Il plug-in non supporta la versione dello schema di stampa specificato nel parametro version .

Commenti

L'associazione a un dispositivo consente al provider di memorizzare nella cache determinati oggetti e di gestire che sarà necessario per i servizi futuri per i ticket di stampa o per i dispositivi in tale dispositivo. Ad esempio, l'handle della stampante nel parametro hPrinter può essere memorizzato nella cache. Il metodo IPrintTicketProvider::BindPrinter viene chiamato solo una volta.

Il driver è responsabile dell'allocazione della memoria per la matrice a cui punta il parametro ppNamespaces e per le stringhe URI dello spazio dei nomi. La matrice deve essere allocata usando la funzione CoTaskMemAlloc ; Le stringhe dello spazio dei nomi devono essere allocate usando la funzione SysAllocString . Entrambe le funzioni sono descritte nella documentazione di Windows SDK. La matrice a cui punta il parametro ppNamespaces non è necessaria per contenere gli spazi dei nomi per le parole chiave dello schema di stampa o il framework dello schema di stampa.

Non è necessario che un oggetto IPrintTicketProvider sia in grado di eseguire l'associazione più volte. Il gestore ticket di stampa usa sempre istanze dell'oggetto IPrintTicketProvider diverse per l'associazione a dispositivi diversi. Tutte le risorse acquisite in una chiamata corretta a IPrintTicketProvider::BindPrinter devono essere rilasciate quando il conteggio dei riferimenti di un oggetto IPrintTicketProvider è zero. Si noti che il provider non deve chiudere l'handle passato alla chiamata a BindPrinter. Lo strumento di gestione ticket di stampa potrebbe creare più provider per lo stesso dispositivo, in versioni diverse, se sono supportate più versioni.