MSGSERVICEENTRY

Aplica-se a: Outlook 2013 | Outlook 2016

Define um protótipo para uma função de ponto de entrada do serviço de mensagem para dar suporte à configuração do serviço de mensagem.

Propriedade	Valor
Arquivo de cabeçalho:	Mapispi.h
Função definida implementada por:	Serviços de mensagem
Função definida chamada por:	MAPI

HRESULT MSGSERVICEENTRY(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG ulContext,
  ULONG cValues,
  LPSPropValue lpProps,
  LPPROVIDERADMIN lpProviderAdmin,
  LPMAPIERROR FAR * lppMapiError
);

Parâmetros

Hinstance

[in] Manipular a instância do provedor de serviçoSDLL. O identificador normalmente é usado para recuperar recursos.

lpMalloc

[in] Ponteiro para um objeto alocador de memória expondo a interface OLE IMalloc . O serviço de mensagem pode precisar usar esse método de alocação ao trabalhar com determinadas interfaces, como o IStream.

lpMAPISup

[in] Ponteiro para uma implementação de interface IMAPISupport : IUnknown .

ulUIParam

[in] Um valor específico da implementação usado para passar informações da interface do usuário para uma função ou zero. O parâmetro ulUIParam é o identificador de janela pai da caixa de diálogo de configuração e é do tipo HWND (lançado em um ULONG_PTR). Um valor de zero indica que não há uma janela pai.

ulFlags

[in] Bitmask de sinalizadores indicando opções para a função de entrada de serviço. Os seguintes sinalizadores podem ser definidos:

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.

MSG_SERVICE_UI_READ_ONLY

A interface do usuário de configuração do serviço deve exibir a configuração atual, mas não permitir que o usuário a altere.

SERVICE_UI_ALLOWED

Permite que uma caixa de diálogo de configuração seja exibida, se necessário. Quando o sinalizador SERVICE_UI_ALLOWED for definido, a caixa de diálogo só deve ser exibida se a matriz de valor da propriedade lpProps estiver vazia ou não contiver uma configuração válida. Se SERVICE_UI_ALLOWED não estiver definido, uma caixa de diálogo ainda poderá ser exibida se o sinalizador SERVICE_UI_ALWAYS estiver definido.

UI_CURRENT_PROVIDER_FIRST

Solicita que a caixa de diálogo de configuração do provedor ativo seja exibida em cima de outras caixas de diálogo.

SERVICE_UI_ALWAYS

Requer que o serviço de mensagem exiba uma caixa de diálogo de configuração. Se o sinalizador SERVICE_UI_ALWAYS não estiver definido, uma caixa de diálogo de configuração ainda poderá ser exibida se o sinalizador SERVICE_UI_ALLOWED estiver definido e as informações de configuração válidas não estiverem disponíveis na matriz de valor da propriedade lpProps . SERVICE_UI_ALLOWED ou SERVICE_UI_ALWAYS deve ser definido para permitir que uma interface do usuário seja exibida.

ulContext

[in] A operação de configuração que o MAPI está executando no momento. O parâmetro ulContext conterá um dos seguintes valores:

MSG_SERVICE_CONFIGURE

As alterações na configuração do serviço devem ser feitas no perfil. Se o sinalizador SERVICE_UI_ALWAYS estiver definido, o serviço deverá exibir sua caixa de diálogo de configuração. A caixa de diálogo também deve ser exibida se o sinalizador SERVICE_UI_ALLOWED estiver definido e o parâmetro lpProps estiver vazio ou não contiver dados de configuração válidos. Se lpProps contiver dados válidos, nenhuma caixa de diálogo deverá ser exibida e o serviço deverá usar esses dados para fazer a alteração de configuração.

MSG_SERVICE_CREATE

O serviço está sendo adicionado a um perfil. Se o sinalizador SERVICE_UI_ALWAYS ou SERVICE_UI_ALLOWED estiver definido, o serviço deverá exibir sua caixa de diálogo de configuração. Se nenhum dos sinalizadores estiver definido, o serviço deverá falhar.

MSG_SERVICE_DELETE

O serviço está sendo removido de um perfil. Depois de receber esse evento, o serviço deve retornar S_OK.

MSG_SERVICE_INSTALL

O serviço foi instalado na estação de trabalho do usuário de uma rede, disquete ou outro meio externo. Depois de receber esse evento, o serviço geralmente retorna S_OK.

MSG_SERVICE_PROVIDER_CREATE

Solicita que o serviço crie uma instância adicional de um provedor. Se o serviço der suporte a essa operação, ele deve chamar IProviderAdmin::CreateProvider. Se o serviço não der suporte a essa operação, ele poderá retornar MAPI_E_NO_SUPPORT.

