Provozní sémantika MB

Asynchronní transakce

Model ovladače MB předpokládá neblokující provozní sémantiku mezi ovladači služby MB a miniportu pomocí asynchronního mechanismu oznámení poskytovaného v NDIS 6.x. Tento mechanismus umožňuje službě MB pokračovat v odesílání požadavků OID na ovladač miniportu ke zpracování bez čekání na dokončení aktuální operace.

Asynchronní transakce je třícestný handshake, která začíná počátečním požadavkem, následován odpovědí na stav požadavku a poté dokončena konečnou indikací transakce. Odpověď na stav žádosti je prozatímní v tom, že uznává pouze, že ovladač miniportu obdržel žádost. Následná asynchronní indikace je transakční v tom, že signalizuje dokončení transakce. Ovladač miniportu vrátí stavový kód a výsledná data v transakční indikaci.

Asynchronní Nastavení a Dotaz Požadavky

Mnoho požadavků OID pro sady a dotazy , které používá služba MB, se zpracovává asynchronně. Další informace o nastavení a dotazu požadavků OID naleznete v tématu NDIS_OID_REQUEST. Tabulka identifikátorů OID specifických pro WWAN v tématu MB datového modelu identifikuje, které identifikátory OID se zpracovávají asynchronně.

Následující diagram znázorňuje sekvenci interakce pro transakci asynchronního dotazu mezi službou MB a ovladačem miniportu. Popisky tučně představují identifikátory identifikátorů OID nebo řízení transakčního toku a popisky v běžném textu představují důležité příznaky v rámci struktury OID.

Třícestný handshake je stejný pro dotaz a nastavení požadavky.

Kromě OID_WWAN_DRIVER_CAPSvšechny ostatní požadavky OID specifické pro MB se řídí asynchronním transakčním mechanismem pro výměnu informací mezi ovladači miniportu a službou MB s následujícími dalšími poznámkami:

• Ovladače miniportu by měly okamžitě odmítnout požadavek OID při jakémkoli chybovém stavu, například u neplatného požadavku OID.

• Řadiče miniportu musí vrátit všechny chybové podmínky specifické pro WWAN se správným kódem chyby (například WWAN_STATUS_XXX) popsáným ve uStatus členu struktury pro oznámení události. Ovladače miniportů by měly také podle potřeby vyplnit členy, které následují člena uStatus. Například ovladače miniportu by měly vyplnit člena ContextState.uNwError struktury NDIS_WWAN_CONTEXT_STATE, pokud je k dispozici. V případě selhání při zpracování OID souvisejících s PIN kódy však miniport ovladače nemusí mít k dispozici aktuální informace o stavu PIN, které se mají specifikovat v členu PinInfo.PinState struktury NDIS_WWAN_PIN_INFO.

• Ovladače miniportu by měly vrátit NDIS_STATUS_INDICATION_REQUIRED jako prozatímní odpověď pro všechny asynchronní požadavky OID.

• Ovladače miniportu by měly být schopné rozlišovat změny stavu zařízení způsobené požadavkem OID od jiných příčin. Ovladače miniportu by měly odesílat transakční oznámení o změnách stavu vyplývajících z požadavků OID a měly by odesílat nevyžádaná oznámení o událostech pro změny stavu z jiných příčin.

• Ovladače miniportu zodpovídají za správu paměti v režimu jádra, přestože služba MB zpočátku přiděluje paměť pro požadavky. Jakmile služba MB obdrží odpověď od ovladače miniportu, může služba uvolnit paměť v uživatelském režimu, kterou přidělila pro požadavek OID.

Následující schéma představuje sekvenci interakce pro asynchronní transakci typu nastavení mezi službou MB a ovladačem miniportu. Popisky tučně představují identifikátory identifikátorů OID nebo řízení transakčního toku a popisky v běžném textu představují důležité příznaky v rámci struktury OID.

Asynchronní odpověď

Specifikace NDIS 6.0 (vydaná v systému Windows Vista) zavedla nový stavový kód NDIS_STATUS_INDICATION_REQUIRED pro ovladače miniportu, které vyjadřují asynchronní povahu transakce službě MB v prozatímní odpovědi ovladače miniportu na požadavek OID.

