IMAPIProp::GetNamesFromIDs
Hace referencia a: Outlook 2013 | Outlook 2016
Proporciona los nombres de propiedad que corresponden a uno o varios identificadores de propiedad.
HRESULT GetNamesFromIDs(
LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
);
Parameters
lppPropTags
[entrada, salida] En la entrada, un puntero a una estructura SPropTagArray que contiene una matriz de etiquetas de propiedad; de lo contrario, NULL, que indica que se deben devolver todos los nombres. El miembro cValues de la matriz de etiquetas de propiedad no puede ser 0. Si lppPropTags es un puntero válido en la entrada, GetNamesFromIDs devuelve nombres para cada identificador de propiedad incluido en la matriz.
lpPropSetGuid
[in] Puntero a un GUID, o estructura GUID , que identifica un conjunto de propiedades. El parámetro lpPropSetGuid puede apuntar a un conjunto de propiedades válido o puede ser NULL.
ulFlags
[in] Máscara de bits de marcas que indica el tipo de nombres que se van a devolver. Se pueden usar las siguientes marcas (si se establecen ambas marcas, no se devolverá ningún nombre):
MAPI_NO_IDS
Solicitudes que solo se devuelven nombres almacenados como cadenas Unicode.
MAPI_NO_STRINGS
Solicitudes que solo se devuelven nombres almacenados como identificadores numéricos.
lpcPropNames
[out] Puntero a un recuento de punteros de nombre de propiedad en la matriz a la que apunta el parámetro lppPropNames .
lpppPropNames
[out] Puntero a una matriz de punteros a estructuras MAPINAMEID que contiene nombres de propiedad.
Valor devuelto
S_OK
Los nombres de propiedad se devolvieron correctamente.
MAPI_E_NO_SUPPORT
El objeto no admite propiedades con nombre.
MAPI_W_ERRORS_RETURNED
La llamada se realizó correctamente en general, pero no se pudieron devolver los nombres de una o varias propiedades. Las etiquetas de propiedad de las propiedades con errores tienen un tipo de propiedad de PT_ERROR. 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
El miembro cValues de una o varias de las entradas de la matriz de etiquetas de propiedad a la que apunta lppPropTags se establece en 0.
Comentarios
Aunque el acceso a la mayoría de las propiedades es por identificador de propiedad, se puede acceder a algunas propiedades por nombre. Se puede llamar al método IMAPIProp::GetNamesFromIDs para hacer lo siguiente:
Recupere los nombres de identificadores de propiedad específicos de un conjunto de propiedades específico.
Recupere los nombres de identificadores de propiedad específicos en cualquier conjunto de propiedades.
Recupere los nombres de todas las propiedades con nombre que se incluyen en la asignación del objeto.
Si lppPropTags apunta a una matriz de etiquetas de propiedad válida con uno o más identificadores de propiedad y lpPropSetGuid apunta a un conjunto de propiedades válido, GetNamesFromIDs omite el conjunto de propiedades y los tipos de propiedad y devuelve todos los nombres que se asignan a los identificadores especificados.
Si lppPropTags apunta a una matriz de etiquetas de propiedad válida con uno o más identificadores de propiedad y lpPropSetGuid es NULL, GetNamesFromIDs devuelve todos los nombres que se asignan a los identificadores especificados.
Si un identificador especificado no tiene un nombre, GetNamesFromIDs devuelve NULL en el lugar de ese identificador en la estructura devuelta en lpppPropNames y también devuelve MAPI_W_ERRORS_RETURNED.
Si lpPropSetGuid y lppPropTags son NULL, GetNamesFromIDs asigna una nueva matriz de etiquetas de propiedad y devuelve todos los nombres de todas las propiedades con nombre para el objeto.
Cuando no hay nombres que devolver, quizás porque no hay propiedades en el conjunto de propiedades solicitado o todas las propiedades son de un tipo excluido por las marcas, GetNamesFromIDs hace lo siguiente:
Devuelve S_OK.
Asigna una nueva estructura SPropTagArray , estableciendo el miembro cValues en 0.
Establece el contenido de lpcPropNames en 0.
Establece el contenido de lpppPropNames en NULL.
Notas a los implementadores
Si lpPropSetGuid apunta a un conjunto de propiedades válido y lppPropTags es NULL, el resultado no está definido. Puede usar una de las siguientes estrategias:
Omita el conjunto de propiedades y devuelva los nombres de los identificadores de la matriz de etiquetas de propiedad.
Devuelve los nombres de solo los identificadores de la matriz de etiquetas de propiedad que pertenecen al conjunto de propiedades especificado.
Se produce un error en la llamada y se devuelve MAPI_E_INVALID_PARAMETER.
Notas para los llamadores
Para recuperar todas las propiedades con nombre de un objeto, primero debe llamar al método IMAPIProp::GetPropList del objeto y, a continuación, pasar los identificadores devueltos que están por encima del intervalo de 0x8000 a GetNamesFromIDs.
Si pasa un conjunto de propiedades válido, pero no una matriz de etiquetas de propiedad válida, prepárese para obtener resultados impredecibles. Algunas implementaciones de GetNamesFromID omiten el conjunto de propiedades y devuelven los nombres de los identificadores de la matriz de etiquetas de propiedad. Algunas implementaciones devuelven MAPI_E_INVALID_PARAMETER. Otras implementaciones devuelven nombres para los identificadores de todas las propiedades del conjunto de propiedades. Si el conjunto de propiedades está PS_PUBLIC_STRINGS, GetNamesFromIDs puede devolver todos los nombres que se hayan creado. No importa si el proveedor de servicios almacena una propiedad en los identificadores asociados a las cadenas públicas.
Cuando haya terminado con los nombres de propiedad, compruebe el contenido del parámetro lpcPropNames para determinar si se devolvieron los nombres. Si es así, llame a la función MAPIFreeBuffer para liberar la memoria a la que apuntan lppPropTags y lpppPropNames cuando se devuelve un resultado correcto. Una llamada a MAPIFreeBuffer es suficiente para cada parámetro; no es necesario recorrer la matriz de punteros y liberar cada estructura MAPINAMEID individualmente.
Para obtener más información sobre las propiedades con nombre, vea Propiedades con nombre MAPI.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedProps |
MFCMAPI usa el método IMAPIProp::GetNamesFromIDs para buscar las propiedades con nombre que se han asignado anteriormente. |