IMAPIFolder::CopyFolder
Aplica-se a: Outlook 2013 | Outlook 2016
Copia ou move uma subpasta.
HRESULT CopyFolder(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
Parâmetros
cbEntryID
[in] A contagem de bytes no identificador de entrada apontada pelo parâmetro lpEntryID .
Lpentryid
[in] Um ponteiro para o identificador de entrada da subpasta 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 à qual o parâmetro lpDestFolder aponta. Passar NULL faz com que o provedor de serviços retorne a interface de pasta padrão, IMAPIFolder : IMAPIContainer. Os valores válidos para lpInterface incluem IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer e IID_IMAPIFolder.
lpDestFolder
[in] Um ponteiro para a pasta aberta para receber a subpasta copiada ou movida.
lpszNewFolderName
[in] Um ponteiro para o nome da pasta copiada ou movida em seu novo destino. Se lpszNewFolderName for definido como NULL, o nome da subpasta de origem será usado para o nome da pasta de destino.
ulUIParam
[in] Um identificador para a janela pai do indicador de progresso. O parâmetro ulUIParam é ignorado, a menos que o sinalizador FOLDER_DIALOG no parâmetro ulFlags seja definido.
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 FOLDER_DIALOG seja definido em ulFlags.
ulFlags
[in] Um bitmask de sinalizadores que controla a operação de cópia ou movimentação. Os seguintes sinalizadores podem ser definidos:
COPY_SUBFOLDERS
Todas as subpastas na subpasta a ser copiada também devem ser copiadas. Quando COPY_SUBFOLDERS não é definido para uma operação de cópia, apenas a subpasta identificada por lpEntryID é copiada. Com uma operação de movimentação, o comportamento COPY_SUBFOLDERS é o padrão, independentemente de o sinalizador ser definido.
FOLDER_DIALOG
Solicita a exibição de um indicador de progresso.
FOLDER_MOVE
A subpasta deve ser movida em vez de copiada. Se FOLDER_MOVE não estiver definido, a subpasta será copiada.
MAPI_DECLINE_OK
Informa ao provedor do repositório de mensagens que, se ele implementar o CopyFolder chamando o método IMAPISupport::D oCopyTo ou IMAPISupport::D oCopyProps do objeto de suporte, o CopyFolder deverá retornar imediatamente MAPI_E_DECLINE_COPY.
MAPI_UNICODE
O nome da pasta de destino está no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, o nome da pasta estará no formato ANSI.
Valor de retorno
S_OK
A pasta especificada foi copiada ou movida com êxito.
MAPI_E_BAD_CHARWIDTH
O sinalizador MAPI_UNICODE foi definido e o provedor do repositório de mensagens não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e o provedor do repositório de mensagens dá suporte apenas ao Unicode.
MAPI_E_COLLISION
O nome da pasta que está sendo movida ou copiada é o mesmo de uma subpasta na pasta de destino. O provedor do repositório de mensagens requer nomes de pasta exclusivos.
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_E_FOLDER_CYCLE
A pasta de origem contém direta ou indiretamente a pasta de destino. Um trabalho significativo pode ter sido realizado antes da descoberta dessa condição, portanto, a pasta de origem e destino pode ser parcialmente modificada.
MAPI_W_PARTIAL_COMPLETION
A chamada foi bem-sucedida, mas nem todas as entradas foram copiadas 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::CopyFolder copia ou move uma subpasta de um local para outro. A subpasta que está sendo copiada ou movida é adicionada à pasta de destino como uma subpasta.
Observações para implementadores
Quando a operação de cópia ou movimentação envolve mais de uma pasta, conforme indicado pela configuração do sinalizador COPY_SUBFOLDERS, execute a operação o mais completamente possível para cada pasta. Às vezes, uma das pastas a serem movidas ou copiadas não existe ou já foi movida ou copiada para outro lugar. 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 todos os identificadores de entrada de mensagem nas mensagens copiadas. Você também deve tentar preservar identificadores de entrada, mas isso não é necessário.
Notas para chamadores
Espere esses valores retornados nas seguintes condições.
| Condition | Valor de retorno |
|---|---|
| CopyFolder copiou ou moveu com êxito cada mensagem e subpasta. | S_OK |
| O CopyFolder não pôde copiar ou mover com êxito cada mensagem e subpasta. | MAPI_W_PARTIAL_COMPLETION ou MAPI_E_NOT_FOUND |
| CopyFolder não pôde ser concluído. | Qualquer valor de erro, exceto MAPI_E_NOT_FOUND |
Quando CopyFolder não puder ser concluído, não suponha que nenhum trabalho tenha sido feito. CopyFolder pode ter sido capaz de copiar ou mover uma ou mais das mensagens e subpastas antes de encontrar o erro.
Se um identificador de entrada de uma pasta que não existe for passado em lpEntryID, CopyFolder retornará MAPI_W_PARTIAL_COMPLETION ou MAPI_E_NOT_FOUND, dependendo da implementação do repositório de mensagens.
Dependendo do provedor do repositório de mensagens, o identificador de entrada da mensagem original pode ou não ser preservado na mensagem copiada. Você deve preservar identificadores de entrada sempre que possível, mas não é um requisito. Geralmente, você pode depender dos seguintes cenários:
Quando você move uma pasta entre dois tipos diferentes de armazenamentos de mensagens, o identificador de entrada é garantido como alterado.
Quando você move uma pasta entre dois repositórios de mensagens do mesmo tipo, o identificador de entrada quase sempre muda.
Quando você move uma pasta para outro local no mesmo repositório de mensagens, o identificador de entrada pode ou não ser alterado, dependendo do provedor do repositório de mensagens.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg::OnPasteFolder |
O MFCMAPI usa o método IMAPIFolder::CopyFolder para copiar pastas de um local para outro. O MFCMAPI lembra a pasta de origem durante a operação de cópia e, na verdade, executa a cópia durante a operação de colar. |