dll/shellext/netshell/README

   1 === Introduction ===
   2
   3 The netshell library is responsible for managing network connections. The user interface is accessed
   4 by opening the control panel and selecting the "Network Connections" folder.
   5 The netshell library provides COM interfaces to enumerate available network adapters, network protocols, network clients and network transports
   6 and 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
  11 The user interface is exposed by implementing the IShellFolder interface as required by explorer
  12 namespace extension. The code is currently placed in shfldr_netconnect.c
  13
  14 The enumeration of the available network connections is performed by the IShellFolder::EnumObjects
  15 (ISF_NetConnect_fnEnumObjects). It uses the INetConnectionManager interface implemented by netshell
  16 in connectmanager.c to enumerate all available network connections.
  17
  18 The 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
  20 IContextMenu::InvokeCommand function (ISF_NetConnect_IContextMenu3_InvokeCommand). At the moment
  21 the actions "Status" / "Properties" are implemented.
  22
  23 === Status Dialog & Notification Area ===
  24
  25 The status dialog is implemented by IOleCommandTarget interface(CLSID_ConnectionTray). This interface manages all status dialogs
  26 for all available dialogs. The interface is implemented as a singleton to avoid multiple notification icons
  27 appearing in the Notification area of the explorer. Every time the IShellFolder object is created (ISF_NetConnect_Constructor),
  28 it creates a reference to IOleCommandTarget interface and calls its IOleCommandTarget::Exec function with CGID_ShellServiceObject.
  29 This causes IOleCommandTarget interface to enumerate all available network connections, check if they should be shown (NCCF_SHOW_ICON flag set
  30 in the NETCON_PROPERTIES dwCharacter), and add them to notification area with Shell_NotifyIcon. For that purpose a hidden window is created (dialog
  31 procedure is LANStatusDlg) which receives WM_SHOWSTATUSDLG msg when it shall show display the status dialog.
  32
  33 When a user wants to display the status dialog by clicking on the context menu of network connection item, the IShellFolder sends the NetCfgInstanceId of
  34 the selected network connection to IOleCommandTarget::Exec function. The function then looks up the specified notification item and then sends
  35 the WM_SHOWSTATUSDLG msg to specific window.
  36
  37 === Network Connections Property Dialog ===
  38
  39 The network connections property dialog is implemented by the INetConnectionPropertyUi2 interface. The class id is obtained by calling
  40 INetConnection::GetUiObjectClassId of the current selected network connection. After obtaining the interface by calling CoCreateInstance, the
  41 selected network connection is stored as reference by calling INetConnectionPropertyUi::SetConnection. The next step is to call
  42 INetConnectionPropertyUi::AddPages to add custom property pages to the property sheet set. If the function succeeds, the caller can then invoke
  43 PropertySheetW 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
  48 The enumeration of network components (protocols, client, transport) is done by using the INetCfg api). Initialization is performed in InitializeLANPropertiesUIDlg
  49 function. When a user accepts changes, it calls INetCfg::Apply or when it aborts the changes INetCfg::Cancel.
  50
  51 === Known Issues ===
  52 * The notification icons are only added once IShellFolder of netshell is created for the first time
  53 * Status changes of an adapter are not automatically updated because the information is cached
  54 * There seems to be an icon problem which makes icon blink in the status dialog