IMAPIFolder::CopyFolder
Hace referencia a: Outlook 2013 | Outlook 2016
Copia o mueve una subcarpeta.
HRESULT CopyFolder(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
Parameters
cbEntryID
[in] Recuento de bytes en el identificador de entrada al que apunta el parámetro lpEntryID .
lpEntryID
[in] Puntero al identificador de entrada de la subcarpeta que se va a copiar o mover.
lpInterface
[in] Puntero al identificador de interfaz (IID) que representa la interfaz que se va a usar para acceder a la carpeta a la que apunta el parámetro lpDestFolder . Pasar NULL hace que el proveedor de servicios devuelva la interfaz de carpeta estándar, IMAPIFolder : IMAPIContainer. Los valores válidos para lpInterface incluyen IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer y IID_IMAPIFolder.
lpDestFolder
[in] Puntero a la carpeta abierta para recibir la subcarpeta copiada o movida.
lpszNewFolderName
[in] Puntero al nombre de la carpeta copiada o movida en su nuevo destino. Si lpszNewFolderName se establece en NULL, se usa el nombre de la subcarpeta de origen para el nombre de la carpeta de destino.
ulUIParam
[in] Identificador de la ventana primaria del indicador de progreso. El parámetro ulUIParam se omite a menos que se establezca la marca FOLDER_DIALOG en el parámetro ulFlags .
lpProgress
[in] Puntero a un objeto de progreso que muestra un indicador de progreso. Si se pasa NULL en lpProgress, el proveedor del almacén de mensajes muestra un indicador de progreso mediante la implementación del objeto de progreso MAPI. El parámetro lpProgress se omite a menos que la marca de FOLDER_DIALOG se establezca en ulFlags.
ulFlags
[in] Máscara de bits de marcas que controla la operación de copia o movimiento. Se pueden establecer las siguientes marcas:
COPY_SUBFOLDERS
También se deben copiar todas las subcarpetas de la subcarpeta que se va a copiar. Cuando no se establece COPY_SUBFOLDERS para una operación de copia, solo se copia la subcarpeta identificada por lpEntryID . Con una operación de movimiento, el comportamiento de COPY_SUBFOLDERS es el predeterminado independientemente de si se establece la marca.
FOLDER_DIALOG
Solicita la visualización de un indicador de progreso.
FOLDER_MOVE
La subcarpeta se va a mover en lugar de copiarse. Si no se establece FOLDER_MOVE, se copia la subcarpeta.
MAPI_DECLINE_OK
Informa al proveedor del almacén de mensajes de que si implementa CopyFolder llamando al método IMAPISupport::D oCopyTo o IMAPISupport::D oCopyProps de su objeto de soporte técnico, copyFolder debería devolver inmediatamente MAPI_E_DECLINE_COPY.
MAPI_UNICODE
El nombre de la carpeta de destino está en formato Unicode. Si no se establece la marca de MAPI_UNICODE, el nombre de la carpeta está en formato ANSI.
Valor devuelto
S_OK
La carpeta especificada se ha copiado o movido correctamente.
MAPI_E_BAD_CHARWIDTH
Se estableció la marca MAPI_UNICODE y el proveedor del almacén de mensajes no admite Unicode, o MAPI_UNICODE no se estableció y el proveedor del almacén de mensajes solo admite Unicode.
MAPI_E_COLLISION
El nombre de la carpeta que se mueve o copia es el mismo que el de una subcarpeta de la carpeta de destino. El proveedor del almacén de mensajes requiere nombres de carpeta únicos.
MAPI_E_DECLINE_COPY
El proveedor implementa este método llamando a un método de objeto de soporte técnico y el autor de la llamada ha pasado la marca de MAPI_DECLINE_OK.
MAPI_E_FOLDER_CYCLE
La carpeta de origen contiene directa o indirectamente la carpeta de destino. Es posible que se haya realizado un trabajo significativo antes de que se detectara esta condición, por lo que la carpeta de origen y destino puede modificarse parcialmente.
MAPI_W_PARTIAL_COMPLETION
La llamada se realizó correctamente, pero no todas las entradas se copiaron correctamente. Cuando se devuelve esta advertencia, la llamada debe controlarse correctamente. Para probar esta advertencia, use la macro HR_FAILED . Para obtener más información, vea Uso de macros para el control de errores.
Comentarios
El método IMAPIFolder::CopyFolder copia o mueve una subcarpeta de una ubicación a otra. La subcarpeta que se va a copiar o mover se agrega a la carpeta de destino como subcarpeta.
Notas a los implementadores
Cuando la operación de copia o movimiento implica más de una carpeta, como se indica al establecer la marca de COPY_SUBFOLDERS, realice la operación de la forma más completa posible para cada carpeta. A veces, una de las carpetas que se va a mover o copiar no existe o ya se ha movido o copiado en otro lugar. No detenga la operación prematuramente a menos que se produzca un error que esté fuera de su control, como quedarse sin memoria, quedarse sin espacio en disco o daños en el almacén de mensajes.
Intente conservar todos los identificadores de entrada de mensaje en los mensajes copiados. También debe intentar conservar los identificadores de entrada, pero no es necesario.
Notas para los llamadores
Espere estos valores devueltos en las condiciones siguientes.
| Condition | Valor devuelto |
|---|---|
| CopyFolder ha copiado o movido correctamente todos los mensajes y subcarpetas. | S_OK |
| CopyFolder no pudo copiar o mover correctamente todos los mensajes y subcarpetas. | MAPI_W_PARTIAL_COMPLETION o MAPI_E_NOT_FOUND |
| CopyFolder no pudo completarse. | Cualquier valor de error excepto MAPI_E_NOT_FOUND |
Cuando CopyFolder no se pueda completar, no suponga que no se ha realizado ningún trabajo. CopyFolder podría haber podido copiar o mover uno o varios de los mensajes y subcarpetas antes de encontrar el error.
Si se pasa un identificador de entrada para una carpeta que no existe en lpEntryID, CopyFolder devuelve MAPI_W_PARTIAL_COMPLETION o MAPI_E_NOT_FOUND, en función de la implementación del almacén de mensajes.
Dependiendo del proveedor del almacén de mensajes, el identificador de entrada del mensaje original puede conservarse o no en el mensaje copiado. Debe conservar los identificadores de entrada siempre que sea posible, pero no es un requisito. Por lo general, puede depender de los siguientes escenarios:
Al mover una carpeta entre dos tipos diferentes de almacenes de mensajes, se garantiza que el identificador de entrada cambie.
Al mover una carpeta entre dos almacenes de mensajes del mismo tipo, el identificador de entrada casi siempre cambia.
Al mover una carpeta a otra ubicación del mismo almacén de mensajes, el identificador de entrada puede cambiar o no, en función del proveedor del almacén de mensajes.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg::OnPasteFolder |
MFCMAPI usa el método IMAPIFolder::CopyFolder para copiar carpetas de una ubicación a otra. MFCMAPI recuerda la carpeta de origen durante la operación de copia y realiza realmente la copia durante la operación de pegado. |