Jak je uvedeno v MB – přehled rozhraní, služba MB nemá přímý přístup k paměti režimu jádra, která je přidělena ovladačem miniportu MB. Výsledek spuštění uložený v paměti v režimu jádra se předpokládá, že byl zkopírován a zpřístupněn službě MB prostřednictvím některého zprostředkujícího prvku, jako je WMI nebo ovladač filtru NDIS. Ovladače miniportu proto mohou uvolnit přidělenou paměť v režimu jádra poté, co se volání funkce NdisMIndicateStatusEx vrátí v rámci transakční indikace.

Postupy handshake, které ovladače miniportu a služba MB musí dodržovat, jsou popsány v následujícím postupu.

Procedura ovladače miniportu MB

Po přijetí požadavku OID by ovladače miniportu měly provést následující kroky:

1. Přidělení paměti v režimu jádra ke zkopírování obsahu datové struktury NDIS_OID_REQUEST přidružené k požadavku OID.

2. Mezi parametry požadavku se ujistěte, že jsou také zkopírovány členy struktury požadavku OID, konkrétně RequestId a RequestHandle. Členy budou později použity v transakčním označení .

3. Vrátí prozatímní stavovou odpověď typu NDIS_STATUS_INDICATION_REQUIRED, aby informovala službu MB, že ovladač miniportu dokončí požadavek asynchronně.

4. Po dokončení operace uložte výsledek do místní paměti nebo do paměti přidělené ovladačem podle potřeby.

5. Vyvolejte funkci NdisMIndicateStatusEx, abyste upozornili službu MB, že byla dokončena nevyřízená operace. Ovladače miniportu by měly vyplnit členy struktury NDIS_STATUS_INDICATION následujícím způsobem:

   1. Nastavte StatusCode člen na typ oznámení o stavu. Například NDIS_STATUS_WWAN_XXX.
   2. Nastavte člena DestinationHandle na člena RequestHandle, který byl přijat v datové struktuře NDIS_OID_REQUEST, když miniportový ovladač obdržel odpovídající žádost OID.
   3. Nastavte položku RequestId tak, aby odpovídala položce RequestId ve struktuře stavu NDIS_OID_REQUEST, když ovladač miniportu obdrží odpovídající požadavek OID.
   4. Nastavte členy StatusBuffer a StatusBufferSize tak, aby směřovaly k paměti přidělené miniport ovladačem a k velikosti vyrovnávací paměti. Tento paměťový buffer obsahuje výsledek dokončené operace.
   5. Pokud se operace úspěšně dokončí, nastavte uStatus člen na WWAN_STATUS_SUCCESS. V opačném případě nastavte položku uStatus na odpovídající hodnotu WWAN_STATUS_XXX pro označení typu selhání.

6. Když se volání funkce vrátí, ovladač miniportu by měl uvolnit paměť přidělenou pro požadavek OID.

Servisní postup MB

Služba MB zpracovává asynchronní transakce pomocí následujícího postupu:

1. Přidělit paměť vyrovnávací paměti pro požadavek podle datové struktury OID. Vyplňte členy datové struktury odpovídajícími hodnotami.

2. Zavolejte funkci NdisOidRequest s členem InformationBuffer odkazujícím na datovou strukturu pro požadavek OID a poté počkejte, až ovladač miniportu odpoví.

3. Po přijetí NDIS_STATUS_INDICATION_REQUIRED prozatímní odpovědi od ovladače miniportu služba MB uloží RequestId, uvolní přidělenou paměť a označí transakci jako otevřenou. V této fázi je služba MB připravena bezplatně zpracovávat další žádosti a oznámení spojená s identifikátory OID.

4. Po přijetí oznámení s NDIS_STATUS_WWAN_XXX jako hodnota StatusCode zkontrolujte, jestli RequestId odpovídá jakékoli transakci označené jako otevřené. Pokud existuje shoda, služba transakci zavře. Pokud se nenajde žádná shoda, považuje se oznámení za oznámení o nevyžádané události.

5. Zpracujte data vrácená v StatusBuffer členu a podle potřeby proveďte změny stavu služby MB.

Náznaky

Existují dva typy indikace specifické pro WWAN, které mohou generovat ovladače miniportu:

• Oznámení událostí, která jsou výsledkem změny stavu objektu v zařízení MB.

• Transakční oznámení, která signalizují dokončení asynchronní operace.

V obou případech by ovladače miniportu měly volat funkci NdisMIndicateStatusEx.

Oznámení o události

