IMAPISupport::DoCopyTo

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Copia o mueve todas las propiedades de un objeto, excepto las propiedades excluidas específicamente, a otro objeto.

HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpSrcInterface

[in] Puntero al identificador de interfaz (IID) que representa la interfaz que se va a usar para acceder al objeto que tiene las propiedades que se van a copiar o mover.

lpSrcObj

[in] Puntero al objeto que tiene las propiedades que se van a copiar o mover.

ciidExclude

[in] Recuento de interfaces que se van a excluir al copiar o mover propiedades.

rgiidExclude

[in] Matriz de identificadores de interfaz que indica interfaces que no se deben usar al copiar o mover 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. DoCopyTo devuelve MAPI_E_INVALID_PARAMETER cuando el miembro cValues de la estructura SPropTagArray a la que apunta lpExcludeProps está establecido 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 .

lpDestInterface

[in] Puntero al identificador de interfaz que representa la interfaz que se va a usar para acceder al objeto para recibir las propiedades copiadas o movidas.

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_DIALOG

Muestra un indicador de progreso.

MAPI_MOVE

DoCopyTo debe realizar una operación de movimiento en lugar de una operación de copia. Cuando no se establece esta marca, DoCopyTo 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, DoCopyTo sobrescribe las propiedades existentes.

lppProblems

[out] 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, DoCopyTo 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

Ya existe una propiedad que se va a copiar o mover en el objeto de destino y se establece la marca de MAPI_NOREPLACE.

MAPI_E_FOLDER_CYCLE

El objeto de origen contiene directa o indirectamente 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

La interfaz identificada por el parámetro lpSrcInterface no es compatible con el objeto al que apunta lpSrcObj, o la interfaz identificada por el parámetro lpDestInterface no es compatible con el objeto al que apunta lpDestObj.

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.

MAPI_E_INVALID_PARAMETER

El parámetro lpSrcInterface es NULL.

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

MAPI_E_BAD_CHARWIDTH

Se estableció la marca MAPI_UNICODE y DoCopyTo no admite Unicode o MAPI_UNICODE no se estableció y DoCopyTo 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

El método IMAPISupport::D oCopyTo se implementa para los objetos de compatibilidad del proveedor del almacén de mensajes. Los proveedores de almacén de mensajes pueden llamar a DoCopyTo para implementar el método IMAPIProp::CopyTo para sus carpetas y mensajes.

De forma predeterminada, DoCopyTo copia o mueve todas las propiedades de un objeto a otro objeto. Los subobjetos del objeto de origen se incluyen automáticamente en la operación y se copian o mueven en su totalidad.

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 para los llamadores

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

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, para evitar la copia o el movimiento de la jerarquía o la tabla de contenido de un contenedor de carpetas o libretas de direcciones, incluya PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) o PR_CONTAINER_CONTENTS (PidTagContainerContents) en la matriz de exclusión de etiquetas de propiedad.

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

El identificador de interfaz al que apunta lpSrcInterface suele ser el mismo que el identificador de interfaz al que apunta lpDestInterface .

Si pasa un identificador de interfaz aceptable en lpDestInterface pero un puntero no válido en lpDestObj, los resultados son impredecibles. Lo más probable es que esto provoque un error en el proveedor.

Por el contrario, si conoce información complementaria que no se debe copiar ni mover, agregue los identificadores de interfaz para que las interfaces se excluyan en la matriz pasada en el parámetro rgiidExclude . Por ejemplo, si va a copiar mensajes, pero no ninguno de sus datos adjuntos, pase IID_IMessage en la matriz rgiidExclude . DoCopyTo omite las interfaces enumeradas en rgiidExclude que no reconoce.

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 la interfaz 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.

DoCopyTo notifica errores globales que se aplican a la operación en su conjunto y errores individuales que se aplican a propiedades individuales. 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 DoCopyTo devuelve S_OK, compruebe si hay posibles errores con propiedades individuales en la estructura. Cuando DoCopyTo devuelve un error, no se devuelve información en la estructura SPropProblemArray . En su lugar, llame al método IMAPISupport::GetLastError para recuperar información detallada del error.

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

Si se produce un error global en la llamada a DoCopyTo , no use ni libere la estructura SPropProblemArray . Los proveedores deben omitir el miembro ulIndex en las estructuras SPropProblemArray devueltas por DoCopyTo.