Compartilhar via

Serviços do modelo de objeto de tempo de execução

  • Artigo

As classes CObject e CRuntimeClass encapsulam vários serviços de objeto, incluindo acesso a informações de classe em tempo de execução, serialização e criação de objeto dinâmico. Todas as classes derivadas de CObject herdam essa funcionalidade.

O acesso às informações de classe em tempo de execução permite determinar informações sobre a classe de um objeto em tempo de execução. A capacidade de determinar a classe de um objeto em tempo de execução é útil quando você precisa de verificação de tipo extra de argumentos de função e quando você deve escrever código de finalidade especial conforme a classe de um objeto. Não há suporte para informações de classe em tempo de execução diretamente pela linguagem C++.

Serialização é o processo de escrever ou ler o conteúdo de um objeto de ou para um arquivo. Você pode usar a serialização para armazenar o conteúdo de um objeto mesmo após a saída do aplicativo. Em seguida, o objeto pode ser lido do arquivo quando o aplicativo é reiniciado. Esses objetos de dados são considerados "persistentes".

A criação de objeto dinâmico permite que você crie um objeto de uma classe especificada em tempo de execução. Por exemplo, objetos de documento, exibição e quadro devem dar suporte à criação dinâmica porque a estrutura precisa criá-los dinamicamente.

A tabela a seguir lista as macros MFC que dão suporte a informações de classe em tempo de execução, serialização e criação dinâmica.

Para mais informações sobre esses serviços de objeto em tempo de execução e serialização, confira o artigo Classe CObject: como acessar informações de classe em tempo de execução.

Macros de serviços do modelo de objeto de tempo de execução

Nome Descrição
DECLARE_DYNAMIC Habilita o acesso a informações de classe em tempo de execução (deve ser usado na declaração de classe).
DECLARE_DYNCREATE Habilita a criação dinâmica e o acesso a informações de classe em tempo de execução (deve ser usado na declaração de classe).
DECLARE_SERIAL Habilita a serialização e o acesso a informações de classe em tempo de execução (deve ser usado na declaração de classe).
IMPLEMENT_DYNAMIC Habilita o acesso a informações de classe em tempo de execução (deve ser usado na implementação da classe).
IMPLEMENT_DYNCREATE Habilita a criação dinâmica e o acesso a informações em tempo de execução (deve ser usado na implementação da classe).
IMPLEMENT_SERIAL Permite serialização e acesso a informações de classe em tempo de execução (deve ser usado na implementação de classe).
RUNTIME_CLASS Retorna a estrutura CRuntimeClass que corresponde à classe nomeada.

O OLE frequentemente requer a criação dinâmica de objetos em tempo de execução. Por exemplo, um aplicativo para servidores OLE deve ser capaz de criar itens OLE dinamicamente em resposta a uma solicitação de um cliente. Da mesma forma, um servidor de automação deve ser capaz de criar itens em resposta a solicitações de clientes de automação.

A biblioteca Microsoft Foundation Class fornece duas macros específicas do OLE.

Criação dinâmica de objetos OLE

Nome Descrição
AFX_COMCTL32_IF_EXISTS Determina se a biblioteca de Controles Comuns implementa a API especificada.
AFX_COMCTL32_IF_EXISTS2 Determina se a biblioteca de Controles Comuns implementa a API especificada.
DECLARE_OLECREATE Permite que objetos sejam criados por meio da automação OLE.
DECLARE_OLECTLTYPE Declara as funções de membro GetUserTypeNameID e GetMiscStatus da classe de controle.
DECLARE_PROPPAGEIDS Declara que o controle OLE fornece uma lista de páginas de propriedades para exibir suas propriedades.
IMPLEMENT_OLECREATE Permite que objetos sejam criados pelo sistema OLE.
IMPLEMENT_OLECTLTYPE Implementa as funções GetUserTypeNameID e GetMiscStatus de membro da classe de controle.
IMPLEMENT_OLECREATE_FLAGS Essa macro ou IMPLEMENT_OLECREATE deve aparecer no arquivo de implementação para qualquer classe que use DECLARE_OLECREATE.

AFX_COMCTL32_IF_EXISTS

Determina se a biblioteca de Controles Comuns implementa a API especificada.

Sintaxe

