Informações e gerenciamento do aplicativo

Artigo
10/12/2023

Ao escrever um aplicativo, você cria um único objeto derivado CWinApp. Às vezes, talvez você queira obter informações sobre esse objeto de fora do objeto derivado CWinApp. Ou talvez você precise de acesso a outros objetos globais de "gerente".

A biblioteca Microsoft Foundation Class fornece as funções globais a seguir para ajudá-lo a realizar essas tarefas:

Funções de informações e gerenciamento do aplicativo

Nome	Descrição
`AfxBeginThread`	Cria um novo thread.
`AfxContextMenuManager`	Ponteiro para o gerenciador de menus de contexto global.
`AfxEndThread`	Encerra o thread atual.
`AfxFindResourceHandle`	Percorre a cadeia de recursos e localiza um recurso específico por ID de recurso e tipo de recurso.
`AfxFreeLibrary`	Diminui a contagem de referência do módulo DLL (biblioteca de vínculo dinâmico) carregado. Quando a contagem de referências atinge zero, o módulo é não mapeado.
`AfxGetApp`	Retorna um ponteiro para o único objeto `CWinApp` do aplicativo.
`AfxGetAppName`	Retorna uma cadeia de caracteres que contém o nome do aplicativo.
`AfxGetInstanceHandle`	Retorna um `HINSTANCE` representando essa instância do aplicativo.
`AfxGetMainWnd`	Retorna um ponteiro para a janela "principal" atual de um aplicativo não OLE ou a janela de quadro in-loco de um aplicativo de servidor.
`AfxGetPerUserRegistration`	Use essa função para determinar se o aplicativo redireciona o acesso do Registro ao nó `HKEY_CURRENT_USER` (`HKCU`).
`AfxGetResourceHandle`	Retorna uma `HINSTANCE` para a fonte dos recursos padrão do aplicativo. Use para acessar diretamente os recursos do aplicativo.
`AfxGetThread`	Recupera um ponteiro para o objeto CWinThread atual.
`AfxInitRichEdit`	Inicializa o controle de edição avançada da versão 1.0 para o aplicativo.
`AfxInitRichEdit2`	Inicializa o controle de edição avançada da versão 2.0 e posterior para o aplicativo.
`AfxIsExtendedFrameClass`	Determina se a janela fornecida é um objeto de quadro estendido.
`AfxIsMFCToolBar`	Determina se a janela fornecida é um objeto de barra de ferramentas.
`AfxKeyboardManager`	Ponteiro para o gerenciador de teclado global.
`AfxLoadLibrary`	Mapeia um módulo DLL e retorna um identificador que pode ser usado para obter o endereço de uma função DLL.
`AfxLoadLibraryEx`	Mapeia um módulo DLL usando as opções especificadas e retorna um identificador que pode ser usado para obter o endereço de uma função DLL.
`AfxMenuTearOffManager`	Ponteiro para o gerenciador de menus destacáveis global.
`AfxMouseManager`	Ponteiro para o gerenciador de mouses global.
`AfxRegisterClass`	Registra uma classe de janela em uma DLL que usa MFC.
`AfxRegisterWndClass`	Registra uma classe de janela do Windows para complementar as janelas registradas automaticamente pelo MFC.
`AfxSetPerUserRegistration`	Define se o aplicativo redireciona o acesso ao Registro para o nó `HKEY_CURRENT_USER` (`HKCU`).
`AfxSetResourceHandle`	Define o identificador HINSTANCE em que os recursos padrão do aplicativo são carregados.
`AfxShellManager`	Ponteiro para o gerenciador de shells global.
`AfxSocketInit`	Chamado em uma substituição de `CWinApp::InitInstance` para inicializar o Windows Sockets.
`AfxUserToolsManager`	Ponteiro para o gerenciador de ferramentas de usuário global.
`AfxWinInit`	Chamado pela função `WinMain` fornecida pelo MFC, como parte da inicialização de `CWinApp` de um aplicativo baseado em GUI, para inicializar o MFC. Deve ser chamado diretamente para aplicativos de console que usam MFC.

`AfxBeginThread`

Chame essa função para criar um novo thread.

CWinThread* AfxBeginThread(
    AFX_THREADPROC pfnThreadProc,
    LPVOID pParam,
    int nPriority = THREAD_PRIORITY_NORMAL,
    UINT nStackSize = 0,
    DWORD dwCreateFlags = 0,
    LPSECURITY_ATTRIBUTES lpSecurityAttrs = NULL);

CWinThread* AfxBeginThread(
    CRuntimeClass* pThreadClass,
    int nPriority = THREAD_PRIORITY_NORMAL,
    UINT nStackSize = 0,
    DWORD dwCreateFlags = 0,
    LPSECURITY_ATTRIBUTES lpSecurityAttrs = NULL);

Parâmetros

pfnThreadProc
Aponta para a função de controle para o thread de trabalho. O ponteiro não pode ser NULL. Essa função deve ser declarada da seguinte maneira:

UINT __cdecl MyControllingFunction( LPVOID pParam );

pThreadClass
O RUNTIME_CLASS de um objeto derivado de CWinThread.

