IMSProvider::Logon

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Registra MAPI en una instancia de un proveedor de almacén de mensajes.

HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG FAR * lpcbSpoolSecurity,
  LPBYTE FAR * lppbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

Parameters

lpMAPISup

[in] Puntero al objeto de compatibilidad mapi actual para el almacén de mensajes.

ulUIParam

[in] Identificador de la ventana primaria de los cuadros de diálogo o ventanas que muestra este método.

lpszProfileName

[in] Puntero a una cadena que contiene el nombre del perfil que se usa para el inicio de sesión del proveedor de almacenamiento. Esta cadena se puede mostrar en cuadros de diálogo, escribirse en un archivo de registro o simplemente omitirse. Debe estar en formato Unicode si la marca de MAPI_UNICODE está establecida en el parámetro ulFlags .

cbEntryID

[in] Tamaño, en bytes, del identificador de entrada al que apunta el parámetro lpEntryID .

lpEntryID

[in] Puntero al identificador de entrada del almacén de mensajes. Pasar null en lpEntryID indica que aún no se ha seleccionado un almacén de mensajes y que se pueden presentar cuadros de diálogo que permitan al usuario seleccionar un almacén de mensajes.

ulFlags

[in] Máscara de bits de marcas que controla cómo se realiza el inicio de sesión. Se pueden establecer las siguientes marcas:

MAPI_DEFERRED_ERRORS

La llamada puede realizarse correctamente incluso si el objeto subyacente no está disponible para la implementación de llamada. Si el objeto no está disponible, una llamada posterior al objeto podría generar un error.

MAPI_UNICODE

Las cadenas pasadas están en formato Unicode. Si no se establece MAPI_UNICODE, las cadenas están en formato ANSI.

MDB_NO_DIALOG

Impide la visualización de cuadros de diálogo de inicio de sesión. Si se establece esta marca, se devuelve el valor de error MAPI_E_LOGON_FAILED si el inicio de sesión no se realiza correctamente. Si no se establece esta marca, el proveedor del almacén de mensajes puede pedir al usuario que corrija un nombre o una contraseña, que inserte un disco o que realice otras acciones necesarias para establecer la conexión con el almacén.

MDB_NO_MAIL

El almacén de mensajes no debe usarse para enviar o recibir correo. La marca indica a MAPI que no notifique a la cola MAPI que se está abriendo este almacén de mensajes. Si se establece esta marca y el almacén de mensajes está estrechamente acoplado con un proveedor de transporte, el proveedor no necesita llamar al método IMAPISupport::SpoolerNotify .

MDB_TEMPORARY

Inicia sesión en el almacén para que la información se pueda recuperar mediante programación desde la sección de perfil, sin usar cuadros de diálogo. Esta marca indica a MAPI que el almacén no se va a agregar a la tabla del almacén de mensajes y que el almacén no se puede convertir en permanente. Si se establece esta marca, los proveedores del almacén de mensajes no necesitan llamar al método IMAPISupport::ModifyProfile .

MDB_WRITE

Solicita permiso de lectura y escritura.

lpInterface

[in] Puntero al identificador de interfaz (IID) para que el almacén de mensajes inicie sesión en . Pasar null indica que se devuelve la interfaz MAPI para el almacén de mensajes ( IMsgStore). El parámetro lpInterface también se puede establecer en un identificador para una interfaz adecuada para el almacén de mensajes (por ejemplo, IID_IUnknown o IID_IMAPIProp).

lpcbSpoolSecurity

[out] Puntero a la variable en la que el proveedor de almacén devuelve el tamaño, en bytes, de los datos de validación del parámetro lppbSpoolSecurity .

lppbSpoolSecurity

[out] Puntero al puntero a los datos de validación devueltos. Estos datos de validación se proporcionan para que el método IMSProvider::SpoolerLogon pueda registrar la cola MAPI en el mismo almacén que el proveedor del almacén de mensajes.

lppMAPIError

