Compartilhar via

Mapas de expedição

  • Artigo

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 ( publicou privateprotected) 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

Confira também

Macros e Globais