pParam
Parâmetro a ser passado para a função de controle.

nPriority
A prioridade a ser definida para o thread. Para obter uma lista completa e uma descrição das prioridades disponíveis, consulte SetThreadPriority no SDK do Windows.

nStackSize
Especifica o tamanho em bytes da pilha para o novo thread. Se for 0, o tamanho da pilha será padronizado com o mesma tamanho da pilha que o thread de criação.

dwCreateFlags
Especifica um sinalizador adicional que controla a criação do thread. Esse sinalizador pode conter um de dois valores:

CREATE_SUSPENDED Iniciar o thread com um suspender contagem de um. Use CREATE_SUSPENDED se quiser inicializar os dados de membro do objeto CWinThread, como m_bAutoDelete ou qualquer membro da classe derivada, antes que o thread comece a ser executado. Depois que a inicialização for concluída, use CWinThread::ResumeThread para iniciar a execução do thread. O thread não será executado até CWinThread::ResumeThread que seja chamado.
0 Inicie o thread imediatamente após a criação.

lpSecurityAttrs
Aponta para uma estrutura SECURITY_ATTRIBUTES que especifica os atributos de segurança do thread. Se NULL, os mesmos atributos de segurança que o thread de criação são usados. Para obter mais informações sobre essa estrutura, confira o SDK do Windows.

Valor de Devolução

Ponteiro para o objeto thread recém-criado ou NULL, se ocorrer uma falha.

Comentários

A primeira forma de AfxBeginThread cria um thread de trabalho. A segunda forma cria um thread que pode servir como um thread de interface do usuário ou como um thread de trabalho.

AfxBeginThread cria um novo objeto CWinThread, chama sua função CreateThread para começar a executar o thread e retorna um ponteiro para o thread. São feitas verificações em todo o procedimento para garantir que todos os objetos sejam desalocados corretamente caso qualquer parte da criação falhe. Para encerrar o thread, chame AfxEndThread de dentro do thread ou retorne da função de controle do thread de trabalho.

O multithreading deve estar habilitado pelo aplicativo; caso contrário, essa função falhará. Para obter mais informações sobre como habilitar o multithreading, consulte /MD, /MT, /LD (Usar biblioteca em tempo de execução).

Para obter mais informações sobre AfxBeginThread, consulte os artigos Multithread: criando threads de trabalho e Multithread: criando threads de interface do usuário.

Exemplo

Confira o exemplo de CSocket::Attach.

Requisitos

Cabeçalhoafxwin.h

`AfxContextMenuManager`

Ponteiro para o gerenciador de menus de contexto global.

Sintaxe

CContextMenuManager* afxContextMenuManager;

Requisitos

Cabeçalhoafxcontextmenumanager.h:

`AfxEndThread`

Chame essa função para terminar o thread em execução no momento.

void AFXAPI AfxEndThread(
    UINT nExitCode,
    BOOL bDelete  = TRUE);

Parâmetros

nExitCode
Especifica o código de saída do thread.

bDelete
Exclui o objeto thread da memória.

Comentários

Deve ser chamado de dentro do thread a ser encerrado.

Para obter mais informações sobre AfxEndThread, consulte o artigo Multithread: encerrando threads.

Requisitos

Cabeçalhoafxwin.h

`AfxFindResourceHandle`

Use AfxFindResourceHandle para percorrer a cadeia de recursos e localizar um recurso específico por ID de recurso e tipo de recurso.

Sintaxe

HINSTANCE AFXAPI AfxFindResourceHandle( LPCTSTR lpszName,  LPCTSTR lpszType );

Parâmetros

lpszName
Um ponteiro para uma cadeia de caracteres que contém a ID do recurso. lpszType
Um ponteiro para o tipo de recurso. Para obter uma lista de tipos de recursos, consulte FindResource no SDK do Windows.

Valor de Devolução

Um identificador do módulo que contém o recurso.

Comentários

AfxFindResourceHandle localiza o recurso específico e retorna um identificador para o módulo que contém o recurso. O recurso pode estar em qualquer DLL de extensão MFC carregada. AfxFindResourceHandle informa qual delas tem o recurso.

Os módulos são pesquisados nesta ordem:

O módulo principal, se for uma DLL de extensão MFC.
Módulos que não são do sistema.
Módulos específicos da linguagem.
O módulo principal, se for uma DLL do sistema.
Módulos do sistema.

Requisitos

Cabeçalhoafxwin.h:

`AfxFreeLibrary`

AfxFreeLibrary e AfxLoadLibrary mantêm uma contagem de referência para cada módulo de biblioteca carregada.

BOOL AFXAPI AfxFreeLibrary(HINSTANCE hInstLib);

Parâmetros

hInstLib
Um identificador do módulo de biblioteca carregada. AfxLoadLibrary retorna esse identificador.

Valor de Devolução

TRUE se a função for bem-sucedida; caso contrário, FALSE.

Comentários

