Using the Windows Zero Config API (Windows Embedded CE 6.0)

1/6/2010

These APIs are defined in the header file wzcsapi.h. However, there is currently no import library exposing these APIs so your application must load the API set manually using LoadLibrary and GetProcAddress, as follows:

HINSTANCE hWZClib = ::LoadLibrary(L"wzcsapi.dll");
pfnWZCQueryInterface = (PFN_WZCQueryInterface)GetProcAddress(hWZClib,L"WZCQueryInterface");
pfnWZCSetInterface = (PFN_WZCSetInterface)GetProcAddress(hWZClib,L"WZCSetInterface");
pfnWZCRefreshInterface = (PFN_WZCRefreshInterface)GetProcAddress(hWZClib,L"WZCRefreshInterface");

With the appropriate function pointers to wzcsapi.dll, the underlying subsystem can be queried for the data structures containing the list of networks that have been configured and the configuration data of each. You can also display current available wireless networks, add, edit, or delete the preferred network list, and allow the user to change settings such as SSID, WEP key, 802.1x requirements and the associated EAP settings for each network in the preferred list.

The first step is to determine whether you have a supported network adapter - NDISUIO.DLL provides adapter bind/unbind notification. Alternatively you can get the adapter name using the NDIS IOCTL call IOCTL_NDIS_GET_ADAPTER_NAMES. Once you have the adapter name you can use it to create and initialize an INTF_ENTRY structure:

ie.wszGuid = pszAdapter;

and then call the WZCQueryInterface method as follows:

pfnWZCQueryInterface(NULL, INTF_ALL, &ie, &dwOIDFlags);

where the dwOIDFlags are initialized to 0.

If the call succeeds it will return information in both the INTF_ENTRY structure and the flags. First check to see if the driver supports the necessary OIDs by checking the dwCtlFlags entry in the INTF_ENTRY, as follows:

If ((ie.dwCtlFlags & INTFCTL_OIDSSUPP) == 0)

Once you know it is a supported interface, you can determine things like the SSID by accessing the INTF_ENTRY. For example: IntfEntry.rdBSSIDList.pData is a PWZC_802_11_CONFIG_LIST structure, containing an array of WZC_WLAN_CONFIG structures. This structure contains most of the interesting 802.11 data, including:

NDIS_802_11_MAC_ADDRESS   MacAddress;   // BSSID
NDIS_802_11_SSID          Ssid;         // SSID
ULONG                     Privacy;      // WEP requirement
NDIS_802_11_RSSI          Rssi;         // signal strength in dBm
NDIS_802_11_NETWORK_TYPE  NetworkTypeInUse;
NDIS_802_11_CONFIGURATION Configuration;
NDIS_802_11_NETWORK_INFRASTRUCTURE  InfrastructureMode;
NDIS_802_11_RATES         SupportedRates; 
ULONG   KeyIndex;     // 0 is per-client key, 1-N are global keys
ULONG   KeyLength;    // length of key in bytes
UCHAR   KeyMaterial[WZCCTL_MAX_WEPK_MATERIAL]; 
NDIS_802_11_AUTHENTICATION_MODE     AuthenticationMode;

The NDIS_802_11_* items are defined in the NDIS header file.

Zero Config also supports a Message Queue where it deposits messages pertaining to the current state of the driver. The following states are defined in WZCMSQ.H:

WZC_STARTED
WZC_ASSOCIATING
WZC_FAILED_ASSOCIATION
WZC_SUCCESSFUL_ASSOCIATION
WZC_CLOSE_EAPOL_SESSION
WZC_AUTHENTICATING
WZC_AUTHENTICATED
WZC_CANCEL_AUTH
WZC_FAILED_AUTH_NO_RETRY
WZC_FAILED_AUTH_WILL_RETRY
WZC_PREFERED_LIST_EXHAUSTED
WZC_REAUTHENTICATING
WZC_VISIBLE_NETWORK // Visible network exists while not connected

The Message Queue can be queried using the ReadMsgQueue function. The WZCMSQ.H header file can be found in public\common\ddk\inc. Sample code for using the Zero Config Message Queue can be found in the ethman.dll source code.

See Also

Concepts

Automatic Configuration Subsystem

Other Resources

Automatic Configuration Functions
Automatic Configuration Samples