AFX_COMCTL32_IF_EXISTS(  proc );

Parâmetros

proc
Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome da função ou especifica o valor ordinal da função. Se esse parâmetro for um valor ordinal, ele deverá estar na palavra de ordem baixa; a palavra de ordem alta deve ser zero. Esse parâmetro deve estar no Unicode.

Comentários

Use essa macro para determinar se a biblioteca controles comuns a função especificada por proc, em vez de chamar GetProcAddress.

Requisitos

afxcomctl32.h, afxcomctl32.inl

AFX_COMCTL32_IF_EXISTS2

Determina se a biblioteca de Controles Comuns implementa a API especificada (esta é a versão Unicode de AFX_COMCTL32_IF_EXISTS).

Sintaxe

AFX_COMCTL32_IF_EXISTS2( proc );

Parâmetros

proc
Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome da função ou especifica o valor ordinal da função. Se esse parâmetro for um valor ordinal, ele deverá estar na palavra de ordem baixa; a palavra de ordem alta deve ser zero. Esse parâmetro deve estar no Unicode.

Comentários

Use essa macro para determinar se a biblioteca controles comuns a função especificada por proc, em vez de chamar GetProcAddress. Essa macro é a versão Unicode de AFX_COMCTL32_IF_EXISTS.

Requisitos

afxcomctl32.h, afxcomctl32.inl

DECLARE_DYNAMIC

Adiciona a capacidade de acessar informações em tempo de execução sobre a classe de um objeto ao derivar uma classe de CObject.

DECLARE_DYNAMIC(class_name)

Parâmetros

class_name
O nome real da classe.

Comentários

Adicione a macro DECLARE_DYNAMIC ao módulo de cabeçalho (.h) da classe e inclua esse módulo em todos os módulos .cpp que precisam de acesso a objetos dessa classe.

Se você usar as macros DECLARE_DYNAMIC e IMPLEMENT_DYNAMIC macros conforme descrito, poderá usar a macro RUNTIME_CLASS e a função CObject::IsKindOf para determinar a classe de seus objetos em tempo de execução.

Se DECLARE_DYNAMIC estiver incluído na declaração de classe, IMPLEMENT_DYNAMIC deverá ser incluído na implementação da classe.

Para mais informações sobre a macro DECLARE_DYNAMIC, confira Tópicos da Classe CObject.

Exemplo

Confira o exemplo de IMPLEMENT_DYNAMIC.

Requisitos

Cabeçalho: afx.h

DECLARE_DYNCREATE

Permite que objetos de classes derivadas de CObject sejam criados dinamicamente em tempo de execução.

DECLARE_DYNCREATE(class_name)

Parâmetros

class_name
O nome real da classe.

Comentários

A estrutura usa essa capacidade de criar objetos dinamicamente. Por exemplo, a exibição criada quando você abre um novo documento. As classes de documento, exibição e quadro devem dar suporte à criação dinâmica porque a estrutura precisa criá-las dinamicamente.

Adicione a macro DECLARE_DYNCREATE ao módulo .h para a classe e inclua esse módulo em todos os módulos .cpp que precisam de acesso a objetos dessa classe.

Se DECLARE_DYNCREATE estiver incluído na declaração de classe, IMPLEMENT_DYNCREATE deverá ser incluído na implementação da classe.

Para mais informações sobre a macro DECLARE_DYNCREATE, confira Tópicos da Classe CObject.

Observação

A macro DECLARE_DYNCREATE inclui todas as funcionalidades de DECLARE_DYNAMIC.

Exemplo

Confira o exemplo de IMPLEMENT_DYNCREATE.

Requisitos

Cabeçalho: afx.h

DECLARE_OLECTLTYPE

Declara as funções de membro GetUserTypeNameID e GetMiscStatus da classe de controle.

Sintaxe

DECLARE_OLECTLTYPE( class_name )

Parâmetros

class_name
O nome da classe de controle.

Comentários

GetUserTypeNameID e GetMiscStatus são funções virtuais puras, declaradas em COleControl. Como essas funções são virtuais puras, elas devem ser substituídas em sua classe de controle. Além de DECLARE_OLECTLTYPE, você deve adicionar a macro IMPLEMENT_OLECTLTYPE à declaração de classe de controle.

Requisitos

