IXPProvider::TransportLogon
Hace referencia a: Outlook 2013 | Outlook 2016
Establece una sesión en la que una aplicación cliente inicia sesión en un proveedor de transporte.
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
Parameters
lpMAPISup: [in] Puntero al objeto de soporte técnico del proveedor de transporte para las funciones de devolución de llamada dentro de MAPI para esta sesión. Este objeto sigue siendo válido hasta que el proveedor de transporte lo libera.
ulUIParam: [in] Controle la ventana primaria de los cuadros de diálogo o ventanas que muestra este método. El parámetro ulUIParam puede ser distinto de null, por ejemplo, cuando la marca de LOGON_SETUP se establece en el parámetro lpulFlags .
lpszProfileName: [in] Puntero al nombre del perfil del usuario. El parámetro lpszProfileName se usa principalmente cuando se debe presentar un cuadro de diálogo.
lpulFlags: [in, out] Máscara de bits de marcas que controla cómo se establece la sesión de inicio de sesión. La cola MAPI puede establecer las siguientes marcas en la entrada:
LOGON_NO_CONNECT: La cuenta de usuario inicia sesión en este proveedor de transporte para fines distintos de la transmisión y recepción de mensajes. El proveedor de transporte no debe intentar realizar ninguna conexión con otros sistemas de mensajería.
LOGON_NO_DIALOG: no se debe mostrar ningún cuadro de diálogo incluso si las credenciales de usuario guardadas actualmente no son válidas o insuficientes para el inicio de sesión.
LOGON_NO_INBOUND: el proveedor de transporte no tiene que inicializarse para la recepción de mensajes y no debe aceptar los mensajes entrantes. La cola MAPI puede usar el método IXPLogon::TransportNotify más adelante para indicar al proveedor de transporte que habilite el procesamiento de mensajes entrantes.
LOGON_NO_OUTBOUND: el proveedor de transporte no tiene que inicializarse para enviar mensajes, ya que la cola MAPI no proporciona ninguno. Si una aplicación cliente requiere una conexión a un proveedor remoto durante la composición de un mensaje para que pueda realizar llamadas al método IXPLogon::AddressTypes , el proveedor de transporte debe realizar la conexión. La cola MAPI puede usar TransportNotify para indicar al proveedor de transporte cuándo pueden comenzar las operaciones salientes.
MAPI_UNICODE: la cadena pasada para el nombre del perfil está en formato Unicode. Si no se establece la marca de MAPI_UNICODE, la cadena está en formato ANSI.
El proveedor de transporte puede establecer las siguientes marcas en la salida:
LOGON_SP_IDLE: solicita que la cola MAPI llame con frecuencia al método IXPLogon::Idle del proveedor de transporte para el procesamiento en tiempo de inactividad.
LOGON_SP_POLL: solicita que la cola MAPI llame con frecuencia al método IXPLogon::P oll en el objeto de inicio de sesión devuelto para comprobar si hay nuevos mensajes. Si no se establece esta marca, la cola MAPI solo comprueba si hay nuevos mensajes cuando el proveedor de transporte usa el método IMAPISupport::SpoolerNotify para notificar a la cola que hay nuevos mensajes que procesar. Un proveedor de transporte se convierte efectivamente en solo envío al no establecer esta marca y no notificar a la cola MAPI de la recepción de mensajes.
LOGON_SP_RESOLVE: solicitudes que la cola MAPI resuelve en direcciones completas todas las direcciones de mensaje de los destinatarios no compatibles con este proveedor de transporte. Por lo tanto, el proveedor de transporte puede construir una ruta de acceso de respuesta para todos los destinatarios.
MAPI_UNICODE: las cadenas devueltas en la estructura MAPIERROR , si las hay, están en formato Unicode. Si no se establece la marca de MAPI_UNICODE, las cadenas están en formato ANSI.
lppMAPIError: [out] Puntero a un puntero a la estructura MAPIERROR devuelta, si existe, que contiene información de versión, componente y contexto para el error. El parámetro lppMAPIError se puede establecer en NULL si no hay ninguna estructura MAPIERROR que devolver.
lppXPLogon: [out] Puntero al puntero al objeto de inicio de sesión del proveedor de transporte devuelto.
Valor devuelto
S_OK: la llamada se realizó correctamente y ha devuelto el valor o los valores esperados.
MAPI_E_FAILONEPROVIDER: Este proveedor no puede iniciar sesión, pero este error no debe deshabilitar el servicio.
MAPI_E_UNCONFIGURED: el perfil no contiene suficiente información para que se complete el inicio de sesión. MAPI llama a la función de punto de entrada del servicio de mensajes del proveedor.
MAPI_E_UNKNOWN_CPID: El proveedor no puede admitir la página de códigos del cliente.
MAPI_E_UNKNOWN_LCID: El proveedor no puede 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 de un cuadro de diálogo.
Comentarios
La cola MAPI llama al método IXPProvider::TransportLogon para establecer una sesión de inicio de sesión para un usuario.
La mayoría de los proveedores de transporte usan el método IMAPISupport::OpenProfileSection proporcionado con el objeto de soporte técnico al que apunta el parámetro lpMAPISup para guardar y recuperar información de identidad de usuario, direcciones de servidor y credenciales. Mediante OpenProfileSection, un proveedor de transporte puede guardar información arbitraria y asociarla con un inicio de sesión a un recurso determinado. Por ejemplo, un proveedor puede usar OpenProfileSection para guardar el nombre de la cuenta y la contraseña asociados a una sesión determinada y cualquier nombre de servidor u otra información necesaria necesaria para acceder a los recursos de esa sesión. MAPI oculta la información asociada a un recurso desde el acceso externo. La sección de perfil disponible a través de lpMAPISup se administra mediante la cola MAPI, por lo que los datos relacionados con este contexto de usuario se separan de los datos de otros contextos.
El proveedor de transporte debe llamar al método IUnknown::AddRef en el objeto de soporte técnico y conservar una copia del puntero a este objeto como parte del objeto de inicio de sesión del proveedor.
El nombre para mostrar del perfil en lpszProfileName se proporciona para que el proveedor de transporte pueda usarlo en mensajes de error o cuadros de diálogo de inicio de sesión. Si el proveedor conserva este nombre, debe copiarse en el almacenamiento asignado por el proveedor.
Los proveedores de transporte estrechamente asociados con otros proveedores de servicios pueden tener que realizar un trabajo adicional al iniciar sesión para establecer las credenciales correctas necesarias para las operaciones entre proveedores complementarios.
Normalmente, los proveedores de transporte se abren cuando el usuario inicia sesión por primera vez en un perfil. Como el primer inicio de sesión en un perfil suele aparecer antes de iniciar sesión en cualquier almacén de mensajes, la cola MAPI suele llamar a TransportLogon con las marcas LOGON_NO_INBOUND y LOGON_NO_OUTBOUND establecidas en lpulFlags. Más adelante, cuando los almacenes de mensajes adecuados están disponibles en la sesión de perfil, la cola MAPI llama a TransportNotify para iniciar operaciones entrantes y salientes para el proveedor de transporte.
Pasar la marca de LOGON_NO_CONNECT en lpulFlags indica el funcionamiento sin conexión del proveedor de transporte. Esta marca indica que no se deben realizar conexiones externas; Si el proveedor de transporte no puede establecer una sesión sin una conexión externa, debe devolver un valor de error para el inicio de sesión.
Un proveedor de transporte debe establecer la marca de LOGON_SP_IDLE en lpulFlags en el momento de la inicialización si está diseñado para usar el tiempo que el sistema pasa inactiva. Este tiempo se usa a menudo para controlar las operaciones automáticas, como la descarga automática de mensajes, la descarga de mensajes con tiempo o el envío de mensajes con tiempo. Si se establece esta marca, la cola MAPI llama a Inactivo cuando se produce el tiempo de inactividad del sistema para iniciar dichas operaciones. La cola MAPI no llama a Idle a intervalos establecidos; en su lugar, se llama solo durante el tiempo de inactividad verdadero. Por lo tanto, los proveedores no deben trabajar en ninguna suposición sobre la frecuencia con la que se llamará a sus métodos inactivos . Los proveedores que admiten operaciones en tiempo de inactividad deben proporcionar una interfaz de usuario de configuración en su hoja de propiedades del proveedor.
Si el inicio de sesión del proveedor de transporte se realiza correctamente, el proveedor debe devolver en el parámetro lppXPLogon un puntero a un objeto de inicio de sesión. La cola MAPI usará este objeto para obtener acceso adicional al proveedor. Si TransportLogon muestra un cuadro de diálogo de inicio de sesión 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.
Para la mayoría de los valores de error devueltos por TransportLogon, MAPI deshabilita los servicios de mensajes a los que pertenece el proveedor. MAPI no llamará a ningún proveedor que pertenezca a ese servicio para el resto de la sesión MAPI. Por el contrario, cuando TransportLogon 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. TransportLogon debe devolver MAPI_E_FAILONEPROVIDER si encuentra un error que no garantiza la deshabilitación del servicio durante el resto de la sesión.
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.
Si el proveedor detecta que toda la información necesaria no está en el perfil, debe devolver MAPI_E_UNCONFIGURED para que MAPI llame a la función de punto de entrada del servicio de mensajes del proveedor.