[out] Puntero a un puntero a la estructura MAPIERROR devuelta, si existe, que contiene información de versión, componente y contexto para un error. El parámetro lppMAPIError se puede establecer en null si no hay ninguna estructura MAPIERROR que devolver.

lppMSLogon

[out] Puntero al puntero al objeto de inicio de sesión del almacén de mensajes para que MAPI inicie sesión en .

lppMDB

[out] Puntero al puntero al objeto de almacén de mensajes para que las aplicaciones cliente y de cola MAPI inicien sesión.

Valor devuelto

S_OK

La llamada se ha realizado correctamente y devuelva el valor esperado o los valores.

MAPI_E_FAILONEPROVIDER

Este proveedor no puede iniciar sesión, pero este error no debe deshabilitar el servicio.

MAPI_E_LOGON_FAILED

No se pudo establecer una sesión de inicio de sesión.

MAPI_E_UNCONFIGURED

El perfil no contiene suficiente información para que se complete el inicio de sesión. Cuando se devuelve este valor, MAPI llama a la función de punto de entrada del servicio de mensajes del proveedor de mensajes.

MAPI_E_USER_CANCEL

El usuario canceló la operación, normalmente haciendo clic en el botón Cancelar de un cuadro de diálogo.

MAPI_E_UNKNOWN_CPID

El servidor no está configurado para admitir la página de códigos del cliente.

MAPI_E_UNKNOWN_LCID

El servidor no está configurado para admitir la información de configuración regional del cliente.

MAPI_W_ERRORS_RETURNED

La llamada se realizó correctamente, pero el proveedor del almacén de mensajes tiene información de error disponible. 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. Para obtener la información de error del proveedor, llame al método IMAPISession::GetLastError .

Comentarios

MAPI llama al método IMSProvider::Logon para realizar la mayoría del procesamiento necesario para obtener acceso a un almacén de mensajes. Los proveedores de almacén de mensajes validan las credenciales de usuario necesarias para acceder a un almacén determinado y devuelven un objeto de almacén de mensajes en el parámetro lppMDB al que pueden iniciar sesión la cola MAPI y las aplicaciones cliente.

Además del objeto de almacén de mensajes devuelto para el cliente y el uso de cola MAPI, el proveedor también devuelve un objeto de inicio de sesión del almacén de mensajes para que MAPI lo use para controlar el almacén abierto. El objeto de inicio de sesión del almacén de mensajes y el objeto de almacén de mensajes deben estar estrechamente vinculados dentro del proveedor del almacén de mensajes para que cada uno pueda afectar al otro. El uso del objeto de almacén y del objeto de inicio de sesión debe ser idéntico; debe haber una correspondencia uno a uno entre el objeto de inicio de sesión y el objeto de almacén de modo que los objetos actúen como si fueran un objeto que expone dos interfaces. Los dos objetos también deben crearse juntos y liberarse juntos.

El objeto de compatibilidad MAPI, creado por MAPI y pasado al proveedor en el parámetro lpMAPISup , proporciona acceso a las funciones de MAPI que requiere el proveedor. Estas incluyen funciones que guardan y recuperan información de perfil, acceden a las libretas de direcciones, etc. El puntero lpMAPISup puede ser diferente para cada almacén que se abre. Al procesar llamadas a un almacén de mensajes después del inicio de sesión, el proveedor de almacén debe usar la variable lpMAPISup específica de ese almacén. Para cualquier llamada de inicio de sesión que abra un almacén de mensajes y cree correctamente un objeto de inicio de sesión del almacén de mensajes, el proveedor debe guardar un puntero al objeto de soporte técnico MAPI en el objeto de inicio de sesión del almacén y debe llamar al método IUnknown::AddRef para agregar una referencia para el objeto de soporte técnico.