Cabeçalho: afxctl.h

DECLARE_PROPPAGEIDS

Declara que o controle OLE fornece uma lista de páginas de propriedades para exibir suas propriedades.

Sintaxe

DECLARE_PROPPAGEIDS( class_name )

Parâmetros

class_name
O nome da classe de controle que tem as páginas de propriedades.

Comentários

Use a macro DECLARE_PROPPAGEIDS no final da declaração de classe. Em seguida, no arquivo .cpp que define as funções de membro da classe, use a macro BEGIN_PROPPAGEIDS, as entradas de macro para cada uma das páginas de propriedades do controle e a macro END_PROPPAGEIDS para declarar o final da lista de páginas de propriedades.

Para mais informações sobre páginas de propriedades, confira o artigo Controles ActiveX: Páginas de propriedades.

Requisitos

Cabeçalho: afxctl.h

DECLARE_SERIAL

Gera o código de cabeçalho C++ necessário para uma classe derivada de CObject que pode ser serializada.

DECLARE_SERIAL(class_name)

Parâmetros

class_name
O nome real da classe.

Comentários

A serialização é o processo de gravar ou ler o conteúdo de um objeto de e para um arquivo.

Use a macro DECLARE_SERIAL em um módulo .h e inclua esse módulo em todos os módulos .cpp que precisam de acesso a objetos dessa classe.

Se DECLARE_SERIAL estiver incluído na declaração de classe, IMPLEMENT_SERIAL deverá ser incluído na implementação da classe.

A macro DECLARE_SERIAL inclui todas as funcionalidades de DECLARE_DYNAMIC e DECLARE_DYNCREATE.

Você pode usar a macro AFX_API para exportar automaticamente o operador de extração CArchive para classes que usam macros DECLARE_SERIAL e IMPLEMENT_SERIAL. Coloque entre colchetes as declarações de classe (localizadas no arquivo .h) com o seguinte código:

#undef AFX_API
#define AFX_API AFX_EXT_CLASS

// <your class declarations here>

#undef AFX_API
#define AFX_API

Para mais informações sobre a macro DECLARE_SERIAL, confira Tópicos da Classe CObject.

Exemplo

class CAge : public CObject
{
public:
   void Serialize(CArchive& ar);
   DECLARE_SERIAL(CAge)

   // remainder of class declaration omitted

Requisitos

Cabeçalho: afx.h

IMPLEMENT_DYNAMIC

Gera o código C++ necessário para uma classe derivada de CObject dinâmica com acesso em tempo de execução ao nome de classe e à posição dentro da hierarquia.

IMPLEMENT_DYNAMIC(class_name, base_class_name)

Parâmetros

class_name
O nome real da classe.

base_class_name
O nome da classe base.

Comentários

Use a macro IMPLEMENT_DYNAMIC em um módulo .cpp e vincule o código de objeto resultante apenas uma vez.

Para mais informações, confira Tópicos da Classe CObject.

Exemplo

class CPerson : public CObject
{
   DECLARE_DYNAMIC(CPerson)

