Metodo IPrintOemUI::D eviceCapabilities (prcomoem.h)

Articolo
02/27/2024

Il IPrintOemUI::DeviceCapabilities metodo consente a un plug-in dell'interfaccia utente di specificare funzionalità personalizzate del dispositivo.

Sintassi

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

Parametri

poemuiobj

Puntatore fornito dal chiamante a una struttura OEMUIOBJ .

hPrinter

Handle fornito dal chiamante al dispositivo stampante.

pDeviceName

Puntatore fornito dal chiamante a una stringa che rappresenta il nome del dispositivo.

wCapability

Flag fornito dal chiamante che indica il tipo di informazioni che il metodo deve restituire. Per un elenco di flag, vedere la descrizione della funzione DrvDeviceCapabilities .

pOutput

Puntatore fornito dal chiamante a un buffer per ricevere le informazioni richieste. Il tipo di informazioni restituite dipende dal flag specificato da wCapability.

pPublicDM

Puntatore fornito dal chiamante a una struttura DEVMODEW convalidata.

pOEMDM

Puntatore fornito dal chiamante ai membri della struttura DEVMODEW privati del plug-in dell'interfaccia utente.

dwOld

Valore restituito fornito dal chiamante dalla funzione DrvDeviceCapabilities del driver della stampante o da un altro plug-in dell'interfaccia utente. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

dwResult

Valore restituito che dipende dal flag specificato da wCapability. Per altre informazioni, vedere la descrizione della funzione DrvDeviceCapabilities e la sezione Osservazioni seguente.

Valore restituito

Il metodo deve restituire uno dei valori seguenti.

Codice restituito	Descrizione
S_OK	Operazione completata.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT	Il plug-in intende usare il buffer a cui punta il parametro pOutput per scopi specifici. Questo valore restituito è definito in prcomoem.h. Per altre informazioni su quando utilizzare questo valore restituito, vedere la sezione Osservazioni seguente.
E_FAIL	Operazione non riuscita.
E_NOTIMPL	Il metodo non è implementato.

Commenti

Il metodo del plug-in di IPrintOemUI::DeviceCapabilities un'interfaccia utente esegue gli stessi tipi di operazioni della funzione DrvDeviceCapabilities esportata dalle DLL dell'interfaccia della stampante in modalità utente. Il metodo specifica le funzionalità fornite dalla stampante.

È possibile usare il metodo per annullare il IPrintOemUI::DeviceCapabilities supporto Unidrv per una funzionalità o per aggiungere una funzionalità non disponibile dal driver della stampante. Il driver chiama IPrintOemUI::DeviceCapabilities dall'interno della funzione DrvDeviceCapabilities .

Se il metodo indica il supporto personalizzato per una funzionalità (impostando i bit appropriati in risposta a un flag di DC_FIELDS ricevuto), il IPrintOemUI::DeviceCapabilities codice personalizzato deve supportare completamente la funzionalità. Il supporto completo include in genere la restituzione di informazioni sulla funzionalità in risposta alle chiamate al IPrintOemUI::DeviceCapabilities metodo, oltre a fornire codice appropriato in modalità utente o in modalità kernel per implementare la funzionalità.

Se IPrintOemUI::DeviceCapabilities i metodi vengono esportati da più plug-in dell'interfaccia utente, i metodi vengono chiamati nell'ordine in cui vengono specificati i plug-in per l'installazione. Ogni volta che viene chiamato il metodo di un plug-in, il valore di IPrintOemUI::DeviceCapabilities input dwOld è il valore restituito dal metodo precedentemente chiamato plug-in IPrintOemUI::DeviceCapabilities . Per il primo plug-in chiamato , dwOld contiene il valore restituito dalla funzione DrvDeviceCapabilities del driver della stampante. Analogamente, il buffer a cui punta pOutput contiene, all'input, tutti i contenuti inseriti da una funzione chiamata IPrintOemUI::DeviceCapabilities in precedenza o DrvDeviceCapabilities .

Affinché più plug-in dell'interfaccia utente funzionino in combinazione tra loro, ogni IPrintOemUI::DeviceCapabilities metodo deve rispettare le regole seguenti:

