Méthode IPrintOemUI ::D eviceCapabilities (prcomoem.h)

  • Article

La IPrintOemUI::DeviceCapabilities méthode permet à un plug-in d’interface utilisateur de spécifier des fonctionnalités d’appareil personnalisées.

Syntaxe

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

Paramètres

poemuiobj

Pointeur fourni par l’appelant vers une structure OEMUIOBJ .

hPrinter

Handle fourni par l’appelant à l’appareil d’imprimante.

pDeviceName

Pointeur fourni par l’appelant vers une chaîne représentant le nom de l’appareil.

wCapability

Indicateur fourni par l’appelant indiquant le type d’informations que la méthode doit retourner. Pour obtenir la liste des indicateurs, consultez la description de la fonction DrvDeviceCapabilities .

pOutput

Pointeur fourni par l’appelant vers une mémoire tampon pour recevoir les informations demandées. Le type d’informations retournées dépend de l’indicateur spécifié par wCapability.

pPublicDM

Pointeur fourni par l’appelant vers une structure DEVMODEW validée.

pOEMDM

Pointeur fourni par l’appelant vers les membres de structure DEVMODEW privés du plug-in d’interface utilisateur.

dwOld

Valeur de retour fournie par l’appelant à partir de la fonction DrvDeviceCapabilities du pilote d’imprimante ou d’un autre plug-in d’interface utilisateur. Pour plus d'informations, consultez la section Notes qui suit.

dwResult

Valeur de retour qui dépend de l’indicateur spécifié par wCapability. Pour plus d’informations, consultez la description de la fonction DrvDeviceCapabilities et la section Remarques suivante.

Valeur retournée

La méthode doit retourner l’une des valeurs suivantes.

Code de retour Description
S_OK
 L’opération a réussi.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 Le plug-in a l’intention d’utiliser la mémoire tampon vers laquelle pointe le paramètre pOutput à ses propres fins. Cette valeur de retour est définie dans prcomoem.h. Pour plus d’informations sur l’utilisation de cette valeur de retour, consultez la section Remarques suivante.
E_FAIL
 L'opération a échoué.
E_NOTIMPL
 Cette méthode n'est pas implémentée.

Remarques

La méthode d’un IPrintOemUI::DeviceCapabilities plug-in d’interface utilisateur effectue les mêmes types d’opérations que la fonction DrvDeviceCapabilities exportée par les DLL d’interface d’imprimante en mode utilisateur. La méthode spécifie les fonctionnalités fournies par l’imprimante.

Vous pouvez utiliser la méthode pour préempter la IPrintOemUI::DeviceCapabilities prise en charge d’Unidrv pour une fonctionnalité ou pour ajouter une fonctionnalité que le pilote d’imprimante ne fournit pas. Le pilote appelle IPrintOemUI::DeviceCapabilities à partir de sa fonction DrvDeviceCapabilities .

Si la méthode indique une IPrintOemUI::DeviceCapabilities prise en charge personnalisée d’une fonctionnalité (en définissant les bits appropriés en réponse à un indicateur de DC_FIELDS reçu), le code personnalisé doit entièrement prendre en charge la fonctionnalité. La prise en charge complète comprend généralement le retour d’informations sur la fonctionnalité en réponse aux appels à la méthode, ainsi que la IPrintOemUI::DeviceCapabilities fourniture de code en mode utilisateur ou en mode noyau approprié pour implémenter la fonctionnalité.

Si IPrintOemUI::DeviceCapabilities les méthodes sont exportées par plusieurs plug-ins d’interface utilisateur, les méthodes sont appelées dans l’ordre dans lequel les plug-ins sont spécifiés pour l’installation. Chaque fois que la méthode d’un IPrintOemUI::DeviceCapabilities plug-in est appelée, sa valeur d’entrée dwOld est la valeur de retour de la méthode du plug-in IPrintOemUI::DeviceCapabilities précédemment appelée. Pour le premier plug-in appelé, dwOld contient la valeur de retour de la fonction DrvDeviceCapabilities du pilote d’imprimante. De même, la mémoire tampon pointée vers pOutput contient, en entrée, tout contenu placé là par une méthode ou une fonction DrvDeviceCapabilities précédemment appeléeIPrintOemUI::DeviceCapabilities.

