Customize the Wireless Configuration UI (Windows Embedded CE 6.0)

Article
01/05/2012

1/5/2010

This topic provides information and guidance about how to customize the wireless configuration user interface (UI) for a Windows Embedded CE powered thin client.

Wireless Configuration UI Overview

A wireless configuration UI enables a user to interact with the wireless auto configuration sub-system that manages the 802.11 wireless connections.

With a wireless configuration UI, you can display information about currently available wireless networks, modify the preferred network list, and enable the user to change settings such as Service Set Identification (SSID), Wired Equivalent Policy (WEP) encryption key, 802.1X requirements, and the associated Extensible Authentication Protocol (EAP) settings for each network in the preferred list. The Service Set Identification (SSID) is an ID of a wireless local area network (LAN), in hexadecimal format.

You should integrate the wireless configuration UI with Ethman. Ethman implements a notification area icon that supplies network information such as IP address and wireless network availability. Ethman also implements a basic configuration dialog for 802.11 adapters where no previous configuration is available.

Wireless Auto Configuration API Overview

To interact with the auto configuration subsystem, also known as a Wireless Zero Configuration (WZC), the wireless configuration UI must use the Wireless Auto Configuration API.

The Wireless Auto Configuration API can be used to retrieve and set 802.11 parameters, such as signal strength, visible SSID list, and so on. This API uses the NDISUIO interface to register for notifications when a wireless adapter is inserted or removed. This API is defined in wzcsapi.h, located in %_WINCEROOT%\PUBLIC\COMMON\OAK\INC.

Wireless Auto Configuration API provides a data structure that contains everything that a remote procedure call (RPC) client has to know about an interface to a network. This structure is INTF_ENTRY, and its extended version is INTF_ENTRY_EX. When you query for this structure, you must specify the wszGuid value.

Wireless Auto Configuration API provides the function WZCQueryInterface and its extended version, WZCQueryInterfaceEx. This queries the driver for information about the specified wireless network adapter. When you call this function, pass in an INTF_ENTRY structure with only the wzcGuid field set. To provide additional information on what to query, you can specify certain flags in dwInFlags. For example, the INFT_ALL flag can be specified to request all information.

To configure wireless settings on the driver that are for the specified wireless network adapter, you can use the function WZCSetInterface or its extended version, WZCSetInterfaceEx. Specific flags are used to specify which settings in the INTF_ENTRY structure must be set for the wireless network adapter. They are specified in dwInFlags. For example, the INTF_PREFLIST flag specifies the list of preferred networks.

The function WZCRefreshInterface updates specific fields of INTF_ENTRY in the automatic configuration interface. For example, if you specify the flag INTF_LIST_SCAN, this function rescans for new networks and updates the INTF_ENTRY structure pointed to by pInf. The extended version of this function is WZCRefreshInterfaceEx.

The function WZCEnumEapExtensions enumerates through all the EAP authentication extensions that are currently installed on the thin client to protect the security of wireless LANs. On return, pEapExtensions contains an array of EAP extension information items.

The function WZCDeleteIntfObj deletes memory associated from a corresponding call to WZCQueryInterface. The extended version of this function is WZCDeleteIntfObjEx.

How to Include the Wireless Automatic Configuration API

Wireless Zero Configuration API is defined in the header file wzcapi.h. However, there is currently no import library exposing these APIs. Therefore, the application must load the API manually by using LoadLibrary and GetProcAddress, as demonstrated in the following example function.

