Compartilhar via

IMAPIStatus::ValidateState

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Confirma as informações de status externas disponíveis para o recurso MAPI ou o provedor de serviços. Esse método tem suporte em todos os objetos status.

HRESULT ValidateState(
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parâmetros

ulUIParam

[in] Um identificador para a janela pai de qualquer caixa de diálogo ou janelas que este método exibe.

ulFlags

[in] Um bitmask de sinalizadores que controla a validação. Os seguintes sinalizadores podem ser definidos:

ABORT_XP_HEADER_OPERATION

O usuário cancelou a operação, normalmente clicando no botão Cancelar na caixa de diálogo correspondente. O objeto status tem duas opções:

  • Continue trabalhando na operação.

  • Pare a operação e retorne MAPI_E_USER_CANCELED.

CONFIG_CHANGED

Uma ou mais propriedades de configuração do objeto status foram alteradas. Os clientes podem definir esse sinalizador para permitir que o spooler MAPI corrija dinamicamente falhas críticas do provedor de transporte.

FORCE_XP_CONNECT

O objeto status deve executar uma conexão. Quando esse sinalizador é usado com o sinalizador REFRESH_XP_HEADER_CACHE ou PROCESS_XP_HEADER_CACHE, a conexão ocorre sem cache.

FORCE_XP_DISCONNECT

O objeto status deve executar uma operação de desconexão. Quando esse sinalizador é usado com o sinalizador REFRESH_XP_HEADER_CACHE ou PROCESS_XP_HEADER_CACHE, a desconexão ocorre sem cache.

PROCESS_XP_HEADER_CACHE

As entradas na tabela de cache de cabeçalho devem ser processadas, todas as mensagens marcadas com o sinalizador MSGSTATUS_REMOTE_DOWNLOAD devem ser baixadas e todas as mensagens marcadas com o sinalizador MSGSTATUS_REMOTE_DELETE devem ser excluídas. As mensagens que têm MSGSTATUS_REMOTE_DOWNLOAD e MSGSTATUS_REMOTE_DELETE definidas devem ser movidas.

REFRESH_XP_HEADER_CACHE

Para um provedor de transporte remoto, uma nova lista de cabeçalhos de mensagem deve ser baixada e todos os sinalizadores que marcam a mensagem status devem ser limpos.

SUPPRESS_UI

Impede que o objeto status exiba uma interface do usuário como parte da operação.

Valor de retorno

S_OK

A validação foi bem-sucedida.

MAPI_E_BUSY

Outra operação está em andamento; ela deve ser autorizada a ser concluída ou deve ser interrompida antes que essa operação seja iniciada.

MAPI_E_NO_SUPPORT

O objeto status não dá suporte ao método de validação, conforme indicado pela ausência do sinalizador de STATUS_VALIDATE_STATE na propriedade PR_RESOURCE_METHODS (PidTagResourceMethods).

MAPI_E_USER_CANCEL

O usuário cancelou a operação de validação, normalmente clicando no botão Cancelar em uma caixa de diálogo. Esse valor é retornado apenas por provedores de transporte remoto.

Comentários

O método IMAPIStatus::ValidateState verifica o estado de um recurso associado a um objeto status. ValidateState é o único método na interface IMAPIStatus necessária para todos os objetos status. O comportamento exato desse método depende da implementação. A tabela a seguir descreve a implementação de cada um dos diferentes tipos de objetos status.

Objeto Status ValidateState implementation
Subsistema MAPI
 Valida o estado de todos os recursos que os provedores de serviços ativos atualmente e o próprio subsistema possuem.
Spooler MAPI
 Executa um logon de todos os provedores de transporte, independentemente de já estarem conectados.
Catálogo de endereços MAPI
 Verifica as entradas em sua seção de perfil.
Provedor de serviços
 A implementação depende do tipo de provedor e dos sinalizadores definidos no parâmetro ulFlags .

Observações para implementadores

Aplicativos cliente remotos chamam o método ValidateState para iniciar o processamento remoto para várias ações. Esse método existe principalmente para definir status bits para se comunicar com o spooler MAPI, em vez de realmente fazer qualquer trabalho. Normalmente, o provedor de transporte define sinalizadores em sua linha status que indicam ao spooler MAPI quais ações precisam ser iniciadas para concluir a solicitação do cliente.

Neste modelo de interação cliente-transporte-spooler, as ações solicitadas pelo cliente são assíncronas, na medida em que ValidateState retorna antes que as ações solicitadas sejam concluídas. No entanto, ações que não envolvem necessariamente o sistema de mensagens subjacente, ou que envolvem uma interface específica do transporte, podem ser síncronas. O aplicativo cliente passa em uma máscara de bits dos sinalizadores a seguir para especificar quais ações o provedor de transporte remoto deve executar.

ABORT_XP_HEADER_OPERATION

Se possível, o provedor de transporte remoto deve cancelar todas as operações que envolvem o download de cabeçalhos. Para fazer isso, o provedor de transporte deve definir os seguintes valores de propriedade na linha status do objeto logon:

  • Desmarque os bits STATUS_INBOUND_ENABLED e STATUS_INBOUND_ACTIVE na propriedade PR_STATUS_CODE (PidTagStatusCode) para informar ao spooler MAPI para interromper o processo de liberação de entrada para esse provedor de transporte.

  • Defina o bit STATUS_OFFLINE na propriedade PR_STATUS_CODE .

  • Defina a propriedade PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) como TRUE.

  • Defina a propriedade PR_STATUS_STRING (PidTagStatusString) como uma cadeia de caracteres que indica o status do provedor de transporte para o usuário.

  • Retorne S_OK. No entanto, se a operação em andamento não puder ser cancelada, ValidateState deverá retornar MAPI_E_BUSY.

