IPrintOemUI ::D eviceCapabilities, méthode (prcomoem.h)

Article
02/07/2025

La méthode IPrintOemUI::DeviceCapabilities 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 sur 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 la structure DEVMODEW privée du plug-in d’interface utilisateur.

dwOld

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

dwResult

Valeur de retour dépendante de l’indicateur spécifié par wCapability. Pour plus d’informations, consultez la description de la fonction DrvDeviceCapabilities et de la section Notes suivantes.

Valeur de retour

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

Retourner le code	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 pointée par 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	La méthode n’est pas implémentée.

Remarques

La méthode IPrintOemUI::DeviceCapabilities d’un plug-in d’interface utilisateur effectue les mêmes types d’opérations que la fonction DrvDeviceCapabilities exportée par des 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 IPrintOemUI::DeviceCapabilities pour préempter la 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 IPrintOemUI::DeviceCapabilities indique la 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 inclut généralement le retour d’informations sur la fonctionnalité en réponse aux appels à la méthode IPrintOemUI::DeviceCapabilities, ainsi que la fourniture d’un code en mode utilisateur ou en mode noyau approprié pour implémenter la fonctionnalité.

Si IPrintOemUI::DeviceCapabilities 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 qu’une méthode IPrintOemUI::DeviceCapabilities d’un plug-in est appelée, sa valeur dwOld dwOld est la valeur de retour de la méthode IPrintOemUI::DeviceCapabilities du plug-in 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 par pOutput contient, en entrée, tout contenu placé là par une méthode IPrintOemUI::DeviceCapabilities précédemment appelée ou fonction DrvDeviceCapabilities.

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

Si un plug-in d’interface utilisateur ne prend pas en charge une fonctionnalité spécifiée, sa méthode IPrintOemUI::DeviceCapabilities doit simplement retourner le contenu du paramètre dwOld dans dwResult .
Si un plug-in d’interface utilisateur prend en charge la fonctionnalité, sa méthode IPrintOemUI::DeviceCapabilities 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és 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 méthode IPrintOemUI::DeviceCapabilities 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 OU 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 de DC_FIELDS, la fonction appelle toutes les méthodes IPrintOemUI::DeviceCapabilities, 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 pointée par le paramètre pOutput. Ni le pilote principal Unidrv ni le pilote Pscript5 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 dans la structure DEVMODEW (qui est pointé par le pPublicDM et paramètres pOEMDM) indique au plug-in d’interface utilisateur qu’il doit signaler les données de capacité d’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 de photos peut nécessiter un ensemble différent de types de papier que 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 définir le paramètre dwResult sur le nombre de types de papier qu’il envisage de signaler. Si pOutput n’est pas NULL, le plug-in doit également remplir la mémoire tampon pointée par pOutput avec l’ensemble souhaité de types de papier 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 pour signifier 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 aucune donnée dans la mémoire tampon pOutput avant d’appeler les plug-ins. (Le pilote principal appelle les plug-ins dans le même ordre que celui spécifié pour leur installation.)

Dans les cas 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 principaux Unidrv et Pscript5 reconnaissent la valeur de retour S_DEVCAP_OUTPUT_FULL_REPLACEMENT uniquement pour les fonctionnalités d’appareil qui utilisent le pOutput tampon 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’imprimantes microsoft.

Exigences

Exigence	Valeur
plateforme cible	Bureau
d’en-tête	prcomoem.h (include Prcomoem.h)

Voir aussi

DrvDeviceCapabilities

IPrintOemUI

Partager via