IMAPIFolder::CopyMessages
Aplica-se a: Outlook 2013 | Outlook 2016
Copia ou move uma ou mais mensagens.
HRESULT CopyMessages(
LPENTRYLIST lpMsgList,
LPCIID lpInterface,
LPVOID lpDestFolder,
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 para copiar ou mover.
lpInterface
[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar a pasta de destino apontada pelo parâmetro lpDestFolder . Passar NULL resulta no provedor de serviços retornando a interface de pasta padrão, IMAPIFolder : IMAPIContainer. Os clientes devem passar NULL. Outros chamadores podem definir o parâmetro lpInterface como IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer ou IID_IMAPIFolder.
lpDestFolder
[in] Um ponteiro para a pasta aberta para receber as mensagens copiadas ou movidas.
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 cliente defina o sinalizador MESSAGE_DIALOG no parâmetro ulFlags e passe NULL no parâmetro lpProgress .
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 objeto de progresso 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 como a operação de cópia ou movimentação é realizada. Os seguintes sinalizadores podem ser definidos:
MAPI_DECLINE_OK
Informa o provedor do repositório de mensagens para retornar imediatamente MAPI_E_DECLINE_COPY se ele implementar o método IMAPIFolder::CopyMessages chamando o método IMAPISupport::D oCopyTo ou IMAPISupport::D oCopyProps .
MESSAGE_DIALOG
Exibe um indicador de progresso à medida que a operação prossegue.
MESSAGE_MOVE
A mensagem ou as mensagens devem ser movidas em vez de copiadas. Se MESSAGE_MOVE não estiver definido, as mensagens serão copiadas.
Valor de retorno
S_OK
A mensagem ou as mensagens foram copiadas ou movidas com êxito.
MAPI_E_DECLINE_COPY
O provedor implementa esse método chamando um método de objeto de suporte e o chamador passou o sinalizador MAPI_DECLINE_OK.
MAPI_W_PARTIAL_COMPLETION
A chamada foi bem-sucedida, mas nem todas as entradas foram copiadas ou movidas 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::CopyMessages copia ou move mensagens para outra pasta.
As mensagens abertas com permissão de leitura/gravação podem ser movidas ou copiadas.
Observações para implementadores
Se você estiver copiando mensagens para outro repositório de mensagens sem usar o método IMAPISupport::CopyMessages , primeiro chame IMAPIFolder::SetReadFlags com o conjunto de sinalizadores GENERATE_RECEIPT_ONLY. O repositório de mensagens de recebimento não é responsável por gerar relatórios de leitura para as mensagens copiadas ou movidas. Se você estiver chamando IMAPISupport::CopyMessages para implementar IMAPIFolder::CopyMessages, não chame SetReadFlags; MAPI vai chamá-lo.
Sua implementação pode mover ou copiar as mensagens em qualquer ordem e gerar relatórios de leitura status em qualquer ordem. Ou seja, você pode concluir a cópia de mensagens antes de gerar qualquer um dos relatórios de leitura status ou enviar os relatórios antes que sua implementação inicie a operação de cópia. No entanto, os relatórios de leitura devem ser enviados para que todas as mensagens sejam copiadas, independentemente de a cópia ter êxito.
Quando a operação de cópia ou movimentação envolve mais de uma mensagem, execute a operação o mais completamente possível. 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.
Tente manter identificadores de entrada em operações de movimentação ou cópia. Você também deve preservar identificadores de entrada, embora não seja necessário.
Envie notificações ao mover ou copiar mensagens para que os clientes sejam avisados de que as chamadas para os métodos IMAPIProp::SaveChanges das mensagens podem falhar.
Não inclua o status de uma mensagem na operação de cópia ou movimentação. Mover ou copiar uma mensagem status afeta muito o desempenho.
Notas para chamadores
Use IMAPIFolder::CopyMessages para preencher pastas de resultados de pesquisa, em que as mensagens geralmente são agrupadas pela pasta pai.
Espere esses valores retornados nas seguintes condições.
| Condition | Valor de retorno |
|---|---|
| IMAPIFolder::CopyMessages copiou ou moveu todas as mensagens com êxito. | S_OK |
| IMAPIFolder::CopyMessages não pôde copiar ou mover todas as mensagens com êxito. | MAPI_W_PARTIAL_COMPLETION |
| IMAPIFolder::CopyMessages não pôde ser concluído. | Qualquer valor de erro |
Quando IMAPIFolder::CopyMessages não puder ser concluído, não suponha que nenhum trabalho tenha sido feito. IMAPIFolder::CopyMessages pode ter sido capaz de copiar ou mover uma ou mais mensagens antes de encontrar o erro.