El parámetro ulUIParam debe usarse si el proveedor presenta cuadros de diálogo durante la llamada de inicio de sesión . Sin embargo, no se deben presentar cuadros de diálogo si ulFlags contiene la marca de MDB_NO_DIALOG. Si es necesario llamar a una interfaz de usuario, pero ulFlags no lo permite, o si por alguna otra razón no se puede mostrar una interfaz de usuario, el proveedor debe devolver MAPI_E_LOGON_FAILED. Si Inicio de sesión muestra un cuadro de diálogo y el usuario cancela el inicio de sesión, normalmente haciendo clic en el botón Cancelar del cuadro de diálogo, el proveedor debe devolver MAPI_E_USER_CANCEL.

El parámetro lpEntryID puede ser null o apuntar a un identificador de entrada de almacén no cifrado que este almacén de mensajes creó anteriormente. Si lpEntryID apunta a un identificador de entrada no cifrado, ese identificador de entrada puede proceder de uno de varios lugares:

Puede ser un identificador de entrada que el proveedor de almacén haya encapsulado y escrito previamente en la sección de perfil como una propiedad PR_ENTRYID (PidTagEntryId).
Puede ser un identificador de entrada que el proveedor envolvió y devolvió previamente a un cliente que realiza la llamada como una propiedad PR_STORE_ENTRYID (PidTagStoreEntryId).
Puede ser un identificador de entrada que el proveedor encapsulaba y devolvía previamente a un cliente que realiza la llamada como la propiedad PR_ENTRYID de un objeto de almacén de mensajes.

En cualquiera de estos casos, es posible que el identificador de entrada se haya creado en un equipo diferente al que se está usando actualmente.

Cuando lpEntryID no es null, debe contener toda la información necesaria para identificar y localizar el almacén de mensajes. Esta información puede incluir nombres de volumen de red, números de teléfono, nombres de cuenta de usuario, etc. Si la conexión con el almacén no se puede realizar mediante los datos del identificador de entrada, el proveedor de almacén debe mostrar un cuadro de diálogo que permita al usuario seleccionar el almacén que se va a abrir. Es posible que sea necesario un cuadro de diálogo, por ejemplo, si se ha cambiado el nombre de un servidor, se ha cambiado el nombre de una cuenta o no hay partes de la red disponibles.

Cuando lpEntryID es null, el almacén de mensajes que se va a usar aún no se ha seleccionado. El proveedor todavía puede acceder a un almacén sin mostrar un cuadro de diálogo si admite otros métodos para especificar el almacén. Por ejemplo, el proveedor puede comprobar su archivo de inicialización o puede buscar propiedades adicionales que se colocaron en su sección de perfil del servicio de mensajes o en la configuración.

Si un proveedor detecta que toda la información necesaria no está en el perfil, debe devolver MAPI_E_UNCONFIGURED. A continuación, MAPI llamará a la función de punto de entrada del servicio de mensajes del proveedor para permitir que el usuario seleccione un almacén, o incluso para crear uno, y escriba un nombre de cuenta y una contraseña, según sea necesario. MAPI crea automáticamente una sección de perfil para un nuevo almacén; Esta nueva sección de perfil puede ser temporal o permanente, en función de cómo se haya agregado. Si el proveedor de almacén llama al método IMAPISupport::ModifyProfile , la nueva sección de perfil se convierte en permanente y el almacén se agrega a la lista de almacenes de mensajes devueltos por el método IMAPISession::GetMsgStoresTable .

El parámetro lpInterface especifica el IID de la interfaz necesaria para el objeto de almacén recién abierto. Al pasar null en lpInterface se especifica que se requiere la interfaz del almacén de mensajes MAPI, IMsgStore. Al pasar el objeto de almacén de mensajes, IID_IMsgStore, también se especifica que se requiere IMsgStore . Si IID_IUnknown se pasa en lpInterface, el proveedor debe abrir el almacén mediante cualquier interfaz derivada de IUnknown es la mejor para el proveedor (de nuevo, suele ser IMsgStore). Cuando se pasa IID_IUnknown, la implementación de llamada usa el método IUnknown::QueryInterface para seleccionar una interfaz después de que la operación de apertura del almacén se realice correctamente.

