1=== Introduction === 2 3The netshell library is responsible for managing network connections. The user interface is accessed 4by opening the control panel and selecting the "Network Connections" folder. 5The netshell library provides COM interfaces to enumerate available network adapters, network protocols, network clients and network transports 6and receive detailed information about them. However, it cannot configure these components. For configuration, look in the netcfgx documentation 7(Hint: INetCfg) 8 9=== Interface === 10 11The user interface is exposed by implementing the IShellFolder interface as required by explorer 12namespace extension. The code is currently placed in shfldr_netconnect.c 13 14The enumeration of the available network connections is performed by the IShellFolder::EnumObjects 15(ISF_NetConnect_fnEnumObjects). It uses the INetConnectionManager interface implemented by netshell 16in connectmanager.c to enumerate all available network connections. 17 18The context menu of network connection items is populated by the IContextMenu::QueryContextMenu 19(ISF_NetConnect_IContextMenu3_QueryContextMenu) which is obtained by IShellFolder::GetUIObjectOf. The actions are performed by the 20IContextMenu::InvokeCommand function (ISF_NetConnect_IContextMenu3_InvokeCommand). At the moment 21the actions "Status" / "Properties" are implemented. 22 23=== Status Dialog & Notification Area === 24 25The status dialog is implemented by IOleCommandTarget interface(CLSID_ConnectionTray). This interface manages all status dialogs 26for all available dialogs. The interface is implemented as a singleton to avoid multiple notification icons 27appearing in the Notification area of the explorer. Every time the IShellFolder object is created (ISF_NetConnect_Constructor), 28it creates a reference to IOleCommandTarget interface and calls its IOleCommandTarget::Exec function with CGID_ShellServiceObject. 29This causes IOleCommandTarget interface to enumerate all available network connections, check if they should be shown (NCCF_SHOW_ICON flag set 30in the NETCON_PROPERTIES dwCharacter), and add them to notification area with Shell_NotifyIcon. For that purpose a hidden window is created (dialog 31procedure is LANStatusDlg) which receives WM_SHOWSTATUSDLG msg when it shall show display the status dialog. 32 33When a user wants to display the status dialog by clicking on the context menu of network connection item, the IShellFolder sends the NetCfgInstanceId of 34the selected network connection to IOleCommandTarget::Exec function. The function then looks up the specified notification item and then sends 35the WM_SHOWSTATUSDLG msg to specific window. 36 37=== Network Connections Property Dialog === 38 39The network connections property dialog is implemented by the INetConnectionPropertyUi2 interface. The class id is obtained by calling 40INetConnection::GetUiObjectClassId of the current selected network connection. After obtaining the interface by calling CoCreateInstance, the 41selected network connection is stored as reference by calling INetConnectionPropertyUi::SetConnection. The next step is to call 42INetConnectionPropertyUi::AddPages to add custom property pages to the property sheet set. If the function succeeds, the caller can then invoke 43PropertySheetW function to display the properties. 44 Note: If the context doesn't match, i.e. the INetConnectionPropertyUi2 cannot work together 45 with current INetConnection, then it should fail INetConnectionPropertyUi::AddPages 46 Note: The function ShowNetConnectionProperties in shlfdr_netconnect.c shows how to invoke the Network Connections Property Dialog 47 48The enumeration of network components (protocols, client, transport) is done by using the INetCfg api). Initialization is performed in InitializeLANPropertiesUIDlg 49function. When a user accepts changes, it calls INetCfg::Apply or when it aborts the changes INetCfg::Cancel. 50 51=== Known Issues === 52* Status changes of an adapter are not automatically updated because the information is cached 53* There seems to be an icon problem which makes icon blink in the status dialog 54 55=== Testing in windows === 56 57Unfortunately in windows the CLSID_ConnectionManager class is implemented in the netman 58service and netshell contains the rpc proxy stubs for it. This means that until we are able to 59reimplement these stubs alongside all its unimplemented interfaces and objects, we can't replace 60the system netshell with ours (INetConnectionManager and IEnumNetConnection are only the tip 61of the iceberg). 62However it is perfectly fine if one copies our netshell in a different folder and change the 63registry settings to make it handle CLSID_ConnectionFolder, CLSID_LanConnectionUi and CLSID_ConnectionTray. 64When doing so there are actually two options about how to test. One is leaving #define USE_CUSTOM_CONMGR 1 65as is and the other is setting is to 0. What this does is that when 0, the connections will be enumerated 66in the shell folder and the tray using the system's INetConnectionManager (which resides in the system's 67netman service and is accessible through the system's netshell.dll). This allows us to implement and 68test our three components against the correct implementation of INetConnectionManager. 69The other option is setting USE_CUSTOM_CONMGR to 1 which will make the shell folder and the tray 70enumerate connections with our connection manager effectively testing it in windows as well. 71