Configuration Panels
[User Interface]


Detailed Description

Configuration panels are the primary means from which the user is presented with an interface to change NetIDMgr and plugin configuration.


Data Structures

struct  tag_khui_config_node_reg
 Registration information for a configuration node. More...
struct  tag_khui_config_init_data
 Initialization data passed in to a subpanel. More...

Defines

#define KHUI_WM_CFG_NOTIFY   (WM_APP + 0x101)
 Configuration window notification message.
#define KHUI_CNFLAG_SORT_CHILDREN   0x0001
 Sort the child nodes by short description.
#define KHUI_CNFLAG_SUBPANEL   0x0002
 Is a subpanel.
#define KHUI_CNFLAG_PLURAL   0x0004
 Node represents a panel that is replicated for all child nodes.
#define KHUI_CNFLAG_SYSTEM   0x0010
 System node.
#define KHUI_CNFLAG_MODIFIED   0x0100
 Settings have been modified.
#define KHUI_CNFLAG_APPLIED   0x0200
 Settings have been applied.
#define KHUI_CNFLAGMASK_STATIC   0x00ff
#define KHUI_CNFLAGMASK_DYNAMIC   0x0f00
#define KHUI_MAXCCH_NAME   256
 Maximum length of the name in characters.
#define KHUI_MAXCB_NAME   (KHUI_MAXCCH_NAME * sizeof(wchar_t))
 Maximum length of the name in bytes.
#define KHUI_MAXCCH_LONG_DESC   1024
 Maximum length of the long description in characters.
#define KHUI_MAXCB_LONG_DESC   (KHUI_MAXCCH_LONG_DESC * sizeof(wchar_t))
 Maximum length of the long description in bytes.
#define KHUI_MAXCCH_SHORT_DESC   256
 Maximum length of the short description in chracters.
#define KHUI_MAXCB_SHORT_DESC   (KHUI_MAXCCH_SHORT_DESC * sizeof(wchar_t))
 Maximum length of the short description in bytes.
#define CFGDLG_WIDTH   255
 Width of a configuration dialog in dialog units.
#define CFGDLG_HEIGHT   182
 Height of a configuration dialog in dialog units.
#define CFGDLG_TAB_WIDTH   235
 Width of a configuration tab dialog in dialog units.
#define CFGDLG_TAB_HEIGHT   151
 Height of configuration tab dialog in dialog units.

Typedefs

typedef tag_khui_config_node_reg khui_config_node_reg
 Registration information for a configuration node.
typedef khm_handle khui_config_node
 A handle to a configuration node.
typedef tag_khui_config_init_data khui_config_init_data
 Initialization data passed in to a subpanel.

Enumerations

enum  khui_wm_cfg_notifications { WMCFG_SHOW_NODE = 1, WMCFG_UPDATE_STATE = 2, WMCFG_APPLY = 3, WMCFG_SYNC_NODE_LIST = 4 }
 Configuration notifications. More...

Functions

KHMEXP khm_int32 KHMAPI khui_cfg_register (khui_config_node parent, const khui_config_node_reg *reg)
 Register a configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_open (khui_config_node parent, const wchar_t *name, khui_config_node *result)
 Open a configuration node by name.
KHMEXP khm_int32 KHMAPI khui_cfg_remove (khui_config_node node)
 Remove a configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_hold (khui_config_node node)
 Hold a handle to a configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_release (khui_config_node node)
 Release a handle to a configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_parent (khui_config_node vnode, khui_config_node *result)
 Get the parent of a node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_first_child (khui_config_node parent, khui_config_node *result)
 Get a handle to the first child node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_first_subpanel (khui_config_node vparent, khui_config_node *result)
 Get a handle to the first subpanel.
KHMEXP khm_int32 KHMAPI khui_cfg_get_next (khui_config_node node, khui_config_node *result)
 Get a handle to the next sibling node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_next_release (khui_config_node *node)
 Get a handle to the next sibling node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_name (khui_config_node node, wchar_t *buf, khm_size *cb_buf)
 Get the name of a configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_reg (khui_config_node node, khui_config_node_reg *reg)
 Get registration information for a node.
