IMAPISupport::DoCopyProps

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Copia ou move uma ou mais propriedades de um objeto para outro objeto.

HRESULT DoCopyProps(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parâmetros

lpSrcInterface

[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar o objeto com as propriedades a serem copiadas ou movidas.

lpSrcObj

[in] Um ponteiro para o objeto que contém as propriedades a serem copiadas ou movidas.

lpIncludeProps

[in] Um ponteiro para uma estrutura SPropTagArray que contém uma matriz contada de marcas de propriedade que indicam as propriedades a serem copiadas ou movidas. O parâmetro lpIncludeProps não pode ser NULL.

ulUIParam

[in] Um identificador para a janela pai do indicador de progresso.

lpProgress

[in] Um ponteiro para uma implementação de um indicador de progresso. Se NULL for passado no parâmetro lpProgress , o indicador de progresso será exibido usando a implementação MAPI. O parâmetro lpProgress é ignorado, a menos que o sinalizador MAPI_DIALOG seja definido no parâmetro ulFlags .

lpDestInterface

[in] Um ponteiro para o identificador de interface que representa a interface a ser usada para acessar o objeto para receber as propriedades copiadas ou movidas.

lpDestObj

[in] Um ponteiro para o objeto para receber as propriedades copiadas ou movidas.

ulFlags

[in] Um bitmask de sinalizadores que controla como a operação de cópia ou movimentação é executada. Os seguintes sinalizadores podem ser definidos:

MAPI_DIALOG

Exibe um indicador de progresso.

MAPI_MOVE

DoCopyProps deve executar uma operação de movimentação em vez de uma operação de cópia. Quando esse sinalizador não é definido, o DoCopyProps executa uma operação de cópia.

MAPI_NOREPLACE

As propriedades existentes no objeto de destino não devem ser substituídas. Quando esse sinalizador não é definido, o DoCopyProps substitui as propriedades existentes.

lppProblems

[in, out] Na entrada, um ponteiro para um ponteiro para uma estrutura SPropProblemArray ; caso contrário, NULL, o que indica que não há necessidade de informações de erro. Se lppProblems for um ponteiro válido na entrada, o DoCopyProps retornará informações detalhadas sobre erros na cópia de uma ou mais propriedades.

Valor de retorno

S_OK

As propriedades foram copiadas ou movidas com êxito.

MAPI_E_COLLISION

Uma propriedade a ser copiada ou movida já existe no objeto de destino e o sinalizador MAPI_NOREPLACE está definido.

MAPI_E_FOLDER_CYCLE

O objeto de origem contém direta ou indiretamente o objeto de destino. Um trabalho significativo pode ter sido realizado antes da descoberta dessa condição, portanto, os objetos de origem e de destino podem ser parcialmente modificados.

MAPI_E_INTERFACE_NOT_SUPPORTED

A interface identificada pelo parâmetro lpSrcInterface não tem suporte para o objeto de origem ou a interface identificada pelo parâmetro lpDestInterface não tem suporte do objeto de destino.

MAPI_E_NO_ACCESS

Foi feita uma tentativa de acessar um objeto para o qual o chamador não tem permissões suficientes. Esse erro será retornado se o objeto de destino for o mesmo que o objeto de origem.

Os valores a seguir podem ser retornados na estrutura SPropProblemArray , mas não como valores retornados para DoCopyProps. Esses erros se aplicam a uma única propriedade.

MAPI_E_BAD_CHARWIDTH

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

MAPI_E_COMPUTED

A propriedade não pode ser modificada pelo chamador porque é uma propriedade somente leitura, calculada pelo proprietário do objeto de destino. Esse erro não é grave; o chamador deve permitir que a operação de cópia continue.

MAPI_E_INVALID_TYPE

O tipo de propriedade é inválido.

MAPI_E_UNEXPECTED_TYPE

O tipo de propriedade não é o tipo esperado pelo chamador.

Comentários

O método IMAPISupport::D oCopyProps é implementado para objetos de suporte do provedor do repositório de mensagens. Os provedores do repositório de mensagens podem chamar DoCopyProps para implementar o método IMAPIProp::CopyProps para suas pastas e mensagens. DoCopyProps copia ou move as propriedades identificadas na matriz de marcas de propriedade apontadas por lpIncludeProps e que estão presentes no objeto apontado por lpSrcObj.

Notas para chamadores

Quando você copia propriedades entre objetos do mesmo tipo, como duas mensagens, os parâmetros lpSrcInterface e lpDestInterface devem conter o mesmo identificador de interface e os parâmetros lpSrcObj e lpDestObj devem apontar para objetos do mesmo tipo. Se lpDestInterface estiver definido como NULL, DoCopyProps retornará MAPI_E_INVALID_PARAMETER. Se você definir lpDestInterface como um identificador de interface aceitável, mas definir lpDestObj como um ponteiro inválido, os resultados serão imprevisíveis. O mais provável é que seu provedor falhe.

Defina o sinalizador MAPI_NOREPLACE se você não quiser que nenhuma das propriedades no objeto de destino seja substituída. As propriedades no objeto de destino que existem no objeto de origem e não são substituídas não são excluídas ou modificadas.

Para copiar a lista de destinatários de uma mensagem, inclua a propriedade PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) na matriz de marcas de propriedade apontada pelo parâmetro lpIncludeProps . Para copiar os anexos da mensagem, inclua a propriedade PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments).

Para copiar a hierarquia ou a tabela de conteúdo de um contêiner de pasta ou catálogo de endereços, inclua PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) ou PR_CONTAINER_CONTENTS (PidTagContainerContents) na matriz de marcas de propriedade. Para incluir a tabela de conteúdo associada de uma pasta, inclua a propriedade PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) na matriz.

Se as subpastas forem copiadas ou movidas, o conteúdo será copiado ou movido em sua totalidade, independentemente do uso das propriedades indicadas pela estrutura SPropTagArray .

O DoCopyProps relata erros globais que ocorrem com a operação como um todo e erros individuais que ocorrem com uma ou mais propriedades. Esses erros individuais são colocados em uma estrutura SPropProblemArray . Você pode suprimir o relatório de erros no nível da propriedade passando NULL, em vez de um ponteiro válido, para o parâmetro de estrutura de matriz de problemas de propriedade.

Se você quiser receber informações sobre erros, passe um ponteiro de estrutura SPropProblemArray válido no parâmetro lppProblems . Quando DoCopyProps retornar S_OK, marcar para possíveis erros com propriedades individuais na estrutura. Quando DoCopyProps retorna um erro, nenhuma informação é retornada na estrutura SPropProblemArray . Em vez disso, chame o método IMAPISupport::GetLastError para recuperar informações detalhadas de erro.

Se DoCopyProps retornar S_OK, libere a estrutura SPropProblemArray retornada chamando a função MAPIFreeBuffer .