AfxFreeLibrary diminui a contagem de referência do módulo DLL (biblioteca de vínculo dinâmico) carregado. Quando a contagem de referência atinge zero, o módulo torna-se desmapeado do espaço de endereço do processo de chamada e o identificador deixa de ser válido. Essa contagem de referência é incrementada a cada vez que AfxLoadLibrary é chamada.

Antes de descompactar um módulo de biblioteca, o sistema permite que a DLL se desanexe dos processos que a usam. Isso dá à DLL a oportunidade de limpar os recursos alocados para o processo atual. Depois que a função de ponto de entrada é retornada, o módulo de biblioteca é removido do espaço de endereço do processo atual.

Use AfxLoadLibrary para mapear um módulo DLL.

Certifique-se de usar AfxFreeLibrary e AfxLoadLibrary (em vez das funções FreeLibrary e LoadLibrary do Win32) se o aplicativo usar vários threads. Usar AfxLoadLibrary e AfxFreeLibrary garante que o código de inicialização e desligamento executado quando a DLL da extensão MFC é carregada e descarregada não corrompa o estado MFC global.

Exemplo

Confira o exemplo de AfxLoadLibrary.

Requisitos

Cabeçalhoafxdll_.h

`AfxGetApp`

O ponteiro retornado por essa função pode ser usado para acessar informações do aplicativo, como o código principal de envio de mensagens ou a janela superior.

CWinApp* AFXAPI AfxGetApp();

Valor de Devolução

Um ponteiro para o único objeto CWinApp para o aplicativo.

Comentários

Se esse método retornar NULL, poderá indicar que a janela principal do aplicativo ainda não foi totalmente inicializada. Também pode indicar um problema.

Exemplo

// Print the application's executable filename.
TRACE(_T("Executable filename = %s\n"), AfxGetApp()->m_pszExeName);

Requisitos

Cabeçalhoafxwin.h

`AfxGetAppName`

A cadeia de caracteres retornada pode ser usada para mensagens de diagnóstico ou como uma raiz para nomes temporários de cadeia de caracteres.

LPCTSTR AFXAPI AfxGetAppName();

Valor de Devolução

Uma cadeia de caracteres terminada em nulo que contém o nome do aplicativo.

Exemplo

// Print the application name to the debugger output window.
TRACE(_T("Application name is %s\n"), AfxGetAppName());

Requisitos

Cabeçalhoafxwin.h

`AfxGetInstanceHandle`

Essa função permite recuperar o identificador de instância do aplicativo atual.

HINSTANCE  AFXAPI AfxGetInstanceHandle();

Valor de Devolução

Uma HINSTANCE para a instância atual do aplicativo. Se for chamada de dentro de uma DLL vinculada à versão USRDLL do MFC, será retornada uma HINSTANCE para a DLL.

Comentários

AfxGetInstanceHandle sempre retorna o HINSTANCE do arquivo executável (.EXE), a menos que seja chamado de dentro de uma DLL vinculada à versão USRDLL do MFC. Nesse caso, ele retorna uma HINSTANCE para a DLL.

Exemplo

// Print the application instance handle to the debugger output window.
TRACE(_T("Application instance handle is 0x%0X\n"), AfxGetInstanceHandle());

Requisitos

Cabeçalhoafxwin.h

`AfxGetMainWnd`

Se o aplicativo for um servidor OLE, chame essa função para recuperar um ponteiro para a janela principal ativa do aplicativo. Use esse resultado em vez de fazer referência direta ao membro m_pMainWnd do objeto do aplicativo.

CWnd* AFXAPI AfxGetMainWnd();

Valor de Devolução

Retorna um ponteiro para o objeto de janela de quadro que contém o documento ativo in-loco, se o servidor tiver um objeto ativo no local dentro de um contêiner ativo.

Se não houver nenhum objeto ativo no local dentro de um contêiner ou seu aplicativo não for um servidor OLE, essa função retornará o m_pMainWnd do objeto do aplicativo.

Se AfxGetMainWnd for chamado do thread primário do aplicativo, ele retornará a janela principal do aplicativo de acordo com as regras acima. Se a função for chamada de um thread secundário no aplicativo, a função retornará a janela principal associada ao thread que fez a chamada.

Comentários

Se o aplicativo não for um servidor OLE, chamar essa função será equivalente a fazer referência direta ao membro m_pMainWnd do objeto do aplicativo.

Exemplo

//The following line send a WM_CLOSE message
//   to the Application's main window. This will cause the
//   Application to exit.
AfxGetMainWnd()->PostMessage(WM_CLOSE, 0, 0);

Requisitos

Cabeçalhoafxwin.h

`AfxGetPerUserRegistration`

Use essa função para determinar se o aplicativo redireciona o acesso do Registro ao nó HKEY_CURRENT_USER (HKCU).

BOOL AFXAPI AfxGetPerUserRegistration();

Valor de Devolução

TRUE indica que as informações do Registro são direcionadas para o nó HKCU. FALSE indica que o aplicativo grava informações do Registro no nó padrão. O nó padrão é HKEY_CLASSES_ROOT (HKCR).

Comentários