FORCE_XP_CONNECT

Um provedor de transporte remoto nunca deve estabelecer uma conexão com um recurso compartilhado (por exemplo, um modem ou porta COM) fora do contexto da interação mapi spooler-transport envolvida no método IXPLogon::FlushQueues . Se ValidateState for chamado com esse sinalizador, seu provedor de transporte deverá fazer o seguinte:

  • Defina um sinalizador de status interno para indicar que a conexão remota deve ser estabelecida quando o método IXPLogon::FlushQueues for chamado.

  • Defina os valores corretos na tabela status para fazer com que o spooler MAPI inicie o processo de liberação de fila.

  • Quando a liberação de filas for concluída, libere o recurso compartilhado.

  • Desmarque a STATUS_OFFLINE bit na propriedade PR_STATUS_CODE .

  • Retorne S_OK.

FORCE_XP_DISCONNECT

O provedor de transporte remoto deve liberar sua conexão com os recursos do sistema de mensagens. Depois de fazer isso, ele deve definir o STATUS_OFFLINE bit na propriedade PR_STATUS_CODE e retornar S_OK.

PROCESS_XP_HEADER_CACHE

O provedor de transporte remoto deve processar mensagens remotas e carregar todas as mensagens que foram adiadas. Para fazer isso, o provedor de transporte deve definir os seguintes valores de propriedade na linha status do objeto logon:

  • Defina a propriedade PR_STATUS_STRING como uma cadeia de caracteres que indica o status do provedor de transporte para o usuário.

  • Defina os bits STATUS_OUTBOUND_ENABLED e STATUS_OUTBOUND_ACTIVE na propriedade PR_STATUS_CODE .

  • Defina a propriedade PR_REMOTE_VALIDATE_OK na linha status do provedor de transporte como FALSE.

  • Se outra operação estiver em andamento (como baixar cabeçalhos) quando ValidateState for chamado, ValidateState deverá retornar MAPI_E_BUSY.

  • Execute o código para processar o sinalizador de REFRESH_XP_HEADER_CACHE também para atender aos requisitos do cliente do Microsoft Exchange.

REFRESH_XP_HEADER_CACHE