La llamada a IMSProvider::Logon debe devolver información suficiente, como una ruta de acceso al almacén y las credenciales para acceder al almacén, para permitir que la cola MAPI inicie sesión en el mismo almacén que el proveedor de almacenamiento sin presentar un cuadro de diálogo. Los parámetros lpcbSpoolSecurity y lppbSpoolSecurity se usan para devolver esta información. El proveedor asigna la memoria para estos datos pasando un puntero a un búfer en el parámetro lpfAllocateBuffer de la función MSProviderInit; el proveedor coloca el tamaño de este búfer en lpcbSpoolSecurity.

MAPI libera este búfer cuando corresponda. Si el inicio de sesión de la cola MAPI en el almacén se puede realizar solo a partir de la información de la sección de perfil, el proveedor puede devolver null en lppbSpoolSecurity y 0 para el tamaño de la información en lpcbSpoolSecurity. El inicio de sesión de cola MAPI se produce como parte de un proceso diferente al inicio de sesión del almacén; dado que el búfer que contiene la información pasada se copia entre procesos, es posible que no esté en la misma ubicación para el proceso de cola MAPI que para el proceso del proveedor de almacenamiento. Por lo tanto, un proveedor no debe colocar direcciones en este búfer. Para obtener más información sobre el inicio de sesión de cola MAPI, vea el método IMSProvider::SpoolerLogon .

La mayoría de los proveedores de almacén usan el método IMAPISession::OpenProfileSection del objeto de soporte técnico pasado en el parámetro lpMAPISup para guardar y recuperar las credenciales y opciones de usuario. OpenProfileSection permite a un proveedor de almacén guardar información arbitraria adicional en una sección de perfil y asociarla a un recurso determinado. Por ejemplo, un proveedor de almacenamiento puede guardar el nombre de cuenta de usuario y la contraseña asociados a un recurso y cualquier ruta de acceso u otra información necesaria para acceder a ese recurso.

Las propiedades con identificadores de propiedad 0x6600 a través de 0x67FF son propiedades seguras disponibles para el proveedor para su propio uso para almacenar datos privados en secciones de perfil. Para obtener más información sobre los usos de propiedades en objetos de sección de perfil, vea el método IProfSect : IMAPIProp .

Además de los datos privados de las propiedades con identificadores 0x6600 a través de 0x67FF, el proveedor de almacén debe proporcionar información para la propiedad PR_DISPLAY_NAME (PidTagDisplayName) en su sección de perfil. Debe colocar PR_DISPLAY_NAME el nombre para mostrar del propio proveedor, una cadena de identificación (por ejemplo, "Microsoft Personal Information Store") que se muestra a los usuarios para que puedan distinguir este almacén de mensajes de otros a los que puedan tener acceso. PR_DISPLAY_NAME normalmente contiene un nombre de servidor, un nombre de cuenta de usuario o una ruta de acceso.

Algunas propiedades de sección de perfil están visibles en la tabla del almacén de mensajes; otros son visibles durante la instalación, instalación y configuración del subsistema MAPI. Normalmente, el proveedor proporciona información para estas propiedades visibles tanto para una nueva sección de perfil, que aún no incluye credenciales guardadas ni información privada, como cuando encuentra que la información de propiedad ha cambiado. Para obtener más información sobre las secciones de perfil, vea IMAPISupport::OpenProfileSection.

Después de iniciar sesión correctamente en un usuario y antes de volver a MAPI, el proveedor de almacén debe crear la matriz de propiedades de la fila de estado del recurso y llamar al método IMAPISupport::ModifyStatusRow .

Las llamadas de inicio de sesión que abren almacenes de mensajes que ya están abiertos para la sesión MAPI actual omiten gran parte del procesamiento descrito anteriormente. Estas llamadas no crean filas de estado, devuelven objetos de inicio de sesión del almacén de mensajes, llaman a AddRef para el objeto de soporte técnico MAPI o devuelven datos para el inicio de sesión de cola MAPI. Estas llamadas devuelven S_OK y devuelven un objeto de almacén de mensajes con la interfaz solicitada.