Se você habilitar o redirecionamento do Registro, a estrutura redirecionará o acesso de HKCR para HKEY_CURRENT_USER\Software\Classes. Somente as estruturas MFC e ATL são afetadas por esse redirecionamento.

Para alterar se o aplicativo redireciona o acesso ao Registro, use AfxSetPerUserRegistration.

Requisitos

Cabeçalhoafxstat_.h

`AfxGetResourceHandle`

Use o identificador HINSTANCE retornado por essa função para acessar diretamente os recursos do aplicativo, por exemplo, em chamadas para a função FindResource do Windows.

extern HINSTANCE  AfxGetResourceHandle();

Valor de Devolução

Um identificador HINSTANCE em que os recursos padrão do aplicativo são carregados.

Exemplo

//Load the menu specifying the module handle where resource is to be
//found & resource ID
HMENU hMenu = ::LoadMenu(AfxGetResourceHandle(), MAKEINTRESOURCE(IDR_MAINFRAME));

Requisitos

Cabeçalhoafxwin.h

`AfxGetThread`

Chame essa função para obter um ponteiro para o objeto CWinThread que representa o thread em execução no momento.

CWinThread* AfxGetThread();

Valor de Devolução

O ponteiro para o thread em execução no momento, caso contrário, NULL.

Comentários

Deve ser chamada de dentro do thread.

Observação

Se você estiver fazendo a portabilidade de um projeto MFC que chama AfxGetThread do Visual C++ versões 4.2, 5.0 ou 6.0, AfxGetThread chamará AfxGetApp se nenhum thread for encontrado. Em versões mais recentes do compilador, AfxGetThread retornará NULL se nenhum thread foi encontrado. Se você quiser o thread do aplicativo, deverá chamar AfxGetApp.

Exemplo

//Print the current thread ID in the Debug Window
TRACE(_T("Current Thread ID = 0x%X\n"), AfxGetThread()->m_nThreadID);

Requisitos

Cabeçalhoafxwin.h

`AfxInitRichEdit`

Chame essa função para inicializar o controle de edição avançada (versão 1.0) para o aplicativo.

BOOL AFXAPI AfxInitRichEdit();

Comentários

Essa função é fornecida para fins de compatibilidade com versões anteriores. Os novos aplicativos devem usar AfxInitRichEdit2.

AfxInitRichEdit carrega RICHED32.DLL para inicializar a versão 1.0 do controle de edição avançada. Para usar as versões 2.0 e 3.0 do controle de edição avançada, é necessário carregar RICHED20.DLL. Ele é carregado fazendo uma chamada para AfxInitRichEdit2.

Para atualizar controles de edição avançada em aplicativos do Visual C++ existentes para a versão 2.0, abra o arquivo .RC como texto, altere o nome da classe de cada controle de edição avançada de "RICHEDIT" para "RichEdit20a". Em seguida, substitua a chamada para AfxInitRichEdit por AfxInitRichEdit2.

Essa função também inicializa a biblioteca de controles comuns, se a biblioteca ainda não tiver sido inicializada para o processo. Se você usar o controle de edição avançada diretamente do aplicativo MFC, chame essa função para garantir que o MFC inicialize corretamente o runtime de controle de edição avançada. Se você chamar o método Create de CRichEditCtrl, CRichEditView ou CRichEditDoc, normalmente não precisa chamar essa função, mas em alguns casos pode ser necessário.

Requisitos

Cabeçalhoafxwin.h

`AfxInitRichEdit2`

Chame essa função para inicializar o controle de edição avançada (versão 2.0 e posterior) para o aplicativo.

BOOL AFXAPI AfxInitRichEdit2();

Comentários

Chame essa função para carregar a RICHED20.DLL e inicializar a versão 2.0 do controle de edição avançada. Se você chamar o método Create de CRichEditCtrl, CRichEditView ou CRichEditDoc, normalmente não precisa chamar essa função, mas em alguns casos pode ser necessário.

Requisitos

Cabeçalhoafxwin.h

`AfxIsExtendedFrameClass`

Determina se a janela fornecida é um objeto de quadro estendido.

Sintaxe

BOOL AFXAPI AfxIsExtendedFrameClass( CWnd* pWnd );

Parâmetros

pWnd
[in] Um ponteiro para um objeto que é derivado da CWnd.

Valor de Devolução

TRUE, se a janela fornecida for um objeto de quadro estendido; caso contrário FALSE.

Comentários

Esse método retornará TRUE se pWnd derivar de uma das classes a seguir:

CFrameWndEx
CMDIFrameWndEx
COleIPFrameWndEx
COleDocIPFrameWndEx
CMDIChildWndEx

Esse método é útil quando você precisa validar que um parâmetro de função ou de método é uma janela de quadro estendido.

Requisitos

Cabeçalhoafxpriv.h:

`AfxIsMFCToolBar`

Determina se a janela fornecida é um objeto de barra de ferramentas.

Sintaxe

BOOL AFXAPI AfxIsMFCToolBar(CWnd* pWnd);

Parâmetros

pWnd
[in] Um ponteiro para um objeto que é derivado da CWnd.

Valor de Devolução

TRUE, se a janela fornecida for um objeto de barra de ferramentas; caso contrário FALSE.

