IMAPIProp::CopyTo

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Copia o mueve todas las propiedades, excepto las propiedades excluidas específicamente.

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

Parameters

ciidExclude

[in] Recuento de interfaces que se excluirán cuando se copien o muevan propiedades.

rgiidExclude

[in] Matriz de identificadores de interfaz (ID) que especifican interfaces que no se deben usar cuando se copia o mueve información complementaria al objeto de destino.

lpExcludeProps

[in] Puntero a una matriz de etiquetas de propiedad que identifica las etiquetas de propiedad que se deben excluir de la operación de copia o movimiento. Pasar null en el parámetro lpExcludeProps indica que se deben copiar o mover todas las propiedades del objeto. CopyTo devuelve MAPI_E_INVALID_PARAMETER cuando el miembro cValues de la estructura SPropProblemArray a la que apunta lpExcludeProps se establece en 0.

ulUIParam

[in] Identificador de la ventana primaria del indicador de progreso.

lpProgress

[in] Puntero a la implementación de un indicador de progreso. Si se pasa null en el parámetro lpProgress , MAPI proporciona la implementación de progreso. El parámetro lpProgress se omite a menos que se establezca la marca MAPI_DIALOG en el parámetro ulFlags .

lpInterface

[in] Puntero al identificador de interfaz (IID) que representa la interfaz que se va a usar para acceder al objeto al que apunta el parámetro lpDestObj . El parámetro lpInterface no debe ser null.

lpDestObj

[in] Puntero al objeto para recibir las propiedades copiadas o movidas.

ulFlags

[in] Máscara de bits de marcas que controla la operación de copia o movimiento. Se pueden establecer las siguientes marcas:

MAPI_DECLINE_OK

Si CopyTo llama al método IMAPISupport::D oCopyTo para controlar la operación de copia o movimiento, debería devolverse inmediatamente con el valor de error MAPI_E_DECLINE_COPY. MAPI establece la marca de MAPI_DECLINE_OK para limitar la recursividad. Los clientes no establecen esta marca.

MAPI_DIALOG

Muestra un indicador de progreso.

MAPI_MOVE

CopyTo debe realizar una operación de movimiento en lugar de una operación de copia. Cuando no se establece esta marca, CopyTo realiza una operación de copia.

MAPI_NOREPLACE

No se deben sobrescribir las propiedades existentes en el objeto de destino. Cuando no se establece esta marca, CopyTo sobrescribe las propiedades existentes.

lppProblems

[entrada, salida] En la entrada, un puntero a un puntero a una estructura SPropProblemArray ; De lo contrario, null, que indica que no se necesita información de error. Si lppProblems es un puntero válido en la entrada, CopyTo devuelve información detallada sobre los errores al copiar una o varias propiedades.

Valor devuelto

S_OK

Las propiedades se han copiado o movido correctamente.

MAPI_E_COLLISION

No se puede copiar un subobjeto porque ya existe un subobjeto con el mismo nombre para mostrar especificado por la propiedad PR_DISPLAY_NAME (PidTagDisplayName) en el objeto de destino.

MAPI_E_DECLINE_COPY

El proveedor de servicios no implementa la operación de copia.

MAPI_E_FOLDER_CYCLE

El objeto de origen que realiza la operación de copia o movimiento directa o indirectamente contiene el objeto de destino. Es posible que se haya realizado un trabajo significativo antes de que se detectara esta condición, por lo que los objetos de origen y destino podrían modificarse parcialmente.

MAPI_E_INTERFACE_NOT_SUPPORTED

El objeto de destino no admite la interfaz identificada por el parámetro lpInterface .

MAPI_E_NO_ACCESS

Se intentó acceder a un objeto para el que el autor de la llamada no tiene permisos suficientes. Este error se devuelve si el objeto de destino es el mismo que el objeto de origen.

Los siguientes valores se pueden devolver en la estructura SPropProblemArray , pero no como valores devueltos para CopyTo. Los siguientes errores se aplican a una sola propiedad:

MAPI_E_BAD_CHARWIDTH

Se estableció la marca MAPI_UNICODE y CopyTo no admite Unicode o MAPI_UNICODE no se estableció y CopyTo solo admite Unicode.