KHMEXP HWND KHMAPI khui_cfg_get_hwnd_inst (khui_config_node node, khui_config_node noderef)
 Internal use.
KHMEXP LPARAM KHMAPI khui_cfg_get_param_inst (khui_config_node node, khui_config_node noderef)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_hwnd_inst (khui_config_node node, khui_config_node noderef, HWND hwnd)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_param_inst (khui_config_node node, khui_config_node noderef, LPARAM param)
 Internal use.
KHMEXP HWND KHMAPI khui_cfg_get_hwnd (khui_config_node node)
 Internal use.
KHMEXP LPARAM KHMAPI khui_cfg_get_param (khui_config_node node)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_hwnd (khui_config_node node, HWND hwnd)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_param (khui_config_node node, LPARAM param)
 Internal use.
KHMEXP void KHMAPI khui_cfg_clear_params (void)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_configui_handle (HWND hwnd)
 Internal use.
KHMEXP void KHMAPI khui_cfg_set_flags (khui_config_node vnode, khm_int32 flags, khm_int32 mask)
 Update the state for the specified node.
KHMEXP khm_int32 KHMAPI khui_cfg_get_flags (khui_config_node vnode)
 Retrieve the state flags for the configuration node.
KHMEXP khm_int32 KHMAPI khui_cfg_init_dialog_data (HWND hwnd_dlg, const khui_config_init_data *data, khm_size cb_extra, khui_config_init_data **new_data, void **extra)
 Utility function: Initialize dialog box window data.
KHMEXP khm_int32 KHMAPI khui_cfg_get_dialog_data (HWND hwnd_dlg, khui_config_init_data **data, void **extra)
 Utility function: Retrieves dialog data.
KHMEXP khm_int32 KHMAPI khui_cfg_free_dialog_data (HWND hwnd_dlg)
 Utility function: Free dialog data.
KHMEXP void KHMAPI khui_cfg_set_flags_inst (khui_config_init_data *d, khm_int32 flags, khm_int32 mask)
 Sets the instance flags for a subpanel.


Define Documentation

#define CFGDLG_HEIGHT   182

Height of a configuration dialog in dialog units.

See also:
CFGDLG_WIDTH

#define CFGDLG_TAB_HEIGHT   151

Height of configuration tab dialog in dialog units.

See also:
CFGDLG_TAB_WIDTH

#define CFGDLG_TAB_WIDTH   235

Width of a configuration tab dialog in dialog units.

CFGDLG_TAB_WIDTH and CFGDLG_TAB_HEIGHT specify the dimensions (in dialog units) of a dialog that will be placed within a tab control for dialogs where multiple display panels need to be shown.

#define CFGDLG_WIDTH   255

Width of a configuration dialog in dialog units.

CFGDLG_WIDTH and CFGDLG_HEIGHT specify the dimensions of a configuration dialog width and height in dialog units. The dialog will be created as a child of the configuration dialog and placed within it.

#define KHUI_CNFLAG_APPLIED   0x0200

Settings have been applied.

Set once any modified settings were successfully applied.

#define KHUI_CNFLAG_MODIFIED   0x0100

Settings have been modified.

Settings for this configuration panel have been modified. This flag should be cleared once the settings have been successfully applied.

#define KHUI_CNFLAG_SYSTEM   0x0010

System node.

Note:
For internal use by the NetIDMgr application. Do not use.

#define KHUI_MAXCB_LONG_DESC   (KHUI_MAXCCH_LONG_DESC * sizeof(wchar_t))

Maximum length of the long description in bytes.

The length includes the terminating NULL

#define KHUI_MAXCB_NAME   (KHUI_MAXCCH_NAME * sizeof(wchar_t))

Maximum length of the name in bytes.

The length includes the terminating NULL

#define KHUI_MAXCB_SHORT_DESC   (KHUI_MAXCCH_SHORT_DESC * sizeof(wchar_t))