Comentários

Esse método retornará TRUE se pWnd derivar de CMFCToolBar. Esse método é útil quando você precisa validar que um parâmetro de função ou método é um objeto CMFCToolBar.

Requisitos

Cabeçalhoafxpriv.h:

`AfxKeyboardManager`

Ponteiro para o gerenciador de teclado global.

Sintaxe

CKeyboardManager* afxKeyboardManager;

Requisitos

Cabeçalhoafxkeyboardmanager.h:

`AfxLoadLibrary`

Use AfxLoadLibrary para mapear um módulo DLL.

HINSTANCE AFXAPI AfxLoadLibrary(LPCTSTR lpszModuleName);

Parâmetros

lpszModuleName
Aponta para uma cadeia de caracteres terminada em nulo que contém o nome do módulo (um arquivo .DLL ou .EXE). O nome especificado é o nome do arquivo do módulo.

Se a cadeia de caracteres especificar um caminho, mas o arquivo não existir no diretório especificado, a função falhará.

Se um caminho não for especificado e a extensão de nome de arquivo for omitida, será acrescentada a extensão padrão .DLL. No entanto, a cadeia de caracteres de nome de arquivo pode incluir um caractere de ponto à direita (.) para indicar que o nome do módulo não tem extensão. Quando nenhum caminho é especificado, a função usa o Pedido de Pesquisa para Aplicativos da Área de Trabalho.

Valor de Devolução

Se a função obtiver êxito, o valor retornado será um identificador para o módulo. Em caso de falha, o valor retornado será NULL.

Comentários

Retorna um identificador que pode ser usado em GetProcAddress para obter o endereço de uma função DLL. AfxLoadLibrary também pode ser usada para mapear outros módulos executáveis.

Cada processo mantém uma contagem de referência para cada módulo de biblioteca carregado. Essa contagem de referência é incrementada a cada vez que AfxLoadLibrary é chamada e é decrementada sempre que AfxFreeLibrary é chamada. Quando a contagem de referência atinge zero, o módulo torna-se desmapeado do espaço de endereço do processo de chamada e o identificador deixa de ser válido.

Certifique-se de usar AfxLoadLibrary e AfxFreeLibrary (em vez das funções LoadLibrary e FreeLibrary do Win32) se o aplicativo usar vários threads e se ele carregar dinamicamente uma DLL de extensão MFC. Usar AfxLoadLibrary e AfxFreeLibrary garante que o código de inicialização e desligamento executado quando a DLL da extensão MFC é carregada e descarregada não corrompa o estado MFC global.

Usar AfxLoadLibrary em um aplicativo exige que você vincule dinamicamente à versão DLL do MFC. O arquivo de cabeçalho para AfxLoadLibrary, Afxdll_.h, só será incluído se o MFC estiver vinculado ao aplicativo como uma DLL. Esse requisito é por design, porque você precisa vincular à versão DLL do MFC para usar ou criar DLLs de extensão MFC.

Exemplo

// The following shows how to create a MDI based application
// using a generic CView derived class that is implemented in
// a dynamically loaded MFC Extension DLL.

typedef CRuntimeClass *(*GETDLLVIEW)();

BOOL CUserApp::InitInstance()
{
   // Standard Application Wizard generated initialization excluded.

// Register the application's document templates.  Document templates
//  serve as the connection between documents, frame windows and views

//Load MFC Extension DLL based view class.
m_hViewDll = AfxLoadLibrary(szMyViewDllPath);
if (!m_hViewDll)
{
   CString str;
   str.Format(_T("Error: Cannot find component %s"), szMyViewDllPath);
   AfxMessageBox(str);
   return FALSE;
}

GETDLLVIEW GetMyView = (GETDLLVIEW)GetProcAddress(m_hViewDll, "GetMyView");
ASSERT(GetMyView != NULL);

CMultiDocTemplate *pDocTemplate;
pDocTemplate = new CMultiDocTemplate(IDR_NVC_MFC_DLLUserTYPE,
                                     RUNTIME_CLASS(CUserDoc),
                                     RUNTIME_CLASS(CChildFrame), // custom MDI child frame
                                     GetMyView());
if (!pDocTemplate)
   return FALSE;
AddDocTemplate(pDocTemplate);

// Standard Application Wizard generated initialization excluded.

return TRUE;
}

int CUserApp::ExitInstance()
{
   if (NULL != m_hViewDll)
   {
      AfxFreeLibrary(m_hViewDll);
      m_hViewDll = NULL;
   }

   return CWinApp::ExitInstance();
}

Requisitos

Cabeçalhoafxdll_.h

`AfxLoadLibraryEx`

Use AfxLoadLibraryEx para mapear um módulo DLL.

HINSTANCE AFXAPI AfxLoadLibraryEx(LPCTSTR lpFileName, HANDLE hFile, DWORD dwFlags);

Parâmetros

lpFileName
Aponta para uma cadeia de caracteres terminada em nulo que contém o nome do módulo (um arquivo .DLL ou .EXE). O nome especificado é o nome do arquivo do módulo.

