Metodo IPrintOemPrintTicketProvider::BindPrinter (prcomoem.h)

Articolo
02/26/2024

Il metodo IPrintOemPrintTicketProvider::BindPrinter consente al driver di base di associare un set di identificatori di risorse uniformi dello spazio dei nomi privato (URI) a un dispositivo. Questo metodo consente anche al plug-in di memorizzare nella cache le informazioni (ad esempio l'handle della stampante) che possono essere usate in un secondo momento.

Sintassi

HRESULT BindPrinter(
  [in]  HANDLE     hPrinter,
  [in]  INT        version,
  [out] POEMPTOPTS pOptions,
  [out] INT        *cNamespaces,
  [out] BSTR       **ppNamespaces
);

Parametri

[in] hPrinter

Handle di stampa di spooler, fornito da Unidrv. 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 su questo oggetto sono relative alla stampante associata a questo handle.

[in] version

Numero di versione principale dello schema di stampa. Windows Vista supporta solo la versione 1.

[out] pOptions

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

OEMPT_DEFAULT

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

OEMPT_NOSNAPSHOT

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

L'oggetto OEM chiamato deve impostare il valore a cui punta questo parametro.

[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 seguenti.

Valore restituito

IPrintOemPrintTicketProvider::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 versione .

Commenti

Il plug-in è 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 queste funzioni sono descritte nella documentazione di Microsoft 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.

L'associazione a un dispositivo consente al provider di memorizzare nella cache determinati oggetti e gestisce che sarà necessario per i futuri servizi di stampa o di stampa su tale dispositivo. Ad esempio, l'handle della stampante in hPrinter può essere memorizzato nella cache. IPrintOemPrintTicketProvider::BindPrinter è garantito che venga chiamato una sola volta.

Un oggetto IPrintOemPrintTicketProvider non deve essere in grado di associare più volte. Gestione ticket di stampa usa sempre diverse istanze dell'oggetto IPrintOemPrintTicketProvider per l'associazione a dispositivi diversi. Tutte le risorse acquisite in una chiamata riuscita a IPrintOemPrintTicketProvider::BindPrinter devono essere rilasciate quando il conteggio dei riferimenti di un oggetto IPrintOemPrintTicketProvider è zero. Si noti che il provider non deve chiudere l'handle passato alla chiamata a BindPrinter. La gestione ticket di stampa può creare più provider per lo stesso dispositivo, in versioni diverse, se sono supportate più versioni.