Oznámení o události není požadováno v tom smyslu, že ovladač miniportu aktivně odesílá indikaci službě MB jako událost změny stavu. Změna stavu je způsobena akcí z jiné entity, než je služba MB. Služba MB předpokládá, že ovladače miniportu dokážou zjistit příčinu změny.

U oznámení události specifické pro WWAN musí ovladače miniportu nastavit RequestId člen struktury NDIS_STATUS_INDICATION na nulu. StatusCode člen určuje, který objekt v zařízení MB se změnil. Ovladač miniportu může nastavit tento objekt na některou z následujících hodnot:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

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_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

Služba MB může také zpracovávat další oznámení událostí ze služby NDIS. Tato oznámení událostí mimo MB nemusí nutně podléhat požadavku, aby jejich identifikátor žádosti byl nastaven na nulu.

Transakční oznámení

Ovladače miniportu používají transakční oznámení k informování služby MB o dokončení asynchronní transakce a služba MB používá transakční oznámení k zavření otevřených transakcí a aktualizaci stavového počítače.

Služba MB očekává transakční oznámení, aby bylo možné zavřít otevřené transakce. Jedná se o poslední výměnu v třístranném handshake mezi službou MB a ovladačem miniportu v rámci asynchronní transakce. Hodnota člena RequestId ve struktuře NDIS_STATUS_INDICATION v jakémkoli transakčním oznámení musí být nenulová a zkopíruje se z odpovídajícího požadavku ve stejné transakci.

Pro správné fungování asynchronního mechanismu je nutné nastavit RequestId člen struktury NDIS_STATUS_INDICATION. Služba MB zajišťuje, že hodnota RequestId je jedinečná a nenulová mezi všemi nevyřízené požadavky. Ovladače miniportu musí vrátit stejnou hodnotu RequestId v odpovídající indikaci, aby služba MB korelovala indikaci s otevřenou transakcí.

Struktura indikací stavu

Asynchronní odpověď pro daný požadavek OID i struktura oznámení nevyžádané události sdílejí následující členy struktury, na které odkazuje StatusBuffer člen StatusIndication parametru 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;

Hodnota nuly v RequestId člen struktury NDIS_STATUS_INDICATION znamená, že se jedná o nevyžádané oznámení o události a může dojít kdykoli.

Pokud člen uStatus ve vrácené indikaci jakékoli sady nebo dotazující OID žádosti není roven WWAN_STATUS_SUCCESS, nemusí být členy přidružené struktury NDIS_WWAN_XXX platné.

V případě nevyžádaných oznámení událostí na základě síťových událostí musí ovladače miniportu vyplnit člen uNwError podle potřeby, pokud je to relevantní.

Následující tabulka uvádí hodnoty selhání příčinných kódů pro registraci, připojení paketů a odpojení paketů, které jsou definovány ve specifikaci 3GPP TS 24.008 pro sítě založené na GSM:

Kód příčiny 3GPP 24.008	Interpretace kódu příčiny
2. Mezinárodní identita mobilního předplatitele (IMSI) neznámá v HLR	Sim kartu nebo zařízení není aktivované nebo předplatné vypršelo, což způsobilo deaktivaci sítě.
4 - IMSI neznámý v VLRu	Funkce roamingu není aktivovaná.
6 - Nelegální ME	MS blokované sítí kvůli odcizené zprávě.
7 . Služby GSM nejsou povoleny	Uživatel nemá předplatné GSM. Uživatel má jenom předplatné hlasového připojení.
8 - GPRS a ne-GPRS služby nejsou povoleny	Služby GPRS a non-GPRS nejsou umožněny.
11 – PLMN není povoleno	Služba je blokována sítí kvůli vypršení platnosti předplatného nebo jiné příčině.
12 . Oblast umístění není povolena	Předplatné uživatele nepovoluje přístup v oblasti aktuálního umístění.
13. Roaming není v této oblasti umístění povolený	Předplatné povoluje roaming, ale roaming není v oblasti aktuálního umístění povolený.
14 - SLUŽBY GSM nejsou v tomto PLMN povoleny	Vybraný poskytovatel sítě neposkytuje službu GPRS pro mobilní stanici.
15 - Žádné vhodné buňky v oblasti umístění	Žádné předplatné pro službu.
17. Selhání sítě	Registrace se nezdařila.
22 - Zahlcení	Registrace selhala kvůli zahlcení sítě.

