Mapas de envío
La automatización OLE proporciona maneras de llamar a métodos y acceder a propiedades entre aplicaciones. El mecanismo proporcionado por la biblioteca MFC (Microsoft Foundation Class) para enviar estas solicitudes es el "mapa de envíos", que designa los nombres internos y externos de las funciones y propiedades de objeto, así como los tipos de datos de las propias propiedades y de los argumentos de función.
| Macro de mapa de envíos | Descripción |
|---|---|
| DECLARE_DISPATCH_MAP | Declara que se usará un mapa de envíos para exponer los métodos y propiedades de una clase (debe usarse en la declaración de clase). |
| BEGIN_DISPATCH_MAP | Inicia la definición de un mapa de envíos. |
| END_DISPATCH_MAP | Finaliza la definición de un mapa de envíos. |
| DISP_FUNCTION | Se usa en un mapa de envíos para definir una función de automatización OLE. |
| DISP_PROPERTY | Define una propiedad de automatización OLE. |
| DISP_PROPERTY_EX | Define una propiedad de automatización OLE y asigna nombres a las funciones Get y Set. |
| DISP_PROPERTY_NOTIFY | Define una propiedad de automatización OLE con notificación. |
| DISP_PROPERTY_PARAM | Define una propiedad de automatización OLE que toma parámetros y asigna nombres a las funciones Get y Set. |
| DISP_DEFVALUE | Convierte una propiedad existente en el valor predeterminado de un objeto. |
DECLARE_DISPATCH_MAP
Si una clase derivada de CCmdTarget del programa admite la automatización OLE, esa clase debe proporcionar un mapa de envíos para exponer sus métodos y propiedades.
DECLARE_DISPATCH_MAP()
Comentarios
Use la macro DECLARE_DISPATCH_MAP al final de la declaración de clase. A continuación, en el archivo .CPP que define las funciones miembro de la clase, use la macro BEGIN_DISPATCH_MAP. A continuación, incluya entradas de macro para cada uno de los métodos y propiedades expuestos de la clase (DISP_FUNCTION, DISP_PROPERTY, etc.). Por último, use la macro END_DISPATCH_MAP.
Nota:
Si declara algún miembro después de DECLARE_DISPATCH_MAP, debe especificar un nuevo tipo de acceso (public, private o protected) para ellos.
El Asistente para aplicaciones y los asistentes para código ayudan a crear clases de automatización y a mantener mapas de envíos. Para más información sobre los mapas de envíos, consulte Servidores de automatización.
Ejemplo
class CMyServerDoc : public COleServerDoc
{
DECLARE_DISPATCH_MAP()
// Remainder of class declaration omitted.
Requisitos
Encabezado: afxwin.h
BEGIN_DISPATCH_MAP
Declara la definición del mapa de envíos.
BEGIN_DISPATCH_MAP(theClass, baseClass)
Parámetros
theClass
Especifica el nombre de la clase propietaria del mapa de envíos.
baseClass
Especifica el nombre de clase base de theClass.
Comentarios
En el archivo de implementación (.cpp) que define las funciones miembro de la clase, inicie el mapa de envíos con la macro BEGIN_DISPATCH_MAP, agregue entradas de macro para cada una de las propiedades y funciones de envío y complete el mapa de envíos con la macro END_DISPATCH_MAP.
Requisitos
Encabezado: afxdisp.h
END_DISPATCH_MAP
Finalización de la definición del mapa de envíos.
END_DISPATCH_MAP()
Comentarios
Se debe usar junto con BEGIN_DISPATCH_MAP.
Requisitos
Encabezado: afxdisp.h
DISP_FUNCTION
Define una función de automatización OLE en un mapa de envíos.
DISP_FUNCTION(
theClass,
pszName,
pfnMember,
vtRetVal,
vtsParams)
Parámetros
theClass
Nombre de la clase.
pszName
Nombre externo de la función.
pfnMember
Nombre de la función miembro.
vtRetVal
Valor que especifica el tipo de valor devuelto de la función.
vtsParams
Lista separada por espacios de una o varias constantes que especifican la lista de parámetros de la función.
Comentarios
El argumento vtRetVal es de tipo VARTYPE. Los siguientes valores posibles del argumento se toman de la enumeración VARENUM:
| Símbolo | Tipo de valor devuelto |
|---|---|
| VT_EMPTY | void |
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | FECHA |
| VT_BSTR | BSTR |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
El argumento vtsParams es una lista separada por espacios de valores de las constantes VTS_*. Uno o varios de estos valores, separados por espacios (no por comas), especifican la lista de parámetros de la función. Por ejemplo,
VTS_I2 VTS_PI2
especifica una lista que contiene un entero corto seguido de un puntero a un entero corto.
A continuación se indican las constantes VTS_ y el significado de cada una de ellas:
| Símbolo | Tipo de parámetro |
|---|---|
| VTS_I2 | short |
| VTS_I4 | long |
| VTS_R4 | float |
| VTS_R8 | double |
| VTS_CY | const CY o CY* |
| VTS_DATE | FECHA |
| VTS_BSTR | LPCSTR |
| VTS_DISPATCH | LPDISPATCH |
| VTS_SCODE | SCODE |
| VTS_BOOL | BOOL |
| VTS_VARIANT | const VARIANT* o VARIANT& |
| VTS_UNKNOWN | LPUNKNOWN |
| VTS_PI2 | short* |
| VTS_PI4 | long* |
| VTS_PR4 | float* |
| 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 | Sin parámetros |
Requisitos
Encabezado: afxdisp.h
DISP_PROPERTY
Define una propiedad de automatización OLE en un mapa de envíos.
DISP_PROPERTY(
theClass,
pszName,
memberName,
vtPropType)
Parámetros
theClass
Nombre de la clase.
pszName
Nombre externo de la propiedad.
memberName
Nombre de la variable miembro en la que se almacena la propiedad.
vtPropType
Valor que especifica el tipo de la propiedad.
Comentarios
El argumento vtPropType es de tipo VARTYPE. Los valores posibles del argumento se toman de la enumeración VARENUM:
| Símbolo | Tipo de propiedad |
|---|---|
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | FECHA |
| VT_BSTR | CString |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
Cuando un cliente externo cambia la propiedad, cambia el valor de la variable miembro especificada por memberName; no hay ninguna notificación del cambio.
Requisitos
Encabezado: afxdisp.h
DISP_PROPERTY_EX
Define una propiedad de automatización OLE y asigna un nombre a las funciones usadas para obtener y establecer el valor de la propiedad en un mapa de envíos.
DISP_PROPERTY_EX(
theClass,
pszName,
memberGet,
memberSet,
vtPropType)
Parámetros
theClass
Nombre de la clase.
pszName
Nombre externo de la propiedad.
memberGet
Nombre de la función miembro usada para obtener la propiedad.
memberSet
Nombre de la función miembro usada para establecer la propiedad.
vtPropType
Valor que especifica el tipo de la propiedad.
Comentarios
Las funciones memberGet y memberSet tienen firmas determinadas por el argumento vtPropType. La función memberGet no toma ningún argumento y devuelve un valor del tipo especificado por vtPropType. La función memberSet toma un argumento del tipo especificado por vtPropType y no devuelve nada.
El argumento vtPropType es de tipo VARTYPE. Los valores posibles del argumento se toman de la enumeración VARENUM. Para obtener una lista de estos valores, vea los comentarios del parámetro vtRetVal en DISP_FUNCTION. Tenga en cuenta que VT_EMPTY, que aparece en los comentarios de DISP_FUNCTION, no se permite como un tipo de datos de propiedad.
Requisitos
Encabezado: afxdisp.h
DISP_PROPERTY_NOTIFY
Define una propiedad de automatización OLE con notificación en un mapa de envíos.
DISP_PROPERTY_NOTIFY(
theClass,
szExternalName,
memberName,
pfnAfterSet,
vtPropType)
Parámetros
theClass
Nombre de la clase.
szExternalName
Nombre externo de la propiedad.
memberName
Nombre de la variable miembro en la que se almacena la propiedad.
pfnAfterSet
Nombre de la función de notificación para szExternalName.
vtPropType
Valor que especifica el tipo de la propiedad.
Comentarios
A diferencia de las propiedades definidas con DISP_PROPERTY, una propiedad definida con DISP_PROPERTY_NOTIFY llamará automáticamente a la función especificada por pfnAfterSet cuando se cambia la propiedad.
El argumento vtPropType es de tipo VARTYPE. Los valores posibles del argumento se toman de la enumeración VARENUM:
| Símbolo | Tipo de propiedad |
|---|---|
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | FECHA |
| VT_BSTR | CString |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
Requisitos
Encabezado: afxdisp.h
DISP_PROPERTY_PARAM
Define una propiedad a la que se accede con funciones miembro Get y Set independientes.
DISP_PROPERTY_PARAM(
theClass,
pszExternalName,
pfnGet,
pfnSet,
vtPropType,
vtsParams)
Parámetros
theClass
Nombre de la clase.
pszExternalName
Nombre externo de la propiedad.
pfnGet
Nombre de la función miembro usada para obtener la propiedad.
pfnSet
Nombre de la función miembro usada para establecer la propiedad.
vtPropType
Valor que especifica el tipo de la propiedad.
vtsParams
Cadena de tipos de parámetros variantes VTS_* separados por espacios, uno para cada parámetro.
Comentarios
A diferencia de la macro DISP_PROPERTY_EX, esta macro permite especificar una lista de parámetros para la propiedad. Resulta útil para implementar propiedades indexadas o parametrizadas.
Ejemplo
Tenga en cuenta la siguiente declaración de funciones miembro Get y Set que permiten al usuario solicitar una fila y una columna específicas al acceder a la propiedad:
SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);
Corresponden a la siguiente macro DISP_PROPERTY_PARAM en el mapa de envíos de controles:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2)
Otro ejemplo: tenga en cuenta las siguientes funciones miembro Get y Set:
IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);
Corresponden a la siguiente macro DISP_PROPERTY_PARAM en el mapa de envíos de controles:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)
Requisitos
Encabezado: afxdisp.h
DISP_DEFVALUE
Convierte una propiedad existente en el valor predeterminado de un objeto.
DISP_DEFVALUE(theClass, pszName)
Parámetros
theClass
Nombre de la clase.
pszName
Nombre externo de la propiedad que representa el "valor" del objeto.
Comentarios
El uso de un valor predeterminado puede simplificar la programación del objeto de automatización para las aplicaciones de Visual Basic.
El "valor predeterminado" del objeto es la propiedad que se recupera o establece cuando una referencia a un objeto no especifica una propiedad o una función miembro.
Requisitos
Encabezado: afxdisp.h