IMAPIProp::CopyTo

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Copia ou move todas as propriedades, exceto para propriedades especificamente excluídas.

HRESULT CopyTo(
 ULONG ciidExclude,
 LPCIID rgiidExclude,
 LPSPropTagArray lpExcludeProps,
 ULONG_PTR ulUIParam,
 LPMAPIPROGRESS lpProgress,
 LPCIID lpInterface,
 LPVOID lpDestObj,
 ULONG ulFlags,
 LPSPropProblemArray FAR * lppProblems
);

Parâmetros

ciidExclude

[in] A contagem de interfaces a serem excluídas quando as propriedades são copiadas ou movidas.

rgiidExclude

[in] Uma matriz de IIDs (identificadores de interface) que especifica interfaces que não devem ser usadas quando as informações complementares são copiadas ou movidas 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 nulo no parâmetro lpExcludeProps indica que todas as propriedades do objeto devem ser copiadas ou movidas. CopyTo retorna MAPI_E_INVALID_PARAMETER quando o membro cValues da estrutura SPropProblemArray 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 .

lpInterface

[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar o objeto apontado pelo parâmetro lpDestObj . O parâmetro lpInterface não deve ser nulo.

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_DECLINE_OK

Se CopyTo chamar o método IMAPISupport::D oCopyTo para manipular a operação de cópia ou movimentação, ele deverá retornar imediatamente com o valor de erro MAPI_E_DECLINE_COPY. O sinalizador MAPI_DECLINE_OK é definido pelo MAPI para limitar a recursão. Os clientes não definem esse sinalizador.

MAPI_DIALOG

Exibe um indicador de progresso.

MAPI_MOVE

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

lppProblems

[in, out] Na entrada, um ponteiro para um ponteiro para uma estrutura SPropProblemArray ; caso contrário, nulo, indicando que não há necessidade de informações de erro. Se lppProblems for um ponteiro válido na entrada, CopyTo 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

Um subobjeto não pode ser copiado porque um subobjecto com o mesmo nome de exibição — especificado pela propriedade PR_DISPLAY_NAME (PidTagDisplayName) – já existe no objeto de destino.

MAPI_E_DECLINE_COPY

O provedor de serviços não implementa a operação de cópia.

MAPI_E_FOLDER_CYCLE

O objeto de origem que executa a operação de cópia ou movimentação direta ou indiretamente contém 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 lpInterface não tem suporte para o 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 CopyTo. Os seguintes erros se aplicam a uma única propriedade:

MAPI_E_BAD_CHARWIDTH

O sinalizador MAPI_UNICODE foi definido e CopyTo não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e CopyTo 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

Por padrão, o método IMAPIProp::CopyTo copia ou move todas as propriedades do objeto atual para um objeto de destino. CopyTo é usado quando um objeto deve ser copiado ou movido exatamente, com todas ou a maioria de suas propriedades intactas.

Todos os subobjetos no objeto de origem são incluídos automaticamente na operação e são copiados ou movidos em sua totalidade. Por padrão, CopyTo substitui quaisquer propriedades no objeto de destino que correspondam às propriedades do objeto de origem. 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.

Observações para implementadores

Você pode fornecer uma implementação completa do CopyTo ou confiar na implementação que o MAPI fornece em seu objeto de suporte. Se você quiser usar a implementação MAPI, chame IMAPISupport::D oCopyTo. No entanto, se você delegar o processamento para o DoCopyTo e for passado o sinalizador MAPI_DECLINE_OK, evite a chamada de suporte e retorne MAPI_E_DECLINE_COPY. O MAPI chamará com esse sinalizador para evitar a possível recursão que pode acontecer quando as pastas forem copiadas.

Como a operação de cópia pode ser longa, você deve exibir um indicador de progresso. Use a implementação IMAPIProgress aprovada no parâmetro lpProgress , se houver uma. Se lpProgress fornulo, chame o método IMAPISupport::D oProgressDialog para usar a implementação MAPI.

Não tente definir nenhuma propriedade conhecida somente leitura no objeto de destino; retornar MAPI_E_NO_ACCESS em vez disso.

Os objetos de origem e de destino devem usar as mesmas interfaces. Retorne MAPI_E_INVALID_PARAMETER se lpInterface não estiver definido.

Retorne MAPI_E_INTERFACE_NOT_SUPPORTED se todas as interfaces conhecidas forem excluídas.

Notas para chamadores

Não defina o sinalizador de MAPI_DECLINE_OK; O MAPI o usa em suas chamadas para o provedor de repositório de mensagens CopyTo implementações.

Como as operações de cópia e movimentação podem levar tempo, você deve solicitar a exibição de um indicador de progresso definindo o sinalizador MAPI_DIALOG. Você pode definir o parâmetro lpProgress para a implementação do IMAPIProgress, se tiver um ou para nulo. Se lpProgress fornulo, CopyTo usará o indicador de progresso padrão que o MAPI fornece.

Você pode suprimir a exibição de um indicador de progresso não definindo o sinalizador MAPI_DIALOG. CopyTo ignorará os parâmetros ulUIParam e lpProgress e não exibirá o indicador.

CopyTo pode relatar erros globais e individuais ou erros 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 nulo, 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 CopyTo retornar S_OK, marcar possíveis erros com propriedades individuais na estrutura. Quando CopyTo retorna um erro, nenhuma informação é retornada na estrutura SPropProblemArray . Em vez disso, chame IMAPIProp::GetLastError para recuperar informações detalhadas de erro.

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

Se você copiar propriedades exclusivas para o tipo de objeto de origem, você deve garantir que o objeto de destino seja do mesmo tipo. CopyTo não impede que você associe propriedades que normalmente pertencem a um tipo de objeto com outro tipo de objeto. Cabe a você copiar propriedades que fazem sentido para o objeto de destino. Por exemplo, você não deve copiar propriedades de mensagem para um contêiner de catálogo de endereços.

Para garantir que você copie entre objetos do mesmo tipo, marcar que o objeto de origem e de destino sejam do mesmo tipo, comparando ponteiros de objeto ou chamando IUnknown::QueryInterface. Defina o identificador de interface apontado por lpInterface para a interface padrão do objeto de origem. Além disso, certifique-se de que a propriedade tipo de objeto ou PR_OBJECT_TYPE (PidTagObjectType) seja a mesma para os dois objetos. Por exemplo, se você copiar de uma mensagem, defina lpInterface como IID_IMessage e o PR_OBJECT_TYPE para ambos os objetos MAPI_MESSAGE.

Se um ponteiro inválido for passado no parâmetro lpDestObj , os resultados serão imprevisíveis.

Excluir propriedades em uma chamada CopyTo pode ser útil. Por exemplo, alguns objetos têm propriedades específicas para uma única instância do objeto, como a data e a hora da entrega da mensagem. 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, impeça a cópia ou movimentação de uma tabela de conteúdo ou hierarquia ou contêiner de catálogo de endereços, incluindo PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) ou PR_CONTAINER_CONTENTS (PidTagContainerContents) na matriz de exclusão da marca de propriedade.

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 da 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)

A marca de propriedade PR_NULL (PidTagNull) não pode ser incluída na matriz lpExcludeProps .

A utilidade do recurso CopyTo para excluir interfaces talvez não seja tão óbvia quanto a utilidade de excluir propriedades. Você pode excluir uma interface ao copiar para um objeto que não tem conhecimento de um grupo de propriedades. Por exemplo, se você copiar propriedades de uma pasta para um anexo, as únicas propriedades com as quais o anexo pode funcionar serão as propriedades genéricas disponíveis com qualquer implementação IMAPIProp . Excluindo IMAPIFolder da operação de cópia, o anexo não receberá nenhuma das propriedades de pasta mais específicas.

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 do 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.

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

Referência do MFCMAPI

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

Arquivo	Função	Comentário
File.cpp	LoadFromMSG	O MFCMAPI usa o método IMAPIProp::CopyTo para copiar propriedades de um arquivo .msg para um objeto IMAPIMessageSite .
FolderDlg.cpp	CFolderDlg::HandlePaste	O MFCMAPI usa o método IMAPIProp::CopyTo para copiar propriedades de uma mensagem de origem para uma mensagem de destino durante uma operação de colagem.