Semántica operativa de MB
Transacciones asincrónicas
El modelo de controlador MB supone que no se bloquea la semántica operativa entre el servicio MB y los controladores de miniporte mediante el mecanismo de notificación asincrónico proporcionado en NDIS 6.x. Este mecanismo permite que el servicio MB continúe enviando solicitudes de OID al controlador de miniporte para su procesamiento sin esperar a que se complete la operación actual.
Una transacción asincrónica es un protocolo de enlace triple que comienza con la solicitud inicial, seguida de una respuesta de estado de solicitud y, a continuación, completada por una indicación transaccional final. La respuesta de estado de la solicitud es provisional en que solo reconoce que el controlador de minipuerto ha recibido la solicitud. La indicación asincrónica de seguimiento es transaccional en que señala la finalización de la transacción. El controlador de minipuerto devuelve el código de estado, así como los datos resultantes en la indicación transaccional.
Solicitudes asincrónicas de conjunto y consulta
Muchas de las solicitudes OID de conjunto y consulta que usa el servicio MB se procesan de forma asincrónica. Para obtener más información sobre las solicitudes OID establecidas y de consulta , consulte NDIS_OID_REQUEST. La tabla "WWAN-specific OIDs" del tema MB Data Model identifica los OID que se procesan de forma asincrónica.
En el diagrama siguiente se representa la secuencia de interacción de una transacción de consulta asincrónica entre el servicio MB y el controlador de minipuerto. Las etiquetas en negrita representan identificadores OID o control de flujo transaccional, y las etiquetas en texto normal representan las marcas importantes dentro de la estructura OID.
El protocolo de enlace triple es el mismo para las solicitudes de consulta y de conjunto .
Excepto por OID_WWAN_DRIVER_CAPS, todas las demás solicitudes de OID específicas de MB siguen el mecanismo de transacción asincrónica para el intercambio de información entre los controladores de minipuerto y el servicio MB, con las siguientes notas adicionales:
Los controladores de miniport deben producir un error inmediato en una solicitud de OID en cualquier condición de error, como una solicitud de OID no válida.
Los controladores miniport deben devolver cualquier condición de error específica de WWAN con el código de error correcto (por ejemplo, WWAN_STATUS_XXX) especificado en el miembro uStatus de la estructura de notificación de eventos. Los controladores de minipuerto también deben rellenar adecuadamente los miembros que siguen al miembro uStatus , según sea necesario. Por ejemplo, los controladores de minipuerto deben rellenar el miembro ContextState.uNwError de la estructura NDIS_WWAN_CONTEXT_STATE , si está disponible. Sin embargo, en el caso de un error al procesar identificadores OID relacionados con PIN, es posible que los controladores de miniporte no tengan necesariamente la información de estado pin actual para especificar en el miembro PinInfo.PinState de NDIS_WWAN_PIN_INFO.
Los controladores de minipuerto deben devolver NDIS_STATUS_INDICATION_REQUIRED como respuesta provisional para todas las solicitudes de OID asincrónicas.
Los controladores de minipuerto deben ser capaces de distinguir los cambios de estado del dispositivo causados por una solicitud de OID de otras causas. Los controladores de miniport deben enviar notificaciones transaccionales para los cambios de estado resultantes de las solicitudes de OID y deben enviar notificaciones de eventos no solicitadas para los cambios de estado de otras causas.
Los controladores de minipuerto son responsables de administrar la memoria en modo kernel, aunque el servicio MB asigna inicialmente la memoria para las solicitudes. Una vez que el servicio MB recibe una respuesta de un controlador de minipuerto, el servicio puede liberar la memoria en modo de usuario que asignó para la solicitud OID.
En el diagrama siguiente se representa la secuencia de interacción de una transacción de conjunto asincrónica entre el servicio MB y el controlador de minipuerto. Las etiquetas en negrita representan identificadores OID o control de flujo transaccional, y las etiquetas en texto normal representan las marcas importantes dentro de la estructura OID.
Respuesta asincrónica
La especificación NDIS 6.0 (publicada con Windows Vista) introdujo un nuevo código de estado, NDIS_STATUS_INDICATION_REQUIRED, para que los controladores de miniporte transmitan la naturaleza asincrónica de una transacción al servicio MB en una respuesta provisional del controlador de miniporte a una solicitud de OID.
Como se mencionó en Información general de la interfaz de MB, el servicio MB no tiene acceso directo a la memoria en modo kernel asignada por un controlador de miniporte MB. Se supone que el resultado de ejecución almacenado en la memoria en modo kernel se copia y se pone a disposición del servicio MB por parte de algún intermediario, como WMI o un controlador de filtro NDIS. Por lo tanto, los controladores de minipuerto pueden liberar la memoria asignada en modo kernel después de que la llamada de función NdisMIndicateStatusEx se devuelva en la indicación transaccional.
Los procedimientos de protocolo de enlace que deben seguir los controladores de miniporte y el servicio MB se describen en el procedimiento siguiente.
Procedimiento del controlador de minipuerto MB
Tras recibir una solicitud de OID, los controladores de minipuerto deben realizar los pasos siguientes:
Asigne memoria en modo kernel para copiar el contenido de la estructura de datos NDIS_OID_REQUEST asociada a la solicitud OID.
Entre los parámetros de la solicitud, asegúrese de que también se copian los miembros RequestId y RequestHandle de la estructura de solicitudes OID. Estos miembros se usarán más adelante en la indicación transaccional.
Devuelve una respuesta de estado de NDIS_STATUS_INDICATION_REQUIRED provisional para informar al servicio MB de que el controlador de miniporte completará la solicitud de forma asincrónica.
Tras la finalización de la operación, almacene el resultado en memoria local o asignada por el controlador, según corresponda.
Llame a la función NdisMIndicateStatusEx para notificar al servicio MB que se ha completado la operación pendiente. Los controladores de minipuerto deben rellenar los miembros de la estructura NDIS_STATUS_INDICATION de la siguiente manera:
- Establezca el miembro StatusCode en el tipo de notificación de estado. Por ejemplo, NDIS_STATUS_WWAN_XXX.
- Establezca el miembro DestinationHandle en el miembro RequestHandle que se recibió en la estructura de datos NDIS_OID_REQUEST cuando el controlador de miniporte recibió la solicitud de OID correspondiente.
- Establezca el miembro RequestId para que coincida con el miembro RequestId de la estructura de estado de NDIS_OID_REQUEST cuando el controlador de miniporte recibió la solicitud de OID correspondiente.
- Establezca los miembros StatusBuffer y StatusBufferSize para que apunten a la memoria asignada por el controlador de miniporte y el tamaño del búfer de memoria, respectivamente. Este búfer de memoria contiene el resultado de la operación completada.
- Si la operación se completa correctamente, establezca el miembro uStatus en WWAN_STATUS_SUCCESS. De lo contrario, establezca el miembro uStatus en el valor de WWAN_STATUS_XXX adecuado para indicar el tipo de error.
Cuando se devuelve la llamada de función, el controlador de minipuerto debe liberar la memoria que asignó para la solicitud OID.
Procedimiento de servicio MB
El servicio MB procesa transacciones asincrónicas mediante el procedimiento siguiente:
Asigne memoria de búfer para la solicitud en función de la estructura de datos OID. Rellene los miembros de la estructura de datos con los valores adecuados.
Llame a la función NdisOidRequest con el miembro InformationBuffer que apunta a la estructura de datos OID para la solicitud OID y espere a que el controlador de miniporte responda.
Tras recibir un NDIS_STATUS_INDICATION_REQUIRED respuesta provisional del controlador de minipuerto, el servicio MB guarda requestId, libera la memoria asignada y marca la transacción como abierta. En este momento, el servicio MB es libre de procesar NOTIFICACIONES y solicitudes de OID posteriores.
Después de recibir una notificación con NDIS_STATUS_WWAN_XXX como valor StatusCode , compruebe si requestId coincide con el de cualquier transacción marcada como abierta. Si hay una coincidencia, el servicio cierra la transacción. Si no se encuentra ninguna coincidencia, trate la notificación como una notificación de eventos no solicitada.
Procese los datos devueltos en el miembro StatusBuffer y realice cambios de estado en el servicio MB según corresponda.
Indicaciones
Hay dos tipos de indicaciones específicas de WWAN que los controladores de miniporte pueden generar:
Notificaciones de eventos que resultan de un cambio de estado de objeto en el dispositivo MB.
Notificaciones transaccionales que indican la finalización de una operación asincrónica.
En ambos casos, los controladores de minipuerto deben llamar a la función NdisMIndicateStatusEx.
Notificación de evento
La notificación de eventos no está solicitada en el sentido de que el controlador de miniporte envía proactivamente la indicación al servicio MB como evento de cambio de estado. El cambio de estado se debe a una acción de alguna entidad distinta del servicio MB. El servicio MB supone que los controladores de minipuerto pueden detectar la causa del cambio.
Para cualquier notificación de eventos específica de WWAN, los controladores de minipuerto deben establecer el miembro RequestId de la estructura de NDIS_STATUS_INDICATION en cero. El miembro StatusCode especifica qué objeto del dispositivo MB ha cambiado. El controlador de minipuerto puede establecer este objeto en cualquiera de los valores siguientes:
NDIS_STATUS_WWAN_HOME_PROVIDER
NDIS_STATUS_WWAN_PREFERRED_PROVIDERS
NDIS_STATUS_WWAN_VISIBLE_PROVIDERS
NDIS_STATUS_WWAN_REGISTER_STATE
NDIS_STATUS_WWAN_PACKET_SERVICE
NDIS_STATUS_WWAN_CONTEXT_STATE
NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS
NDIS_STATUS_WWAN_SERVICE_ACTIVATION
NDIS_STATUS_WWAN_SMS_CONFIGURATION
NDIS_STATUS_WWAN_VENDOR_SPECIFIC
El servicio MB también puede procesar otras notificaciones de eventos de NDIS. Estas notificaciones de eventos que no son MB no están necesariamente sujetas al requisito de que sus valores RequestId se establezcan en cero.
Notificaciones transaccionales
Los controladores de miniporte usan notificaciones transaccionales para informar al servicio MB de que se ha completado una transacción asincrónica y el servicio MB usa notificaciones transaccionales para cerrar las transacciones abiertas y actualizar su máquina de estado.
El servicio MB espera notificaciones transaccionales para que pueda cerrar las transacciones abiertas. Es el intercambio final del protocolo de enlace triple entre el servicio MB y el controlador de miniporte en una transacción asincrónica. El valor del miembro RequestId del NDIS_STATUS_INDICATION en cualquier notificación transaccional debe ser distinto de cero, que se copia de la solicitud correspondiente en la misma transacción.
Debe establecer el miembro RequestId de la estructura de NDIS_STATUS_INDICATION correctamente para que el mecanismo asincrónico funcione correctamente. El servicio MB garantiza que el valor requestId sea único y distinto de cero entre todas las solicitudes pendientes. Los controladores de miniport deben devolver el mismo valor RequestId en la indicación correspondiente para que el servicio MB ponga en correlación la indicación con una transacción abierta.
Estructura de indicación de estado
Tanto la respuesta asincrónica para una solicitud de OID determinada como las estructuras de notificación de eventos no solicitadas comparten los siguientes miembros de estructura a los que apunta el miembro StatusBuffer del parámetro StatusIndication a NdisMIndicateStatusEx:
typedef struct _NDIS_WWAN_XXX {
NDIS_OBJECT_HEADER Header;
WWAN_STATUS uStatus;
ULONG uNwError;//Optional. Only used for network operations.
WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;
Un valor de cero en el miembro RequestId de la estructura de NDIS_STATUS_INDICATION significa que es una notificación de eventos no solicitada y puede producirse en cualquier momento.
Si el miembro uStatus de la indicación devuelta de cualquier solicitud OID de conjunto o consulta no es igual a WWAN_STATUS_SUCCESS los miembros de la estructura de NDIS_WWAN_XXX asociada no necesitan ser válidos.
En el caso de notificaciones de eventos no solicitadas basadas en eventos de red, los controladores de minipuerto deben rellenar el miembro uNwError según corresponda.
En la tabla siguiente se muestran los valores de error de código de registro, conexión de paquetes y desasociación de paquetes definidos en la especificación TS 24.008 de 3GPP para redes basadas en GSM:
| 3GPP 24.008 Código de causa | Interpretación del código de causa |
|---|---|
2 - Identidad de suscriptor móvil internacional (IMSI) desconocida en HLR |
La SIM o el dispositivo no están activados o la suscripción ha expirado, lo que provocó una desactivación de red. |
4 - IMSI desconocido en VLR |
La característica de itinerancia no está suscrita. |
6 - ME ilegal |
MS bloqueado por la red debido a un informe robado. |
7- No se permiten los servicios GPRS |
El usuario no tiene una suscripción a GPRS. El usuario solo tiene una suscripción de conexión de voz. |
8- No se permiten los servicios GPRS y no GPRS |
No se permiten los servicios GPRS y no GPRS. |
11 - PLMN no permitido |
La red bloquea el servicio debido a una suscripción expirada u otra causa. |
12 - Área de ubicación no permitida |
La suscripción de usuario no permite el acceso en el área de ubicación actual. |
13 - Itinerancia no permitida en esta área de ubicación |
La suscripción permite itinerancia, pero no se permite itinerancia en el área de ubicación actual. |
14 - Servicios GPRS no permitidos en este PLMN |
El proveedor de red seleccionado no proporciona el servicio GPRS a MS. |
15 - No hay celdas adecuadas en el área de ubicación |
No hay ninguna suscripción para el servicio. |
17- Error de red |
Error de registro. |
22 - Congestión |
Error de registro debido a la congestión de la red. |
Por ejemplo, si la red inicia un evento de contexto de desactivación porque no se permite itinerancia en el área de ubicación, los controladores de minipuerto deben establecer el miembro uNwError en 13 según los códigos de causa TS 24.008 de 3GPP para las redes basadas en GSM.
También se debe aplicar lógica similar a las redes basadas en CONFIDENCIALIDAD. Sin embargo, no hay ningún estándar para los códigos de error de red basados en ASCII. Los dispositivos basados en ASCII deben usar los códigos de error específicos de la red o específicos del dispositivo.
En el caso de una respuesta asincrónica del controlador de miniporte a las solicitudes OID, el miembro RequestId de la estructura de NDIS_STATUS_INDICATION es un número distinto de cero que se pasó al controlador de minipuerto como parte de una solicitud de consulta o conjunto. El controlador de minipuerto debe rellenar el miembro uStatus según corresponda. Por ejemplo, WWAN_STATUS_SUCCESS o cualquiera de los valores de error adecuados enumerados en la sección siguiente. Además de esto, el controlador de minipuerto debe rellenar el miembro uNwError cuando corresponda y esté disponible.
Estado de notificación de eventos
En la tabla siguiente se enumeran los códigos de WWAN_STATUS que los controladores de miniporte MB pueden especificar en el miembro uStatus de las estructuras de notificación de eventos de NDIS_WWAN_XXX.
| Valor | Significado |
|---|---|
WWAN_STATUS_SUCCESS |
La operación se realizó correctamente. |
WWAN_STATUS_FAILURE |
Error en la operación (error genérico). |
WWAN_STATUS_BUSY |
Error en la operación porque el dispositivo está ocupado. |
WWAN_STATUS_SIM_NOT_INSERTED |
Error en la operación porque la tarjeta SIM no se insertó completamente en el dispositivo. |
WWAN_STATUS_BAD_SIM |
Error en la operación porque la tarjeta SIM es incorrecta y no se puede usar más. |
WWAN_STATUS_PIN_REQUIRED |
Error en la operación porque se debe escribir un PIN para continuar. |
WWAN_STATUS_PIN_DISABLED |
Error en la operación porque el PIN está deshabilitado. |
WWAN_STATUS_NOT_REGISTERED |
Error en la operación porque el dispositivo no está registrado en ninguna red. |
WWAN_STATUS_PROVIDERS_NOT_FOUND |
Error en la operación porque no se encontró ningún proveedor de red. |
WWAN_STATUS_NO_DEVICE_SUPPORT |
Error en la operación porque el dispositivo no admite la operación. |
WWAN_STATUS_PROVIDER_NOT_VISIBLE |
Error en la operación porque el proveedor de servicios no está visible actualmente. |
WWAN_STATUS_DATA_CLASS_NOT_AVAILABLE |
Error en la operación porque la clase de datos solicitada no estaba disponible. |
WWAN_STATUS_PACKET_SVC_DETACHED |
Error en la operación porque el servicio de paquetes está desasociado. |
WWAN_STATUS_MAX_ACTIVATED_CONTEXTS |
Error en la operación porque se ha alcanzado el número máximo de contextos activados. |
WWAN_STATUS_NOT_INITIALIZED |
Error en la operación porque el dispositivo está en proceso de inicialización. Vuelva a intentar la operación después de que el estado listo del dispositivo cambie a WwanReadyStateInitialized. |
WWAN_STATUS_VOICE_CALL_IN_PROGRESS |
Error en la operación porque hay una llamada de voz en curso. |
WWAN_STATUS_CONTEXT_NOT_ACTIVATED |
Error en la operación porque el contexto no está activado. |
WWAN_STATUS_SERVICE_NOT_ACTIVATED |
Error en la operación porque el servicio no está activado. |
WWAN_STATUS_INVALID_ACCESS_STRING |
Error en la operación porque la cadena de acceso no es válida. |
WWAN_STATUS_INVALID_USER_NAME_PWD |
Error en la operación porque el nombre de usuario o la contraseña proporcionados no son válidos. |
WWAN_STATUS_RADIO_POWER_OFF |
Error en la operación porque la radio está apagada actualmente. |
WWAN_STATUS_INVALID_PARAMETERS |
Error en la operación debido a parámetros no válidos. |
WWAN_STATUS_READ_FAILURE |
Error en la operación debido a un error de lectura. |
WWAN_STATUS_WRITE_FAILURE |
Error en la operación debido a un error de escritura. |
En la tabla siguiente se muestran los valores de estado específicos de SMS.
| Valor | Significado |
|---|---|
WWAN_STATUS_SMS_OPERATION_NOT_ALLOWED |
Error en la operación de SMS porque no se permite la operación. |
WWAN_STATUS_SMS_MEMORY_FAILURE |
Error en la operación de SMS debido a un error de memoria. |
WWAN_STATUS_SMS_INVALID_MEMORY_INDEX |
Error en la operación de SMS debido a un índice de memoria no válido: WwanSmsFlagIndex para OID_WWAN_SMS_READ. |
WWAN_STATUS_SMS_UNKNOWN_SMSC_ADDRESS |
Error en la operación de SMS porque el número del centro de servicios no es válido o desconocido. |
WWAN_STATUS_SMS_NETWORK_TIMEOUT |
Error en la operación de SMS debido a un tiempo de espera de red. |
WWAN_STATUS_SMS_MEMORY_FULL |
Error en la operación de SMS porque el almacén de mensajes SMS está lleno. |
WWAN_STATUS_SMS_UNKNOWN_ERROR |
Error en la operación de SMS debido a un error desconocido (un error genérico). |
WWAN_STATUS_SMS_FILTER_NOT_SUPPORTED |
Error en la operación de SMS porque no se admite el tipo de filtro solicitado. |
WWAN_STATUS_SMS_MORE_DATA |
Esta transacción aún no se ha completado. Se han devuelto algunos datos y hay más datos que se van a devolver. |
WWAN_STATUS_SMS_LANG_NOT_SUPPORTED |
Error en la operación de SMS porque no se admite el idioma sms. Esto solo se aplica a los dispositivos basados en FRAMEWORK. |
WWAN_STATUS_SMS_ENCODING_NOT_SUPPORTED |
Error en la operación de SMS porque no se admite la codificación sms. Esto solo se aplica a los dispositivos basados en FRAMEWORK. |
WWAN_STATUS_SMS_FORMAT_NOT_SUPPORTED |
Error en la operación de SMS porque no se admite el formato SMS. |
Nota Estos códigos de estado específicos de WWAN solo se usan para transacciones asincrónicas en el miembro uStatus de las estructuras NDIS_WWAN_XXX.
Los controladores de minipuerto usan notificaciones de eventos para informar al servicio MB sobre un cambio de estado de objeto en su dispositivo MB sin haber recibido primero una solicitud de OID. El servicio MB usa notificaciones de eventos para actualizar solo su máquina de estado.
Tenga en cuenta que, aunque NDIS serializa todas las solicitudes que se envían a los controladores de minipuerto, es posible que los controladores de miniporte no devuelvan las respuestas en el mismo orden. Esto se debe a que las solicitudes en cola del controlador de minipuerto se pueden procesar en paralelo. Por lo tanto, el servicio MB garantiza que, si dos solicitudes dependen entre sí, no enviará la segunda solicitud hasta que el controlador de minipuerto complete la primera solicitud.
Notificación de cambio de estado
En general, los controladores de minipuerto siempre deben notificar al servicio MB el estado actualizado de su dispositivo MB a través de notificaciones transaccionales o a través de notificaciones de eventos no solicitados. Los siguientes escenarios son algunas excepciones en las que los controladores de minipuerto no deben responder con información de estado actualizada. El servicio MB puede determinar el estado actualizado a partir del estado de finalización de otras operaciones:
Los controladores de minipuerto no necesitan enviar una indicación de evento de NDIS_STATUS_WWAN_PIN_LIST cuando se producen cambios de estado de PIN porque el servicio MB solicitó habilitar o deshabilitar el PIN.
Los controladores de minipuerto no necesitan devolver la lista actualizada de los contextos aprovisionados en las respuestas transaccionales a OID_WWAN_PROVISIONED_CONTEXT establecer operaciones.
Los controladores de minipuerto no necesitan responder con la lista actualizada de los proveedores preferidos en las respuestas transaccionales a OID_WWAN_PREFERRED_PROVIDERS operaciones establecidas . El servicio MB puede determinar esta información en función de la lista inicial y el estado correcto de la operación de establecimiento .
Los controladores de minipuerto no necesitan responder con el valor de WWAN_SMS_CONFIGURATION actual para OID_WWAN_SMS_CONFIGURATION establecer operaciones.