Semântica Operacional do MB
Transações assíncronas
O modelo de driver MB pressupõe semântica operacional sem bloqueio entre o Serviço MB e os drivers de miniport usando o mecanismo de notificação assíncrona fornecido no NDIS 6.x. Esse mecanismo permite que o Serviço mb continue a enviar solicitações OID para o driver de miniporto para processamento sem aguardar a conclusão da operação atual.
Uma transação assíncrona é um handshake de três vias que começa com a solicitação inicial, seguido por uma solicitação status resposta e, em seguida, concluído por uma indicação transacional final. A solicitação status resposta é provisória, pois apenas reconhece que o driver de miniporto recebeu a solicitação. A indicação assíncrona de acompanhamento é transacional, pois sinaliza a conclusão da transação. O driver de miniporta retorna o código status, bem como os dados resultantes na indicação transacional.
Definir e consultar solicitações assíncronas
Muitas das solicitações OID de definição e consulta usadas pelo Serviço MB são processadas de forma assíncrona. Para obter mais informações sobre o conjunto e consultar solicitações OID, consulte NDIS_OID_REQUEST. A tabela "OIDs específicas do WWAN" no tópico Modelo de Dados do MB identifica quais OIDs são processados de forma assíncrona.
O diagrama a seguir representa a sequência de interação para uma transação de consulta assíncrona entre o Serviço MB e o driver de miniporto. Os rótulos em negrito representam identificadores OID ou controle de fluxo transacional, e os rótulos em texto regular representam os sinalizadores importantes dentro da estrutura OID.
O handshake de três vias é o mesmo para solicitações de consulta e de definição .
Exceto por OID_WWAN_DRIVER_CAPS, todas as outras solicitações OID específicas do MB seguem o mecanismo de transação assíncrona para troca de informações entre drivers de miniporto e o Serviço MB, com as seguintes observações adicionais:
Os drivers de miniporte devem falhar imediatamente em uma solicitação OID em qualquer condição de erro, como uma solicitação OID inválida.
Os drivers de miniporto devem retornar quaisquer condições de erro específicas do WWAN com o código de erro correto (por exemplo, WWAN_STATUS_XXX) especificado no membro uStatus da estrutura de notificação de eventos. Os drivers de miniporto também devem preencher adequadamente os membros que seguem o membro uStatus , conforme necessário. Por exemplo, os drivers de miniporto devem preencher o membro ContextState.uNwError da estrutura NDIS_WWAN_CONTEXT_STATE , se disponível. No entanto, no caso de uma falha ao processar OIDs relacionados a PINs, os drivers de miniport podem não ter necessariamente as informações de estado do PIN atuais para especificar no membro PinInfo.PinState do NDIS_WWAN_PIN_INFO.
Os drivers de miniporto devem retornar NDIS_STATUS_INDICATION_REQUIRED como uma resposta provisória para todas as solicitações OID assíncronas.
Os drivers de miniporta devem ser capazes de distinguir as alterações de estado do dispositivo causadas por uma solicitação OID de outras causas. Os drivers de miniporta devem enviar notificações transacionais para alterações de estado resultantes de solicitações OID e devem enviar notificações de eventos não solicitadas para alterações de estado de outras causas.
Drivers de miniporta são responsáveis por gerenciar a memória do modo kernel, embora o Serviço MB inicialmente aloque a memória para solicitações. Depois que o Serviço MB receber uma resposta de um driver de miniporto, o serviço poderá liberar a memória do modo de usuário alocada para a solicitação OID.
O diagrama a seguir representa a sequência de interação para uma transação de conjunto assíncrona entre o Serviço MB e o driver de miniporto. Os rótulos em negrito representam identificadores OID ou controle de fluxo transacional, e os rótulos em texto regular representam os sinalizadores importantes dentro da estrutura OID.
Resposta assíncrona
A Especificação do NDIS 6.0 (lançada com o Windows Vista) introduziu um novo código de status, NDIS_STATUS_INDICATION_REQUIRED, para que os drivers de miniporto transmitam a natureza assíncrona de uma transação para o Serviço MB em uma resposta provisória do driver de miniporto a uma solicitação OID.
Conforme mencionado em Visão geral da interface MB, o serviço MB não tem acesso direto à memória do modo kernel alocada por um driver de miniporto MB. O resultado da execução armazenado na memória do modo kernel é considerado copiado e disponibilizado para o Serviço MB por algum intermediário, como WMI ou um driver de filtro NDIS. Portanto, os drivers de miniport podem liberar a memória alocada no modo kernel após a chamada da função NdisMIndicateStatusEx retornar na indicação transacional.
Os procedimentos de handshake que miniportam drivers e o Serviço MB devem seguir são descritos no procedimento a seguir.
Procedimento de driver de miniporta MB
Ao receber uma solicitação OID, os drivers de miniporto devem executar as seguintes etapas:
Aloque memória no modo kernel para copiar o conteúdo da estrutura de dados NDIS_OID_REQUEST associada à solicitação OID.
Entre os parâmetros da solicitação, verifique se os membros RequestId e RequestHandle da estrutura de solicitação OID também são copiados. Esses membros serão usados posteriormente na indicação transacional.
Retornar uma resposta NDIS_STATUS_INDICATION_REQUIRED status provisória para informar ao Serviço MB que o driver de miniporto concluirá a solicitação de forma assíncrona.
Após a conclusão da operação, armazene o resultado na memória local ou alocada pelo driver, conforme apropriado.
Chame a função NdisMIndicateStatusEx para notificar o Serviço MB de que a operação pendente foi concluída. Os drivers de miniport devem preencher os membros da estrutura NDIS_STATUS_INDICATION da seguinte maneira:
- Defina o membro StatusCode como o tipo de notificação de status. Por exemplo, NDIS_STATUS_WWAN_XXX.
- Defina o membro DestinationHandle como o membro RequestHandle que foi recebido na estrutura de dados NDIS_OID_REQUEST quando o driver de miniporto recebeu a solicitação OID correspondente.
- Defina o membro RequestId para corresponder ao membro RequestId da estrutura NDIS_OID_REQUEST status quando o driver de miniporto recebeu a solicitação OID correspondente.
- Defina os membros StatusBuffer e StatusBufferSize para apontar para a memória alocada pelo driver de miniport e o tamanho do buffer de memória, respectivamente. Esse buffer de memória contém o resultado da operação concluída.
- Se a operação for concluída com êxito, defina o membro uStatus como WWAN_STATUS_SUCCESS. Caso contrário, defina o membro uStatus como o valor de WWAN_STATUS_XXX apropriado para indicar o tipo de falha.
Quando a chamada de função retorna, o driver de miniporto deve liberar a memória alocada para a solicitação OID.
Procedimento de serviço MB
O Serviço MB processa transações assíncronas usando o seguinte procedimento:
Aloque memória de buffer para a solicitação com base na estrutura de dados OID. Preencha os membros da estrutura de dados com os valores apropriados.
Chame a função NdisOidRequest com o membro InformationBuffer apontando para a estrutura de dados OID para a solicitação OID e aguarde até que o driver de miniporto responda.
Após o recebimento de um NDIS_STATUS_INDICATION_REQUIRED resposta provisória do driver de miniporta, o Serviço MB salva o RequestId, libera a memória alocada e marca a transação como aberta. Neste ponto, o Serviço mb é gratuito para processar solicitações e notificações OID subsequentes.
Após o recebimento de uma notificação com NDIS_STATUS_WWAN_XXX como o valor StatusCode, marcar se RequestId corresponde à de qualquer transação marcada como aberta. Se houver uma correspondência, o serviço fechará a transação. Se nenhuma correspondência for encontrada, trate a notificação como uma notificação de evento não solicitada.
Processe os dados retornados no membro StatusBuffer e faça alterações de estado no Serviço MB conforme apropriado.
Indicações
Há dois tipos de indicações específicas do WWAN que os drivers de miniporto podem gerar:
Notificações de evento resultantes de uma alteração de estado de objeto no dispositivo MB.
Notificações transacionais que sinalizam a conclusão de uma operação assíncrona.
Em ambos os casos, os drivers de miniport devem chamar a função NdisMIndicateStatusEx.
Notificação de eventos
A notificação de evento não é solicitada no sentido de que o driver de miniporto envia proativamente a indicação para o Serviço MB como um evento de alteração de estado. A alteração de estado é causada por uma ação de alguma entidade diferente do Serviço MB. O Serviço MB pressupõe que os drivers de miniporto sejam capazes de detectar a causa da alteração.
Para qualquer notificação de evento específica do WWAN, os drivers de miniporto devem definir o membro RequestId da estrutura NDIS_STATUS_INDICATION como zero. O membro StatusCode especifica qual objeto no dispositivo MB foi alterado. O driver de miniporta pode definir esse objeto como qualquer um dos seguintes valores:
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
O Serviço MB também pode processar outras notificações de evento do NDIS. Essas notificações de evento não MB não estão necessariamente sujeitas ao requisito de que seus valores RequestId sejam definidos como zero.
Notificações transacionais
Os drivers de miniport usam notificações transacionais para informar ao Serviço MB que uma transação assíncrona foi concluída e o Serviço MB usa notificações transacionais para fechar transações abertas e atualizar seu computador de estado.
O Serviço MB espera notificações transacionais para que possa fechar transações abertas. É a troca final do handshake de três vias entre o Serviço MB e o driver de miniporto em uma transação assíncrona. O valor do membro RequestId do NDIS_STATUS_INDICATION em qualquer notificação transacional deve ser diferente de zero, que é copiado da solicitação correspondente na mesma transação.
Você deve definir o membro RequestId da estrutura NDIS_STATUS_INDICATION corretamente para que o mecanismo assíncrono funcione corretamente. O Serviço MB garante que o valor RequestId seja exclusivo e diferente de zero entre todas as solicitações pendentes. Os drivers de miniport devem retornar o mesmo valor RequestId na indicação correspondente para que o Serviço MB correlacione a indicação com uma transação aberta.
Estrutura de indicação de status
Tanto a resposta assíncrona para uma determinada solicitação OID quanto as estruturas de notificação de eventos não solicitadas compartilham os seguintes membros da estrutura apontados pelo membro StatusBuffer do parâmetro StatusIndication para 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;
Um valor igual a zero no membro RequestId da estrutura NDIS_STATUS_INDICATION significa que ele é uma notificação de evento não solicitada e pode ocorrer a qualquer momento.
Se o membro uStatus na indicação retornada de qualquer solicitação OID de conjunto ou consulta não for igual WWAN_STATUS_SUCCESS os membros da estrutura de NDIS_WWAN_XXX associada não precisarão ser válidos.
No caso de notificações de evento não solicitadas com base em eventos de rede, os drivers de miniport devem preencher o membro uNwError conforme apropriado, se aplicável.
A tabela a seguir mostra os valores de falha de código de registro, anexação de pacotes e desanexação de pacotes definidos na Especificação 3GPP TS 24.008 para redes baseadas em GSM:
| Código de causa 3GPP 24.008 | Interpretação do código de causa |
|---|---|
2 – IMSI (Identidade internacional do assinante móvel) desconhecida no HLR |
O SIM ou o dispositivo não está ativado ou a assinatura expirou, o que causou uma desativação da rede. |
4 – IMSI desconhecido na VLR |
O recurso de roaming não está inscrito. |
6 - ME ilegal |
MS bloqueada pela rede devido a um relatório roubado. |
7 – Serviços gprs não permitidos |
O usuário não tem uma assinatura gprs. O usuário tem apenas uma assinatura de conexão de voz. |
8 – Serviços GPRS e não GPRS não permitidos |
Serviços GPRS e não GPRS não são permitidos. |
11 – PLMN não permitido |
O serviço é bloqueado pela rede devido a uma assinatura expirada ou outra causa. |
12 – Área de localização não permitida |
A assinatura do usuário não permite o acesso na área de localização atual. |
13 – Roaming não permitido nesta área de localização |
A assinatura permite roaming, mas roaming não é permitido na área de localização atual. |
14 – Serviços gprs não permitidos neste PLMN |
O provedor de rede selecionado não fornece serviço GPRS para a MS. |
15 – Não há células adequadas na área de localização |
Nenhuma assinatura para o serviço. |
17 – Falha na rede |
Falha no registro. |
22 - Congestionamento |
Falha no registro devido ao congestionamento de rede. |
Por exemplo, se a rede iniciar um evento de contexto desativado porque roaming não é permitido na área de localização, os drivers de miniport devem definir o membro uNwError como 13 de acordo com os códigos de causa 3GPP TS 24.008 para redes baseadas em GSM.
Lógica semelhante também deve ser aplicada a redes baseadas em CDMA. No entanto, não há padrão para códigos de erro de rede baseados em CDMA. Os dispositivos baseados em CDMA devem usar os códigos de erro específicos da rede ou do dispositivo.
No caso da resposta assíncrona de um driver de miniporto às solicitações OID, o membro RequestId da estrutura NDIS_STATUS_INDICATION é um número diferente de zero que foi passado para o driver de miniporto como parte de um conjunto ou solicitação de consulta . O driver de miniporto deve preencher o membro uStatus conforme apropriado. Por exemplo, WWAN_STATUS_SUCCESS ou qualquer um dos valores de erro apropriados listados na seção a seguir. Além disso, o driver de miniporto deve preencher o membro uNwError quando apropriado e disponível.
Status da notificação de evento
A tabela a seguir lista os códigos de WWAN_STATUS que os drivers de miniporto MB podem especificar no membro uStatus das estruturas de notificação de eventos NDIS_WWAN_XXX.
| Valor | Significado |
|---|---|
WWAN_STATUS_SUCCESS |
A operação foi realizada com êxito. |
WWAN_STATUS_FAILURE |
Falha na operação (uma falha genérica). |
WWAN_STATUS_BUSY |
A operação falhou porque o dispositivo está ocupado. |
WWAN_STATUS_SIM_NOT_INSERTED |
A operação falhou porque a cartão sim não foi totalmente inserida no dispositivo. |
WWAN_STATUS_BAD_SIM |
A operação falhou porque o cartão sim está inválido e não pode ser usado mais. |
WWAN_STATUS_PIN_REQUIRED |
A operação falhou porque um PIN deve ser inserido para continuar. |
WWAN_STATUS_PIN_DISABLED |
A operação falhou porque o PIN está desabilitado. |
WWAN_STATUS_NOT_REGISTERED |
A operação falhou porque o dispositivo não está registrado em nenhuma rede. |
WWAN_STATUS_PROVIDERS_NOT_FOUND |
A operação falhou porque nenhum provedor de rede pôde ser encontrado. |
WWAN_STATUS_NO_DEVICE_SUPPORT |
A operação falhou porque o dispositivo não dá suporte à operação. |
WWAN_STATUS_PROVIDER_NOT_VISIBLE |
A operação falhou porque o provedor de serviços não está visível no momento. |
WWAN_STATUS_DATA_CLASS_NOT_AVAILABLE |
A operação falhou porque a classe de dados solicitada não estava disponível. |
WWAN_STATUS_PACKET_SVC_DETACHED |
A operação falhou porque o serviço de pacotes está desanexado. |
WWAN_STATUS_MAX_ACTIVATED_CONTEXTS |
A operação falhou porque o número máximo de contextos ativados foi atingido. |
WWAN_STATUS_NOT_INITIALIZED |
A operação falhou porque o dispositivo está em processo de inicialização. Repita a operação após o estado pronto do dispositivo ser alterado para WwanReadyStateInitialized. |
WWAN_STATUS_VOICE_CALL_IN_PROGRESS |
A operação falhou porque uma chamada de voz está em andamento. |
WWAN_STATUS_CONTEXT_NOT_ACTIVATED |
A operação falhou porque o contexto não está ativado. |
WWAN_STATUS_SERVICE_NOT_ACTIVATED |
A operação falhou porque o serviço não está ativado. |
WWAN_STATUS_INVALID_ACCESS_STRING |
A operação falhou porque a cadeia de caracteres de acesso é inválida. |
WWAN_STATUS_INVALID_USER_NAME_PWD |
A operação falhou porque o nome de usuário e/ou a senha fornecidos são inválidos. |
WWAN_STATUS_RADIO_POWER_OFF |
A operação falhou porque o rádio está desligado no momento. |
WWAN_STATUS_INVALID_PARAMETERS |
A operação falhou devido a parâmetros inválidos. |
WWAN_STATUS_READ_FAILURE |
A operação falhou devido a uma falha de leitura. |
WWAN_STATUS_WRITE_FAILURE |
A operação falhou devido a uma falha de gravação. |
A tabela a seguir mostra valores de status específicos do SMS.
| Valor | Significado |
|---|---|
WWAN_STATUS_SMS_OPERATION_NOT_ALLOWED |
A operação de SMS falhou porque a operação não é permitida. |
WWAN_STATUS_SMS_MEMORY_FAILURE |
A operação de SMS falhou devido a uma falha de memória. |
WWAN_STATUS_SMS_INVALID_MEMORY_INDEX |
Falha na operação de SMS devido a um índice de memória inválido – WwanSmsFlagIndex para OID_WWAN_SMS_READ. |
WWAN_STATUS_SMS_UNKNOWN_SMSC_ADDRESS |
Falha na operação de SMS porque o número da central de serviços é inválido ou desconhecido. |
WWAN_STATUS_SMS_NETWORK_TIMEOUT |
A operação de SMS falhou devido a um tempo limite de rede. |
WWAN_STATUS_SMS_MEMORY_FULL |
A operação sms falhou porque o repositório de mensagens SMS está cheio. |
WWAN_STATUS_SMS_UNKNOWN_ERROR |
A operação sms falhou devido a um erro desconhecido (um erro genérico). |
WWAN_STATUS_SMS_FILTER_NOT_SUPPORTED |
Falha na operação de SMS porque não há suporte para o tipo de filtro solicitado. |
WWAN_STATUS_SMS_MORE_DATA |
Essa transação ainda não foi concluída. Alguns dados foram retornados e há mais dados a serem retornados. |
WWAN_STATUS_SMS_LANG_NOT_SUPPORTED |
A operação sms falhou porque não há suporte para a linguagem SMS. Isso se aplica somente a dispositivos baseados em CDMA. |
WWAN_STATUS_SMS_ENCODING_NOT_SUPPORTED |
Falha na operação de SMS porque não há suporte para a codificação de SMS. Isso se aplica somente a dispositivos baseados em CDMA. |
WWAN_STATUS_SMS_FORMAT_NOT_SUPPORTED |
Falha na operação de SMS porque não há suporte para o formato SMS. |
Nota Esses códigos de status específicos do WWAN são usados apenas para transações assíncronas no membro uStatus das estruturas de NDIS_WWAN_XXX.
Os drivers de miniport usam notificações de evento para informar o Serviço MB sobre uma alteração de estado de objeto em seu dispositivo MB sem primeiro ter recebido uma solicitação OID. O Serviço MB usa notificações de evento para atualizar apenas sua máquina de estado.
Lembre-se de que, embora o NDIS serialize todas as solicitações enviadas para drivers de miniporta, os drivers de miniporto podem não retornar as respostas na mesma ordem. Isso ocorre porque as solicitações enfileiradas no driver de miniporto podem ser processadas em paralelo. Portanto, o Serviço MB garante que, se duas solicitações dependerem umas das outras, ela não enviará a segunda solicitação até que o driver de miniporta conclua a primeira solicitação.
Notificação de alteração de estado
Em geral, os drivers de miniporto sempre devem notificar o Serviço MB sobre o estado atualizado de seu dispositivo MB por meio de notificações transacionais ou por meio de notificações de eventos não solicitadas. Os cenários a seguir são algumas exceções em que os drivers de miniporta não devem responder com informações de estado atualizadas. O Serviço MB pode determinar o estado atualizado do status de conclusão de outras operações:
Os drivers de miniporta não precisam enviar uma indicação de evento NDIS_STATUS_WWAN_PIN_LIST quando ocorrem alterações no estado do PIN porque o Serviço MB solicitou habilitar ou desabilitar o PIN.
Os drivers de miniporto não precisam retornar a lista atualizada dos contextos provisionados em respostas transacionais para OID_WWAN_PROVISIONED_CONTEXT definir operações.
Os drivers de miniporto não precisam responder com a lista atualizada dos provedores preferenciais em respostas transacionais para OID_WWAN_PREFERRED_PROVIDERS definir operações. O Serviço MB pode determinar essas informações com base na lista inicial e na status de êxito da operação de conjunto.
Os drivers de miniporto não precisam responder com o valor de WWAN_SMS_CONFIGURATION atual para OID_WWAN_SMS_CONFIGURATION operações definidas .