O provedor de transporte remoto deve recuperar quaisquer novos cabeçalhos de mensagem do sistema de mensagens. Para fazer isso, o provedor de transporte deve fazer o seguinte:

  • Defina a propriedade PR_STATUS_STRING como uma cadeia de caracteres que indica o status do provedor de transporte para o usuário.

  • Defina os bits STATUS_INBOUND_ENABLED e STATUS_INBOUND_ACTIVE na propriedade PR_STATUS_CODE .

  • Desmarque a STATUS_OFFLINE bit na propriedade PR_STATUS_CODE .

  • Defina o bit STATUS_ONLINE na propriedade PR_STATUS_CODE .

  • Defina a propriedade PR_REMOTE_VALIDATE_OK na linha status do provedor de transporte como FALSE.

SHOW_XP_SESSION_UI

Se o provedor de transporte tiver qualquer parte da interface do usuário para processar os cabeçalhos de mensagem (como uma caixa de diálogo que confirme o download de mensagens), essa caixa de diálogo deverá ser exibida. Caso contrário, ValidateState poderá retornar MAPI_E_NO_SUPPORT.

Se quaisquer sinalizadores diferentes desses forem passados, ValidateState deverá retornar MAPI_E_UNKNOWN_FLAGS.

A chamada do cliente para o provedor de transporte geralmente será para o método IMAPIStatus::ValidateState . Durante o processamento do ValidateState, o provedor de transporte não deve executar nenhuma ação que aloque recursos escassos do sistema, como um modem ou uma porta COM. Isso ocorre porque o spooler MAPI às vezes precisará liberar filas em mais de um provedor de transporte. No entanto, o cliente pode chamar o método ValidateState de qualquer provedor de transporte a qualquer momento. Se o provedor de transporte tentar alocar um recurso escasso durante o processamento do ValidateState, um erro poderá resultar devido ao conflito com outro provedor de transporte que o spooler MAPI instruiu a liberar suas filas. Se você permitir que todas as alocações de recursos escassas ocorram sob a direção do spooler MAPI, você poderá evitar esses conflitos. Seu provedor de transporte deve dar suporte à propriedade PR_REMOTE_VALIDATE_OK para que os aplicativos cliente possam detectar quando o provedor de transporte estiver ocupado ou aguardando que o spooler MAPI inicie uma ação.

Notas para chamadores

Como esse método pode fazer com que outras chamadas potencialmente longas sejam feitas, o ValidateState pode retornar MAPI_E_BUSY para informar que esse método está aguardando a conclusão de outra operação. Você deve aguardar até que a operação pendente seja concluída antes de tentar outra tarefa.

Você tem o maior controle sobre suas chamadas para o provedor de transporte status objetos. Você pode passar um ou mais sinalizadores para ValidateState que afetam as operações do provedor de transporte. Por exemplo, o sinalizador ABORT_XP_HEADER_OPERATION indica que o usuário cancelou a validação. Os provedores de transporte podem decidir abortar, retornar MAPI_E_USER_CANCELED ou continuar.

Você pode definir o sinalizador CONFIG_CHANGED em uma chamada para o objeto status de um provedor de serviços ou o spooler MAPI para indicar que uma opção de configuração foi alterada. Você pode usar CONFIG_CHANGED para reconfigurar dinamicamente um provedor de transporte. Quando você define CONFIG_CHANGED em uma chamada para o objeto status de um provedor de serviços, o provedor responde com uma chamada para IMAPISupport::SpoolerNotify para alertar o spooler MAPI da alteração. Quando você define CONFIG_CHANGED em uma chamada para o objeto status do carreteiro MAPI, o spooler chama IXPLogon::AddressTypes para cada provedor de transporte ativo. AddressTypes informa o spooler MAPI dos tipos de endereço com suporte de um transporte. Alguns provedores de serviços também exibem um indicador de progresso se a validação deve levar muito tempo. Exibir um indicador de progresso é útil, mas não é necessário.

Quando o sinalizador de SUPPRESS_UI é definido, nenhuma das planilhas de propriedades de configuração ou caixas de diálogo de progresso podem ser exibidas.

Confira também