Para detectar estas llamadas, el proveedor debe mantener una lista en el objeto de proveedor de almacén de mensajes de los almacenes que ya están abiertos para este objeto de proveedor. Al procesar una llamada de inicio de sesión, el proveedor debe examinar esta lista de almacenes abiertos y determinar si el almacén en el que se va a iniciar sesión ya está abierto. Si es así, no es necesario comprobar las credenciales de usuario y, si es posible, se debe evitar la visualización de un cuadro de diálogo. Si se deben mostrar cuadros de diálogo, el proveedor debe comprobar la información devuelta para ver si se ha abierto un almacén por segunda vez. Además, el proveedor debe comprobar si hay aperturas duplicadas mediante lpEntryID al principio del procesamiento de llamadas de inicio de sesión .

El procesamiento estándar de una llamada de inicio de sesión que accede a un almacén abierto es el siguiente:

El proveedor de almacén llama a AddRef para el objeto de almacén existente si la nueva interfaz que se solicita es la misma que la interfaz del almacén existente. De lo contrario, llama a QueryInterface para obtener la nueva interfaz. Si el almacén no admite la nueva interfaz, el proveedor debe devolver el valor de error MAPI_E_INTERFACE_NOT_SUPPORTED.
El proveedor devuelve un puntero a la interfaz necesaria del objeto de almacén existente en lppMDB.
El proveedor devuelve null en lppMSLogon.
El proveedor no debe abrir el perfil del objeto de soporte técnico pasado en la llamada. Además, no debe registrar un identificador único del proveedor, registrar una fila de estado ni devolver datos de inicio de sesión de cola MAPI.
El proveedor no debe llamar a AddRef para el objeto de soporte técnico, ya que no requiere un puntero al objeto .

Siempre que sea posible, los proveedores deben devolver las cadenas de error y advertencia adecuadas para las llamadas de inicio de sesión, ya que hacerlo facilita enormemente la carga de los usuarios para determinar por qué algo no funcionó. Para devolver estas cadenas, un proveedor establece los miembros de la estructura MAPIERROR . MAPI busca, usa y libera la estructura MAPIERROR si lo devuelve un proveedor.

La memoria de esta estructura MAPIERROR debe asignarse mediante el búfer pasado en lpfAllocateBuffer en la llamada MSProviderInit . Las cadenas de error contenidas en la estructura devuelta deben estar en formato Unicode si MAPI_UNICODE se establece en el ulFlagsde inicio de sesión; de lo contrario, deben estar en el conjunto de caracteres ANSI.

Para la mayoría de los valores de error devueltos por Logon, MAPI deshabilita los servicios de mensajes a los que pertenece el proveedor con errores. MAPI no llamará a ningún proveedor que pertenezca a esos servicios durante la vida útil de la sesión MAPI. Por el contrario, cuando Logon devuelve el valor de error MAPI_E_FAILONEPROVIDER de su inicio de sesión, MAPI no deshabilita el servicio de mensajes al que pertenece el proveedor. El inicio de sesión debe devolver MAPI_E_FAILONEPROVIDER si encuentra un error que no garantiza deshabilitar todo el servicio durante toda la sesión. Por ejemplo, un proveedor podría devolver este error cuando no permite la presentación de una interfaz de usuario y una contraseña necesaria no está disponible.

Si un proveedor devuelve MAPI_E_UNCONFIGURED de su inicio de sesión, MAPI llamará a la función de entrada del servicio de mensajes del proveedor y, a continuación, volverá a intentar el inicio de sesión. MAPI pasa MSG_SERVICE_CONFIGURE como contexto para dar al servicio la oportunidad de configurarse a sí mismo. Si el cliente ha elegido permitir una interfaz de usuario en el inicio de sesión, el servicio puede presentar su hoja de propiedades de configuración para que el usuario pueda escribir información de configuración.