IMAPIProp::GetProps

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Recupera el valor de propiedad de una o varias propiedades de un objeto.

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

Parameters

lpPropTagArray

[in] Puntero a una matriz de etiquetas de propiedad que identifican las propiedades cuyos valores se van a recuperar. El parámetro lpPropTagArray debe ser NULL, lo que indica que se deben devolver valores para todas las propiedades del objeto, o bien apuntar a una estructura SPropTagArray que contenga una o varias etiquetas de propiedad.

ulFlags

[in] Máscara de bits de marcas que indica el formato de las propiedades que tienen el tipo PT_UNSPECIFIED. Se puede establecer la marca siguiente:

MAPI_UNICODE

Los valores de cadena de estas propiedades deben devolverse en formato Unicode. Si no se establece la marca MAPI_UNICODE, los valores de cadena deben devolverse en el formato ANSI.

lpcValues

[out] Puntero a un recuento de valores de propiedad a los que apunta el parámetro lppPropArray . Si lppPropArray es NULL, el contenido del parámetro lpcValues es cero.

lppPropArray

[out] Puntero a un puntero a los valores de propiedad recuperados.

Valor devuelto

S_OK

Los valores de propiedad se recuperaron correctamente.

MAPI_W_ERRORS_RETURNED

La llamada se realizó correctamente en general, pero no se pudo acceder a una o varias propiedades. El miembro aulPropTag del valor de propiedad para cada propiedad no disponible tiene un tipo de propiedad de PT_ERROR y un identificador de cero. 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.

MAPI_E_INVALID_PARAMETER

Se pasó cero en el miembro cValues de la estructura SPropTagArray a la que apunta lpPropTagArray.

Comentarios

El método IMAPIProp::GetProps obtiene los valores de propiedad de una o varias propiedades de un objeto.

Los valores de propiedad se devuelven en el mismo orden que se solicitaron (es decir, el orden de las propiedades de la matriz de etiquetas de propiedad a la que apunta lpPropTagArray coincide con el orden de la matriz de estructuras de valor de propiedad a las que apunta lppPropArray).

Los tipos de propiedad especificados en los miembros aulPropTag de la matriz de etiquetas de propiedad indican el tipo de valor que se debe devolver en el miembro Value de cada estructura de valor de propiedad. Sin embargo, si el autor de la llamada no conoce el tipo de una propiedad, el tipo del miembro aulPropTag se puede establecer en su lugar en PT_UNSPECIFIED. Al recuperar el valor, GetProps establece el tipo correcto en el miembro aulPropTag de la estructura de valores de propiedad de la propiedad.

Si se especifican tipos de propiedad en SPropTagArray en lpPropTagArray, los valores de propiedad de SPropValue devueltos en lppPropArray tienen tipos que coinciden exactamente con los tipos solicitados, a menos que se devuelva un valor de error en su lugar.

Las propiedades de cadena pueden tener uno de los dos tipos de propiedad: PT_UNICODE para representar el formato Unicode y PT_STRING8 para representar el formato ANSI. Si la marca de MAPI_UNICODE se establece en el parámetro ulFlags , siempre que GetProps no pueda determinar el formato adecuado para una propiedad de cadena, devuelve su valor en formato Unicode. GetProps no puede determinar un tipo de propiedad de cadena exacto en las situaciones siguientes:

El parámetro lpPropTagArray se establece en NULL para solicitar todas las propiedades.
El miembro aulPropTag incluye el valor PT_UNSPECIFIED como su tipo de propiedad en la matriz de etiquetas de propiedad.

Si el parámetro lpPropTagArray se establece en NULL para recuperar todas las propiedades del objeto y no existen propiedades, GetProps hace lo siguiente:

Devuelve S_OK.
Establece el valor de recuento en el miembro cValues de la estructura de valores de propiedad en 0.
Establece el contenido de lpcValues en 0.
Establece lppPropArray en NULL.

GetProps no debe devolver propiedades de varios valores con cValues establecido en 0.

Notas a los implementadores

Llame a la función MAPIAllocateBuffer para asignar memoria inicialmente para la estructura SPropValue a la que apunta lpPropTagArray; llame a MAPIAllocateMore para asignar cualquier memoria adicional necesaria para los miembros de la estructura.

Devuelve MAPI_W_ERRORS_RETURNED si no puede recuperar el valor de una o varias de las propiedades solicitadas. En la estructura de valores de propiedad, establezca el tipo del miembro aulPropTag en PT_ERROR y el miembro Value en un código de estado que describa el error. Por ejemplo, si tiene que convertir una cadena en Unicode y no admite Unicode, establezca el miembro Value en MAPI_E_BAD_CHARWIDTH. Si la propiedad es demasiado grande, establézcala en MAPI_E_NOT_ENOUGH_MEMORY. Si el objeto no admite la propiedad , establézcala en MAPI_E_NOT_FOUND.

