Mappe di invio
L'automazione OLE consente di chiamare i metodi e di accedere alle proprietà tra le applicazioni. Il meccanismo fornito dalla Libreria di classi di Microsoft Foundation per l'invio di queste richieste è la "mappa dispatch", che definisce i nomi interni ed esterni di funzioni e proprietà degli oggetti, nonché i tipi di dati delle proprietà stesse e degli argomenti di funzione.
| Macro mappa dispatch | Descrizione |
|---|---|
| DECLARE_DISPATCH_MAP | Dichiara che una mappa dispatch verrà usata per esporre i metodi e le proprietà di una classe (deve essere usata nella dichiarazione di classe). |
| BEGIN_DISPATCH_MAP | Avvia la definizione di una mappa di distribuzione. |
| END_DISPATCH_MAP | Termina la definizione di una mappa di distribuzione. |
| DISP_FUNCTION | Utilizzato in una mappa dispatch per definire una funzione di automazione OLE. |
| DISP_PROPERTY | Definisce una proprietà di automazione OLE. |
| DISP_PROPERTY_EX | Definisce una proprietà di automazione OLE e assegna un nome alle funzioni Get e Set. |
| DISP_PROPERTY_NOTIFY | Definisce una proprietà di automazione OLE con notifica. |
| DISP_PROPERTY_PARAM | Definisce una proprietà di automazione OLE che accetta parametri e assegna nomi alle funzioni Get e Set. |
| DISP_DEFVALUE | Imposta una proprietà esistente come il valore predefinito di un oggetto. |
DECLARE_DISPATCH_MAP
Se una classe derivata da - CCmdTargetnel programma supporta l'automazione OLE, tale classe deve fornire una mappa dispatch per esporre i relativi metodi e proprietà.
DECLARE_DISPATCH_MAP()
Osservazioni:
Usare la macro DECLARE_DISPATCH_MAP alla fine della dichiarazione di classe. Quindi, in . File CPP che definisce le funzioni membro per la classe , usare la macro BEGIN_DISPATCH_MAP. Includere quindi voci di macro per ognuno dei metodi e delle proprietà esposti della classe (DISP_FUNCTION, DISP_PROPERTY e così via). Infine, usare la macro END_DISPATCH_MAP.
Nota
Se si dichiarano membri dopo DECLARE_DISPATCH_MAP, è necessario specificare un nuovo tipo di accesso ( public, privateo protected) per tali membri.
La Creazione guidata applicazione e le procedure guidate del codice consentono di creare classi di automazione e di gestire le mappe di distribuzione. Per altre informazioni sulle mappe dispatch, vedere Server di automazione.
Esempio
class CMyServerDoc : public COleServerDoc
{
DECLARE_DISPATCH_MAP()
// Remainder of class declaration omitted.
Requisiti
Intestazione: afxwin.h
BEGIN_DISPATCH_MAP
Dichiara la definizione della mappa di distribuzione.
BEGIN_DISPATCH_MAP(theClass, baseClass)
Parametri
theClass
Specifica il nome della classe proprietaria della mappa dispatch.
baseClass
Specifica il nome della classe di base di theClass.
Osservazioni:
Nel file di implementazione (.cpp) che definisce le funzioni membro per la classe, avviare la mappa dispatch con la macro BEGIN_DISPATCH_MAP, aggiungere voci di macro per ognuna delle funzioni e delle proprietà dispatch e completare la mappa dispatch con la macro END_DISPATCH_MAP.
Requisiti
Intestazione: afxdisp.h
END_DISPATCH_MAP
Termina la definizione della mappa di distribuzione.
END_DISPATCH_MAP()
Osservazioni:
Deve essere utilizzata in combinazione con BEGIN_DISPATCH_MAP.
Requisiti
Intestazione: afxdisp.h
DISP_FUNCTION
Definisce una funzione di automazione OLE in una mappa dispatch.
DISP_FUNCTION(
theClass,
pszName,
pfnMember,
vtRetVal,
vtsParams)
Parametri
theClass
Nome della classe.
pszName
Nome esterno della funzione.
pfnMember
Nome della funzione membro.
vtRetVal
Valore che specifica il tipo restituito della funzione.
vtsParams
Elenco delimitato da spazi di una o più costanti che specificano l'elenco di parametri della funzione.
Osservazioni:
L'argomento vtRetVal è di tipo VARTYPE. I valori possibili seguenti per questo argomento vengono ricavati dall'enumerazione VARENUM :
| Simbolo | Tipo restituito |
|---|---|
| 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'argomento vtsParams è un elenco di valori separati da spazi dalle VTS_* costanti. Uno o più di questi valori separati da spazi (non da virgole) specifica l'elenco di parametri della funzione. ad esempio:
VTS_I2 VTS_PI2
specifica un elenco contenente un numero intero breve seguito da un puntatore a un numero intero breve.
Le VTS_ costanti e i relativi significati sono le seguenti:
| Simbolo | Tipo parametro |
|---|---|
| VTS_I2 | short |
| VTS_I4 | long |
| VTS_R4 | float |
| VTS_R8 | double |
| VTS_CY | const CY oppure CY* |
| VTS_DATE | DATE |
| VTS_BSTR | LPCSTR |
| VTS_DISPATCH | LPDISPATCH |
| VTS_SCODE | SCODE |
| VTS_BOOL | BOOL |
| VTS_VARIANT | const VARIANT* oppure VARIANT& |
| VTS_UNKNOWN | LPUNKNOWN |
| VTS_PI2 | corto* |
| VTS_PI4 | lungo* |
| VTS_PR4 | galleggiare* |
| VTS_PR8 | doppio* |
| 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 | Nessun parametro |
Requisiti
Intestazione: afxdisp.h
DISP_PROPERTY
Definisce una proprietà di automazione OLE in una mappa dispatch.
DISP_PROPERTY(
theClass,
pszName,
memberName,
vtPropType)
Parametri
theClass
Nome della classe.
pszName
Nome esterno della proprietà.
memberName
Nome della variabile membro in cui è archiviata la proprietà.
vtPropType
Valore che specifica il tipo della proprietà.
Osservazioni:
L'argomento vtPropType è di tipo VARTYPE. I valori possibili per questo argomento sono tratti dall'enumerazione VARENUM:
| Simbolo | Tipo di proprietà |
|---|---|
| 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 |
Quando un client esterno modifica la proprietà, il valore della variabile membro specificata da memberName cambia; non viene inviata alcuna notifica della modifica.
Requisiti
Intestazione: afxdisp.h
DISP_PROPERTY_EX
Definisce una proprietà di automazione OLE e denominare le funzioni usate per ottenere e impostare il valore della proprietà in una mappa dispatch.
DISP_PROPERTY_EX(
theClass,
pszName,
memberGet,
memberSet,
vtPropType)
Parametri
theClass
Nome della classe.
pszName
Nome esterno della proprietà.
memberGet
Nome della funzione membro utilizzata per ottenere la proprietà .
memberSet
Nome della funzione membro utilizzata per impostare la proprietà.
vtPropType
Valore che specifica il tipo della proprietà.
Osservazioni:
Le funzioni memberGet e memberSet hanno firme determinate dall'argomento vtPropType . La funzione memberGet non accetta argomenti e restituisce un valore del tipo specificato da vtPropType. La funzione memberSet accetta un argomento del tipo specificato da vtPropType e non restituisce nulla.
L'argomento vtPropType è di tipo VARTYPE. I valori possibili per questo argomento vengono ricavati dall'enumerazione VARENUM. Per un elenco di questi valori, vedere la sezione Osservazioni per il parametro vtRetVal in DISP_FUNCTION. Si noti che VT_EMPTY, elencato nelle note DISP_FUNCTION, non è consentito come tipo di dati di proprietà.
Requisiti
Intestazione: afxdisp.h
DISP_PROPERTY_NOTIFY
Definisce una proprietà di automazione OLE con notifica in una mappa dispatch.
DISP_PROPERTY_NOTIFY(
theClass,
szExternalName,
memberName,
pfnAfterSet,
vtPropType)
Parametri
theClass
Nome della classe.
szExternalName
Nome esterno della proprietà.
memberName
Nome della variabile membro in cui è archiviata la proprietà.
pfnAfterSet
Nome della funzione di notifica per szExternalName.
vtPropType
Valore che specifica il tipo della proprietà.
Osservazioni:
A differenza delle proprietà definite con DISP_PROPERTY, una proprietà definita con DISP_PROPERTY_NOTIFY chiamerà automaticamente la funzione specificata da pfnAfterSet quando la proprietà viene modificata.
L'argomento vtPropType è di tipo VARTYPE. I valori possibili per questo argomento sono tratti dall'enumerazione VARENUM:
| Simbolo | Tipo di proprietà |
|---|---|
| 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 |
Requisiti
Intestazione: afxdisp.h
DISP_PROPERTY_PARAM
Definisce una proprietà a cui si accede con funzioni separate Get e Set membro.
DISP_PROPERTY_PARAM(
theClass,
pszExternalName,
pfnGet,
pfnSet,
vtPropType,
vtsParams)
Parametri
theClass
Nome della classe.
pszExternalName
Nome esterno della proprietà.
pfnGet
Nome della funzione membro utilizzata per ottenere la proprietà .
pfnSet
Nome della funzione membro utilizzata per impostare la proprietà.
vtPropType
Valore che specifica il tipo della proprietà.
vtsParams
Stringa di tipi di parametro variant separati da VTS_* spazi, uno per ogni parametro.
Osservazioni:
A differenza della macro DISP_PROPERTY_EX, questa macro consente di specificare un elenco di parametri per la proprietà . Ciò è utile per l'implementazione di proprietà indicizzate o con parametri.
Esempio
Si consideri la dichiarazione seguente di funzioni membro get e set che consentono all'utente di richiedere una riga e una colonna specifica durante l'accesso alla proprietà:
SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);
Questi corrispondono alla macro DISP_PROPERTY_PARAM seguente nella mappa di invio dei controlli:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2)
Come altro esempio, considerare le funzioni membro get e set seguenti:
IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);
Questi corrispondono alla macro DISP_PROPERTY_PARAM seguente nella mappa di invio dei controlli:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)
Requisiti
Intestazione: afxdisp.h
DISP_DEFVALUE
Imposta una proprietà esistente come il valore predefinito di un oggetto.
DISP_DEFVALUE(theClass, pszName)
Parametri
theClass
Nome della classe.
pszName
Nome esterno della proprietà che rappresentata il "valore" dell'oggetto.
Osservazioni:
L'utilizzo di un valore predefinito può rendere più facile la programmazione dell'oggetto di automazione per le applicazioni Visual Basic.
Il "valore predefinito" dell'oggetto è la proprietà che viene recuperata o impostata quando un riferimento a un oggetto non specifica una proprietà o una funzione membro.
Requisiti
Intestazione: afxdisp.h