Share via

Função de retorno de chamada MAPIFINDNEXT (mapi.h)

  • Artigo

[O uso dessa função é desencorajado. Ele pode estar alterado ou indisponível nas versões subsequentes do Windows.]

A função MAPIFindNext recupera o próximo (ou primeiro) identificador de mensagem de um tipo especificado de mensagem de entrada.

Sintaxe

MAPIFINDNEXT Mapifindnext;

ULONG Mapifindnext(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszMessageType,
  [in]  LPSTR lpszSeedMessageID,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
  [out] LPSTR lpszMessageID
)
{...}

Parâmetros

[in] lhSession

Identificador de sessão que representa uma sessão MAPI Simples. O valor do parâmetro lhSession deve representar uma sessão válida; não pode ser zero.

[in] ulUIParam

Identificador de janela pai ou zero, indicando que, se uma caixa de diálogo for exibida, ela será modal do aplicativo. Se o parâmetro ulUIParam contiver um identificador de janela pai, ele será do tipo HWND (convertido em um ULONG_PTR). Se nenhuma caixa de diálogo for exibida durante a chamada, ulUIParam será ignorado.

[in] lpszMessageType

Ponteiro para uma cadeia de caracteres que identifica a classe de mensagem a ser pesquisada. Para localizar uma mensagem interpessoal (IPM), especifique NULL no parâmetro lpszMessageType ou faça com que ela aponte para uma cadeia de caracteres vazia. Sistemas de mensagens cuja única classe de mensagem com suporte é IPM podem ignorar esse parâmetro.

[in] lpszSeedMessageID

Ponteiro para uma cadeia de caracteres que contém a semente do identificador de mensagem para a solicitação. Se o parâmetro lpszSeedMessageID for NULL ou apontar para uma cadeia de caracteres vazia, MAPIFindNext recuperará a primeira mensagem que corresponde ao tipo especificado no parâmetro lpszMessageType .

[in] flFlags

Máscara de bits de sinalizadores de opção. Os sinalizadores a seguir podem ser definidos.

Valor Significado
MAPI_GUARANTEE_FIFO
Os identificadores de mensagem retornados devem estar na ordem do tempo recebido. As chamadas MAPIFindNext poderão demorar mais se esse sinalizador estiver definido. Algumas implementações não podem atender a essa solicitação e retornar o valor MAPI_E_NO_SUPPORT.
MAPI_LONG_MSGID
O identificador de mensagem retornado pode ter até 512 caracteres. Se esse sinalizador estiver definido, o parâmetro lpszMessageID deverá ser grande o suficiente para acomodar 512 caracteres.

Versões mais antigas do MAPI suportavam identificadores de mensagens menores (64 bytes) e não incluíam esse sinalizador. MAPIFindNext terá êxito sem esse sinalizador definido, desde que lpszMessageID seja grande o suficiente para manter o identificador de mensagem. Se lpszMessageID não puder manter o identificador de mensagem, MAPIFindNext falhará.
MAPI_UNREAD_ONLY
Somente mensagens não lidas do tipo especificado devem ser enumeradas. Se esse sinalizador não estiver definido, MAPIFindNext poderá retornar qualquer mensagem do tipo especificado.

ulReserved

Reservados; deve ser zero.

[out] lpszMessageID

Ponteiro para o identificador de mensagem retornado. O chamador é responsável por alocar a memória. Para garantir a compatibilidade, aloque 512 caracteres e defina MAPI_LONG_MSGID no parâmetro flFlags . Um buffer menor só será suficiente se o identificador de mensagem retornado tiver sempre 64 caracteres ou menos.

Retornar valor

Essa função retorna um dos valores a seguir.

Código de retorno Descrição
MAPI_E_FAILURE
Ocorreu um ou mais erros não especificados ao corresponder ao tipo de mensagem. A chamada falhou antes que a correspondência de tipo de mensagem pudesse ocorrer.
MAPI_E_INSUFFICIENT_MEMORY
Não havia memória suficiente para continuar. Nenhuma mensagem foi encontrada.
MAPI_E_INVALID_MESSAGE
Um identificador de mensagem inválido foi passado no parâmetro lpszSeedMessageID . Nenhuma mensagem foi encontrada.
MAPI_E_INVALID_SESSION
Um identificador de sessão inválido foi passado no parâmetro lhSession . Nenhuma mensagem foi encontrada.
MAPI_E_NO_MESSAGES
Não foi possível encontrar uma mensagem correspondente.
SUCCESS_SUCCESS
A chamada foi bem-sucedida e o identificador de mensagem foi retornado.

Comentários

A função MAPIFindNext permite que um aplicativo cliente enumere mensagens de um determinado tipo. Essa função pode ser chamada repetidamente para listar todas as mensagens na pasta. Os identificadores de mensagem retornados de MAPIFindNext podem ser usados em outras chamadas MAPI simples para recuperar o conteúdo da mensagem e excluir mensagens. Essa função é para processar mensagens de entrada, não para gerenciar mensagens recebidas.

MAPIFindNext procura mensagens na pasta na qual novas mensagens do tipo especificado são entregues. As chamadas MAPIFindNext só podem ser feitas no contexto de uma sessão MAPI simples válida estabelecida com a função MAPILogon.

Quando o parâmetro lpszSeedMessageID é NULL ou aponta para uma cadeia de caracteres vazia, MAPIFindNext retorna o identificador de mensagem para a primeira mensagem do tipo especificado pelo parâmetro lpszMessageType . Quando lpszSeedMessageID contém um identificador válido, a função retorna a próxima mensagem correspondente do tipo especificado por lpszMessageType. Chamadas repetidas para MAPIFindNext , em última análise, resultam em um retorno do valor MAPI_E_NO_MESSAGES, o que significa que a enumeração está concluída.

A correspondência de tipo de mensagem é feita em cadeias de caracteres de classe de mensagem. Todos os tipos de mensagem cujos nomes correspondem (até o comprimento especificado em lpszMessageType) são retornados.

Como os identificadores de mensagem são específicos do sistema de mensagens e podem ser invalidados a qualquer momento, os identificadores de mensagem são válidos apenas para a sessão atual. Se o identificador de mensagem passado em lpszSeedMessageID for inválido, MAPIFindNext retornará o valor MAPI_E_INVALID_MESSAGE.

Requisitos

Requisito Valor
Plataforma de Destino Windows
Cabeçalho mapi.h

Confira também

MAPILogon

MAPI simples