Partilhar via

Macros e funções para gerenciar DLLs

  • Artigo
Nome Descrição
AFX_EXT_CLASS] Exporta classes.
AFX_MANAGE_STATE Proteja uma função exportada em uma DLL.
AfxOleInitModule Fornece suporte OLE de uma DLL MFC regular que está vinculada dinamicamente ao MFC.
AfxNetInitModule Fornece suporte a Soquetes MFC de uma DLL MFC regular que está vinculada dinamicamente ao MFC.
AfxGetAmbientActCtx Obtém o estado atual do sinalizador de estado por módulo.
AfxGetStaticModuleState Define o estado do módulo antes da inicialização e restaura o estado do módulo anterior após a limpeza.
AfxInitExtensionModule Inicializa a DLL.
AfxSetAmbientActCtx Defina o sinalizador de estado por módulo, que afeta o comportamento de WinSxS do MFC.
AfxTermExtensionModule Permite que o MFC limpe a DLL da extensão MFC quando cada processo se desanexa da DLL.

AFX_EXT_CLASS

As DLLs de extensão de MFC usam a macro AFX_EXT_CLASS para exportar classes; os executáveis que vinculam à DLL de extensão de MFC usam a macro para importar classes.

Comentários

Com a macro AFX_EXT_CLASS, os mesmos arquivos de cabeçalho usados para criar a DLL da extensão de MFC podem ser usados com os executáveis que se vinculam à DLL.

No arquivo de cabeçalho da DLL, adicione a palavra-chave AFX_EXT_CLASS à declaração da classe da seguinte maneira:

class AFX_EXT_CLASS CMyClass : public CDocument
{
// <body of class>
};

Para obter mais informações, confira Exportar e importar usando AFX_EXT_CLASS.

Requisitos

Header:<afxv_dll.h>

AFX_MANAGE_STATE

Chame essa macro para proteger uma função exportada em uma DLL.

Sintaxe

AFX_MANAGE_STATE(AFX_MODULE_STATE* pModuleState )

Parâmetros

pModuleState
Um ponteiro para uma estrutura AFX_MODULE_STATE.

Comentários

Quando essa macro é invocada, pModuleState é o estado efetivo do módulo para o restante do escopo de contenção imediato. Ao sair do escopo, o estado do módulo efetivo anterior será restaurado automaticamente.

A estrutura AFX_MODULE_STATE contém dados globais para o módulo, ou seja, a parte do estado do módulo cujo push é efetuado ou que é removida mais recente da pilha.

Por padrão, o MFC usa o identificador de recurso do aplicativo principal para carregar o modelo de recurso. Se você tiver uma função exportada em uma DLL, como uma que inicia uma caixa de diálogo na DLL, o modelo de recurso será armazenado no módulo de DLL. Alterne o estado do módulo para que o identificador correto seja usado. Você pode alternar o estado adicionando o seguinte código ao início da função:

AFX_MANAGE_STATE(AfxGetStaticModuleState( ));

Essa macro troca o estado do módulo atual pelo estado retornado de AfxGetStaticModuleState até o final do escopo atual.

Para obter mais informações sobre estados de módulo e o MFC, consulte Gerenciando os dados de estado dos módulos MFC e Nota técnica 58.

Observação

Quando o MFC cria um contexto de ativação para um assembly, ele usa AfxWinInit para criar o contexto e AFX_MANAGE_STATE para ativá-lo e desativá-lo. Observe também que AFX_MANAGE_STATE está habilitado para bibliotecas MFC estáticas, bem como DLLs de MFC, a fim de permitir que o código MFC seja executado no contexto de ativação adequado selecionado pela DLL do usuário. Para obter mais informações, consulte Suporte para contextos de ativação no estado do módulo MFC.

Requisitos

Header:<afxstat_.h>

AfxOleInitModule

Para o suporte OLE de uma DLL de MFC regular que esteja vinculada dinamicamente ao MFC, chame essa função na função CWinApp::InitInstance da DLL de MFC regular para inicializar a DLL OLE de MFC.

Sintaxe

void AFXAPI AfxOleInitModule( );

Comentários

A DLL OLE de MFC é uma DLL de extensão MFC; para que uma DLL de extensão MFC seja conectada a uma cadeia CDynLinkLibrary, ela deve criar um objeto CDynLinkLibrary no contexto de cada módulo que o usará. AfxOleInitModule cria o objeto CDynLinkLibrary no contexto da DLL de MFC regular para que ela seja conectada à cadeia de objetos CDynLinkLibrary da DLL de MFC regular.