Pour que plusieurs plug-ins d’interface utilisateur fonctionnent ensemble, chaque IPrintOemUI::DeviceCapabilities méthode doit respecter les règles suivantes :

  • Si un plug-in d’interface utilisateur ne prend pas en charge une fonctionnalité spécifiée, sa IPrintOemUI::DeviceCapabilities méthode doit simplement retourner le contenu du paramètre dwOld dans dwResult.
  • Si un plug-in d’interface utilisateur prend en charge la fonctionnalité, sa IPrintOemUI::DeviceCapabilities méthode doit ignorer dwOld et le contenu de la mémoire tampon pointée par pOutput. Il doit fournir une valeur de retour et un contenu de mémoire tampon approprié pour indiquer qu’il prend en charge la fonctionnalité spécifiée. Si la méthode détecte une erreur, elle doit retourner GDI_ERROR dans dwResult.
  • Si vous souhaitez qu’un plug-in d’interface utilisateur modifie les informations de fonctionnalités reçues dans la mémoire tampon pointée par pOutput, sa IPrintOemUI::DeviceCapabilities méthode doit modifier le contenu de la mémoire tampon et retourner une valeur de retour appropriée dans dwResult. Par exemple, si wCapability est DC_FIELDS, la méthode doit OR les bits qu’elle doit définir avec les bits définis dans dwOld et retourner le résultat de l’opération OR dans dwResult.
  • Les règles précédentes doivent être suivies même si le contenu reçu de dwOld est GDI_ERROR.
Lorsque la fonction DrvDeviceCapabilities du pilote est appelée avec le jeu d’indicateurs DC_FIELDS, la fonction appelle toutes les IPrintOemUI::DeviceCapabilities méthodes, en spécifiant également DC_FIELDS et retourne l’union de tous les bits définis à l’appelant.

La valeur de retour S_DEVCAP_OUTPUT_FULL_REPLACEMENT est nouvelle dans Windows Vista et s’applique aux plug-ins d’interface utilisateur Unidrv et Pscript5. Un plug-in doit utiliser la valeur de retour S_DEVCAP_OUTPUT_FULL_REPLACEMENT uniquement s’il nécessite un contrôle total sur ce qui est placé dans la mémoire tampon vers laquelle pointe le paramètre pOutput . Ni le pilote Unidrv ni le pilote Pscript5 core ne placent les données dans la mémoire tampon pOutput lorsque le plug-in retourne S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Un plug-in peut avoir besoin de renvoyer cette valeur lorsqu’un paramètre de la structure DEVMODEW (qui est pointé par les paramètres pPublicDM et pOEMDM ) indique au plug-in d’interface utilisateur qu’il doit signaler les données de capacité de l’appareil qui sont différentes de celles spécifiées dans le fichier GPD ou PPD. Par exemple, une structure DEVMODEW qui spécifie l’impression photo peut nécessiter un ensemble de types de papier différent de ceux spécifiés dans le fichier GPD ou PPD. Dans ce cas, et quelles que soient les valeurs des paramètres pOutput et dwOld , le plug-in doit retourner S_DEVCAP_OUTPUT_FULL_REPLACEMENT et doit définir le paramètre dwResult sur le nombre de types de papier qu’il a l’intention de signaler. Si pOutput n’a pas la valeur NULL, le plug-in doit également remplir la mémoire tampon vers laquelle pOutput pointe avec l’ensemble de types de papier souhaité, et doit définir dwResult sur le nombre de types de papier que le plug-in a l’intention de signaler.

Lorsque plusieurs plug-ins d’interface utilisateur sont actifs en même temps et que l’un d’eux retourne S_DEVCAP_OUTPUT_FULL_REPLACEMENT, le pilote Unidrv ou Pscript5 core interprète cette valeur de retour comme signifiant que les plug-ins ont l’intention de fournir des données de sortie de remplacement complètes. Par conséquent, le pilote principal ne place pas de données dans la mémoire tampon pOutput avant d’appeler les plug-ins. (Le pilote principal appelle les plug-ins dans l’ordre spécifié pour leur installation.)

Dans les situations où les valeurs que le pilote principal place dans la mémoire tampon pOutput n’ont pas besoin d’être remplacées, le plug-in doit retourner S_OK. Les pilotes Unidrv et Pscript5 core reconnaissent la valeur de retour S_DEVCAP_OUTPUT_FULL_REPLACEMENT uniquement pour les fonctionnalités d’appareil qui utilisent la mémoire tampon pOutput , en d’autres termes, lorsque le paramètre wCapability est défini sur l’un des indicateurs suivants :

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Pour plus d’informations sur la création et l’installation de plug-ins d’interface utilisateur, consultez Personnalisation des pilotes d’imprimante Microsoft.

Configuration requise

Condition requise Valeur
Plateforme cible Desktop (Expérience utilisateur)
En-tête prcomoem.h (inclure Prcomoem.h)

Voir aussi

DrvDeviceCapabilities

IPrintOemUI