IMAPIProp::GetIDsFromNames
Hace referencia a: Outlook 2013 | Outlook 2016
Proporciona los identificadores de propiedad que corresponden a uno o varios nombres de propiedad.
HRESULT GetIDsFromNames(
ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
);
Parameters
cPropNames
[in] Recuento de nombres de propiedad a los que apunta el parámetro lppPropNames . Si lppPropNames es NULL, el parámetro cPropNames debe ser 0.
lppPropNames
[in] Puntero a una matriz de nombres de propiedad o NULL. Al pasar NULL, se solicitan identificadores de propiedad para todos los nombres de propiedad de todos los conjuntos de propiedades sobre los que el objeto tiene información. El parámetro lppPropNames no debe ser NULL si la marca de MAPI_CREATE se establece en el parámetro ulFlags .
ulFlags
[in] Máscara de bits de marcas que indica cómo se deben devolver los identificadores de propiedad. Se puede establecer la marca siguiente:
MAPI_CREATE
Asigna un identificador de propiedad, si aún no se ha asignado uno, a uno o varios de los nombres incluidos en la matriz de nombres de propiedad a los que apunta lppPropNames. Esta marca registra internamente el identificador en la tabla de asignación de nombre a identificador.
lppPropTags
[out] Puntero a un puntero a una matriz de etiquetas de propiedad que contiene identificadores de propiedad existentes o recién asignados. Los tipos de propiedad de las etiquetas de propiedad de esta matriz se establecen en PT_UNSPECIFIED.
Valor devuelto
S_OK
Los identificadores de los nombres de propiedad especificados se devolvieron correctamente.
MAPI_E_NO_SUPPORT
El objeto no admite propiedades con nombre.
MAPI_E_NOT_ENOUGH_MEMORY
No había suficiente memoria disponible para recuperar los identificadores.
MAPI_E_TOO_BIG
No se puede realizar la operación porque requiere que se devuelvan demasiadas etiquetas de propiedad.
MAPI_W_ERRORS_RETURNED
La llamada se realizó correctamente en general, pero no se pudieron devolver uno o varios identificadores de propiedad. El tipo de propiedad correspondiente para cada propiedad no disponible se establece en PT_ERROR y su identificador en cero. Cuando se devuelva esta advertencia, controle la llamada como correcta. Para probar esta advertencia, use la macro HR_FAILED . Consulte Uso de macros para el control de errores.
Comentarios
El método IMAPIProp::GetIDsFromNames recupera una matriz de etiquetas de propiedad que contienen los identificadores de propiedad de una o varias propiedades con nombre. Se puede llamar a IMAPIProp::GetIDsFromNames para hacer lo siguiente:
Cree identificadores para nuevos nombres.
Recuperar identificadores para nombres específicos.
Recupere los identificadores de todas las propiedades con nombre que se incluyen en la asignación del objeto.
Los proveedores de almacén de mensajes suelen usar las propiedades con nombre para carpetas y mensajes. Es posible que otros objetos, como usuarios de mensajería y secciones de perfil, no admitan la asociación de nombres a identificadores de propiedad y que devuelvan MAPI_E_NO_SUPPORT de GetIDsFromNames.
Si hay un error que devuelve un identificador para un nombre determinado, GetIDsFromNames devuelve MAPI_W_ERRORS_RETURNED y establece el tipo de propiedad en la entrada de matriz de etiquetas de propiedad que corresponde al nombre a PT_ERROR y el identificador a cero.
La asignación de nombre a identificador se representa mediante la propiedad PR_MAPPING_SIGNATURE (PidTagMappingSignature) de un objeto. PR_MAPPING_SIGNATURE contiene una estructura MAPIUID que indica el proveedor de servicios responsable del objeto. Si la propiedad PR_MAPPING_SIGNATURE es la misma para dos objetos, suponga que estos objetos usan la misma asignación de nombre a identificador.
Notas a los implementadores
Los identificadores que se pasan de vuelta en la matriz de etiquetas de propiedad a las que apunta el parámetro lppPropNames deben estar en el 0x8000 para 0xFFFE intervalo. Las entradas de esta matriz deben estar en el mismo orden que los nombres pasados en la matriz de nombres de propiedad a la que apunta lppPropNames.
Si admite propiedades con nombre en un contenedor, use la misma asignación de nombre a identificador para todos los objetos del contenedor (es decir, no use una asignación diferente para cada carpeta del almacén de mensajes o de cada mensaje de la carpeta).
Notas para los llamadores
Dado que los tipos de propiedad de los identificadores devueltos en la matriz de etiquetas de propiedad a los que apunta lppPropTags se establecen en PT_UNSPECIFIED, tendrá que llamar al método IMAPIProp::SetProps para recuperar los tipos precisos.
Si mueve o copia objetos con propiedades con nombre y los objetos de origen y destino tienen distintas firmas de asignación, como se indica en los valores de sus propiedades de PR_MAPPING_SIGNATURE , debe conservar los nombres durante estas operaciones. Para conservar los nombres de propiedad, ajuste los identificadores de propiedad correspondientes para que coincidan con la asignación de nombre a identificador del objeto de destino.
Algunos objetos tienen un límite en cuanto al número de identificadores de propiedad que pueden asignar. Si una llamada a GetIDsFromNames hace que se supere este límite, el método devuelve MAPI_E_TOO_BIG. En este caso, consulte por identificador.
Para obtener más información, 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::FindAllNamedPropsUsed |
MFCMAPI usa el método IMAPIProp::GetIDsFromNames para obtener etiquetas de propiedad para todas las propiedades con nombre que se han asignado. |