IMAPIProp::CopyProps

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Copia o mueve las propiedades seleccionadas.

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

Parameters

lpIncludeProps

[in] Puntero a una matriz de etiquetas de propiedad que especifica las propiedades que se van a copiar o mover. PR_NULL (PidTagNull) no se puede incluir en la matriz. El parámetro lpIncludeProps no puede ser null.

ulUIParam

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

lpProgress

[in] Puntero a una implementación de un indicador de progreso. Si se pasa null en el parámetro lpProgress , el indicador de progreso se muestra mediante la implementación mapi. 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 debe usar para tener acceso 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 CopyProps llama al método IMAPISupport::D oCopyProps 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

CopyProps debe realizar una operación de movimiento en lugar de una operación de copia. Cuando no se establece esta marca, CopyProps 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, CopyProps 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 es necesario obtener información de error. Si lppProblems es un puntero válido en la entrada, CopyProps 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 un subobjeto con el mismo nombre para mostrar, definido por la propiedad PR_DISPLAY_NAME (PidTagDisplayName), ya existe 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 CopyProps. Estos errores se aplican a una sola propiedad.

MAPI_E_BAD_CHARWIDTH

Se estableció la marca MAPI_UNICODE y CopyProps no admite Unicode o MAPI_UNICODE no se estableció y CopyProps 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 IMAPIProp::CopyProps copia o mueve las propiedades seleccionadas del objeto actual a un objeto de destino. CopyProps se usa principalmente para responder y reenviar mensajes, donde solo algunas de las propiedades del mensaje original viajan con la respuesta o la copia reenviada.

Los subobjetos del objeto de origen se incluyen automáticamente en la operación y se copian o mueven en su totalidad, independientemente del uso de propiedades indicadas por la estructura SPropTagArray . De forma predeterminada, CopyProps 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 CopyProps o confiar en la implementación que PROPORCIONA MAPI en su objeto de soporte técnico. Si desea usar la implementación mapi, llame al método IMAPISupport::D oCopyProps . Sin embargo, si delega el procesamiento en DoCopyProps 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 le llamará con esta marca para evitar la posible recursividad que puede producirse al copiar carpetas.

Dado que la operación de copia puede ser larga, debe mostrar un indicador de progreso. Use la implementación de IMAPIProgress que se pasa 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.

Notas para los llamadores

No establezca la marca de MAPI_DECLINE_OK; mapi lo usa en sus llamadas a implementaciones copyprops del proveedor de almacén de mensajes.

Dado que las operaciones de copia y movimiento pueden tardar tiempo, es aconsejable 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, CopyProps usará el indicador de progreso predeterminado proporcionado por MAPI.

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

CopyProps puede notificar errores globales e individuales, o errores que se producen con una o varias de las 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 CopyProps devuelve S_OK, compruebe si hay posibles errores con propiedades individuales en la estructura. Cuando CopyProps devuelve un error, no se devuelve información en la estructura SPropProblemArray . En su lugar, llame al método IMAPIProp::GetLastError para recuperar información detallada del error.

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

Si va a copiar propiedades que son únicas para el tipo de objeto de origen, debe asegurarse de que el objeto de destino es del mismo tipo. CopyProps 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 que está copiando 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 al método 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 va a copiar desde un mensaje, establezca lpInterface en IID_IMessage y el PR_OBJECT_TYPE para que ambos objetos MAPI_MESSAGE.

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

Para copiar la lista de destinatarios de un mensaje, llame al método CopyProps del mensaje e incluya la propiedad PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) en la matriz de etiquetas de propiedad. Para copiar los datos adjuntos del mensaje, incluya la propiedad PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments).

Para copiar la jerarquía o la tabla de contenido de un contenedor de carpetas o libretas de direcciones, incluya las propiedades PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) o PR_CONTAINER_CONTENTS (PidTagContainerContents) en la matriz de etiquetas de propiedad. Para incluir la tabla de contenido asociada de una carpeta, incluya la propiedad PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) en la matriz.

Referencia de MFCMAPI

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

Archivo	Función	Comment
MAPIFunctions.cpp	CopyNamedProps	MFCMAPI usa el método IMAPIProp::CopyProps para copiar las propiedades con nombre de un mensaje a otro.
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl::OnPasteProperty	MFCMAPI usa el método IMAPIProp::CopyProps para pegar una propiedad que se ha copiado de otro objeto.