Se estiver criando um controle OLE e usando COleControlModule, você não deverá chamar AfxOleInitModule porque a função de membro InitInstance para COleControlModule chama AfxOleInitModule.

Requisitos

Cabeçalho: <afxdll_.h>

AfxNetInitModule

Para suporte a Soquetes MFC de uma DLL MFC regular que esteja dinamicamente vinculada ao MFC, adicione uma chamada a essa função na função CWinApp::InitInstance da DLL de MFC regular para inicializar a DLL de Soquetes MFC.

Sintaxe

void AFXAPI AfxNetInitModule( );

Comentários

A DLL de Soquetes MFC é uma DLL de extensão MFC; para que uma DLL de extensão MFC seja conectada a uma cadeia CDynLinkLibrary, ela deve criar um objeto CDynLinkLibrary no contexto de cada módulo que o usará. AfxNetInitModule cria o objeto CDynLinkLibrary no contexto da DLL de MFC regular para que ela seja conectada à cadeia de objetos CDynLinkLibrary da DLL de MFC regular.

Requisitos

Header:<afxdll_.h>

AfxGetAmbientActCtx

Use essa função para obter o estado atual do sinalizador de estado por módulo, o que afeta o comportamento de WinSxS do MFC.

Sintaxe

BOOL AFXAPI AfxGetAmbientActCtx();

Valor retornado

Valor atual do sinalizador de estado do módulo.

Comentários

Quando o sinalizador é definido (que é o padrão) e um thread entra em um módulo de MFC (consulte AFX_MANAGE_STATE), o contexto do módulo é ativado.

Se o sinalizador não estiver definido, o contexto do módulo não será ativado na entrada.

O contexto de um módulo é determinado a partir de seu manifesto, geralmente inserido em recursos de módulo.

Requisitos

Header:<afxcomctl32.h>

AfxGetStaticModuleState

Chame essa função para definir o estado do módulo antes da inicialização e restaurar o estado do módulo anterior após a limpeza.

Sintaxe

AFX_MODULE_STATE* AFXAPI AfxGetStaticModuleState( );

Valor retornado

Um ponteiro para uma estrutura AFX_MODULE_STATE.

Comentários

A estrutura AFX_MODULE_STATE contém dados globais para o módulo, ou seja, a parte do estado do módulo cujo push é efetuado ou que é removida mais recente da pilha.

Por padrão, o MFC usa o identificador de recurso do aplicativo principal para carregar o modelo de recurso. Se você tiver uma função exportada em uma DLL, como uma que inicia uma caixa de diálogo na DLL, o modelo de recurso será armazenado no módulo de DLL. Alterne o estado do módulo para que o identificador correto seja usado. Você pode alternar o estado adicionando o seguinte código ao início da função:

AFX_MANAGE_STATE(AfxGetStaticModuleState( ));

Essa macro troca o estado do módulo atual pelo estado retornado de AfxGetStaticModuleState até o final do escopo atual.

Para obter mais informações sobre estados de módulo e o MFC, consulte Gerenciando os dados de estado dos módulos MFC e Nota técnica 58.

Requisitos

Header:<afxstat_.h>

AfxInitExtensionModule

Chame essa função em um DllMain da DLL de extensão de MFC para inicializar a DLL.

Sintaxe

BOOL AFXAPI AfxInitExtensionModule( AFX_EXTENSION_MODULE& state,  HMODULE hModule );

Parâmetros

state
Uma referência à estrutura AFX_EXTENSION_MODULEStructure que conterá o estado do módulo de DLL da extensão de MFC após a inicialização. O estado inclui uma cópia dos objetos de classe de runtime que foram inicializados pela DLL de extensão de MFC como parte da construção de objeto estático normal executada antes da inserção de DllMain.

hModule
Um identificador do módulo DLL de extensão de MFC.

Valor de retorno

TRUE se a DLL da extensão de MFC for inicializada com êxito; caso contrário, FALSE.

Comentários

Por exemplo:

static AFX_EXTENSION_MODULE NVC_MFC_DLLDLL;
extern "C" int APIENTRY
DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved)
{
    // Remove this if you use lpReserved
    UNREFERENCED_PARAMETER(lpReserved);

    if (dwReason == DLL_PROCESS_ATTACH)
    {
        TRACE0("NVC_MFC_DLL.DLL Initializing!\n");

        // MFC extension DLL one-time initialization
        if (!AfxInitExtensionModule(NVC_MFC_DLLDLL, hInstance))
            return 0;
...

AfxInitExtensionModule faz uma cópia do HMODULE da DLL e captura as classes de runtime da DLL (estruturas CRuntimeClass) e também suas fábricas de objetos (objetos COleObjectFactory) para uso posteriormente quando o objeto CDynLinkLibrary é criado. As DLLs de extensão do MFC precisam fazer duas coisas em sua função DllMain:

Você pode chamar AfxTermExtensionModule para limpar a DLL de extensão de MFC quando cada processo é desanexado da DLL de extensão de MFC (o que acontece quando o processo é encerrado ou quando a DLL é descarregada por uma chamada AfxFreeLibrary).

Requisitos

Header:<afxdll_.h>

AfxSetAmbientActCtx

Use esta função para definir o sinalizador de estado por módulo, que afeta o comportamento de WinSxS do MFC.

Sintaxe

void AFXAPI AfxSetAmbientActCtx(BOOL bSet);

Parâmetros

bSet
Novo valor do sinalizador de estado do módulo.

Comentários

Quando o sinalizador é definido (que é o padrão) e um thread entra em um módulo de MFC (consulte AFX_MANAGE_STATE), o contexto do módulo é ativado. Se o sinalizador não estiver definido, o contexto do módulo não será ativado na entrada. O contexto de um módulo é determinado a partir de seu manifesto, geralmente inserido em recursos de módulo.

Exemplo

BOOL CMFCListViewApp::InitInstance()
{
   AfxSetAmbientActCtx(FALSE);
   // Remainder of function definition omitted.
}

Requisitos

Header:<afxcomctl32.h>

AfxTermExtensionModule

Chame essa função para permitir que o MFC limpe a DLL de extensão de MFC quando cada processo for desanexado da DLL (o que acontece quando o processo é encerrado ou quando a DLL é descarregada por uma chamada AfxFreeLibrary).

Sintaxe

void AFXAPI AfxTermExtensionModule( AFX_EXTENSION_MODULE& state, BOOL bAll = FALSE );

Parâmetros

state
Uma referência à estrutura AFX_EXTENSION_MODULE que contém o estado do módulo DLL da extensão de MFC.

bAll
Se TRUE, limpe todos os módulos da DLL de extensão de MFC. Caso contrário, limpe apenas o módulo da DLL atual.

Comentários

AfxTermExtensionModule excluirá qualquer armazenamento local anexado ao módulo e removerá todas as entradas do cache de mapa de mensagens. Por exemplo:

static AFX_EXTENSION_MODULE NVC_MFC_DLLDLL;
extern "C" int APIENTRY
DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved)
{
    // Remove this if you use lpReserved
    UNREFERENCED_PARAMETER(lpReserved);

    if (dwReason == DLL_PROCESS_ATTACH)
    {
        TRACE0("NVC_MFC_DLL.DLL Initializing!\n");

        // MFC extension DLL one-time initialization
        if (!AfxInitExtensionModule(NVC_MFC_DLLDLL, hInstance))
            return 0;

        new CMyDynLinkLibrary(NVC_MFC_DLLDLL);

    }
    else if (dwReason == DLL_PROCESS_DETACH)
    {
        TRACE0("NVC_MFC_DLL.DLL Terminating!\n");

        // Terminate the library before destructors are called
        AfxTermExtensionModule(NVC_MFC_DLLDLL);
    }
    return 1;   // ok
}

Se o aplicativo carregar e liberar DLLs de extensão de MFC dinamicamente, certifique-se de chamar AfxTermExtensionModule. Como a maioria das DLLs de extensão de MFC não são carregadas dinamicamente (normalmente, elas são vinculadas por meio de suas bibliotecas de importação), a chamada para AfxTermExtensionModule geralmente não é necessária.

As DLLs de extensão de MFC precisam chamar AfxInitExtensionModule em seu DllMain. Se a DLL exportar objetos CRuntimeClass ou tiver seus próprios recursos personalizados, você também precisará criar um objeto CDynLinkLibrary em DllMain.

Requisitos

Header:<afxdll_.h>

Confira também

Macros e globais
AfxMessageBox
Gerenciando os dados de estado dos módulos MFC