Se un plug-in dell'interfaccia utente non supporta una funzionalità specificata, il relativo IPrintOemUI::DeviceCapabilities metodo deve restituire solo il contenuto del parametro dwOld in dwResult.
Se un plug-in dell'interfaccia utente supporta la funzionalità, il relativo IPrintOemUI::DeviceCapabilities metodo deve ignorare dwOld e il contenuto del buffer a cui punta pOutput. Deve fornire un valore restituito e un contenuto del buffer appropriato per indicare che supporta la funzionalità specificata. Se il metodo rileva un errore, deve restituire GDI_ERROR in dwResult.
Se si vuole che un plug-in dell'interfaccia utente modifichi le informazioni sulle funzionalità ricevute nel buffer a cui punta pOutput, il relativo IPrintOemUI::DeviceCapabilities metodo deve modificare il contenuto del buffer e restituire un valore restituito appropriato in dwResult. Ad esempio, se wCapability è DC_FIELDS, il metodo deve or i bit che deve impostare con i bit impostati in dwOld e restituire il risultato dell'operazione OR in dwResult.
Le regole precedenti devono essere seguite anche se il contenuto ricevuto di dwOld è GDI_ERROR.

Quando la funzione DrvDeviceCapabilities del driver viene chiamata con il flag DC_FIELDS impostato, la funzione chiama tutti i IPrintOemUI::DeviceCapabilities metodi, specificando anche DC_FIELDS e restituisce l'unione di tutti i bit impostati al chiamante.

Il valore restituito S_DEVCAP_OUTPUT_FULL_REPLACEMENT è nuovo in Windows Vista e si applica ai plug-in dell'interfaccia utente Unidrv e Pscript5. Un plug-in deve usare il valore restituito S_DEVCAP_OUTPUT_FULL_REPLACEMENT solo se richiede il controllo completo sugli elementi inseriti nel buffer a cui punta il parametro pOutput . Né il driver Unidrv né il driver core Pscript5 inseriscono i dati nel buffer pOutput quando il plug-in restituisce S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Un plug-in potrebbe dover restituire questo valore quando un'impostazione nella struttura DEVMODEW (a cui puntano i parametri pPublicDM e pOEMDM ) indica al plug-in dell'interfaccia utente che deve segnalare i dati delle funzionalità del dispositivo diversi da quello specificato nel file GPD o PPD. Ad esempio, una struttura DEVMODEW che specifica la stampa fotografica potrebbe richiedere un set diverso di tipi di carta rispetto a quelli specificati nel file GPD o PPD. In tale situazione, e indipendentemente dai valori dei parametri pOutput e dwOld , il plug-in deve restituire S_DEVCAP_OUTPUT_FULL_REPLACEMENT e deve impostare il parametro dwResult sul numero di tipi di carta che intende segnalare. Se pOutput non è NULL, il plug-in deve anche riempire il buffer a cui punta pOutput con il set desiderato di tipi di carta e deve impostare dwResult sul numero di tipi di carta che il plug-in intende segnalare.

Quando più plug-in dell'interfaccia utente sono attivi contemporaneamente e uno di essi restituisce S_DEVCAP_OUTPUT_FULL_REPLACEMENT, il driver Unidrv o Pscript5 interpreta questo valore restituito per indicare che i plug-in intendono fornire dati di output sostitutivi completi. Di conseguenza, il driver principale non inserisce dati nel buffer pOutput prima di chiamare i plug-in. Il driver principale chiama i plug-in nello stesso ordine specificato per l'installazione.

Nei casi in cui non è necessario sostituire i valori inseriti dal driver principale nel buffer pOutput , il plug-in deve restituire S_OK. I driver di base Unidrv e Pscript5 riconoscono il valore restituito S_DEVCAP_OUTPUT_FULL_REPLACEMENT solo per le funzionalità del dispositivo che usano il buffer pOutput , in altre parole, quando il parametro wCapability è impostato su uno dei flag seguenti:

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Per altre informazioni sulla creazione e l'installazione di plug-in dell'interfaccia utente, vedere Personalizzazione dei driver della stampante microsoft.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	prcomoem.h (include Prcomoem.h)

Vedi anche

DrvDeviceCapabilities

IPrintOemUI

Condividi tramite