Maximum length of the short description in bytes.

The length includes the terminating NULL

#define KHUI_MAXCCH_LONG_DESC   1024

Maximum length of the long description in characters.

The length includes the terminating NULL

#define KHUI_MAXCCH_NAME   256

Maximum length of the name in characters.

The length includes the terminating NULL

#define KHUI_MAXCCH_SHORT_DESC   256

Maximum length of the short description in chracters.

The length includes the terminating NULL

#define KHUI_WM_CFG_NOTIFY   (WM_APP + 0x101)

Configuration window notification message.

This is the message that will be used to notify dialog panels.

The format of the message is :

Note:
This is the same as KHUI_WM_NC_NOTIFY


Typedef Documentation

typedef struct tag_khui_config_init_data khui_config_init_data

Initialization data passed in to a subpanel.

When creating a subpanel, a pointer to the following strucutred will be passed in as the creation parameter for the dialog.

typedef khm_handle khui_config_node

A handle to a configuration node.

See also:
khui_cfg_open_node(), khui_cfg_close_node()

typedef struct tag_khui_config_node_reg khui_config_node_reg

Registration information for a configuration node.

See also:
khui_cfg_register_node()


Enumeration Type Documentation

enum khui_wm_cfg_notifications

Configuration notifications.

These are sent thorugh a KHUI_WM_CFG_NOTIFY message.

The format of the message is :

Enumerator:
WMCFG_SHOW_NODE  Sent to the configuration dialog to request that the panel for the specified node be shown. The lParam message parameter will contain a held khui_config_node handle. The sender of the mssage is responsible for releasing the handle.
WMCFG_UPDATE_STATE  Sent to the configuration dialog to indicate that the state flags for the specified configuration node have changed.

WMCFG_APPLY  Sent to all the configuration panels when the user clicks the 'Apply' button or the 'Ok' button. The panels are responsible for applying the configuration changes and updating their flags using khui_cfg_set_flags().
WMCFG_SYNC_NODE_LIST  Sent from the UI library to the configuration window to notify the window that the node list has changed. This message is sent synchronously before the node is removed.


Function Documentation

KHMEXP void KHMAPI khui_cfg_clear_params ( void   ) 

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_free_dialog_data ( HWND  hwnd_dlg  ) 

Utility function: Free dialog data.

Deallocates the memory allcated in a previous call to khui_cfg_init_dialog_data()

KHMEXP khm_int32 KHMAPI khui_cfg_get_dialog_data ( HWND  hwnd_dlg,
khui_config_init_data **  data,
void **  extra 
)

Utility function: Retrieves dialog data.

Retrieves the dialog data previoulsy stored using khui_cfg_init_dialog_data().

Parameters:
[in] hwnd_dlg Handle to the dialog box
[out] data Receives a pointer to the khui_config_init_data block.
[out] extra Receives a pointer to the extra memory allocated. Optional (set to NULL if this value is not needed).

KHMEXP khm_int32 KHMAPI khui_cfg_get_first_child ( khui_config_node  parent,
khui_config_node result 
)

Get a handle to the first child node.

If the call is successful, result will receieve a handle to the first child node of the specified node. The returned handle must be released with a call to khui_cfg_release()

If parent does not have any child nodes, the function will return KHM_ERROR_NOT_FOUND and set result to NULL.

Parameters:
[in] parent Parent node. Set to NULL to specify root node.
[out] result Receives a held handle to the first child node.
See also:
khui_cfg_get_next()

KHMEXP khm_int32 KHMAPI khui_cfg_get_first_subpanel ( khui_config_node  vparent,
khui_config_node result 
)

Get a handle to the first subpanel.

If the call is successful, result will receieve a handle to the first subpanel node of the specified node. The returned handle must be released with a call to khui_cfg_release()

If parent does not have any subpanels, the function will return KHM_ERROR_NOT_FOUND and set result to NULL.