Se a cadeia de caracteres especificar um caminho, mas o arquivo não existir no diretório especificado, a função falhará.

hFile
Esse parâmetro é reservado para uso futuro. Deve ser NULL.

dwFlags
A ação a ser executada ao carregar o módulo. Se nenhum sinalizador for especificado, o comportamento dessa função será idêntico à função AfxLoadLibrary. Os valores possíveis desse parâmetro são descritos na documentação LoadLibraryEx.

Valor de Devolução

Se a função obtiver êxito, o valor retornado será um identificador para o módulo. Em caso de falha, o valor retornado será NULL.

Comentários

AfxLoadLibraryEx retorna um identificador que pode ser usado em GetProcAddress para obter o endereço de uma função DLL. AfxLoadLibraryEx também pode ser usada para mapear outros módulos executáveis.

Cada processo mantém uma contagem de referência para cada módulo de biblioteca carregado. Essa contagem de referência é incrementada a cada vez que AfxLoadLibraryEx é chamada e é decrementada sempre que AfxFreeLibrary é chamada. Quando a contagem de referência atinge zero, o módulo torna-se desmapeado do espaço de endereço do processo de chamada e o identificador deixa de ser válido.

Certifique-se de usar AfxLoadLibraryEx e AfxFreeLibrary (em vez das funções LoadLibraryEx e FreeLibrary do Win32) se o aplicativo usar vários threads e se ele carregar dinamicamente uma DLL de extensão MFC. Usar AfxLoadLibraryEx e AfxFreeLibrary garante que o código de inicialização e desligamento executado quando a DLL da extensão MFC é carregada e descarregada não corrompa o estado MFC global.

Usar AfxLoadLibraryEx em um aplicativo exige que você vincule dinamicamente à versão DLL do MFC. O arquivo de cabeçalho para AfxLoadLibraryEx, Afxdll_.h, só será incluído se o MFC estiver vinculado ao aplicativo como uma DLL. Esse requisito é por design, porque você precisa vincular à versão DLL do MFC para usar ou criar DLLs de extensão MFC.

Requisitos

Cabeçalhoafxdll_.h

`AfxMenuTearOffManager`

Ponteiro para o gerenciador de menus destacáveis global.

Sintaxe

CMenuTearOffManager* g_pTearOffMenuManager;

Requisitos

Cabeçalhoafxmenutearoffmanager.h:

`AfxMouseManager`

Ponteiro para o gerenciador de mouses global.

Sintaxe

CMouseManager* afxMouseManager;

Requisitos

Cabeçalhoafxmousemanager.h:

`AfxRegisterClass`

Use essa função para registrar classes de janela em uma DLL que usa MFC.

BOOL AFXAPI AfxRegisterClass(WNDCLASS* lpWndClass);

Parâmetros

lpWndClass
Ponteiro para uma estrutura WNDCLASS que contém informações sobre a classe de janela a ser registrada. Para obter mais informações sobre essa estrutura, confira o SDK do Windows.

Valor de Devolução

TRUE, se a classe foi registrada com êxito; caso contrário, FALSE.

Comentários

Se você usar essa função, o registro da classe será automaticamente cancelado quando a DLL for descarregada.

Em builds não DLL, o identificador AfxRegisterClass é definido como uma macro que mapeia para a função RegisterClass do Windows, uma vez que as classes registradas em um aplicativo são automaticamente não registradas. Se você usar AfxRegisterClass em vez de RegisterClass, seu código poderá ser usado sem alteração em um aplicativo e em uma DLL.

Exemplo

// Register your unique class name that you wish to use
WNDCLASS wndcls;

memset(&wndcls, 0, sizeof(WNDCLASS));   // start with NULL defaults

wndcls.style = CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW;

//you can specify your own window procedure
wndcls.lpfnWndProc = ::DefWindowProc; 
wndcls.hInstance = AfxGetInstanceHandle();
wndcls.hIcon = LoadIcon(wndcls.hInstance, MAKEINTRESOURCE(IDI_MYICON));
wndcls.hCursor = LoadCursor(wndcls.hInstance, MAKEINTRESOURCE(IDC_ARROW));
wndcls.hbrBackground = (HBRUSH)(COLOR_WINDOW + 1);
wndcls.lpszMenuName = NULL;

// Specify your own class name for using FindWindow later
wndcls.lpszClassName = _T("MyNewClass");

// Register the new class and trace if it fails
if(!AfxRegisterClass(&wndcls))
{
   TRACE("Class Registration Failed\n");
}

Requisitos

Cabeçalhoafxwin.h

`AfxRegisterWndClass`

Permite que você registre suas próprias classes de janela.

LPCTSTR AFXAPI AfxRegisterWndClass(
    UINT nClassStyle,
    HCURSOR hCursor = 0,
    HBRUSH hbrBackground = 0,
    HICON hIcon = 0);

Parâmetros

nClassStyle
Especifica o estilo de classe do Windows ou a combinação de estilos, criados usando o operador bit a bit OR (|) para a classe de janela. Para obter uma lista de estilos de classe, consulte a estrutura WNDCLASS no SDK do Windows. Se NULL, os padrões são definidos da seguinte maneira:

