IMAPISession::QueryIdentity

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Devuelve el identificador de entrada del objeto que proporciona la identidad principal de la sesión.

HRESULT QueryIdentity(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpcbEntryID

[out] Puntero al recuento de bytes en el identificador de entrada al que apunta el parámetro lppEntryID .

lppEntryID

[out] Puntero a un puntero al identificador de entrada del objeto que proporciona la identidad principal.

Valor devuelto

S_OK

La identidad principal se devolvió correctamente.

MAPI_W_NO_SERVICE

La llamada se realizó correctamente, pero no hay ninguna identidad principal para la sesión. 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.

Comentarios

El método IMAPISession::QueryIdentity recupera la identidad principal de la sesión actual y devuelve el valor a través del parámetro lppEntryID . La identidad principal es un objeto, normalmente un usuario de mensajería, que representa al usuario de una sesión. lppEntryID devuelve la identidad principal de un objeto IMailUser , que también se almacena como la propiedad PidTagEntryID . Puede usar el valor devuelto en lppEntryID para abrir un objeto IMailUser mediante IMAPISession::OpenEntry.

Aunque muchos proveedores de servicios de varios servicios de mensajes pueden proporcionar la identidad principal para una sesión, MAPI designa un único proveedor de servicios. El proveedor de servicios que proporciona la identidad principal establece los siguientes elementos:

Marca de STATUS_PRIMARY_IDENTITY en la propiedad PR_RESOURCE_FLAGS (PidTagResourceFlags).
Propiedad PR_IDENTITY_DISPLAY (PidTagIdentityDisplay).
Propiedad PR_IDENTITY_ENTRYID (PidTagIdentityEntryId).
Propiedad PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey).

Si el proveedor de servicios que proporciona la identidad principal pertenece a un servicio de mensajes, los demás proveedores de servicios del servicio de mensajes también establecen las propiedades PR_IDENTITY. Estas propiedades se publican en la tabla de estado de la sesión.

Si es posible, QueryIdentity devuelve el valor de la propiedad PR_IDENTITY_ENTRYID de la fila de estado etiquetada con STATUS_PRIMARY_IDENTITY. Si falta la propiedad PR_IDENTITY_ENTRYID de la fila de identidad principal, QueryIdentity devuelve un identificador de entrada único creado con otra información de esa fila.

Si falta la marca de STATUS_PRIMARY_IDENTITY de todas las columnas PR_RESOURCE_FLAG de la tabla de estado, QueryIdentity devuelve el primer identificador de entrada que encuentra. Cuando no hay ningún identificador de entrada adecuado que devolver, QueryIdentity se ejecuta correctamente con la advertencia MAPI_W_NO_SERVICE y apunta lppEntryID a un identificador de entrada codificado de forma rígida.

Notas para los llamadores

Puede llamar al método IMsgServiceAdmin::SetPrimaryIdentity para asignar a un servicio de mensajes la tarea de proporcionar la identidad principal de la sesión.

Otra manera de recuperar la identidad principal es buscar en la tabla de estado la fila con las columnas de PR_RESOURCE_FLAGS establecidas en STATUS_PRIMARY_IDENTITY. Para obtener más información sobre esta forma alternativa de recuperar información de identidad, vea Tabla de estado y Objetos de estado.

Cuando haya terminado de usar el identificador de entrada para la identidad principal devuelta por QueryIdentity, libere su memoria llamando a la función MAPIFreeBuffer .

Para obtener más información sobre la identidad en general, vea Identidad principal MAPI.

Para obtener más información sobre cómo recuperar la identidad de sesión MAPI, vea Recuperación de la identidad principal y del proveedor.

Referencia de MFCMAPI

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

Archivo	Función	Comment
MainDlg.cpp	CMainDlg::OnQueryIdentity	MFCMAPI usa el método IMAPISession::QueryIdentity para abrir la entrada de la libreta de direcciones para la identidad principal de la sesión.