MAPILogonEx

Artículo
04/04/2023

Hace referencia a: Outlook 2013 | Outlook 2016

Registra una aplicación cliente en una sesión con el sistema de mensajería.

Propiedad	Valor
Archivo de encabezado:	Mapix.h
Implementado por:	MAPI
Llamado por:	Aplicaciones cliente

HRESULT MAPILogonEx(
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  LPSTR lpszPassword,
  FLAGS flFlags,
  LPMAPISESSION FAR * lppSession
);

Parameters

ulUIParam

[in] Controle la ventana en la que el cuadro de diálogo de inicio de sesión es modal. Si no aparece ningún cuadro de diálogo durante la llamada, se omite el parámetro ulUIParam . Este parámetro puede ser cero.

lpszProfileName

[in] Puntero a una cadena que contiene el nombre del perfil que se usará cuando el usuario inicie sesión. Esta cadena está limitada a 64 caracteres.

lpszPassword

[in] Puntero a una cadena que contiene la contraseña del perfil. El parámetro lpszPassword debe ser NULL.

flFlags

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

MAPI_ALLOW_OTHERS

Se debe devolver la sesión compartida, lo que permite a los clientes posteriores obtener la sesión sin proporcionar credenciales de usuario.

MAPI_BG_SESSION

Inicie sesión en una sesión y ejecute cualquier operación en segundo plano. En general, si un cliente pretende realizar el procesamiento en un subproceso en segundo plano o en un proceso independiente de forma discreta para el subproceso en primer plano, debe llamar a con la marca MAPI_BG_SESSION. Una aplicación cliente como un motor de indexación o la apertura de un archivo de carpetas personales (PST) para el acceso de tipo en segundo plano son algunos ejemplos de dónde usar MAPI_BG_SESSION. MAPILogonEx.

MAPI_EXPLICIT_PROFILE

No se debe usar el perfil predeterminado y el usuario debe ser necesario para proporcionar un perfil.

MAPI_EXTENDED

Inicie sesión con funcionalidades extendidas. Esta marca siempre debe establecerse.

MAPI_FORCE_DOWNLOAD

Se debe intentar descargar todos los mensajes del usuario antes de devolverlos. Si no se establece la marca de MAPI_FORCE_DOWNLOAD, los mensajes se pueden descargar en segundo plano después de que se devuelva la llamada a MAPILogonEx.

MAPI_LOGON_UI

Se debe mostrar un cuadro de diálogo para solicitar al usuario información de inicio de sesión si es necesario. Cuando no se establece la marca MAPI_LOGON_UI, el cliente que realiza la llamada no muestra un cuadro de diálogo de inicio de sesión y devuelve un valor de error si el usuario no ha iniciado sesión.

MAPI_NEW_SESSION

Se debe intentar crear una nueva sesión MAPI en lugar de adquirir la sesión compartida. Si no se establece la marca MAPI_NEW_SESSION, MAPILogonEx usa una sesión compartida existente incluso si el parámetro lpszprofileName no es NULL.

MAPI_NO_MAIL

MAPI no debe informar a la cola MAPI de la existencia de la sesión. El resultado es que no se puede enviar ni recibir ningún mensaje en la sesión, excepto a través de un par de almacenamiento y transporte estrechamente acoplado. Un cliente que realiza la llamada establece esta marca si actúa como agente, si se debe realizar el trabajo de configuración o si el cliente está explorando los almacenes de mensajes disponibles.

MAPI_NT_SERVICE

El autor de la llamada se ejecuta como un servicio de Windows. Los autores de llamadas que no se ejecutan como un servicio de Windows no deben establecer esta marca; Los autores de llamadas que se ejecutan como servicio deben establecer esta marca.

MAPI_SERVICE_UI_ALWAYS

MAPILogonEx debe mostrar un cuadro de diálogo de configuración para cada servicio de mensajes del perfil. Los cuadros de diálogo se muestran después de elegir el perfil, pero antes de que se inicie sesión en cualquier servicio de mensajes. El cuadro de diálogo común MAPI para el inicio de sesión también contiene una casilla que solicita la misma operación.

MAPI_TIMEOUT_SHORT

El inicio de sesión debe producir un error si se bloquea durante más de unos segundos.

MAPI_UNICODE

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

MAPI_USE_DEFAULT

El subsistema de mensajería debe sustituir el nombre del perfil predeterminado por el parámetro lpszProfileName . La marca de MAPI_EXPLICIT_PROFILE se omite a menos que lpszProfileName sea NULL o esté vacío.

lppSession

[out] Puntero a un puntero a la interfaz de sesión MAPI.

Valor devuelto

S_OK

El inicio de sesión se realizó correctamente.

MAPI_E_LOGON_FAILED

El inicio de sesión no se realizó correctamente, ya sea porque uno o varios de los parámetros de MAPILogonEx no eran válidos o porque ya había demasiadas sesiones abiertas.

MAPI_E_TIMEOUT

MAPI serializa todos los inicios de sesión a través de una exclusión mutua. Esto se devuelve si se ha establecido la marca de MAPI_TIMEOUT_SHORT y otro subproceso mantiene la exclusión mutua.

MAPI_E_USER_CANCEL

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

Comentarios

Las aplicaciones cliente MAPI llaman a la función MAPILogonEx para iniciar sesión en una sesión con el sistema de mensajería. Todas las cadenas que se pasan y devuelven a y desde llamadas MAPI están terminadas en null y deben especificarse en el juego de caracteres actual o en la página de códigos del sistema operativo del cliente o proveedor que realiza la llamada.

El parámetro lpszProfileName se omite si hay una sesión anterior existente que llamó a MapiLogonEx con la marca MAPI_ALLOW_OTHERS establecida y si la marca MAPI_NEW_SESSION no está establecida. Si el parámetro lpszProfileName es NULL o apunta a una cadena vacía y el parámetro flFlags incluye la marca MAPI_LOGON_UI, la función MAPILogonEx genera un cuadro de diálogo de inicio de sesión que tiene un campo vacío para el nombre del perfil.

Al iniciar sesión en un perfil específico, un cliente debe pasar la marca de MAPI_NEW_SESSION a MAPILogonEx, además del nombre del perfil. De lo contrario, si otro cliente ha establecido una sesión compartida iniciando sesión con MAPI_ALLOW_OTHERS, el cliente iniciará sesión en la sesión compartida en lugar de en el perfil solicitado.

La marca de MAPI_EXPLICIT_PROFILE no hace que se use el nombre de perfil predeterminado cuando lpszProfileName es NULL o está vacío, a menos que la marca de MAPI_USE_DEFAULT también esté presente.

La marca MAPI_NO_MAIL tiene varios efectos que provocan lo siguiente cuando no se usa la cola MAPI:

La cola MAPI no puede enviar ni entregar ningún mensaje durante esta sesión. Solo los proveedores de almacenamiento y transporte estrechamente acoplados pueden enviar y entregar mensajes.
Los almacenes basados en servidor pueden seguir enviando o entregando mensajes.
Los mensajes enviados o entregados por almacenes basados en servidor no son procesados por ningún proveedor de enlaces.
Las opciones por mensaje y por destinatario para los transportes no están disponibles.
La tabla de estado no contiene entradas para los proveedores de transporte y ninguna funcionalidad de transporte que dependa de objetos de estado (como la configuración) no está disponible.
La fila de cola de mensajes de la tabla de estado contiene el valor STATUS_FAILURE.
Se permiten los inicios de sesión con piggyback, pero esos inicios de sesión no hacen que el inicio de sesión anterior reciba actualizaciones del objeto de estado.