Define o estilo do mouse como CS_DBLCLKS, que envia mensagens de clique duplo para o procedimento da janela quando o usuário clica duas vezes no mouse.
Define o estilo do cursor de seta para o padrão IDC_ARROW do Windows.
Define o pincel de fundo como NULL, para que a janela não apague o plano de fundo.
Define o ícone como o ícone de logotipo padrão do Windows com sinalizador de ondulação.

hCursor
Especifica um identificador para o recurso de cursor a ser instalado em cada janela criada a partir da classe de janela. Se você usar o padrão de 0, obterá o cursor padrão IDC_ARROW.

hbrBackground
Especifica um identificador para o recurso pincel a ser instalado em cada janela criada a partir da classe de janela. Se você usar o padrão 0, terá um pincel NULL em segundo plano e, por padrão, sua janela não apagará a tela de fundo durante o processamento de WM_ERASEBKGND.

hIcon
Especifica um identificador para o recurso ícone a ser instalado em cada janela criada a partir da classe de janela. Se você usar o padrão de 0, obterá o ícone de logotipo padrão do Windows com sinalizador de agitação.

Valor de Devolução

Uma cadeia de caracteres terminada em nulo que contém o nome da classe. Você pode passar esse nome de classe para a função de membro Create em CWnd, ou outras classes derivadas de **CWnd-**para criar uma janela. O nome é gerado pela biblioteca Microsoft Foundation Class.

Observação

O valor retornado será um ponteiro para um buffer estático. Para salvar essa cadeia de caracteres, atribua-a a uma variável CString.

Comentários

A biblioteca Microsoft Foundation Class registra automaticamente várias classes de janela padrão para você. Chame essa função se quiser registrar suas próprias classes de janela.

O nome registrado para uma classe por AfxRegisterWndClass depende apenas dos parâmetros. Se você chamar AfxRegisterWndClass várias vezes com parâmetros idênticos, ela registrará apenas uma classe na primeira chamada. Chamadas posteriores de AfxRegisterWndClass com parâmetros idênticos retornarão o nome de classe já registrado.

Se você chamar AfxRegisterWndClass para várias classes derivadas de CWnd com parâmetros idênticos, em vez de obter uma classe de janela separada para cada classe, cada classe compartilhará a mesma classe de janela. Esse compartilhamento poderá causar problemas se for usado o estilo da classe CS_CLASSDC. Em vez de várias classes de janela CS_CLASSDC, você acaba com apenas uma classe de janela CS_CLASSDC. Todas as janelas C++ que usam essa classe compartilham o mesmo DC. Para evitar esse problema, chame AfxRegisterClass para registrar a classe.

Consulte a Nota Técnica TN001: Registro de Classe de Janela para obter mais informações sobre o registro de classe de janela e sobre a função AfxRegisterWndClass.

Exemplo

CString strMyClass;

// load stock cursor, brush, and icon for
// my own window class

try
{
   strMyClass = AfxRegisterWndClass(
       CS_VREDRAW | CS_HREDRAW,
       ::LoadCursor(NULL, IDC_ARROW),
       (HBRUSH)::GetStockObject(WHITE_BRUSH),
       ::LoadIcon(NULL, IDI_APPLICATION));
}
catch (CResourceException *pEx)
{
   AfxMessageBox(_T("Couldn't register class! (Already registered?)"));
   pEx->Delete();
}

Requisitos

Cabeçalhoafxwin.h

`AfxSetPerUserRegistration`

Define se o aplicativo redireciona o acesso ao Registro para o nó HKEY_CURRENT_USER (HKCU).

void AFXAPI AfxSetPerUserRegistration(BOOL bEnable);

Parâmetros

bEnable
[in] TRUE indica que as informações do Registro são direcionadas para o nó HKCU. FALSE indica que o aplicativo grava informações do Registro no nó padrão. O nó padrão é HKEY_CLASSES_ROOT (HKCR).

Comentários

Antes do Windows Vista, os aplicativos que acessavam o Registro geralmente usavam o nó HKEY_CLASSES_ROOT. No entanto, com o Windows Vista ou sistemas operacionais posteriores, você deve executar um aplicativo no modo elevado para gravar em HKCR.

Esse método permite que seu aplicativo leia e escreva no Registro sem ser executado no modo elevado. Ele funciona redirecionando o acesso do Registro de HKCR para HKCU. Para obter mais informações, consulte Páginas de Propriedades do Vinculador.

Se você habilitar o redirecionamento do Registro, a estrutura redirecionará o acesso de HKCR para HKEY_CURRENT_USER\Software\Classes. Somente as estruturas MFC e ATL são afetadas por esse redirecionamento.

A implementação padrão acessa o Registro em HKCR.

Requisitos

Cabeçalhoafxstat_.h

`AfxSetResourceHandle`

Use essa função para definir o identificador HINSTANCE que determina onde os recursos padrão do aplicativo serão carregados.

void AFXAPI AfxSetResourceHandle(HINSTANCE hInstResource);

Parâmetros

