IMAPIFormContainer::InstallForm
Aplica-se a: Outlook 2013 | Outlook 2016
Instala um formulário em uma biblioteca de formulários.
HRESULT InstallForm(
ULONG_PTR ulUIParam,
ULONG ulFlags,
LPCSTR szCfgPathName
);
Parâmetros
ulUIParam
[in] Um identificador para a janela pai de qualquer caixa de diálogo ou janelas que este método exibe. O parâmetro ulUIParam é ignorado, a menos que o aplicativo cliente defina o sinalizador MAPI_DIALOG no parâmetro ulFlags . O parâmetro ulUIParam pode ser NULL se MAPI_DIALOG também não for passado.
ulFlags
[in] Um bitmask de sinalizadores que controla a instalação do formulário. Os seguintes sinalizadores podem ser definidos:
MAPI_DIALOG
Exibe uma caixa de diálogo para fornecer informações de progresso ou solicitar ao usuário mais informações. Se esse sinalizador não estiver definido, nenhuma caixa de diálogo será exibida.
MAPI_UNICODE
As cadeias de caracteres passadas estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres estarão no formato ANSI.
MAPIFORM_INSTALL_OVERWRITEONCONFLICT
Se já existir outro formulário que manipula a classe de mensagem manipulada por esse formulário, substitua o formulário existente por este. Esse sinalizador será ignorado se o sinalizador MAPI_DIALOG também estiver presente.
szCfgPathName
[in] O caminho para o arquivo de configuração do formulário.
Valor de retorno
S_OK
A chamada foi bem-sucedida e retornou o valor ou valores esperados.
MAPI_E_EXTENDED_ERROR
Ocorreu um erro de implementação. Para obter a estrutura MAPIERROR associada ao erro, chame o método IMAPIFormContainer::GetLastError .
MAPI_E_USER_CANCEL
O usuário cancelou a instalação do formulário, normalmente clicando no botão Cancelar em uma caixa de diálogo.
Observações para implementadores
Os provedores de biblioteca de formulários devem preencher uma estrutura MAPIERROR e retornar MAPI_E_EXTENDED_ERROR se alguma das seguintes condições ocorrer:
O arquivo de configuração não foi encontrado.
O arquivo de configuração não é legível.
O arquivo de configuração é inválido.
Notas para chamadores
Os aplicativos cliente chamam o método IMAPIFormContainer::InstallForm para instalar um formulário em um contêiner de formulário específico. O parâmetro szCfgPathName deve conter o caminho de um arquivo de configuração de formulário (ou seja, um arquivo com a extensão .cfg que descreve o formulário e sua implementação). Os sinalizadores no parâmetro ulFlags especificam o seguinte:
Se o sinalizador MAPI_DIALOG for definido, uma interface do usuário será exibida, permitindo que o usuário que está instalando o formulário especifique os detalhes da instalação.
Se o sinalizador MAPIFORM_INSTALL_OVERWRITEONCONFLICT for definido, qualquer formulário anterior para a mesma classe de mensagem será substituído pelo formulário que está sendo instalado. Caso contrário, a instalação do formulário será mesclada com a descrição do formulário atual, se existir.
Se MAPI_DIALOG estiver definido, MAPIFORM_INSTALL_OVERWRITEONCONFLICT será ignorado.
A ausência de MAPIFORM_INSTALL_OVERWRITEONCONFLICT no conjunto de sinalizadores significa que uma mesclagem será feita. Todas as novas plataformas no arquivo .cfg que não estão presentes no momento na descrição do formulário serão instaladas e nenhuma outra alteração ocorrerá.
Se o sinalizador MAPI_UNICODE for definido, o caminho do arquivo de configuração de formulário será uma cadeia de caracteres Unicode.
Os clientes devem chamar IMAPIFormContainer::GetLastError se InstallForm retornar MAPI_E_EXTENDED_ERROR e eles devem marcar a estrutura MAPIERROR retornada para determinar a condição que gerou o erro.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| FormContainerDlg.cpp |
CFormContainerDlg::OnInstallForm |
O MFCMAPI usa o método IMAPIFormContainer::InstallForm para instalar um formulário em um contêiner de formulário. |