IMAPIStatus::ValidateState
Hace referencia a: Outlook 2013 | Outlook 2016
Confirma la información de estado externo disponible para el recurso MAPI o el proveedor de servicios. Este método se admite en todos los objetos de estado.
HRESULT ValidateState(
ULONG_PTR ulUIParam,
ULONG ulFlags
);
Parameters
ulUIParam
[in] Identificador de la ventana primaria de los cuadros de diálogo o ventanas que muestra este método.
ulFlags
[in] Máscara de bits de marcas que controla la validación. Se pueden establecer las siguientes marcas:
ABORT_XP_HEADER_OPERATION
El usuario canceló la operación, normalmente haciendo clic en el botón Cancelar del cuadro de diálogo correspondiente. El objeto de estado tiene dos opciones:
Continúe trabajando en la operación.
Detenga la operación y devuelva MAPI_E_USER_CANCELED.
CONFIG_CHANGED
Una o varias propiedades de configuración del objeto de estado han cambiado. Los clientes pueden establecer esta marca para permitir que la cola MAPI corrija dinámicamente los errores críticos del proveedor de transporte.
FORCE_XP_CONNECT
El objeto de estado debe realizar una conexión. Cuando se usa esta marca con la marca REFRESH_XP_HEADER_CACHE o PROCESS_XP_HEADER_CACHE, la conexión se produce sin almacenamiento en caché.
FORCE_XP_DISCONNECT
El objeto de estado debe realizar una operación de desconexión. Cuando se usa esta marca con la marca REFRESH_XP_HEADER_CACHE o PROCESS_XP_HEADER_CACHE, la desconexión se produce sin almacenar en caché.
PROCESS_XP_HEADER_CACHE
Se deben procesar las entradas de la tabla de caché de encabezados, se deben descargar todos los mensajes marcados con la marca MSGSTATUS_REMOTE_DOWNLOAD y se deben eliminar todos los mensajes marcados con la marca MSGSTATUS_REMOTE_DELETE. Se deben mover los mensajes que tengan MSGSTATUS_REMOTE_DOWNLOAD y MSGSTATUS_REMOTE_DELETE establecidos.
REFRESH_XP_HEADER_CACHE
Para un proveedor de transporte remoto, se debe descargar una nueva lista de encabezados de mensaje y se deben borrar todas las marcas que marcan el estado del mensaje.
SUPPRESS_UI
Impide que el objeto de estado muestre una interfaz de usuario como parte de la operación.
Valor devuelto
S_OK
La validación se realizó correctamente.
MAPI_E_BUSY
Hay otra operación en curso; se debe permitir que se complete, o se debe detener, antes de que se inicie esta operación.
MAPI_E_NO_SUPPORT
El objeto status no admite el método de validación, como se indica en la ausencia de la marca de STATUS_VALIDATE_STATE en la propiedad PR_RESOURCE_METHODS (PidTagResourceMethods).
MAPI_E_USER_CANCEL
El usuario canceló la operación de validación, normalmente haciendo clic en el botón Cancelar de un cuadro de diálogo. Este valor solo lo devuelven los proveedores de transporte remotos.
Comentarios
El método IMAPIStatus::ValidateState comprueba el estado de un recurso asociado a un objeto de estado. ValidateState es el único método de la interfaz IMAPIStatus necesario para todos los objetos de estado. El comportamiento exacto de este método depende de la implementación. En la tabla siguiente se describe la implementación de cada uno de los diferentes tipos de objetos de estado.
| Status (objeto) | Implementación de ValidateState |
|---|---|
| Subsistema MAPI |
Valida el estado de todos los recursos que poseen los proveedores de servicios actualmente activos y el propio subsistema. |
| Cola MAPI |
Realiza un inicio de sesión de todos los proveedores de transporte, independientemente de si ya han iniciado sesión. |
| Libreta de direcciones MAPI |
Comprueba las entradas de su sección de perfil. |
| Proveedor de servicios |
La implementación depende del tipo de proveedor y de las marcas establecidas en el parámetro ulFlags . |
Notas a los implementadores
Las aplicaciones cliente remotas llaman al método ValidateState para iniciar el procesamiento remoto de varias acciones. Este método existe principalmente para establecer bits de estado para comunicarse con la cola MAPI, en lugar de para realizar realmente cualquier trabajo. Normalmente, el proveedor de transporte establece marcas en su fila de estado que indican al colador MAPI qué acciones se deben iniciar para completar la solicitud del cliente.
En este modelo de interacción cliente-transporte-cola, las acciones solicitadas por el cliente son asincrónicas, en que ValidateState devuelve antes de que se completen las acciones solicitadas. Sin embargo, las acciones que no implican necesariamente el sistema de mensajería subyacente, o que implican una interfaz específica del transporte, pueden ser sincrónicas. La aplicación cliente pasa una máscara de bits de las siguientes marcas para especificar qué acciones debe realizar el proveedor de transporte remoto.
ABORT_XP_HEADER_OPERATION
Si es posible, el proveedor de transporte remoto debe cancelar las operaciones que impliquen la descarga de encabezados. Para ello, el proveedor de transporte debe establecer los siguientes valores de propiedad en la fila de estado del objeto de inicio de sesión:
Borre los bits STATUS_INBOUND_ENABLED y STATUS_INBOUND_ACTIVE de la propiedad PR_STATUS_CODE (PidTagStatusCode) para indicar a la cola MAPI que detenga el proceso de vaciado entrante para este proveedor de transporte.
Establezca el bit STATUS_OFFLINE en la propiedad PR_STATUS_CODE .
Establezca la propiedad PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) en TRUE.
Establezca la propiedad PR_STATUS_STRING (PidTagStatusString) en una cadena que indique el estado del proveedor de transporte para el usuario.
Devuelve S_OK. Sin embargo, si no se puede cancelar la operación en curso, ValidateState debe devolver MAPI_E_BUSY.
FORCE_XP_CONNECT
Un proveedor de transporte remoto nunca debe establecer una conexión a un recurso compartido (por ejemplo, un módem o un puerto COM) fuera del contexto de la interacción de transporte de cola MAPI implicada en el método IXPLogon::FlushQueues . Si se llama a ValidateState con esta marca, el proveedor de transporte debe hacer lo siguiente:
Establezca una marca de estado interno para indicar que se debe establecer la conexión remota cuando se llama al método IXPLogon::FlushQueues .
Establezca los valores correctos en la tabla de estado para que la cola MAPI inicie el proceso de vaciado de cola.
Cuando se complete el vaciado de colas, libere el recurso compartido.
Borre el bit STATUS_OFFLINE de la propiedad PR_STATUS_CODE .
Devuelve S_OK.
FORCE_XP_DISCONNECT
El proveedor de transporte remoto debe liberar su conexión a los recursos del sistema de mensajería. Después de hacerlo, debe establecer el bit STATUS_OFFLINE en la propiedad PR_STATUS_CODE y devolver S_OK.
PROCESS_XP_HEADER_CACHE
El proveedor de transporte remoto debe procesar mensajes remotos y cargar los mensajes que se hayan aplazado. Para ello, el proveedor de transporte debe establecer los siguientes valores de propiedad en la fila de estado del objeto de inicio de sesión:
Establezca la propiedad PR_STATUS_STRING en una cadena que indique el estado del proveedor de transporte para el usuario.
Establezca los bits STATUS_OUTBOUND_ENABLED y STATUS_OUTBOUND_ACTIVE en la propiedad PR_STATUS_CODE .
Establezca la propiedad PR_REMOTE_VALIDATE_OK de la fila de estado del proveedor de transporte en FALSE.
Si hay otra operación en curso (como descargar encabezados) cuando se llama a ValidateState , ValidateState debe devolver MAPI_E_BUSY.
Ejecute también el código para procesar la marca de REFRESH_XP_HEADER_CACHE para satisfacer los requisitos del cliente de Microsoft Exchange.
REFRESH_XP_HEADER_CACHE
El proveedor de transporte remoto debe recuperar los nuevos encabezados de mensaje del sistema de mensajería. Para ello, el proveedor de transporte debe hacer lo siguiente:
Establezca la propiedad PR_STATUS_STRING en una cadena que indique el estado del proveedor de transporte para el usuario.
Establezca los bits STATUS_INBOUND_ENABLED y STATUS_INBOUND_ACTIVE en la propiedad PR_STATUS_CODE .
Borre el bit STATUS_OFFLINE de la propiedad PR_STATUS_CODE .
Establezca el bit STATUS_ONLINE en la propiedad PR_STATUS_CODE .
Establezca la propiedad PR_REMOTE_VALIDATE_OK de la fila de estado del proveedor de transporte en FALSE.
SHOW_XP_SESSION_UI
Si el proveedor de transporte tiene algún fragmento de interfaz de usuario para procesar los encabezados de mensaje (por ejemplo, un cuadro de diálogo que confirma la descarga de mensajes), se debe mostrar ese cuadro de diálogo. De lo contrario, ValidateState puede devolver MAPI_E_NO_SUPPORT.
Si se pasan marcas distintas de estas, ValidateState debe devolver MAPI_E_UNKNOWN_FLAGS.
La llamada del cliente al proveedor de transporte suele ser al método IMAPIStatus::ValidateState . Durante el procesamiento de ValidateState, el proveedor de transporte no debe realizar ninguna acción que asigne recursos escasos del sistema, como un módem o un puerto COM. Esto se debe a que la cola MAPI a veces tendrá que vaciar las colas en más de un proveedor de transporte. Sin embargo, el cliente puede llamar al método ValidateState de cualquier proveedor de transporte en cualquier momento. Si el proveedor de transporte intenta asignar un recurso escaso durante el procesamiento de ValidateState, puede producirse un error debido a un conflicto con otro proveedor de transporte que la cola MAPI ha indicado para vaciar sus colas. Si permite que todas las asignaciones de recursos escasas se produzcan bajo la dirección de la cola MAPI, puede evitar estos conflictos. El proveedor de transporte debe admitir la propiedad PR_REMOTE_VALIDATE_OK para que las aplicaciones cliente puedan detectar cuándo está ocupado el proveedor de transporte o esperando a que la cola MAPI inicie una acción.
Notas para los llamadores
Dado que este método puede hacer que se realicen otras llamadas potencialmente largas, ValidateState puede devolver MAPI_E_BUSY para informarle de que este método está esperando a que se complete otra operación. Debe esperar hasta que se complete la operación pendiente antes de intentar otra tarea.
Tiene el mayor control sobre las llamadas a objetos de estado del proveedor de transporte. Puede pasar una o varias marcas a ValidateState que afectan a las operaciones del proveedor de transporte. Por ejemplo, la marca ABORT_XP_HEADER_OPERATION indica que el usuario canceló la validación. Los proveedores de transporte pueden decidir anular, devolver MAPI_E_USER_CANCELED o continuar.
Puede establecer la marca de CONFIG_CHANGED en una llamada al objeto de estado de un proveedor de servicios o a la cola MAPI para indicar que se ha cambiado una opción de configuración. Puede usar CONFIG_CHANGED para volver a configurar dinámicamente un proveedor de transporte. Cuando se establece CONFIG_CHANGED en una llamada al objeto de estado de un proveedor de servicios, el proveedor responde con una llamada a IMAPISupport::SpoolerNotify para alertar al colador MAPI del cambio. Al establecer CONFIG_CHANGED en una llamada al objeto de estado de la cola MAPI, el colador llama a IXPLogon::AddressTypes para cada proveedor de transporte activo. AddressTypes informa a la cola MAPI de los tipos de direcciones admitidos de un transporte. Algunos proveedores de servicios también muestran un indicador de progreso si se espera que la validación dure mucho tiempo. Mostrar un indicador de progreso es útil, pero no necesario.
Cuando se establece la marca de SUPPRESS_UI, no se puede mostrar ninguna de las hojas de propiedades de configuración ni los cuadros de diálogo de progreso.