1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
|
/*
* 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
|