IABProvider::Logon
Hace referencia a: Outlook 2013 | Outlook 2016
Establece una conexión a una sesión activa.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
Parameters
lpMAPISup
[in] Puntero al objeto de soporte técnico del proveedor de libretas de direcciones.
ulUIParam
[in] Identificador de la ventana primaria del cuadro de diálogo de inicio de sesión que muestra el método Logon , si se permite. El parámetro ulUIParam contiene el valor del parámetro del mismo nombre pasado a MAPI en la llamada anterior a la función MAPILogonEx .
lpszProfileName
[in] Puntero al nombre del perfil de sesión.
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:
AB_NO_DIALOG
El proveedor no debe mostrar un cuadro de diálogo durante el inicio de sesión. Si no se establece esta marca, el proveedor puede mostrar un cuadro de diálogo para solicitar al usuario información de configuración que falta.
MAPI_DEFERRED_ERRORS
Permite que Logon devuelva correctamente, posiblemente antes de que finalice el proceso de inicio de sesión.
MAPI_UNICODE
Todas las cadenas deben estar en formato Unicode. Si no se establece la marca de MAPI_UNICODE, las cadenas deben estar en formato ANSI.
lpulcbSecurity
[entrada, salida] Puntero al tamaño, en bytes, de la estructura de credenciales de seguridad a la que apunta el parámetro lppbSecurity . En la entrada, el valor debe ser distinto de cero; en la salida, el valor debe ser cero. En ambos casos, los punteros deben ser válidos.
lppbSecurity
[entrada, salida] Puntero a un puntero a las credenciales de seguridad. En la entrada, el valor debe ser distinto de cero; en la salida, el valor debe ser cero. En ambos casos, el puntero debe ser válido.
lppMAPIError
[out] Puntero a un puntero a una estructura MAPIERROR . El parámetro lppMAPIError se puede establecer en NULL si no hay ninguna estructura MAPIERROR que devolver.
lppABLogon
[out] Puntero a un puntero al objeto de inicio de sesión del proveedor.
Valor devuelto
S_OK
Se estableció correctamente una conexión a una sesión activa.
MAPI_E_FAILONEPROVIDER
El proveedor no puede iniciar sesión, pero MAPI puede seguir iniciando sesión en los otros proveedores del servicio de mensajes al que pertenece el proveedor.
MAPI_E_UNCONFIGURED
El proveedor no tiene suficiente información para completar el inicio de sesión. MAPI llama a la función de entrada del servicio de mensajes del proveedor.
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_E_USER_CANCEL
El usuario canceló la operación, normalmente haciendo clic en el botón Cancelar del cuadro de diálogo de inicio de sesión.
Comentarios
Connections se establecen con cada proveedor de libreta de direcciones en el perfil de sesión cuando un cliente llama al método IMAPISession::OpenAddressBook. A continuación, OpenAddressBook llama al método Logon de cada proveedor.
El nombre del perfil al que apunta el parámetro lpszProfileName se muestra en el conjunto de caracteres del cliente del usuario, como se indica en la presencia o ausencia de la marca MAPI_UNICODE en el parámetro ulFlags .
Notas a los implementadores
En la implementación del método Logon , llame al método IMAPISupport::SetProviderUID para registrar un identificador único o una estructura MAPIUID . Cada uno de los objetos tendrá un identificador de entrada que incluye esta MAPIUID. MAPI usa MAPIUID para hacer coincidir un objeto con su proveedor. Por ejemplo, cuando un cliente llama al método IMAPISession::OpenEntry para abrir un usuario de mensajería, OpenEntry examina la parte MAPIUID del identificador de entrada que se pasó y lo coincide con un MAPIUID registrado por un proveedor de libreta de direcciones.
Si un cliente inicia sesión en el proveedor más de una vez, es posible que desee registrar un MAPIUID diferente para cada inicio de sesión. El registro de estructuras MAPIUID únicas permite a MAPI enrutar correctamente las solicitudes a la instancia de proveedor adecuada. Sin embargo, es posible que desee que cada objeto de inicio de sesión comparta un MAPIUID. En este caso, debe ser capaz de controlar el enrutamiento usted mismo en lugar de confiar en MAPI. Para obtener más información sobre cómo crear una MAPIUID, vea Registrar identificadores únicos del proveedor de servicios.
El objeto de compatibilidad que MAPI pasa al método Logon en el parámetro lpMAPISup proporciona acceso a muchos de los métodos incluidos en la interfaz IMAPISupport : IUnknown . MAPI crea un objeto de soporte técnico que se personaliza para el tipo de proveedor. Por ejemplo, si necesita iniciar sesión en un sistema de mensajería subyacente o un servicio de directorio al establecer la conexión, puede llamar al método IMAPISupport::OpenProfileSection para recuperar las credenciales de seguridad de esta sesión de inicio de sesión determinada.
Si Logon se realiza correctamente, asegúrese de llamar al método IUnknown::AddRef del objeto de soporte técnico para incrementar su número de referencias. Esto permite que el proveedor mantenga el puntero de objeto de soporte técnico para el resto de la sesión. Si no llama a este método AddRef , MAPI descargará el proveedor.
Puede incluir el nombre del perfil pasado en el parámetro lpszProfileName en cuadros de diálogo de error, pantallas de inicio de sesión u otras interfaces de usuario. Para usar el nombre del perfil, cópielo en el almacenamiento que ha asignado.
Cree un objeto de inicio de sesión y devuelva un puntero a él en el parámetro lppABLogon . MAPI usa este objeto de inicio de sesión para realizar llamadas a los métodos de la implementación de IABLogon .
Si necesita una contraseña durante el inicio de sesión, muestre un cuadro de diálogo de inicio de sesión solo si la marca de AB_NO_DIALOG no está establecida. Si el usuario cancela el proceso de inicio de sesión, normalmente haciendo clic en el botón Cancelar del cuadro de diálogo, devuelve MAPI_E_USER_CANCEL del inicio de sesión.
Normalmente, cuando un proveedor de libreta de direcciones no puede iniciar sesión, MAPI deshabilita el servicio de mensajes al que pertenece el proveedor con errores, es decir, MAPI no intentará establecer conexiones para ninguno de los otros proveedores que pertenecen al servicio durante el resto de la duración de la sesión. Sin embargo, si el proveedor no puede establecer una conexión y no desea deshabilitar todo el servicio, devuelva MAPI_E_FAILONEPROVIDER o MAPI_E_UNCONFIGURED. MAPI no deshabilitará el servicio de mensajes al que pertenece el proveedor.
Devuelve MAPI_E_FAILONEPROVIDER si se produce un error que no es lo suficientemente grave como para impedir que los demás proveedores del servicio de mensajes establezcan conexiones. Devuelva MAPI_E_UNCONFIGURED si falta la información de configuración necesaria en el perfil y no puede mostrar un cuadro de diálogo para preguntar al usuario. MAPI responderá llamando a la función de punto de entrada del servicio de mensajes del proveedor con MSG_SERVICE_CONFIGURE establecido como parámetro ulContext para dar al servicio la oportunidad de configurarse a sí mismo, ya sea mediante programación o mediante una hoja de propiedades. Una vez finalizada la función de punto de entrada del servicio de mensajes, MAPI vuelve a intentar el inicio de sesión.