MAPI_E_COMPUTED

El autor de la llamada no puede modificar la propiedad porque es una propiedad de solo lectura calculada por el propietario del objeto de destino. Este error no es grave; el autor de la llamada debe permitir que continúe la operación de copia.

MAPI_E_INVALID_TYPE

El tipo de propiedad no es válido.

MAPI_E_UNEXPECTED_TYPE

El tipo de propiedad no es el tipo esperado por el autor de la llamada.

Comentarios

De forma predeterminada, el método IMAPIProp::CopyTo copia o mueve todas las propiedades del objeto actual a un objeto de destino. CopyTo se usa cuando un objeto se debe copiar o mover exactamente, con todas o la mayoría de sus propiedades intactas.

Los subobjetos del objeto de origen se incluyen automáticamente en la operación y se copian o mueven en su totalidad. De forma predeterminada, CopyTo sobrescribe las propiedades del objeto de destino que coincidan con las propiedades del objeto de origen. Si ya existe alguna de las propiedades copiadas o movidas en el objeto de destino, las propiedades existentes se sobrescriben con las nuevas propiedades, a menos que la marca de MAPI_NOREPLACE se establezca en el parámetro ulFlags . La información existente en el objeto de destino que no se sobrescribe queda intacta.

Notas a los implementadores

Puede proporcionar una implementación completa de CopyTo o confiar en la implementación que MAPI proporciona en su objeto de soporte técnico. Si desea usar la implementación mapi, llame a IMAPISupport::D oCopyTo. Sin embargo, si delega el procesamiento en DoCopyTo y se le pasa la marca de MAPI_DECLINE_OK, evite la llamada de soporte técnico y devuelva MAPI_E_DECLINE_COPY en su lugar. MAPI llamará con esta marca para evitar la posible recursividad que puede producirse cuando se copian las carpetas.

Dado que la operación de copia puede ser larga, debe mostrar un indicador de progreso. Use la implementación IMAPIProgress pasada en el parámetro lpProgress , si hay una. Si lpProgress es null, llame al método IMAPISupport::D oProgressDialog para usar la implementación mapi.

No intente establecer ninguna propiedad de solo lectura conocida en el objeto de destino; devuelve MAPI_E_NO_ACCESS en su lugar.

Los objetos de origen y destino deben usar las mismas interfaces. Devuelve MAPI_E_INVALID_PARAMETER si lpInterface no está establecido.

Devuelve MAPI_E_INTERFACE_NOT_SUPPORTED si se excluyen todas las interfaces conocidas.

Notas para los llamadores

No establezca la marca de MAPI_DECLINE_OK; MAPI lo usa en sus llamadas a implementaciones copyto del proveedor de almacenes de mensajes.

Dado que las operaciones de copia y movimiento pueden tardar tiempo, debe solicitar la visualización de un indicador de progreso estableciendo la marca de MAPI_DIALOG. Puede establecer el parámetro lpProgress en la implementación de IMAPIProgress, si tiene uno, o en null. Si lpProgress es null, CopyTo usará el indicador de progreso predeterminado que proporciona MAPI.

Puede suprimir la visualización de un indicador de progreso si no establece la marca de MAPI_DIALOG. CopyTo omitirá los parámetros ulUIParam y lpProgress y no mostrará el indicador.

CopyTo puede notificar errores globales e individuales, o errores que se producen con una o varias propiedades. Estos errores individuales se colocan en una estructura SPropProblemArray . Puede suprimir los informes de errores en el nivel de propiedad pasando null, en lugar de un puntero válido, para el parámetro de estructura de matriz de problemas de propiedad.

Si desea recibir información sobre los errores, pase un puntero de estructura SPropProblemArray válido en el parámetro lppProblems . Cuando CopyTo devuelve S_OK, compruebe si hay posibles errores con propiedades individuales en la estructura. Cuando CopyTo devuelve un error, no se devuelve información en la estructura SPropProblemArray . En su lugar, llame a IMAPIProp::GetLastError para recuperar información detallada del error.

Si CopyTo devuelve S_OK, libere la estructura SPropProblemArray devuelta llamando a la función MAPIFreeBuffer .