Například pokud síť inicializuje událost deaktivace kontextu z důvodu, že roaming není povolen v oblasti lokace, ovladače miniportu by měly nastavit položku uNwError na hodnotu 13 podle příčinných kódů 3GPP TS 24.008 pro sítě na bázi GSM.

Podobná logika by se měla použít i v sítích založených na CDMA. Pro kódy chyb sítě založené na CDMA ale neexistuje žádný standard. Zařízení založená na CDMA by měla používat síťové -specific nebo kódy chyb specifických pro zařízení.

V případě asynchronní odpovědi ovladače miniportu na požadavky OID je člen RequestId struktury NDIS_STATUS_INDICATION nenulové číslo, které bylo předáno ovladači miniportu jako součást požadavku na nastavení nebo dotaz. Ovladač miniportu musí podle potřeby vyplnit uStatus člen. Například WWAN_STATUS_SUCCESS nebo některou z odpovídajících chybových hodnot uvedených v následující části. Kromě toho musí ovladač miniportu vyplnit položku uNwError, pokud je to vhodné a dostupné.

Stav oznámení události

Následující tabulka uvádí kódy WWAN_STATUS, které ovladače miniportu MB mohou zadat jako údaj ve struktuře oznámení událostí NDIS_WWAN_XXX pomocí členu uStatus.

Hodnota	Význam
WWAN_STATUS_SUCCESS	Operace byla úspěšná.
WWAN_STAV_CHYBA	Operace selhala (obecná chyba).
WWAN_STATUS_BUSY	Operace selhala, protože zařízení je zaneprázdněné.
WWAN_STATUS_SIM_NEPOCHEN	Operace selhala, protože sim karta nebyla zcela vložena do zařízení.
Stav WWAN: chybná SIM.	Operace selhala, protože sim karta je chybná a nelze ji použít dál.
Stav_WWAN_PIN_požadováno	Operace se nezdařila, protože je nutné zadat PIN kód, aby bylo možné pokračovat.
Stav WWAN: PIN deaktivován	Operace selhala, protože pin kód je zakázaný.
WWAN_STATUS_NEREGISTROVÁN	Operace selhala, protože zařízení není zaregistrované v žádné síti.
Stav WWAN: Nenalezeni poskytovatelé	Operace selhala, protože se nenašli žádní poskytovatelé sítě.
WWAN_STATUS_NEPODPOROVANÉ_ZAŘÍZENÍ	Operace se nezdařila, protože zařízení operaci nepodporuje.
WWAN_STATUS_POSKYTOVATEL_NENÍ_VIDITELNÝ	Operace se nezdařila, protože poskytovatel služeb není aktuálně viditelný.
WWAN_STATUS_TŘÍDA_DAT_NENÍ_DOSTUPNÁ	Operace selhala, protože požadovaná třída dat nebyla k dispozici.
Stav připojení paketové služby byl odpojen (WWAN_STATUS_PACKET_SVC_DETACHED)	Operace selhala, protože je odpojena služba paketů.
WWAN_STATUS_MAX_ACTIVATED_CONTEXTS	Operace selhala, protože byl dosažen maximální počet aktivovaných kontextů.
WWAN_STATUS_NEINITIALIZOVÁNO	Operace se nezdařila, protože zařízení probíhá inicializace. Opakujte operaci poté, co se stav zařízení změní na WwanReadyStateInitialized.
Stav_sítě_WWAN_hlasový_hovor_probíhá	Operace selhala, protože probíhá hlasový hovor.
WWAN_STATUS_CONTEXT_NOT_ACTIVATED (kontekst mobilní sítě není aktivován)	Operace selhala, protože kontext není aktivovaný.
WWAN_STATUS_SLUŽBA_NEAKTIVOVÁNA	Operace selhala, protože služba není aktivována.
WWAN_STATUS_INVALID_ACCESS_STRING	Operace se nezdařila, protože přístupový řetězec je neplatný.
WWAN_STATUS_NEPLATNÉ_UŽIVATELSKÉ_JMÉNO_HESLO	Operace se nezdařila, protože zadané uživatelské jméno nebo heslo je neplatné.
WWAN_STATUS_RADIO_POWER_OFF	Operace selhala, protože rádio je aktuálně vypnuté.
WWAN_STATUS_INVALID_PARAMETERS (Neplatné parametry)	Operace selhala kvůli neplatným parametrům.
WWAN_STAV_CHYBA_ČTENÍ	Operace selhala kvůli chybě čtení.
Porucha zápisu WWAN_STATUS	Operace selhala kvůli chybě při zápisu.