hInstResource
O identificador de instância ou de módulo para um arquivo .EXE ou DLL do qual os recursos do aplicativo são carregados.

Exemplo

// This code is taken from CMyApp::InitInstance
HINSTANCE hRes = NULL;
hRes = LoadLibrary(_T("Resource.dll"));
if (hRes)
   AfxSetResourceHandle(hRes);

Requisitos

Cabeçalhoafxwin.h

`AfxShellManager`

Ponteiro para o gerenciador de shells global.

Sintaxe

CShellManager* afxShellManager;

Requisitos

Cabeçalhoafxshellmanager.h:

`AfxSocketInit`

Chame essa função para substituir CWinApp::InitInstance para inicializar o Windows Sockets.

BOOL AfxSocketInit(WSADATA* lpwsaData = NULL);

Parâmetros

lpwsaData
Um ponteiro para uma estrutura WSADATA. Se lpwsaData não for igual a NULL, o endereço da estrutura WSADATA será preenchido pela chamada para WSAStartup. Essa função também garante que WSACleanup seja chamada para você antes que o aplicativo seja encerrado.

Valor de Devolução

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Ao usar soquetes MFC em threads secundários em um aplicativo MFC vinculado estaticamente, você deve chamar AfxSocketInit em cada thread que usa soquetes para inicializar as bibliotecas de soquete. Por padrão, AfxSocketInit é chamado somente no thread primário.

Requisitos

Cabeçalhoafxsock.h

`AfxUserToolsManager`

Ponteiro para o gerenciador de ferramentas de usuário global.

Sintaxe

CUserToolsManager* afxUserToolsManager;

Requisitos

Cabeçalhoafxusertoolsmanager.h:

`AfxWinInit`

Essa função é chamada pela função WinMain, fornecida pelo MFC, como parte da inicialização de CWinApp de um aplicativo baseado em GUI, para inicializar o MFC.

BOOL AFXAPI AfxWinInit(
    HINSTANCE hInstance,
    HINSTANCE hPrevInstance,
    LPTSTR lpCmdLine,
    int nCmdShow);

Parâmetros

hInstance
O identificador do módulo em execução no momento.

hPrevInstance
Um identificador para uma instância anterior do aplicativo. Para um aplicativo baseado em Win32, esse parâmetro será sempre NULL.

lpCmdLine
Aponta para uma cadeia de caracteres terminada em nulo especificando a linha de comando para o aplicativo.

nCmdShow
Especifica como a janela principal de um aplicativo de GUI seria mostrada.

Comentários

Para um aplicativo de console, que não usa a função WinMain fornecida pelo MFC, você deve chamar AfxWinInit diretamente para inicializar o MFC.

Se você se chamar AfxWinInit, deverá declarar a instância de uma classe CWinApp. Para um aplicativo de console, você poderá optar por não derivar sua própria classe de CWinApp e, em vez disso, usar uma instância de CWinApp diretamente. Essa técnica será apropriada se você decidir deixar todas as funcionalidades para seu aplicativo ao implementar main.

Observação

Quando cria um contexto de ativação para um assembly, o MFC usa um recurso de manifesto fornecido pelo módulo do usuário. O contexto de ativação é criado em AfxWinInit. Para obter mais informações, consulte Suporte para contextos de ativação no estado do módulo MFC.

Exemplo

#include <afx.h>
#include <afxdb.h>

int _tmain(int /*argc*/, TCHAR * /*argv[]*/, TCHAR * /*envp[]*/)
{
   int nRetCode = 0;

   // initialize MFC and print and error on failure
   if (!AfxWinInit(::GetModuleHandle(NULL), NULL, ::GetCommandLine(), 0))
   {
      // TODO: change error code to suit your needs
      _tprintf(_T("Fatal Error: MFC initialization failed\n"));
      nRetCode = 1;
   }
   else
   {
      // try to connect to an ODBC database that doesn't exist
      // (this wouldn't work at all without initializing MFC)

      CDatabase db;
      try
      {
         db.Open(_T("This Databsae Doesn't Exist"));

         // we shouldn't realistically get here

         _tprintf_s(_T("Successful!\n")
                    _T("Closing ...\n"));
         db.Close();
         _tprintf_s(_T("Closed!"));
      }
      catch (CDBException *pEx)
      {
         // we got an exception! print an error message
         // (this wouldn't work without initializing MFC)

         TCHAR sz[1024];

         _tprintf_s(_T("Error: "));
         if (pEx->GetErrorMessage(sz, 1024))
            _tprintf_s(sz);
         else
            _tprintf_s(_T("No error message was available"));
         _tprintf_s(_T("\n"));

         pEx->Delete();

         nRetCode = 1;
      }
   }

   return nRetCode;
}

Requisitos

Cabeçalhoafxwin.h

Confira também

Macros e Globais
Classe CWinApp
Classe CContextMenuManager
Classe CWnd
Classe CFrameWndEx
Classe CMFCToolBar
Classe CKeyboardManager
Classe CMenuTearOffManager
Classe CMouseManager
Classe CShellManager
Classe CUserToolsManager