MSG_SERVICE_PROVIDER_DELETE

Solicita que o serviço exclua uma instância do provedor. Se o serviço der suporte a essa operação, ele deve chamar IProviderAdmin::D eleteProvider. Se o serviço não der suporte a essa operação, ele poderá retornar MAPI_E_NO_SUPPORT.

MSG_SERVICE_UNINSTALL

O serviço está sendo removido. Depois de receber esse evento, o serviço pode executar todas as tarefas de limpeza que devem ser feitas antes do término do serviço e, em seguida, retornar com um valor de sucesso. Se o usuário cancelar a remoção, o serviço deverá retornar MAPI_E_USER_CANCEL.

cValues

[in] Contagem de valores de propriedade na matriz apontada pelo parâmetro lpProps . O valor do parâmetro cValues será zero se MAPI não estiver passando valores de propriedade.

lpProps

[in] Ponteiro para uma matriz opcional de estruturas SPropValue indicando valores para propriedades com suporte ao provedor que a função usará na configuração do serviço de mensagem. A função só usa esse parâmetro se o parâmetro ulContext estiver definido como MSG_SERVICE_CONFIGURE. Esse parâmetro é comumente usado para passar o caminho para um arquivo para um serviço baseado em arquivo, como um serviço de catálogo de endereços pessoal. Se o sinalizador MSG_SERVICE_CONFIGURE não for passado no parâmetro ulFlags , o parâmetro lpProps deverá ser zero.

lpProviderAdmin

[in] Ponteiro para uma interface IProviderAdmin:IUnknown que a função pode usar para localizar seções de perfil para um provedor específico no serviço de mensagens atual.

lppMapiError

[out] Ponteiro para uma estrutura MAPIERROR . A estrutura é alocada com a função MAPIAllocateBuffer . Todos os membros são opcionais, embora a maioria das estruturas contenha uma cadeia de caracteres de mensagem de erro válida no membro lpszError . Se os membros lpszComponent ou lpszError da estrutura estiverem presentes, sua memória deverá eventualmente ser liberada por uma única chamada para MAPIFreeBuffer na estrutura base.

Valor de retorno

S_OK

A chamada foi bem-sucedida e retornou o valor ou valores esperados.

MAPI_E_UNCONFIGURED

O provedor de serviços não foi configurado.

MAPI_E_USER_CANCEL

O usuário cancelou a operação, normalmente clicando no botão Cancelar em uma caixa de diálogo.

MAPI_E_NO_SUPPORT

O provedor não dá suporte a alterações em seus objetos ou não dá suporte à notificação de alterações.

MAPI_E_BAD_CHARWIDTH

O sinalizador MAPI_UNICODE foi definido e a implementação não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e a implementação dá suporte apenas ao Unicode.

Comentários

Uma função definida usando o protótipo de função MSGSERVICEENTRY permite que os serviços de mensagem se configurem ou executem outras ações específicas do serviço. A função fornece principalmente uma caixa de diálogo na qual o usuário pode alterar configurações específicas para o serviço de mensagem. Ele também pode dar suporte à configuração programática usando a matriz de valor de propriedade passada no parâmetro lpProps . A configuração programática é opcional, a menos que o serviço dê suporte ao Assistente de Perfil, para o qual ele é necessário.

MAPI chama esse ponto de entrada do aplicativo Painel de Controle ou em resposta a um aplicativo cliente chamando IMsgServiceAdmin::CreateMsgService ou IMsgServiceAdmin::ConfigureMsgService.

O MAPI não coloca nenhuma restrição no nome da função que um serviço de mensagem usa para o protótipo MSGSERVICEENTRY , mas prefere o nome ServiceEntry. Não há restrição no ordinal para a função e uma única DLL de provedor pode conter mais de uma função. No entanto, apenas uma das funções pode ser chamada de ServiceEntry.

Um serviço de mensagem pode usar a função BuildDisplayTable e o método IMAPISupport::D oConfigPropsheet para simplificar a implementação da caixa de diálogo de configuração.

É possível que um usuário cancele uma operação de MSG_SERVICE_UNINSTALL. Nesse caso, a função ServiceEntry deve marcar com o usuário para verificar se o serviço não deve ser removido e retornar MAPI_E_USER_CANCEL se o serviço permanecer instalado.

Uma função baseada no protótipo MSGSERVICEENTRY retorna um dos valores HRESULT listados. O MAPI encaminha esse valor ao responder à chamada de um cliente para IMsgServiceAdmin::ConfigureMsgService.

Os serviços de mensagem que exportam uma função de entrada de serviço devem incluir as propriedades PR_SERVICE_DLL_NAME (PidTagServiceDllName) e PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) na seção serviço de mensagem de MAPISVC.INF.