IMAPIProp::CopyProps

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Copia ou move propriedades selecionadas.

HRESULT CopyProps(
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parâmetros

lpIncludeProps

[in] Um ponteiro para uma matriz de marcas de propriedade que especifica as propriedades a serem copiadas ou movidas. PR_NULL (PidTagNull) não pode ser incluído na matriz. O parâmetro lpIncludeProps não pode ser nulo.

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 .

lpInterface

[in] Um ponteiro para o IID (identificador de interface) que representa a interface que deve 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 CopyProps chamar o método IMAPISupport::D oCopyProps 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

CopyProps deve executar uma operação de movimentação em vez de uma operação de cópia. Quando esse sinalizador não é definido, CopyProps 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, CopyProps 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, CopyProps 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, definido 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 CopyProps. Esses erros se aplicam a uma única propriedade.

MAPI_E_BAD_CHARWIDTH

O sinalizador MAPI_UNICODE foi definido e CopyProps não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e CopyProps 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 IMAPIProp::CopyProps copia ou move propriedades selecionadas do objeto atual para um objeto de destino. CopyProps é usado principalmente para responder e encaminhar mensagens, em que apenas algumas das propriedades da mensagem original viajam com a resposta ou a cópia encaminhada.

Todos os subobjetos no objeto de origem são incluídos automaticamente na operação e copiados ou movidos em sua totalidade, independentemente do uso das propriedades indicadas pela estrutura SPropTagArray . Por padrão, CopyProps 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 CopyProps ou confiar na implementação que o MAPI fornece em seu objeto de suporte. Se você quiser usar a implementação MAPI, chame o método IMAPISupport::D oCopyProps . No entanto, se você delegar o processamento para DoCopyProps e for passado o sinalizador MAPI_DECLINE_OK, evite a chamada de suporte e retorne MAPI_E_DECLINE_COPY em vez disso. Você será chamado com esse sinalizador pelo MAPI para evitar a possível recursão que pode ocorrer quando você copiar pastas.

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

Notas para chamadores

Não defina o sinalizador de MAPI_DECLINE_OK; ele é usado pelo MAPI em suas chamadas para implementações do provedor de repositório de mensagens CopyProps .

Como as operações de cópia e movimentação podem levar tempo, é sábio 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 for nulo, CopyProps usará o indicador de progresso padrão fornecido pelo MAPI.

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

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

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

Se você estiver copiando propriedades exclusivas para o tipo de objeto de origem, verifique se o objeto de destino é do mesmo tipo. CopyProps 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ê esteja copiando entre objetos do mesmo tipo, marcar que o objeto de origem e de destino sejam do mesmo tipo, comparando ponteiros de objeto ou chamando o método IUnknown::QueryInterface. Defina o identificador de interface apontado por lpInterface para a interface padrão do objeto de origem. Além disso, verifique se a propriedade tipo de objeto ou PR_OBJECT_TYPE (PidTagObjectType) é a mesma para os dois objetos. Por exemplo, se você estiver copiando 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.

Para copiar a lista de destinatários de uma mensagem, chame o método CopyProps da mensagem e inclua a propriedade PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) na matriz de marcas de propriedade. 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 as propriedades 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.

Referência do MFCMAPI

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

Arquivo	Função	Comentário
MAPIFunctions.cpp	CopyNamedProps	O MFCMAPI usa o método IMAPIProp::CopyProps para copiar propriedades nomeadas de uma mensagem para outra.
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl::OnPasteProperty	O MFCMAPI usa o método IMAPIProp::CopyProps para colar uma propriedade copiada de outro objeto.