BOOL InitZeroConfig(void)
{
     HINSTANCE hWZCLib = NULL;

     if (g_fWZCInit) {
          return TRUE; // Already initialized
     }

    // See if zero config API present in system
    if ((hWZCLib = LoadLibrary(L"wzcsapi.dll")) == NULL) {
        DEBUGMSG(ZONE_WARN,(TEXT("!WZCUI: WZCAPI.DLL not present in  
        system\r\n")));
        return FALSE;
    }
    pfnWZCQueryInterfaceEx = (PFN_WZCQueryInterfaceEx)GetProcAddress(hWZCLib,L"WZCQueryInterfaceEx");
    pfnWZCSetInterfaceEx = (PFN_WZCSetInterfaceEx)GetProcAddress(hWZCLib,L"WZCSetInterfaceEx");
    pfnWZCRefreshInterfaceEx  = (PFN_WZCRefreshInterfaceEx)GetProcAddress(hWZCLib,L"WZCRefreshInterfaceEx");
    pfnWZCEnumEapExtensions = (PFN_WZCEnumEapExtensions)GetProcAddress(hWZCLib,L"WZCEnumEapExtensions");
    pfnWZCDeleteIntfObjEx     = (PFN_WZCDeleteIntfObjEx)GetProcAddress(hWZCLib,L"WZCDeleteIntfObjEx");
    pfnWZCQueryContext  = (PFN_WZCQueryContext)GetProcAddress(hWZCLib,L"WZCQueryContext");
    pfnWZCSetContext  = (PFN_WZCSetContext)GetProcAddress(hWZCLib,L"WZCSetContext");
    pfnWZCPassword2Key      = (PFN_WZCPassword2Key)GetProcAddress(hWZCLib,L"WZCPassword2Key");

    if ((pfnWZCQueryInterfaceEx == NULL)   ||
        (pfnWZCSetInterfaceEx == NULL)     ||
        (pfnWZCRefreshInterfaceEx == NULL) ||
        (pfnWZCEnumEapExtensions == NULL)||
        (pfnWZCDeleteIntfObjEx == NULL)    ||
        (pfnWZCSetContext == NULL)       ||
        (pfnWZCQueryContext == NULL)) {
        DEBUGMSG(ZONE_ERROR,(TEXT("!WZCUI: WZC APis not present in system\r\n")));
        FreeLibrary(hWZCLib);
        return FALSE;
    }

    g_fWZCInit = TRUE;
    return TRUE;
}

Basic Tasks for a Wireless Configuration UI

After you obtain the appropriate function pointers to wcsapi.dll, you can query the automatic configuration subsystem for the data structures that contain items such as the list of configured networks and their configuration data.

First, you have to determine whether you have a supported network adapter, and then retrieve the adapter name in the form of a Unicode string. NDISUIO.DLL provides notification of binding and unbinding a network adapter. Or, you can retrieve the adapter name by using IOCTL_NDIS_GET_ADAPTER_NAMES. After you have retrieved the adapter name, you can create and initialize an INTF_ENTRY structure, passing in the adapter name as the value of the wszGuid field. The following example function shows you how to query for the network adapter.

INTF_ENTRY ie = NULL;
DWORD dwOIDFlags = 0;
ie.wszGuid = pszAdapter;
pfnWZCQueryInterface(NULL, INTF_ALL, &ie, &dwOIDFlags);

If the WZCQueryInterface call succeeds, it will return information in both the INTF_ENTRY structure and in the flags. First, check whether the driver supports the necessary object identifiers (OIDs) by checking the dwCtlFlags field in the INTF_ENTRY structure. The following example function shows you how to check the dwCtlFlags field.

if ((ie.dwCtlFlags & INTFCTL_OIDSSUP) == 0)

After you have determined that the interface is supported, you can retrieve information, such as the SSID, by accessing values in INTF_ENTRY. For example, INTF_ENTRY.rdBSSIDList.pData is a WZC_802_11_CONFIG_LIST structure that stores a list of preferred wireless zero configurations. Each of these is a WZC_WLAN_CONFIG structure. WZC_WLAN_CONFIG contains a variety of information about 802.11, some of which is stored in data structures that are defined in the header file Ntddndis.h.

The automatic configuration subsystem also supports a message queue to which it sends messages that indicate the current state of the network driver. These driver states are defined in wzcmsq.h located in %_WINCEROOT%\PUBLIC\COMMON\DDK\INC.

The message queue can be queried by using the ReadMsgQueue function. For sample code that uses the message queue, see ethman.c in %_WINCEROOT%\PUBLIC\OAK\DRIVERS\NETSAMP\ETHMAN.

Wireless Configuration UI Resource Strings

As a final step, you can customize resource strings in Ethman related to wireless configuration UI. To do this, open netui.rc and edit the resource strings as you want. The following list shows some resource strings related to wireless networking UI:

IDS_QCWZC_TITLE
IDS_NETWORK_WLAN_TITLE
IDC_WZC_DLG_PROPS_W
IDC_WZC_DLG_PROPS_N
IDD_LAN_WZC_ADVANCED

Exploring the Sample Code

The wireless configuration sample code is located in wzcui.c in %_WINCEROOT%\PUBLIC\COMMON\OAK\DRIVERS\NETUI. The wireless configuration sample code uses wireless network data to populate a dialog, and uses the UI to re-populate this data. To customize the wireless configuration UI, you can either modify this code or replace it with a new module.

The sample code for the network connection status UI is located in wzcquickcfgui.c in %_WINCEROOT%\PUBLIC\COMMON\OAK\DRIVERS\NETUI. As an alternative to wzcui.c, wzcquickcfgui.c updates the UI more frequently than the dialog in wzcui.c. The network connection status UI, Ethman, might be more practical for portable devices where wireless networks change more frequently. Periodically, Ethman calls WZCRefreshInterface and updates the UI to let users see visibly updated network activity. For more information, see Automatic Configuration Samples.

Customize the Wireless Configuration UI (Windows Embedded CE 6.0)

Wireless Configuration UI Overview

Wireless Auto Configuration API Overview

How to Include the Wireless Automatic Configuration API

Basic Tasks for a Wireless Configuration UI

Wireless Configuration UI Resource Strings

Exploring the Sample Code

See Also

Concepts

Other Resources

Additional resources