IMAPIProp::OpenProperty
Hace referencia a: Outlook 2013 | Outlook 2016
Devuelve un puntero a una interfaz que se puede usar para acceder a una propiedad.
HRESULT OpenProperty(
ULONG ulPropTag,
LPCIID lpiid,
ULONG ulInterfaceOptions,
ULONG ulFlags,
LPUNKNOWN FAR * lppUnk
);
Parameters
ulPropTag
[in] Etiqueta de propiedad de la propiedad a la que se va a tener acceso. Tanto el identificador como el tipo deben incluirse en la etiqueta de propiedad.
lpiid
[in] Puntero al identificador de la interfaz que se va a usar para acceder a la propiedad . El parámetro lpiid no debe ser null.
ulInterfaceOptions
[in] Datos relacionados con la interfaz identificada por el parámetro lpiid .
ulFlags
[in] Máscara de bits de marcas que controla el acceso a la propiedad . Se pueden establecer las siguientes marcas:
MAPI_CREATE
Si la propiedad no existe, se debe crear. Si la propiedad existe, se debe descartar el valor actual de la propiedad. Cuando un llamador establece la marca de MAPI_CREATE, también debe establecer la marca de MAPI_MODIFY.
MAPI_DEFERRED_ERRORS
Permite que OpenProperty devuelva correctamente, posiblemente antes de que el objeto esté totalmente disponible para el autor de la llamada. Si el objeto no está disponible, la realización de una llamada de objeto posterior puede generar un error.
MAPI_MODIFY
MAPI_MODIFY es necesario en estas situaciones:
Al abrir una propiedad de secuencia, como IID_IStream, para modificarla.
Al abrir datos adjuntos de un mensaje incrustado, como PR_ATTACH_DATA_OBJ abierto con IID_IMessage, para modificarlo.
lppUnk
[out] Puntero a la interfaz solicitada que se va a usar para el acceso a propiedades.
Valor devuelto
S_OK
El puntero de interfaz solicitado se devolvió correctamente.
MAPI_E_INTERFACE_NOT_SUPPORTED
No se admite la interfaz solicitada para esta propiedad.
MAPI_E_NO_ACCESS
El autor de la llamada no tiene permisos suficientes para acceder a la propiedad .
MAPI_E_NO_SUPPORT
El objeto no puede proporcionar acceso a esta propiedad a través de la interfaz solicitada.
MAPI_E_NOT_FOUND
La propiedad solicitada no existe y MAPI_CREATE no se estableció en el parámetro ulFlags .
MAPI_E_INVALID_PARAMETER
El tipo de propiedad de la etiqueta se establece en PT_UNSPECIFIED.
Comentarios
El método IMAPIProp::OpenProperty proporciona acceso a una propiedad a través de una interfaz determinada. OpenProperty es una alternativa a los métodos IMAPIProp::GetProps e IMAPIProp::SetProps . Cuando se produce un error en GetProps o SetProps porque la propiedad es demasiado grande o demasiado compleja, llame a OpenProperty. OpenProperty se usa normalmente para acceder a las propiedades de tipo PT_OBJECT.
Notas para los llamadores
Para acceder a los datos adjuntos del mensaje, abra la propiedad PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) con un identificador de interfaz diferente, en función del tipo de datos adjuntos. En la tabla siguiente se describe cómo llamar a OpenProperty para los diferentes tipos de datos adjuntos:
| Tipo de datos adjuntos | Identificador de interfaz que se va a usar |
|---|---|
| Binario |
IID_IStream |
| Cadena |
IID_IStream |
| Mensaje |
IID_IMessage |
| OLE 2.0 |
IID_IStreamDocfile |
IStreamDocfile es un derivado de la interfaz IStream que se basa en un archivo compuesto OLE 2.0. IStreamDocfile es la mejor opción para acceder a los datos adjuntos de OLE 2.0 porque implica la menor cantidad de sobrecarga. Puede usar IID_IStreamDocFile para las propiedades que contienen datos almacenados en almacenamiento estructurado disponibles a través de la interfaz IStorage .
Para obtener más información sobre cómo usar OpenProperty con datos adjuntos, vea la propiedad PR_ATTACH_DATA_OBJ y Abrir datos adjuntos.
No use el puntero IStream que recibe para llamar a su método Seek o SetSize a menos que use una posición cero o una variable de tamaño. Además, no se base en el valor del parámetro de salida plibNewPosition devuelto desde la llamada a Seek .
Si llama a OpenProperty para acceder a una propiedad con la interfaz IStream , use solo esa interfaz para realizar cambios en ella. No intente actualizar la propiedad con ninguno de los otros métodos IMAPIProp : IUnknown , como SetProps o IMAPIProp::D eleteProps.
No intente abrir una propiedad con OpenProperty más de una vez. Los resultados no están definidos porque pueden variar de proveedor a proveedor.
Si necesita modificar la propiedad que se va a abrir, establezca la marca de MAPI_MODIFY. Si no está seguro de si el objeto admite la propiedad pero cree que debe hacerlo, establezca las marcas MAPI_CREATE y MAPI_MODIFY. Cada vez que se establece MAPI_CREATE, también se debe establecer MAPI_MODIFY.
Es responsable de volver a convertir el puntero de interfaz devuelto en el parámetro lppUnk a uno adecuado para la interfaz especificada en el parámetro lpiid . También debe usar el puntero devuelto para llamar a su método IUnknown::Release cuando haya terminado con él.
A veces, establecer las marcas en el parámetro ulFlags no es suficiente para indicar el tipo de acceso a la propiedad necesaria. Puede colocar datos adicionales, como marcas, en el parámetro ulInterfaceOptions . Estos datos dependen de la interfaz. Algunas interfaces (como IStream) lo usan y otras no. Por ejemplo, al abrir una propiedad que se va a modificar con IStream, establezca la marca STGM_WRITE en el parámetro ulInterfaceOptions además de MAPI_MODIFY. Al abrir una tabla mediante la interfaz IMAPITable , puede establecer ulInterfaceOptions en MAPI_UNICODE para indicar si las columnas de la tabla que contienen propiedades de cadena deben estar en formato Unicode.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| StreamEditor.cpp |
CStreamEditor::ReadTextStreamFromProperty |
MFCMAPI usa el método IMAPIProp::OpenProperty para recuperar una interfaz de flujo para propiedades binarias y de texto de gran tamaño. |