Compartilhar via

IMAPIFolder::SetReadFlags

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Define ou limpa o sinalizador MSGFLAG_READ na propriedade PR_MESSAGE_FLAGS (PidTagMessageFlags) de uma ou mais mensagens da pasta e gerencia o envio de relatórios de leitura.

HRESULT SetReadFlags(
  LPENTRYLIST lpMsgList,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parâmetros

lpMsgList

[in] Um ponteiro para uma matriz de estruturas ENTRYLIST que identificam a mensagem ou as mensagens que têm sinalizadores de leitura para definir ou limpar. Se lpMsgList estiver definido como NULL, os sinalizadores de leitura para todas as mensagens da pasta serão definidos ou desmarcados.

ulUIParam

[in] Um identificador para a janela pai do indicador de progresso. O parâmetro ulUIParam é ignorado, a menos que o sinalizador MESSAGE_DIALOG seja definido no parâmetro ulFlags .

lpProgress

[in] Um ponteiro para um objeto de progresso que exibe um indicador de progresso. Se NULL for passado em lpProgress, o provedor do repositório de mensagens exibirá um indicador de progresso usando a implementação do MAPI. O parâmetro lpProgress é ignorado, a menos que o sinalizador MESSAGE_DIALOG seja definido em ulFlags.

ulFlags

[in] Um bitmask de sinalizadores que controla a configuração do sinalizador de leitura de uma mensagem e o processamento de relatórios de leitura. Os seguintes sinalizadores podem ser definidos:

  • CLEAR_READ_FLAG: o sinalizador MSGFLAG_READ deve ser limpo em PR_MESSAGE_FLAGS e um relatório de leitura não deve ser enviado.

  • CLEAR_NRN_PENDING: o sinalizador MSGFLAG_NRN_PENDING deve ser limpo em PR_MESSAGE_FLAGS e um relatório não lido não deve ser enviado.

  • CLEAR_RN_PENDING: o sinalizador MSGFLAG_RN_PENDING deve ser limpo em PR_MESSAGE_FLAGS e um relatório de leitura não deve ser enviado.

  • GENERATE_RECEIPT_ONLY: um relatório de leitura deve ser enviado se um estiver pendente, mas não deve haver alteração no estado do sinalizador MSGFLAG_READ.

  • MAPI_DEFERRED_ERRORS: permite que SetReadFlags retorne com êxito, possivelmente antes da conclusão da operação.

  • MESSAGE_DIALOG: exibe um indicador de progresso enquanto a operação prossegue.

  • SUPPRESS_RECEIPT: um relatório de leitura pendente deve ser cancelado se um relatório de leitura tiver sido solicitado e essa chamada alterar o estado da mensagem de não lido para lido. Se essa chamada não alterar o estado da mensagem, o provedor do repositório de mensagens poderá ignorar esse sinalizador.

Valores de retorno

S_OK

O sinalizador de leitura da mensagem ou das mensagens especificadas foi definido ou desmarcado com êxito.

MAPI_E_NO_SUPPRESS

O provedor do repositório de mensagens não dá suporte à supressão de relatórios de leitura.

MAPI_E_INVALID_PARAMETER

Uma das seguintes combinações incompatíveis de sinalizadores é definida no parâmetro ulFlags :

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

  • CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

MAPI_W_PARTIAL_COMPLETION

A chamada foi bem-sucedida, mas nem todas as mensagens foram processadas com êxito. Quando esse aviso é retornado, a chamada deve ser tratada como bem-sucedida. Para testar esse aviso, use a macro HR_FAILED . Para obter mais informações, confira Usando macros para tratamento de erros.

Comentários

O método IMAPIFolder::SetReadFlags define ou limpa o sinalizador MSGFLAG_READ na propriedade PR_MESSAGE_FLAGS de uma ou mais mensagens da pasta. Definir o sinalizador MSGFLAG_READ marca uma mensagem como leitura, o que não indica necessariamente que o destinatário pretendido realmente leu a mensagem.

SetReadFlags também gerencia o envio de relatórios de leitura.

O sinalizador de leitura não pode ser alterado para o seguinte:

  • Mensagens que não existem.

  • Mensagens que foram movidas para outro lugar.

  • Mensagens abertas com permissão de leitura/gravação.

  • Mensagens enviadas no momento.

Observações para implementadores

Você pode decidir não dar suporte ao envio de relatórios de leitura e à solicitação para suprimir relatórios de leitura. Para evitar suprimir um relatório de leitura, retorne MAPI_E_NO_SUPPRESS quando SetReadFlags for chamado com SUPPRESS_RECEIPT definido no parâmetro ulFlags .

Quando o parâmetro lpMsgList aponta para mais de uma mensagem, execute a operação o mais completamente possível para cada mensagem. Não interrompa a operação prematuramente, a menos que ocorra uma falha que esteja fora de seu controle, como ficar sem memória, ficar sem espaço em disco ou corrupção no repositório de mensagens.

Se nenhum dos sinalizadores for definido no parâmetro ulFlags, as seguintes regras se aplicam:

  • Se MSGFLAG_READ já estiver definido, não faça nada.

  • Se MSGFLAG_READ não estiver definido, defina-o imediatamente e envie relatórios de leitura pendentes se a propriedade PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) for definida.

Quando o sinalizador de SUPPRESS_RECEIPT é definido, as seguintes regras se aplicam:

  • Se MSGFLAG_READ já estiver definido, não faça nada.

  • Se MSGFLAG_READ não estiver definido, defina-o e cancele todos os relatórios de leitura pendentes.

Quando o sinalizador CLEAR_READ_FLAG for definido, desmarque o sinalizador MSGFLAG_READ na propriedade PR_MESSAGE_FLAGS de cada mensagem e não envie relatórios de leitura.

Quando o sinalizador de GENERATE_RECEIPT_ONLY for definido, envie todos os relatórios de leitura pendentes. Não defina ou desmarque MSGFLAG_READ.

Quando os sinalizadores SUPPRESS_RECEIPT e GENERATE_RECEIPT_ONLY forem definidos, defina PR_READ_RECEIPT_REQUESTED como FALSE se estiver definido e não enviar um relatório de leitura.

Notas para chamadores

Espere esses valores retornados nas seguintes condições.

Condition Valor de retorno
SetReadFlags processou com êxito cada mensagem. S_OK
SetReadFlags não pôde processar todas as mensagens com êxito. MAPI_W_PARTIAL_COMPLETION ou MAPI_E_NOT_FOUND
SetReadFlags não pôde ser concluído. Qualquer valor de erro, exceto MAPI_E_NOT_FOUND

Quando SetReadFlags não puder ser concluído, não suponha que nenhum trabalho tenha sido feito. SetReadFlags pode ter sido capaz de definir ou limpar o sinalizador de MSGFLAG_READ para uma ou mais mensagens antes de encontrar o erro.

Referência do MFCMAPI

Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.

Arquivo Função Comentário
FolderDlg.cpp
 CFolderDlg::OnSetReadFlag
 O MFCMAPI usa o método IMAPIFolder::SetReadFlags para definir manualmente o status de leitura nas mensagens especificadas.

Confira também