Mapas de expedição
A Automação OLE fornece meios de chamar métodos e acessar propriedades entre aplicativos. O mecanismo fornecido pela biblioteca Microsoft Foundation Class para expedição dessas solicitações é o "mapa de expedição", que designa os nomes internos e externos de funções e propriedades de objeto, bem como os tipos de dados das propriedades em si e dos argumentos de função.
Macro de mapa de expedição | Descrição |
---|---|
DECLARE_DISPATCH_MAP | Declara que um mapa de expedição será usado para expor os métodos e as propriedades de uma classe (deve ser usado na declaração de classe). |
BEGIN_DISPATCH_MAP | Inicia a definição de um mapa de expedição. |
END_DISPATCH_MAP | Termina a definição de um mapa de expedição. |
DISP_FUNCTION | Usado em um mapa de expedição para definir uma função de automação OLE. |
DISP_PROPERTY | Define uma propriedade de automação OLE. |
DISP_PROPERTY_EX | Define uma propriedade de automação OLE e nomeia as funções Get e Set. |
DISP_PROPERTY_NOTIFY | Define uma propriedade de automação OLE com notificação. |
DISP_PROPERTY_PARAM | Define uma propriedade de automação OLE que usa parâmetros e nomeia as funções Get e Set. |
DISP_DEFVALUE | Torna uma propriedade existente o valor padrão de um objeto. |
DECLARE_DISPATCH_MAP
Se uma classe CCmdTarget
derivada em seu programa der suporte à Automação OLE, essa classe deverá fornecer um mapa de expedição para expor seus métodos e propriedades.
DECLARE_DISPATCH_MAP()
Comentários
Use a macro DECLARE_DISPATCH_MAP no final da declaração de classe. Então, no arquivo .CPP que define as funções de membro para a classe, use a macro BEGIN_DISPATCH_MAP. Depois inclua entradas de macro para cada um dos métodos e propriedades expostos de sua classe (DISP_FUNCTION, DISP_PROPERTY etc.). Por fim, use a macro END_DISPATCH_MAP.
Observação
Se você declarar membros após DECLARE_DISPATCH_MAP, deverá especificar um novo tipo de acesso ( public
ou private
protected
) para eles.
O Assistente de Aplicativo e os assistentes de código ajudam na criação de classes de Automação e na manutenção de mapas de expedição. Para mais informações sobre mapas de expedição, confira Servidores de Automação.
Exemplo
class CMyServerDoc : public COleServerDoc
{
DECLARE_DISPATCH_MAP()
// Remainder of class declaration omitted.
Requisitos
Cabeçalho: afxwin.h
BEGIN_DISPATCH_MAP
Declara a definição do mapa de expedição.
BEGIN_DISPATCH_MAP(theClass, baseClass)
Parâmetros
theClass
Especifica o nome da classe que detém esse mapa de expedição.
baseClass
Especifica o nome de classe base theClass.
Comentários
No arquivo de implementação (.cpp) que define as funções de membro para sua classe, inicie o mapa de expedição com a macro BEGIN_DISPATCH_MAP, adicione entradas de macro para cada uma de suas funções e propriedades de expedição e conclua o mapa de expedição com a macro END_DISPATCH_MAP.
Requisitos
Cabeçalho afxdisp.h
END_DISPATCH_MAP
Termina a definição do mapa de expedição.
END_DISPATCH_MAP()
Comentários
Ele deve ser usado em conjunto com BEGIN_DISPATCH_MAP.
Requisitos
Cabeçalho afxdisp.h
DISP_FUNCTION
Define uma função de automação OLE em um mapa de expedição.
DISP_FUNCTION(
theClass,
pszName,
pfnMember,
vtRetVal,
vtsParams)
Parâmetros
theClass
Nome da classe.
pszName
Nome externo da função.
pfnMember
Nome da função de membro.
vtRetVal
Um valor que especifica o tipo de retorno da função.
vtsParams
Uma lista separada por espaço de uma ou mais constantes que especificam a lista de parâmetros da função.
Comentários
O argumento vtRetVal é do tipo VARTYPE. Os seguintes valores possíveis para esse argumento são obtidos da enumeração VARENUM
:
Símbolo | Tipo de retorno |
---|---|
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 |
O argumento vtsParams é uma lista de valores separados por espaço das constantes VTS_*
. Um ou mais desses valores separados por espaços (não vírgulas) especifica a lista de parâmetros da função. Por exemplo,
VTS_I2 VTS_PI2
especifica uma lista que contém um inteiro curto seguido por um ponteiro para um inteiro curto.
As constantes VTS_
e seus significados são os seguintes:
Símbolo | Tipo de parâmetro |
---|---|
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 | 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 | Sem parâmetros |
Requisitos
Cabeçalho afxdisp.h
DISP_PROPERTY
Define uma propriedade de automação OLE em um mapa de expedição.
DISP_PROPERTY(
theClass,
pszName,
memberName,
vtPropType)
Parâmetros
theClass
Nome da classe.
pszName
Nome externo da propriedade.
memberName
Nome da variável de membro na qual a propriedade é armazenada.
vtPropType
Um valor que especifica o tipo da propriedade.
Comentários
O argumento vtPropType é do tipo VARTYPE. Os valores possíveis para esse argumento são obtidos da enumeração VARENUM:
Símbolo | Tipo de propriedade |
---|---|
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 um cliente externo altera a propriedade, o valor da variável membro especificada por memberName é alterado; não há notificação da alteração.
Requisitos
Cabeçalho afxdisp.h
DISP_PROPERTY_EX
Define uma propriedade de automação OLE e nomeia as funções usadas para obter e definir o valor da propriedade em um mapa de expedição.
DISP_PROPERTY_EX(
theClass,
pszName,
memberGet,
memberSet,
vtPropType)
Parâmetros
theClass
Nome da classe.
pszName
Nome externo da propriedade.
memberGet
Nome da função membro usada para obter a propriedade.
memberSet
Nome da função membro usada para definir a propriedade.
vtPropType
Um valor que especifica o tipo da propriedade.
Comentários
As funções memberGet e memberSet têm assinaturas determinadas pelo argumento vtPropType. A função memberGet não usa argumentos e retorna um valor do tipo especificado por vtPropType. A função memberSet usa um argumento do tipo especificado por vtPropType e não retorna nada.
O argumento vtPropType é do tipo VARTYPE. Os valores possíveis para esse argumento são obtidos da enumeração VARENUM. Para uma lista desses valores, confira os Comentários para o parâmetro vtRetVal em DISP_FUNCTION. Observe que VT_EMPTY, listado nas observações DISP_FUNCTION, não é permitido como um tipo de dados de propriedade.
Requisitos
Cabeçalho afxdisp.h
DISP_PROPERTY_NOTIFY
Define uma propriedade de automação OLE com notificação em um mapa de expedição.
DISP_PROPERTY_NOTIFY(
theClass,
szExternalName,
memberName,
pfnAfterSet,
vtPropType)
Parâmetros
theClass
Nome da classe.
szExternalName
Nome externo da propriedade.
memberName
Nome da variável de membro na qual a propriedade é armazenada.
pfnAfterSet
Nome da função de notificação para szExternalName.
vtPropType
Um valor que especifica o tipo da propriedade.
Comentários
Ao contrário das propriedades definidas com DISP_PROPERTY, uma propriedade definida com DISP_PROPERTY_NOTIFY chamará automaticamente a função especificada por pfnAfterSet quando a propriedade for alterada.
O argumento vtPropType é do tipo VARTYPE. Os valores possíveis para esse argumento são obtidos da enumeração VARENUM:
Símbolo | Tipo de propriedade |
---|---|
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 |
Requisitos
Cabeçalho afxdisp.h
DISP_PROPERTY_PARAM
Define uma propriedade acessada com funções de membro Get
e Set
separadas.
DISP_PROPERTY_PARAM(
theClass,
pszExternalName,
pfnGet,
pfnSet,
vtPropType,
vtsParams)
Parâmetros
theClass
Nome da classe.
pszExternalName
Nome externo da propriedade.
pfnGet
Nome da função membro usada para obter a propriedade.
pfnSet
Nome da função membro usada para definir a propriedade.
vtPropType
Um valor que especifica o tipo da propriedade.
vtsParams
Uma cadeia de caracteres de tipos de parâmetro variante VTS_*
separados por espaço, um para cada parâmetro.
Comentários
Ao contrário da macro DISP_PROPERTY_EX, essa macro permite que você especifique uma lista de parâmetros para a propriedade. Isso é útil para implementar propriedades indexadas ou parametrizadas.
Exemplo
Considere a seguinte declaração das funções de membro get e set que permitem que o usuário solicite uma linha e uma coluna específicas ao acessar a propriedade:
SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);
Elas correspondem à seguinte macro DISP_PROPERTY_PARAM no mapa de expedição de controle:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2)
Como outro exemplo, considere as seguintes funções de membro get e set:
IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);
Elas correspondem à seguinte macro DISP_PROPERTY_PARAM no mapa de expedição de controle:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)
Requisitos
Cabeçalho afxdisp.h
DISP_DEFVALUE
Torna uma propriedade existente o valor padrão de um objeto.
DISP_DEFVALUE(theClass, pszName)
Parâmetros
theClass
Nome da classe.
pszName
Nome externo da propriedade que representa o "valor" do objeto.
Comentários
Usar um valor padrão pode facilitar a programação do objeto de automação para aplicativos do Visual Basic.
O "valor padrão" do objeto é a propriedade recuperada ou definida quando uma referência a um objeto não especifica uma propriedade ou função de membro.
Requisitos
Cabeçalho afxdisp.h