Si copia propiedades que son únicas para el tipo de objeto de origen, debe asegurarse de que el objeto de destino es del mismo tipo. CopyTo no impide asociar propiedades que normalmente pertenecen a un tipo de objeto con otro tipo de objeto. Depende de usted copiar las propiedades que tienen sentido para el objeto de destino. Por ejemplo, no debe copiar las propiedades del mensaje en un contenedor de libreta de direcciones.

Para asegurarse de copiar entre objetos del mismo tipo, compruebe que el objeto de origen y de destino sean del mismo tipo, ya sea comparando punteros de objeto o llamando a IUnknown::QueryInterface. Establezca el identificador de interfaz al que apunta lpInterface en la interfaz estándar para el objeto de origen. Además, asegúrese de que el tipo de objeto o la propiedad PR_OBJECT_TYPE (PidTagObjectType) es la misma para los dos objetos. Por ejemplo, si copia desde un mensaje, establezca lpInterface en IID_IMessage y el PR_OBJECT_TYPE de ambos objetos para MAPI_MESSAGE.

Si se pasa un puntero no válido en el parámetro lpDestObj , los resultados son impredecibles.

Excluir las propiedades de una llamada CopyTo puede ser útil. Por ejemplo, algunos objetos tienen propiedades específicas de una única instancia del objeto, como la fecha y hora de entrega de mensajes. Para evitar copiar el tiempo de entrega de un mensaje al copiar el mensaje en otra carpeta, especifique PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) en la matriz de exclusión de etiqueta de propiedad. Para excluir la lista de destinatarios de un mensaje, agregue la propiedad PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) a la matriz exclude. Para excluir los datos adjuntos de un mensaje, agregue la propiedad PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) a la matriz.

De forma similar, evite copiar o mover la jerarquía o la tabla de contenido de un contenedor de carpetas o libretas de direcciones incluyendo PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) o PR_CONTAINER_CONTENTS (PidTagContainerContents) en la matriz de exclusión de etiquetas de propiedad.

Para excluir propiedades de la operación de copia o movimiento, incluya sus etiquetas de propiedad en el parámetro lpExcludeProps . Si pasa los resultados de la macro PROP_TAG para compilar una etiqueta de propiedad a partir de un identificador específico en la matriz de etiquetas de propiedad, se excluirán todas las propiedades con ese identificador. Por ejemplo, la siguiente entrada en la matriz de etiquetas de propiedad hace que se excluyan todas las propiedades con un identificador de 0x8002, independientemente del tipo:

PROP_TAG(PT_LONG, 0x8002)

La etiqueta de propiedad PR_NULL (PidTagNull) no se puede incluir en la matriz lpExcludeProps .

La utilidad de la característica CopyTo para excluir interfaces quizás no sea tan obvia como la utilidad de excluir propiedades. Puede excluir una interfaz al copiar en un objeto que no tiene conocimiento de un grupo de propiedades. Por ejemplo, si copia propiedades de una carpeta en un archivo adjunto, las únicas propiedades con las que pueden trabajar los datos adjuntos son las propiedades genéricas disponibles con cualquier implementación IMAPIProp . Al excluir IMAPIFolder de la operación de copia, los datos adjuntos no recibirán ninguna de las propiedades de carpeta más específicas.

Cuando se usa el parámetro rgiidExclude para excluir una interfaz, también se excluyen todas las interfaces derivadas de esa interfaz. Por ejemplo, la exclusión de IMAPIContainer hace que se excluyan carpetas o contenedores de libreta de direcciones, en función del tipo de proveedor. No excluya IMAPIProp o IUnknown porque muchas interfaces se derivan de ellas.

Omita MAPI_E_COMPUTED errores devueltos en la estructura SPropProblemArray del parámetro lppProblems .

Referencia de MFCMAPI

Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.

Archivo	Función	Comment
File.cpp	LoadFromMSG	MFCMAPI usa el método IMAPIProp::CopyTo para copiar propiedades de un archivo .msg a un objeto IMAPIMessageSite .
FolderDlg.cpp	CFolderDlg::HandlePaste	MFCMAPI usa el método IMAPIProp::CopyTo para copiar las propiedades de un mensaje de origen en un mensaje de destino durante una operación de pegado.