   // other declarations
};

 

IMPLEMENT_DYNAMIC(CPerson, CObject)

Requisitos

Cabeçalho: afx.h

IMPLEMENT_DYNCREATE

Permite que objetos de classes derivadas de CObject sejam criados dinamicamente em tempo de execução quando usados com a macro DECLARE_DYNCREATE.

IMPLEMENT_DYNCREATE(class_name, base_class_name)

Parâmetros

class_name
O nome real da classe.

base_class_name
O nome real da classe base.

Comentários

A estrutura usa essa capacidade de criar novos objetos dinamicamente, por exemplo, quando lê um objeto do disco durante a serialização. Adicione a macro IMPLEMENT_DYNCREATE ao arquivo de implementação de classe. Para mais informações, confira Tópicos da Classe CObject.

Se você usar as macros DECLARE_DYNCREATE e IMPLEMENT_DYNCREATE macros, poderá usar a macro RUNTIME_CLASS e a função de membro CObject::IsKindOf para determinar a classe de seus objetos em tempo de execução.

Se DECLARE_DYNCREATE estiver incluído na declaração de classe, IMPLEMENT_DYNCREATE deverá ser incluído na implementação da classe.

Observe que essa definição de macro invocará o construtor padrão para sua classe. Se um construtor não trivial for explicitamente implementado pela classe, ele também deverá implementar explicitamente o construtor padrão. O construtor padrão pode ser adicionado às seções de membro private ou protected da classe para impedir que ele seja chamado de fora da implementação da classe.

Exemplo

class CMyDynCreateObj : public CObject
{
   int m_Num;
public:
   DECLARE_DYNCREATE(CMyDynCreateObj)
   CMyDynCreateObj(int Num) { m_Num = Num; }
private:
   CMyDynCreateObj() { m_Num = 0; }  // provide default constructor only for 
                                     // dynamic creation 
};

 

IMPLEMENT_DYNCREATE(CMyDynCreateObj, CObject)

Requisitos

Cabeçalho: afx.h

IMPLEMENT_OLECREATE_FLAGS

Essa macro ou IMPLEMENT_OLECREATE deve aparecer no arquivo de implementação para qualquer classe que use DECLARE_OLECREATE.

Sintaxe

IMPLEMENT_OLECREATE_FLAGS( class_name, external_name, nFlags,
    l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)

Parâmetros

class_name
O nome real da classe.

external_name
O nome do objeto exposto a outros aplicativos (entre aspas).

nFlags
Contém um ou mais dos seguintes sinalizadores:

  • afxRegInsertable Permite que o controle apareça na caixa de diálogo Inserir Objeto para objetos OLE.
  • afxRegApartmentThreading Define o modelo de threading no Registro como ThreadingModel=Apartment.
  • afxRegFreeThreading Define o modelo de threading no Registro como ThreadingModel=Free.

Você pode combinar os dois sinalizadores afxRegApartmentThreading e afxRegFreeThreading para definir ThreadingModel=Both. Confira InprocServer32 no SDK do Windows para mais informações sobre o registro de modelo de threading.

Componentes l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8 da CLSID da classe.

Comentários

Observação

Se você usar IMPLEMENT_OLECREATE_FLAGS, poderá especificar a qual modelo de threading seu objeto dá suporte usando o parâmetro nFlags. Se você quiser dar suporte apenas ao modelo de threading simples, use IMPLEMENT_OLECREATE.

O nome externo é o identificador exposto a outros aplicativos. Os aplicativos cliente usam o nome externo para solicitar um objeto dessa classe de um servidor de automação.

A ID da classe OLE é um identificador exclusivo de 128 bits para o objeto. Ela consiste em um long, dois **WORD**s e oito **BYTE**s, conforme representado por l, w1, w2 e b1 a b8 na descrição da sintaxe. O Assistente de Aplicativo e os assistentes de código criam IDs de classe OLE exclusivas para você, conforme necessário.

Requisitos

Cabeçalho: afxdisp.h

IMPLEMENT_OLECTLTYPE

Implementa as funções GetUserTypeNameID e GetMiscStatus de membro da classe de controle.

Sintaxe

DECLARE_OLECTLTYPE( class_name, idsUserTypeName, dwOleMisc )

Parâmetros

class_name
O nome da classe de controle.

idsUserTypeName
A ID do recurso de uma cadeia de caracteres que contém o nome externo do controle.

dwOleMisc
Uma enumeração que contém um ou mais sinalizadores. Para mais informações sobre essa enumeração, confira OLEMISC no SDK do Windows.

Comentários

Além de IMPLEMENT_OLECTLTYPE, você deve adicionar a macro DECLARE_OLECTLTYPE à declaração de classe de controle.

A função de membro GetUserTypeNameID retorna a cadeia de caracteres de recurso que identifica sua classe de controle. GetMiscStatus retorna os bits OLEMISC para o controle. Essa enumeração especifica uma coleção de configurações que descrevem características diversas do controle. Para uma descrição completa das configurações de OLEMISC, confira OLEMISC no SDK do Windows.

Observação

As configurações padrão usadas pelo ActiveX ControlWizard são: OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_INSIDEOUT, OLEMISC_CANTLINKINSIDE e OLEMISC_RECOMPOSEONRESIZE.

Requisitos

Cabeçalho: afxctl.h

IMPLEMENT_SERIAL

Gera o código C++ necessário para uma classe derivada de CObject dinâmica com acesso em tempo de execução ao nome de classe e à posição dentro da hierarquia.

IMPLEMENT_SERIAL(class_name, base_class_name, wSchema)

Parâmetros

class_name
O nome real da classe.

base_class_name
O nome da classe base.

wSchema
Um "número de versão" UINT que será codificado no arquivo morto para habilitar um programa desserializador para identificar e manipular dados criados por versões anteriores do programa. O número do esquema de classe não deve ser -1.

Comentários

Use a macro IMPLEMENT_SERIAL em um módulo .cpp e vincule o código de objeto resultante apenas uma vez.

Você pode usar a macro AFX_API para exportar automaticamente o operador de extração CArchive para classes que usam macros DECLARE_SERIAL e IMPLEMENT_SERIAL. Coloque entre colchetes as declarações de classe (localizadas no arquivo .h) com o seguinte código:

#undef AFX_API
#define AFX_API AFX_EXT_CLASS

// <your class declarations here>

#undef AFX_API
#define AFX_API

Para mais informações, confira a Tópicos da classe CObject.

Exemplo

IMPLEMENT_SERIAL(CAge, CObject, VERSIONABLE_SCHEMA | 2)

Requisitos

Cabeçalho: afx.h

RUNTIME_CLASS

Obtém a estrutura de classe em tempo de execução do nome de uma classe C++.

RUNTIME_CLASS(class_name)

Parâmetros

class_name
O nome real da classe (não entre aspas).

Comentários

RUNTIME_CLASS retorna um ponteiro para uma estrutura CRuntimeClass para a classe especificada por class_name. Somente classes derivadas de CObjectdeclaradas com DECLARE_DYNAMIC, DECLARE_DYNCREATE ou DECLARE_SERIAL retornarão ponteiros para uma estrutura CRuntimeClass.

Para mais informações, confira Tópicos da Classe CObject.

Exemplo

CRuntimeClass* prt = RUNTIME_CLASS(CAge);
ASSERT(strcmp(prt->m_lpszClassName, "CAge") == 0);

Requisitos

Cabeçalho: afx.h

DECLARE_OLECREATE

Permite que objetos de classes derivadas de CCmdTarget sejam criados por meio da automação OLE.

DECLARE_OLECREATE(class_name)

Parâmetros

class_name
O nome real da classe.

Comentários

Essa macro permite que outros aplicativos habilitados para OLE criem objetos desse tipo.

Adicione a macro DECLARE_OLECREATE ao módulo .h para a classe e inclua esse módulo em todos os módulos .cpp que precisam de acesso a objetos dessa classe.

Se DECLARE_OLECREATE estiver incluído na declaração de classe, IMPLEMENT_OLECREATE deverá ser incluído na implementação da classe. Uma declaração de classe usando DECLARE_OLECREATE também deve usar DECLARE_DYNCREATE ou DECLARE_SERIAL.

Requisitos

Cabeçalho: afxdisp.h

IMPLEMENT_OLECREATE

Essa macro ou IMPLEMENT_OLECREATE_FLAGS deve aparecer no arquivo de implementação para qualquer classe que use DECLARE_OLECREATE.

IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)

Parâmetros

class_name
O nome real da classe.

external_name
O nome do objeto exposto a outros aplicativos (entre aspas).

Componentes l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8 da CLSID da classe.

Comentários

Observação

Se você usar IMPLEMENT_OLECREATE, por padrão, dará suporte apenas ao modelo de threading simples. Se você usar IMPLEMENT_OLECREATE_FLAGS, poderá especificar a qual modelo de threading seu objeto dá suporte usando o parâmetro nFlags.

O nome externo é o identificador exposto a outros aplicativos. Os aplicativos cliente usam o nome externo para solicitar um objeto dessa classe de um servidor de automação.

A ID da classe OLE é um identificador exclusivo de 128 bits para o objeto. Ela consiste em um long, dois **WORD**s e oito **BYTE**s, conforme representado por l, w1, w2 e b1 a b8 na descrição da sintaxe. O Assistente de Aplicativo e os assistentes de código criam IDs de classe OLE exclusivas para você, conforme necessário.

Requisitos

Cabeçalho: afxdisp.h

Confira também

Macros e Globais
Isolamento da biblioteca de controles comuns MFC
Chave CLSID