V následující tabulce jsou uvedeny hodnoty stavu specifické pro SMS.

Hodnota	Význam
Stav_USB_Mobilní_sítě_SMS_operace_nepovolena	Operace SMS selhala, protože operace není povolená.
Stav sítě WWAN: chyba paměti SMS	Operace SMS selhala kvůli selhání paměti.
WWAN_STATUS_SMS_INVALID_MEMORY_INDEX	Operace SMS selhala kvůli neplatnému indexu paměti – WwanSmsFlagIndex pro OID_WWAN_SMS_READ.
WWAN_STATUS_SMS_NEZNÁMÉ_SMS_CENTER_ADRESA	Operace SMS selhala, protože číslo centra služeb je neplatné nebo neznámé.
Stav_sítě_WWAN_SMS_vypršení_času_sítě	Operace SMS selhala kvůli vypršení časového limitu sítě.
Stav WWAN: Paměť SMS je plná	Operace SMS selhala, protože úložiště zpráv SMS je plné.
Stav WWAN: Neznámá chyba SMS	Operace SMS selhala kvůli neznámé chybě (obecná chyba).
Stav WWAN: Filtrování SMS není podporováno	Operace SMS selhala, protože požadovaný typ filtru není podporován.
WWAN_STATUS_SMS_MORE_DATA	Tato transakce ještě není dokončena. Některá data se vrátila a je potřeba vrátit další data.
Stav WWAN: Jazyk SMS není podporován	Operace SMS selhala, protože jazyk SMS není podporován. To platí jenom pro zařízení založená na CDMA.
Stav WWAN: Kódování SMS není podporováno.	Operace SMS selhala, protože kódování SMS není podporováno. To platí jenom pro zařízení založená na CDMA.
WWAN_STAV_FORMAT_SM_SE_NEPOCHOPEN	Operace SMS selhala, protože formát SMS není podporován.

Poznámka: Tyto stavové kódy specifické pro WWAN se používají pouze pro asynchronní transakce v uStatus člen struktury NDIS_WWAN_XXX.

Ovladače miniportu používají oznámení událostí k informování služby MB o změně stavu objektu v jejich zařízení MB, aniž by nejprve obdržely požadavek OID. Služba MB používá oznámení událostí k aktualizaci pouze stavového počítače.

Mějte na paměti, že zatímco NDIS serializuje všechny požadavky odeslané na ovladače miniportu, ovladače miniport nemusí vrátit odpovědi ve stejném pořadí. Důvodem je to, že žádosti zařazené do fronty v ovladači miniportu mohou být zpracovány paralelně. Služba MB tedy zajišťuje, že pokud jsou na sobě závislé dva požadavky, nebude odesílat druhý požadavek, dokud ovladač miniportu nedokončí první požadavek.

Oznámení o změně stavu

Obecně platí, že ovladače miniportu by měly vždy informovat službu MB o aktualizovaném stavu jejich zařízení MB buď prostřednictvím transakčních oznámení, nebo prostřednictvím oznámení o nevyžádaných událostech. Následující scénáře jsou některé výjimky, kdy ovladače miniportu nemají reagovat aktualizovanými informacemi o stavu. Služba MB může zjistit aktualizovaný stav ze stavu dokončení jiných operací:

1. Ovladače miniportu nemusí posílat indikaci události NDIS_STATUS_WWAN_PIN_LIST, kdy dojde ke změnám stavu PIN kódu, protože služba MB si vyžádala povolení nebo zakázání kódu PIN.

2. Ovladače miniportu nemusí vracet aktualizovaný seznam zadaných kontextů v transakčních odpovědích na OID_WWAN_PROVISIONED_CONTEXT pro operace nastavení.

3. Ovladače miniportu nemusí odpovídat aktualizovaným seznamem upřednostňovaných poskytovatelů v transakčních odpovědích na OID_WWAN_PREFERRED_PROVIDERS nastavit operace. Služba MB může tyto informace určit na základě počátečního seznamu a stavu úspěchu nastavené operace.

4. Ovladače miniportu nemusí odpovídat s aktuální hodnotou WWAN_SMS_CONFIGURATION pro operace nastavení OID_WWAN_SMS_CONFIGURATION .