IMAPISupport::DoCopyTo

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Copia ou move todas as propriedades de um objeto, exceto propriedades especificamente excluídas, para outro objeto.

HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  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 que tem as propriedades a serem copiadas ou movidas.

lpSrcObj

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

ciidExclude

[in] A contagem de interfaces a serem excluídas quando você copiar ou mover propriedades.

rgiidExclude

[in] Uma matriz de identificadores de interface que indica interfaces que não devem ser usadas quando você copia ou move informações complementares para o objeto de destino.

lpExcludeProps

[in] Um ponteiro para uma matriz de marcas de propriedade que identifica as marcas de propriedade que devem ser excluídas da operação de cópia ou movimentação. Passar NULL no parâmetro lpExcludeProps indica que todas as propriedades do objeto devem ser copiadas ou movidas. DoCopyTo retorna MAPI_E_INVALID_PARAMETER quando o membro cValues da estrutura SPropTagArray apontada por lpExcludeProps é definido como 0.

ulUIParam

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

lpProgress

[in] Um ponteiro para uma implementação de indicador de progresso. Se NULL for passado no parâmetro lpProgress , o MAPI fornecerá a implementação de progresso. 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 a operação de cópia ou movimentação. Os seguintes sinalizadores podem ser definidos:

MAPI_DIALOG

Exibe um indicador de progresso.

MAPI_MOVE

DoCopyTo deve executar uma operação de movimentação em vez de uma operação de cópia. Quando esse sinalizador não está definido, o DoCopyTo 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 DoCopyTo substitui as propriedades existentes.

lppProblems

[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, DoCopyTo 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 pelo objeto apontado por lpSrcObj ou a interface identificada pelo parâmetro lpDestInterface não tem suporte pelo objeto apontado por lpDestObj.

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.

MAPI_E_INVALID_PARAMETER

O parâmetro lpSrcInterface é NULL.

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

MAPI_E_BAD_CHARWIDTH

O sinalizador MAPI_UNICODE foi definido e o DoCopyTo não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e o DoCopyTo 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 oCopyTo é implementado para objetos de suporte do provedor do repositório de mensagens. Os provedores do repositório de mensagens podem chamar DoCopyTo para implementar o método IMAPIProp::CopyTo para suas pastas e mensagens.

Por padrão, o DoCopyTo copia ou move todas as propriedades de um objeto para outro objeto. Todos os subobjetos no objeto de origem são incluídos automaticamente na operação e copiados ou movidos em sua totalidade.

Se alguma das propriedades copiadas ou movidas já existir no objeto de destino, as propriedades existentes serão substituídas pelas novas propriedades, a menos que o sinalizador MAPI_NOREPLACE seja definido no parâmetro ulFlags . As informações existentes no objeto de destino que não é substituído são deixadas intocadas.

Notas para chamadores

Para excluir propriedades da operação de cópia ou movimentação, inclua suas marcas de propriedade no parâmetro lpExcludeProps . Se você passar os resultados de usar a macro PROP_TAG para criar uma marca de propriedade de um identificador específico na matriz de marcas de propriedade, todas as propriedades com esse identificador serão excluídas. Por exemplo, a seguinte entrada na matriz de marcas de propriedade faz com que todas as propriedades com um identificador de 0x8002 sejam excluídas, independentemente do tipo:

PROP_TAG(PT_LONG, 0x8002)

Para evitar copiar o tempo de entrega de uma mensagem quando você copiar a mensagem para uma pasta diferente, especifique PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) na matriz de exclusão da marca de propriedade. Para excluir a lista de destinatários de uma mensagem, adicione a propriedade PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) à matriz de exclusão. Para excluir os anexos de uma mensagem, adicione a propriedade PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) à matriz.

Da mesma forma, para impedir a cópia ou movimentação de uma tabela de conteúdo ou hierarquia ou contêiner de catálogo de endereços, inclua PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) ou PR_CONTAINER_CONTENTS (PidTagContainerContents) na matriz de exclusão da marca de propriedade.

Ignore MAPI_E_COMPUTED erros retornados na estrutura SPropProblemArray no parâmetro lppProblems .

O identificador de interface ao qual lpSrcInterface aponta geralmente é o mesmo que o identificador de interface ao qual lpDestInterface aponta.

Se você passar um identificador de interface aceitável em lpDestInterface , mas um ponteiro inválido em lpDestObj, os resultados serão imprevisíveis. Provavelmente isso fará com que seu provedor falhe.

Por outro lado, se você estiver ciente de informações suplementares que não devem ser copiadas ou movidas, adicione os identificadores de interface para que as interfaces sejam excluídas na matriz passada no parâmetro rgiidExclude . Por exemplo, se você estiver copiando mensagens, mas não qualquer um de seus anexos de mensagem, passe IID_IMessage na matriz rgiidExclude . O DoCopyTo ignora todas as interfaces listadas no rgiidExclude que ela não reconhece.

Quando você usa o parâmetro rgiidExclude para excluir uma interface, ele também exclui todas as interfaces derivadas dessa interface. Por exemplo, a exclusão da interface IMAPIContainer faz com que pastas ou contêineres de catálogo de endereços sejam excluídos, dependendo do tipo de provedor. Não exclua IMAPIProp ou IUnknown porque muitas interfaces derivam delas.

DoCopyTo relata erros globais que se aplicam à operação como um todo e erros individuais que se aplicam a propriedades individuais. 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 DoCopyTo retornar S_OK, marcar para possíveis erros com propriedades individuais na estrutura. Quando DoCopyTo 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 DoCopyTo retornar S_OK, libere a estrutura SPropProblemArray retornada chamando a função MAPIFreeBuffer .

Se ocorrer um erro global na chamada DoCopyTo , não use ou libere a estrutura SPropProblemArray . Os provedores devem ignorar o membro ulIndex nas estruturas SPropProblemArray retornadas pelo DoCopyTo.