Tables de dispatch
OLE Automation fournit des moyens d’appeler des méthodes et d’accéder aux propriétés entre les applications. Le mécanisme fourni par la bibliothèque de classes Microsoft Foundation pour la distribution de ces requêtes est le « mappage de répartition », qui désigne les noms internes et externes des fonctions et propriétés d’objet, ainsi que les types de données des propriétés elles-mêmes et des arguments de fonction.
| Macro de mappage de répartition | Description |
|---|---|
| DECLARE_DISPATCH_MAP | Déclare qu’une carte de répartition sera utilisée pour exposer les méthodes et propriétés d’une classe (doit être utilisée dans la déclaration de classe). |
| BEGIN_DISPATCH_MAP | Démarre la définition d’une carte de répartition. |
| END_DISPATCH_MAP | Termine la définition d’une carte de répartition. |
| DISP_FUNCTION | Utilisé dans une carte de répartition pour définir une fonction d’automatisation OLE. |
| DISP_PROPERTY | Définit une propriété OLE Automation. |
| DISP_PROPERTY_EX | Définit une propriété OLE Automation et nomme les fonctions Get et Set. |
| DISP_PROPERTY_NOTIFY | Définit une propriété OLE Automation avec notification. |
| DISP_PROPERTY_PARAM | Définit une propriété OLE Automation qui prend des paramètres et nomme les fonctions Get et Set. |
| DISP_DEFVALUE | Rend une propriété existante la valeur par défaut d’un objet. |
DECLARE_DISPATCH_MAP
Si une CCmdTargetclasse dérivée de votre programme prend en charge OLE Automation, cette classe doit fournir un mappage de répartition pour exposer ses méthodes et ses propriétés.
DECLARE_DISPATCH_MAP()
Notes
Utilisez la macro DECLARE_DISPATCH_MAP à la fin de votre déclaration de classe. Puis, dans le . Fichier CPP qui définit les fonctions membres de la classe, utilisez la macro BEGIN_DISPATCH_MAP. Incluez ensuite les entrées de macro pour chacune des méthodes et propriétés exposées de votre classe (DISP_FUNCTION, DISP_PROPERTY, etc.). Enfin, utilisez la macro END_DISPATCH_MAP.
Remarque
Si vous déclarez des membres après DECLARE_DISPATCH_MAP, vous devez spécifier un nouveau type d’accès ( public, privateou protected) pour ceux-ci.
L’Assistant Application et les Assistants code aident à créer des classes Automation et à gérer des cartes de répartition. Pour plus d’informations sur les mappages de répartition, consultez Serveurs Automation.
Exemple
class CMyServerDoc : public COleServerDoc
{
DECLARE_DISPATCH_MAP()
// Remainder of class declaration omitted.
Spécifications
En-tête : afxwin.h
BEGIN_DISPATCH_MAP
Déclare la définition de votre carte de répartition.
BEGIN_DISPATCH_MAP(theClass, baseClass)
Paramètres
theClass
Spécifie le nom de la classe propriétaire de cette carte de répartition.
baseClass
Spécifie le nom de la classe de base de la classe.
Notes
Dans le fichier d’implémentation (.cpp) qui définit les fonctions membres de votre classe, démarrez le mappage de répartition avec la macro BEGIN_DISPATCH_MAP, ajoutez des entrées de macro pour chacune de vos fonctions et propriétés de répartition, puis terminez la carte de répartition avec la macro END_DISPATCH_MAP.
Spécifications
En-tête : afxdisp.h
END_DISPATCH_MAP
Termine la définition de votre carte de répartition.
END_DISPATCH_MAP()
Notes
Elle doit être utilisée conjointement avec BEGIN_DISPATCH_MAP.
Spécifications
En-tête : afxdisp.h
DISP_FUNCTION
Définit une fonction d’automatisation OLE dans une carte de répartition.
DISP_FUNCTION(
theClass,
pszName,
pfnMember,
vtRetVal,
vtsParams)
Paramètres
theClass
Nom de la classe.
pszName
Nom externe de la fonction.
pfnMember
Nom de la fonction membre.
vtRetVal
Valeur spécifiant le type de retour de la fonction.
vtsParams
Liste séparée par un espace d’une ou plusieurs constantes spécifiant la liste des paramètres de la fonction.
Notes
L’argument vtRetVal est de type VARTYPE. Les valeurs possibles suivantes pour cet argument sont extraites de l’énumération VARENUM :
| Symbole | Type renvoyé |
|---|---|
| VT_EMPTY | void |
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | DATE |
| VT_BSTR | BSTR |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
L’argument vtsParams est une liste séparée par un espace des valeurs des VTS_* constantes. Une ou plusieurs de ces valeurs séparées par des espaces (et non des virgules) spécifient la liste des paramètres de la fonction. Par exemple,
VTS_I2 VTS_PI2
spécifie une liste contenant un entier court suivi d’un pointeur vers un entier court.
Les VTS_ constantes et leurs significations sont les suivantes :
| Symbole | Type de paramètre |
|---|---|
| VTS_I2 | short |
| VTS_I4 | long |
| VTS_R4 | float |
| VTS_R8 | double |
| VTS_CY | const CY ou CY* |
| VTS_DATE | DATE |
| VTS_BSTR | LPCSTR |
| VTS_DISPATCH | LPDISPATCH |
| VTS_SCODE | SCODE |
| VTS_BOOL | BOOL |
| VTS_VARIANT | const VARIANT* ou VARIANT& |
| VTS_UNKNOWN | LPUNKNOWN |
| VTS_PI2 | court* |
| VTS_PI4 | long* |
| VTS_PR4 | flotter* |
| VTS_PR8 | double* |
| VTS_PCY | CY* |
| VTS_PDATE | DATE* |
| VTS_PBSTR | BSTR* |
| VTS_PDISPATCH | LPDISPATCH* |
| VTS_PSCODE | SCODE* |
| VTS_PBOOL | BOOL* |
| VTS_PVARIANT | VARIANT* |
| VTS_PUNKNOWN | LPUNKNOWN* |
| VTS_NONE | Aucun paramètre |
Spécifications
En-tête : afxdisp.h
DISP_PROPERTY
Définit une propriété OLE Automation dans une carte de répartition.
DISP_PROPERTY(
theClass,
pszName,
memberName,
vtPropType)
Paramètres
theClass
Nom de la classe.
pszName
Nom externe de la propriété.
memberName
Nom de la variable membre dans laquelle la propriété est stockée.
vtPropType
Valeur spécifiant le type de la propriété.
Notes
L’argument vtPropType est de type VARTYPE. Les valeurs possibles pour cet argument sont extraites de l’énumération VARENUM :
| Symbole | Type de propriété |
|---|---|
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | DATE |
| VT_BSTR | CString |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
Lorsqu’un client externe modifie la propriété, la valeur de la variable membre spécifiée par memberName change ; il n’existe aucune notification de la modification.
Spécifications
En-tête : afxdisp.h
DISP_PROPERTY_EX
Définit une propriété OLE Automation et nomme les fonctions utilisées pour obtenir et définir la valeur de la propriété dans une carte de répartition.
DISP_PROPERTY_EX(
theClass,
pszName,
memberGet,
memberSet,
vtPropType)
Paramètres
theClass
Nom de la classe.
pszName
Nom externe de la propriété.
memberGet
Nom de la fonction membre utilisée pour obtenir la propriété.
memberSet
Nom de la fonction membre utilisée pour définir la propriété.
vtPropType
Valeur spécifiant le type de la propriété.
Notes
Les fonctions memberGet et memberSet ont des signatures déterminées par l’argument vtPropType . La fonction memberGet ne prend aucun argument et retourne une valeur du type spécifié par vtPropType. La fonction memberSet prend un argument du type spécifié par vtPropType et ne retourne rien.
L’argument vtPropType est de type VARTYPE. Les valeurs possibles pour cet argument sont extraites de l’énumération VARENUM. Pour obtenir la liste de ces valeurs, consultez les remarques relatives au paramètre vtRetVal dans DISP_FUNCTION. Notez que VT_EMPTY, répertoriées dans les remarques DISP_FUNCTION, n’est pas autorisée en tant que type de données de propriété.
Spécifications
En-tête : afxdisp.h
DISP_PROPERTY_NOTIFY
Définit une propriété OLE Automation avec notification dans une carte de répartition.
DISP_PROPERTY_NOTIFY(
theClass,
szExternalName,
memberName,
pfnAfterSet,
vtPropType)
Paramètres
theClass
Nom de la classe.
szExternalName
Nom externe de la propriété.
memberName
Nom de la variable membre dans laquelle la propriété est stockée.
pfnAfterSet
Nom de la fonction de notification pour szExternalName.
vtPropType
Valeur spécifiant le type de la propriété.
Notes
Contrairement aux propriétés définies avec DISP_PROPERTY, une propriété définie avec DISP_PROPERTY_NOTIFY appelle automatiquement la fonction spécifiée par pfnAfterSet lorsque la propriété est modifiée.
L’argument vtPropType est de type VARTYPE. Les valeurs possibles pour cet argument sont extraites de l’énumération VARENUM :
| Symbole | Type de propriété |
|---|---|
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | DATE |
| VT_BSTR | CString |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
Spécifications
En-tête : afxdisp.h
DISP_PROPERTY_PARAM
Définit une propriété accessible avec des fonctions distinctes Get et Set membres.
DISP_PROPERTY_PARAM(
theClass,
pszExternalName,
pfnGet,
pfnSet,
vtPropType,
vtsParams)
Paramètres
theClass
Nom de la classe.
pszExternalName
Nom externe de la propriété.
pfnGet
Nom de la fonction membre utilisée pour obtenir la propriété.
pfnSet
Nom de la fonction membre utilisée pour définir la propriété.
vtPropType
Valeur spécifiant le type de la propriété.
vtsParams
Chaîne de types de paramètres variant séparés par VTS_* l’espace, une pour chaque paramètre.
Notes
Contrairement à la macro DISP_PROPERTY_EX, cette macro vous permet de spécifier une liste de paramètres pour la propriété. Cela est utile pour implémenter des propriétés indexées ou paramétrables.
Exemple
Tenez compte de la déclaration suivante d’obtenir et de définir des fonctions membres qui permettent à l’utilisateur de demander une ligne et une colonne spécifiques lors de l’accès à la propriété :
SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);
Ces éléments correspondent à la macro DISP_PROPERTY_PARAM suivante dans la carte de répartition du contrôle :
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2)
Comme autre exemple, considérez les fonctions membres get et set suivantes :
IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);
Ces éléments correspondent à la macro DISP_PROPERTY_PARAM suivante dans la carte de répartition du contrôle :
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)
Spécifications
En-tête : afxdisp.h
DISP_DEFVALUE
Rend une propriété existante la valeur par défaut d’un objet.
DISP_DEFVALUE(theClass, pszName)
Paramètres
theClass
Nom de la classe.
pszName
Nom externe de la propriété qui représente la « valeur » de l’objet.
Notes
L’utilisation d’une valeur par défaut permet de simplifier la programmation de votre objet Automation pour les applications Visual Basic.
La « valeur par défaut » de votre objet est la propriété récupérée ou définie lorsqu’une référence à un objet ne spécifie pas de propriété ou de fonction membre.
Spécifications
En-tête : afxdisp.h