A subpanel node is a node which has the KHUI_CNFLAG_SUBPANEL flag set.

Parameters:
[in] parent Parent node. Set to NULL to specify root node.
[out] result Receives a held handle to the first subpanel node.
See also:
khui_cfg_get_next()

KHMEXP khm_int32 KHMAPI khui_cfg_get_flags ( khui_config_node  vnode  ) 

Retrieve the state flags for the configuration node.

See also:
khui_cfg_set_flags()

KHMEXP HWND KHMAPI khui_cfg_get_hwnd ( khui_config_node  node  ) 

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP HWND KHMAPI khui_cfg_get_hwnd_inst ( khui_config_node  node,
khui_config_node  noderef 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_get_name ( khui_config_node  node,
wchar_t *  buf,
khm_size cb_buf 
)

Get the name of a configuration node.

Gets the name (not the short description or the long description) of the given configuration node.

KHMEXP khm_int32 KHMAPI khui_cfg_get_next ( khui_config_node  node,
khui_config_node result 
)

Get a handle to the next sibling node.

If the call is successful, result will receive a held handle to the next sibling node. The returned handle must be released with a call to khui_cfg_release().

If there are no more sibling nodes, then the function return KHM_ERROR_NOT_FOUND and set result to NULL.

This function can be used to traverse a list of child nodes as well as a list of subpanel nodes.

KHMEXP khm_int32 KHMAPI khui_cfg_get_next_release ( khui_config_node node  ) 

Get a handle to the next sibling node.

Similar to khui_cfg_get_next(), but implicitly releases the handle that was supplied. Equivalent to doing :

    khui_cfg_get_next(node, &next);
    khui_cfg_release(node);
    node = next;

Parameters:
[in,out] node On entry, specifies the node whose sibling needs to be fetched. On exit, will have either NULL or a held handle to the sibling node. The handle which was supplied to the function is released.
Return values:
KHM_ERROR_SUCCESS The next node is now in node
KHM_ERROR_INVALID_PARAM node was not a valid handle
KHM_ERROR_NOT_FOUND There are no more siblings. node is set to NULL.
Note:
Even if there are no more siblings, the handle specified in node on entry is released.

KHMEXP LPARAM KHMAPI khui_cfg_get_param ( khui_config_node  node  ) 

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP LPARAM KHMAPI khui_cfg_get_param_inst ( khui_config_node  node,
khui_config_node  noderef 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_get_parent ( khui_config_node  vnode,
khui_config_node result 
)

Get the parent of a node.

Returns a held handle to the parent of the node, or NULL if the current node is a top level node. The returned handle must be released with khui_cfg_release().

Return values:
KHM_ERROR_SUCCESS The handle to the parent node is in result
KHM_ERROR_NOT_FOUND The node is a top level node

KHMEXP khm_int32 KHMAPI khui_cfg_get_reg ( khui_config_node  node,
khui_config_node_reg reg 
)

Get registration information for a node.

The registration information that is returned is a shallow copy of the data kept by NetIDMgr. In particular, the strings that will be returned actually point to internal buffers and should not be modified.

No further action is necessary to release the information. However, the returned data ceases to be valid when node is released with a call to khui_cfg_release().

Parameters:
[in] node Node for which information is requested. Can be NULL if requesting information about the root node.
[out] reg Pointer to a khui_config_node_reg structure.

KHMEXP khm_int32 KHMAPI khui_cfg_hold ( khui_config_node  node  ) 

Hold a handle to a configuration node.

Obtains an additional hold on the handle specified by node. The hold must be released with a call to khui_cfg_release()

KHMEXP khm_int32 KHMAPI khui_cfg_init_dialog_data ( HWND  hwnd_dlg,
const khui_config_init_data data,
khm_size  cb_extra,
khui_config_init_data **  new_data,
void **  extra 
)

Utility function: Initialize dialog box window data.

This function initializes the dialog box window data using the khui_config_init_data that was passed into the WM_INITDIALOG message.

A new block of memory will be alocated to store the dialog data as well as any extra space specified. A pointer to this memory block will be stored in the DWLP_USER slot in the dialog box.

The allocated block of memory must be freed by a call to khui_cfg_free_dialog_data(). While handling other messages, the dialog data can be retrieved using khui_cfg_get_dialog_data().

Parameters:
[in] hwnd_dlg Handle to the dialog box
[in] data Pointer to the khui_config_init_data that was passed in to WM_INITDIALOG (this is the value of lParam)
[in] cb_extra Number of extra bytes to allocate, along with the space required to store the contents of khui_config_init_data. The extra space will be initialized to zero.
[out] new_data Receives a pointer to the copy of the initialization data that was allocated. Optional. Pass in NULL if this value is not required.
[out] extra Receives a pointer to the block of extra memory allocated as specified in cb_extra. If cb_extra is 0, then this receives a NULL.
See also:
khui_cfg_get_dialog_data(), khui_cfg_free_dialog_data()

KHMEXP khm_int32 KHMAPI khui_cfg_open ( khui_config_node  parent,
const wchar_t *  name,
khui_config_node result 
)

Open a configuration node by name.

If successful, the result parameter will receive a handle to the configuration node. Use khui_cfg_release() to release the handle.

Parameters:
[in] parent Parent node. Set to NULL to specify root node.

KHMEXP khm_int32 KHMAPI khui_cfg_register ( khui_config_node  parent,
const khui_config_node_reg reg 
)

Register a configuration node.

The caller fills the registration information in the khui_config_node_reg structre. If the call succeeds, the function will return KHM_ERROR_SUCCESS.

Parameters:
[in] parent Parent of the node to be registered. Set to NULL if the parent is the root node.
[in] reg Registration information
[out] new_id Receives the new unique identifier of the configuration node. Pass in NULL if the new identifier is not required.
Return values:
KHM_ERROR_SUCCESS Success
KHM_ERROR_INVALID_PARAM One or more parameters, or fields of reg were invalid
KHM_ERROR_DUPLICATE A node with the same name exists as a child of the specified parent node.
Note:
The name (not the short or long description) of the node can not be the same as the name of a custom action. See khui_action_create().

KHMEXP khm_int32 KHMAPI khui_cfg_release ( khui_config_node  node  ) 

Release a handle to a configuration node.

See also:
khui_cfg_hold()

KHMEXP khm_int32 KHMAPI khui_cfg_remove ( khui_config_node  node  ) 

Remove a configuration node.

Marks a configuration node as deleted. Once all the handles, including the handle specified in node have been released, it will be deleted.

KHMEXP void KHMAPI khui_cfg_set_configui_handle ( HWND  hwnd  ) 

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_flags ( khui_config_node  vnode,
khm_int32  flags,
khm_int32  mask 
)

Update the state for the specified node.

Parameters:
[in] node khui_config_node handle for the configuration node.
[in] flags New flags. Combination of KHUI_CNFLAG_APPLIED and KHUI_CNFLAG_MODIFIED
[in] mask Valid bits in flags
Note:
Should only be called from within the dialog procedure for the configuration node.

KHMEXP void KHMAPI khui_cfg_set_flags_inst ( khui_config_init_data d,
khm_int32  flags,
khm_int32  mask 
)

Sets the instance flags for a subpanel.

Since there can be more than one subpanel in a configuration panel, they shouldn't modify the flags of the configuration node directly. Instead, they should call this function to set the instance flags.

The instance flags will be merged with the flags for the configuration node automatically.

KHMEXP void KHMAPI khui_cfg_set_hwnd ( khui_config_node  node,
HWND  hwnd 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_hwnd_inst ( khui_config_node  node,
khui_config_node  noderef,
HWND  hwnd 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_param ( khui_config_node  node,
LPARAM  param 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_param_inst ( khui_config_node  node,
khui_config_node  noderef,
LPARAM  param 
)

Internal use.

This function is used internally by NetIDMgr. Do not use.


Generated on Fri Aug 3 08:27:14 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu