/* * Copyright (c) 2005 Massachusetts Institute of Technology * * Permission is hereby granted, free of charge, to any person * obtaining a copy of this software and associated documentation * files (the "Software"), to deal in the Software without * restriction, including without limitation the rights to use, copy, * modify, merge, publish, distribute, sublicense, and/or sell copies * of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be * included in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. */ /* $Id$ */ #ifndef __KHIMAIRA_KHCONFIGUI_H #define __KHIMAIRA_KHCONFIGUI_H /*! \addtogroup khui @{ */ /*! \defgroup khui_cfg Configuration Panels Configuration panels are the primary means from which the user is presented with an interface to change NetIDMgr and plugin configuration. @{ */ /*! \brief Configuration window notification message This is the message that will be used to notify dialog panels. The format of the message is : - uMsg : KHUI_WM_CFG_NOTIFY - HIWORD(wParam) : one of ::khui_wm_cfg_notifications \note This is the same as ::KHUI_WM_NC_NOTIFY */ #define KHUI_WM_CFG_NOTIFY (WM_APP + 0x101) /*! \brief Configuration notifications These are sent thorugh a ::KHUI_WM_CFG_NOTIFY message. The format of the message is : - uMsg : KHUI_WM_CFG_NOTIFY - HIWORD(wParam) : one of ::khui_wm_cfg_notifications */ enum khui_wm_cfg_notifications { WMCFG_SHOW_NODE = 1, /*!< Sent to the configuration dialog to request that the panel for the specified node be shown. The \a 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 = 2, /*!< Sent to the configuration dialog to indicate that the state flags for the specified configuration node have changed. - LOWORD(wParam) : new flags - lParam : ::khui_config_node for the node*/ WMCFG_APPLY = 3, /*!< 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 = 4, /*!< 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. */ }; /*! \brief Registration information for a configuration node \see khui_cfg_register_node() */ typedef struct tag_khui_config_node_reg { const wchar_t * name; /*!< Internal identifier (not-localized, required). The name is required to be unique among sibling nodes. However it is not required to be unique globally. The size of the name is constrained by ::KHUI_MAXCCH_NAME*/ const wchar_t * short_desc; /*!< Short description (Localized, required). This is the name which identifies the node within a collection of siblings. The size of the string is constrained by ::KHUI_MAXCCH_SHORT_DESC*/ const wchar_t * long_desc; /*!< Global name of the node. (Localized, required). This uniquely identifies the node in the collection of all configuration nodes. The size of the string is constrained by ::KHUI_MAXCCH_LONG_DESC.*/ HMODULE h_module; /*!< Module which contains the dialog resource specified in \a dlg_template */ LPWSTR dlg_template; /*!< Dialog template for the configuration window */ DLGPROC dlg_proc; /*!< Dialog procedure */ khm_int32 flags; /*!< Flags. Can be a combination of ::KHUI_CNFLAG_SORT_CHILDREN and ::KHUI_CNFLAG_SUBPANEL*/ } khui_config_node_reg; /*! \brief Sort the child nodes by short description */ #define KHUI_CNFLAG_SORT_CHILDREN 0x0001 /*! \brief Is a subpanel */ #define KHUI_CNFLAG_SUBPANEL 0x0002 /*! \brief Node represents a panel that is replicated for all child nodes */ #define KHUI_CNFLAG_PLURAL 0x0004 /*! \brief System node \note For internal use by the NetIDMgr application. Do not use. */ #define KHUI_CNFLAG_SYSTEM 0x0010 /*! \brief 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_MODIFIED 0x0100 /*! \brief Settings have been applied Set once any modified settings were successfully applied. */ #define KHUI_CNFLAG_APPLIED 0x0200 #define KHUI_CNFLAGMASK_STATIC 0x00ff #define KHUI_CNFLAGMASK_DYNAMIC 0x0f00 /*! \brief Maximum length of the name in characters The length includes the terminating NULL */ #define KHUI_MAXCCH_NAME 256 /*! \brief Maximum length of the name in bytes The length includes the terminating NULL */ #define KHUI_MAXCB_NAME (KHUI_MAXCCH_NAME * sizeof(wchar_t)) /*! \brief Maximum length of the long description in characters The length includes the terminating NULL */ #define KHUI_MAXCCH_LONG_DESC 1024 /*! \brief Maximum length of the long description in bytes The length includes the terminating NULL */ #define KHUI_MAXCB_LONG_DESC (KHUI_MAXCCH_LONG_DESC * sizeof(wchar_t)) /*! \brief Maximum length of the short description in chracters The length includes the terminating NULL */ #define KHUI_MAXCCH_SHORT_DESC 256 /*! \brief Maximum length of the short description in bytes The length includes the terminating NULL */ #define KHUI_MAXCB_SHORT_DESC (KHUI_MAXCCH_SHORT_DESC * sizeof(wchar_t)) /*! \brief 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 CFGDLG_WIDTH 255 /*! \brief Height of a configuration dialog in dialog units \see ::CFGDLG_WIDTH */ #define CFGDLG_HEIGHT 182 /*! \brief 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_TAB_WIDTH 235 /*! \brief Height of configuration tab dialog in dialog units \see ::CFGDLG_TAB_WIDTH */ #define CFGDLG_TAB_HEIGHT 151 /*! \brief A handle to a configuration node \see khui_cfg_open_node(), khui_cfg_close_node() */ typedef khm_handle khui_config_node; /*! \brief 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 struct tag_khui_config_init_data { khui_config_node ctx_node; /*!< The node under which the current dialog subpanel is being created. */ khui_config_node this_node; /*!< The node which provided the registration information for the creation of the subpanel. */ khui_config_node ref_node; /*!< The parent node of the subpanel node. In nodes which have the ::KHUI_CNFLAG_PLURAL, this would be different from the \a node. This is the node under which the subpanel was registered. */ } khui_config_init_data; /*! \brief 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. \param[in] parent Parent of the node to be registered. Set to NULL if the parent is the root node. \param[in] reg Registration information \param[out] new_id Receives the new unique identifier of the configuration node. Pass in NULL if the new identifier is not required. \retval KHM_ERROR_SUCCESS Success \retval KHM_ERROR_INVALID_PARAM One or more parameters, or fields of reg were invalid \retval 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_register(khui_config_node parent, const khui_config_node_reg * reg); /*!\brief Open a configuration node by name If successful, the \a result parameter will receive a handle to the configuration node. Use khui_cfg_release() to release the handle. \param[in] parent Parent node. Set to NULL to specify root node. */ KHMEXP khm_int32 KHMAPI khui_cfg_open(khui_config_node parent, const wchar_t * name, khui_config_node * result); /*! \brief Remove a configuration node Marks a configuration node as deleted. Once all the handles, including the handle specified in \a node have been released, it will be deleted. */ KHMEXP khm_int32 KHMAPI khui_cfg_remove(khui_config_node node); /*! \brief Hold a handle to a configuration node Obtains an additional hold on the handle specified by \a node. The hold must be released with a call to \a khui_cfg_release() */ KHMEXP khm_int32 KHMAPI khui_cfg_hold(khui_config_node node); /*! \brief Release a handle to a configuration node \see khui_cfg_hold() */ KHMEXP khm_int32 KHMAPI khui_cfg_release(khui_config_node node); /*! \brief 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(). \retval KHM_ERROR_SUCCESS The handle to the parent node is in \a result \retval KHM_ERROR_NOT_FOUND The node is a top level node */ KHMEXP khm_int32 KHMAPI khui_cfg_get_parent(khui_config_node vnode, khui_config_node * result); /*! \brief Get a handle to the first child node If the call is successful, \a 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 \a parent does not have any child nodes, the function will return KHM_ERROR_NOT_FOUND and set \a result to NULL. \param[in] parent Parent node. Set to NULL to specify root node. \param[out] result Receives a held handle to the first child node. \see khui_cfg_get_next() */ KHMEXP khm_int32 KHMAPI khui_cfg_get_first_child(khui_config_node parent, khui_config_node * result); /*! \brief Get a handle to the first subpanel If the call is successful, \a 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 \a parent does not have any subpanels, the function will return KHM_ERROR_NOT_FOUND and set \a result to NULL. A subpanel node is a node which has the ::KHUI_CNFLAG_SUBPANEL flag set. \param[in] parent Parent node. Set to NULL to specify root node. \param[out] result Receives a held handle to the first subpanel node. \see khui_cfg_get_next() */ KHMEXP khm_int32 KHMAPI khui_cfg_get_first_subpanel(khui_config_node vparent, khui_config_node * result); /*! \brief Get a handle to the next sibling node If the call is successful, \a 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 \a 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(khui_config_node node, khui_config_node * result); /*! \brief 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 : \code khui_cfg_get_next(node, &next); khui_cfg_release(node); node = next; \endcode \param[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. \retval KHM_ERROR_SUCCESS The next node is now in \a node \retval KHM_ERROR_INVALID_PARAM \a node was not a valid handle \retval KHM_ERROR_NOT_FOUND There are no more siblings. \a node is set to NULL. \note Even if there are no more siblings, the handle specified in \a node on entry is released. */ KHMEXP khm_int32 KHMAPI khui_cfg_get_next_release(khui_config_node * node); /*! \brief 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_name(khui_config_node node, wchar_t * buf, khm_size * cb_buf); /*! \brief 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 \a node is released with a call to khui_cfg_release(). \param[in] node Node for which information is requested. Can be NULL if requesting information about the root node. \param[out] reg Pointer to a ::khui_config_node_reg structure. */ KHMEXP khm_int32 KHMAPI khui_cfg_get_reg(khui_config_node node, khui_config_node_reg * reg); /*! \brief 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); /*! \brief 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); /*! \brief 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); /*! \brief 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); /*! \brief Internal use This function is used internally by NetIDMgr. Do not use. */ KHMEXP HWND KHMAPI khui_cfg_get_hwnd(khui_config_node node); /*! \brief Internal use This function is used internally by NetIDMgr. Do not use. */ KHMEXP LPARAM KHMAPI khui_cfg_get_param(khui_config_node node); /*! \brief Internal use This function is used internally by NetIDMgr. Do not use. */ KHMEXP void KHMAPI khui_cfg_set_hwnd(khui_config_node node, HWND hwnd); /*! \brief 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); /*! \brief Internal use This function is used internally by NetIDMgr. Do not use. */ KHMEXP void KHMAPI khui_cfg_clear_params(void); /*! \brief Internal use This function is used internally by NetIDMgr. Do not use. */ KHMEXP void KHMAPI khui_cfg_set_configui_handle(HWND hwnd); /*! \brief Update the state for the specified node \param[in] node ::khui_config_node handle for the configuration node. \param[in] flags New flags. Combination of ::KHUI_CNFLAG_APPLIED and ::KHUI_CNFLAG_MODIFIED \param[in] mask Valid bits in \a flags \note Should only be called from within the dialog procedure for the configuration node. */ KHMEXP void KHMAPI khui_cfg_set_flags(khui_config_node vnode, khm_int32 flags, khm_int32 mask); /*! \brief Retrieve the state flags for the configuration node \see khui_cfg_set_flags() */ KHMEXP khm_int32 KHMAPI khui_cfg_get_flags(khui_config_node vnode); /*! \brief 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 \a 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(). \param[in] hwnd_dlg Handle to the dialog box \param[in] data Pointer to the ::khui_config_init_data that was passed in to WM_INITDIALOG (this is the value of \a lParam) \param[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. \param[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. \param[out] extra Receives a pointer to the block of extra memory allocated as specified in \a cb_extra. If \a cb_extra is 0, then this receives a NULL. \see khui_cfg_get_dialog_data(), khui_cfg_free_dialog_data() */ 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); /*! \brief Utility function: Retrieves dialog data Retrieves the dialog data previoulsy stored using khui_cfg_init_dialog_data(). \param[in] hwnd_dlg Handle to the dialog box \param[out] data Receives a pointer to the ::khui_config_init_data block. \param[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_dialog_data(HWND hwnd_dlg, khui_config_init_data ** data, void ** extra); /*! \brief 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_free_dialog_data(HWND hwnd_dlg); /*! \brief 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_flags_inst(khui_config_init_data * d, khm_int32 flags, khm_int32 mask); /*!@} */ /*!@} */ #endif