La implementación del proveedor de transporte remoto del método GetProps debe devolver los valores de propiedad de la carpeta para las propiedades solicitadas por el autor de la llamada. La implementación debe hacer lo siguiente:

Asigne una matriz de valores de propiedad para volver al autor de la llamada y almacenar su dirección en el parámetro de puntero de valor de propiedad pasado para ese propósito.
Copie las etiquetas de propiedad de las propiedades de la carpeta en las etiquetas de propiedad de la matriz de valores de propiedad según la matriz de etiquetas de propiedad que se pasan a GetProps.
Asegúrese de que el tipo de propiedad está establecido para todas las etiquetas de propiedad que se pasan a GetProps. El autor de la llamada puede pasar un tipo de propiedad de PT_UNSPECIFIED, en cuyo caso GetProps debe establecer el tipo de propiedad correcto para esa etiqueta de propiedad.
Establezca el valor de cada propiedad de la matriz de valores de propiedad según su etiqueta. Por ejemplo, si la etiqueta de propiedad solicitada por el autor de la llamada es PR_OBJECT_TYPE (PidTagObjectType), GetProps puede establecer el valor en MAPI_FOLDER.
Si el autor de la llamada pasa las etiquetas de propiedad que no controla la implementación, puede establecer la etiqueta de propiedad en PT_ERROR para esas propiedades y establecer el valor de propiedad en MAPI_E_NOT_FOUND.
Devuelve S_OK si no se produjo ningún error o MAPI_W_ERRORS_RETURNED si se produjeron errores.

Como mínimo, la implementación del proveedor de transporte remoto del método GetProps debe admitir las siguientes propiedades:

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

Notas para los llamadores

Para las propiedades de tipo PT_OBJECT, llame al método IMAPIProp::OpenProperty en lugar de a GetProps.

Para las propiedades seguras, no espere recuperarlas llamando a GetProps con el parámetro lppPropTagArray establecido en NULL. Debe establecer explícitamente el identificador de una propiedad segura en el miembro aulPropTag de su matriz de etiquetas de propiedad al llamar a GetProps. El proveedor de servicios depende de cuándo y cómo está disponible una propiedad segura.

Libere la estructura SPropValue devuelta llamando a la función MAPIFreeBuffer solo si GetProps devuelve S_OK o MAPI_W_ERRORS_RETURNED.

Si GetProps devuelve MAPI_W_ERRORS_RETURNED porque no pudo acceder a una o varias propiedades, compruebe las etiquetas de propiedad de las propiedades devueltas. Las propiedades con errores tendrán los siguientes valores establecidos en su estructura de valores de propiedad:

Tipo de propiedad en el miembro aulPropTag establecido en PT_ERROR.
Valor de propiedad del miembro Value establecido en un código de estado para el error, como MAPI_E_NOT_FOUND.

Las propiedades que producen un error porque son demasiado grandes para devolverse convenientemente en la estructura de valores de propiedad tienen su miembro Value establecido en MAPI_E_NOT_ENOUGH_MEMORY. Normalmente, esto ocurre con las propiedades de cadena o binarias de tipo PT_STRING8, PT_UNICODE o PT_BINARY cuando el valor de la propiedad es de 4 KB o más. Llame a IMAPIProp::OpenProperty para recuperar propiedades grandes.

No todas las implementaciones de GetProps admiten los formatos Unicode y ANSI para las cadenas de caracteres. Cuando una propiedad determinada requiere la conversión de formato de cadena y GetProps no puede admitirla, el miembro Value de la propiedad se establece en MAPI_E_BAD_CHARWIDTH.

Para comprobar si un PST es un PST de SharePoint, monte el PST mediante IMAPISession::OpenMsgStore y, a continuación, llame a GetProps en el objeto del almacén de mensajes que solicita esta propiedad. Si existe, puede suponer que el PST se ha configurado para SharePoint; Si no es así, el PST no se ha configurado como un PST de SharePoint.

Para obtener más información sobre cómo usar GetProps para acceder a las propiedades, vea Recuperar propiedades MAPI.

Referencia de MFCMAPI

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

Archivo	Función	Comment
MAPIFunctions.cpp	GetPropsNULL	MFCMAPI usa el método IMAPIProp::GetProps para obtener todas las propiedades de un objeto pasando NULL o la matriz devuelta por el método IMAPIProp::GetPropList en el parámetro lpPropTagArray .