2
* Copyright (c) 2005 Massachusetts Institute of Technology
4
* Permission is hereby granted, free of charge, to any person
5
* obtaining a copy of this software and associated documentation
6
* files (the "Software"), to deal in the Software without
7
* restriction, including without limitation the rights to use, copy,
8
* modify, merge, publish, distribute, sublicense, and/or sell copies
9
* of the Software, and to permit persons to whom the Software is
10
* furnished to do so, subject to the following conditions:
12
* The above copyright notice and this permission notice shall be
13
* included in all copies or substantial portions of the Software.
15
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27
#ifndef __KHIMAIRA_KHNEWCRED_H
28
#define __KHIMAIRA_KHNEWCRED_H
30
/********************************************************************
31
New credentials windows
32
*********************************************************************/
37
/*! \defgroup khui_cred Credentials acquisition
39
Declarations associated with credentials acquisition.
43
/*! \brief Window message sent to credentials type panels
45
This message is sent to the child windows.
47
The format of the message is :
48
- uMsg : KHUI_WM_NC_NOTIFY
49
- HIWORD(wParam) : one of ::khui_wm_nc_notifications
50
- LPARAM : pointer to the ::khui_new_creds structure (except where noted)
52
#define KHUI_WM_NC_NOTIFY (WM_APP + 0x101)
54
/*! \brief The first control ID that may be used by an identity provider */
55
#define KHUI_CW_ID_MIN 8016
57
/*! \brief The maximum number of controls that may be created by an identity provider*/
58
#define KHUI_CW_MAX_CTRLS 8
60
/*! \brief The maximum control ID that may be used by an identity provider */
61
#define KHUI_CW_ID_MAX (KHUI_CW_ID_MIN + KHUI_CW_MAX_CTRLS - 1)
64
/*! \brief Credentials dialog notifications
66
These notifications will be sent to the individual dialog
67
procedures of the credential type panels or to the new credentials
68
window as a ::KHUI_WM_NC_NOTIFY message.
70
enum khui_wm_nc_notifications {
71
WMNC_DIALOG_EXPAND = 1,
72
/*!< The dialog is switching from basic to advanced mode or vice
75
In expanded mode, all credentials type panels are visible as
76
opposed to the compressed mode where they are not visible. The
77
message is not sent to credentials type panels.
79
Only sent to the new credentials window.
83
/*!< Sent to the new creds window to notify it that the dialog
84
should create all the type configuration panels.
86
Until this message is issued, none of the credentials type
87
panels exist. The credentials type panels will receive
88
WM_INITDIALOG etc as per the normal dialog creation process.
90
Only sent to the new credentials window.
94
/*!< Sent to the new creds window to notify it that the dialog
95
should do final initialization work and activate.
97
Only sent to the new credentials window.
101
/*!< The new credentials window has moved.
103
This message is sent to all the credentials type panels when the
104
new credentials window is being moved. It will be sent
105
continuously if the user is dragging the window. Plug-ins
106
rarely need to know their position on the screen. However, if
107
there are any other windows that were created by the plug-in,
108
such as floating controls or tooltips, they may need to be
109
repositioned in response to this message.
111
Sent to all the credentials type panels.
114
WMNC_DIALOG_SWITCH_PANEL,
115
/*!< Sent to the new creds window to cause it to switch to the
116
panel identified by LOWORD(wParam).
118
Does nothing if the specified panel is already the current
119
panel. If the dialog is in compact mode and making the
120
specified panel visible requires switching to expanded mode, the
123
Only sent to the new credentials window.
126
WMNC_UPDATE_CREDTEXT,
127
/*!< Update the credentials text associated with a panel.
129
During the new credentials operation, each plug-in is expected
130
to maintain a textual representation of the credentials that the
131
plug-in expects to obtain for the selected identity. It can,
132
alternatively, be used to indicate the state of the credentials
133
type in respect to the selected identity (for example, whether
134
the credentials type is disabled for the identity and why).
136
This text is not visible when the new credentials window is in
137
basic mode, but it is visible when the window is in advanced
138
mode. The following image shows the expanded new credentials
139
window including the credentials text from a several plug-ins:
141
\image html new_creds_expanded.png
143
Once this message is received, each plug-in should construct its
144
credentials text string and store it in the \c credtext member
145
of its ::khui_new_creds_by_type structure as shown in the sample
149
// Handler for window message WM_NC_NOTIFY with
150
// HWND hwnd, WPARAM wParam and LPARAM lParam
152
// This structure holds the dialog data for the panel. We
153
// assume it has 'nc' and 'nct' fields that point to the
154
// khui_new_creds and khui_new_creds_by_type structures
158
struct nc_dialog_data * d;
161
// Retrieve the data structure from the dialog user data.
162
d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER);
164
switch (HIWORD(wParam)) {
165
case WMNC_UPDATE_CREDTEXT:
167
wchar_t buffer[KHUI_MAXCCH_LONG_DESC];
170
// we are being requested to update the credentials text. We
171
// already allocated a buffer when we created the nct
172
// structure. So we can just set the text here.
174
// The credentials text should reflect the credentials that
175
// will be obtained when the new credentials operation
178
assert(d && d->nc && d->nct);
180
if (d->nct->credtext) {
181
free(d->nct->credtext);
182
d->nct->credtext = NULL;
185
// We only display something if there is a selected identity
186
if (d->nc->n_identities > 0) {
187
StringCbPrintf(buffer, sizeof(buffer),
188
L"<p>My Credentials<tab>: %s</p>",
189
get_credential_name(d));
190
StringCbLength(buffer, sizeof(buffer), &cb_size);
191
cb_size += sizeof(wchar_t); // account for the terminating NULL
193
d->nct->credtext = malloc(cb_size);
194
if (d->nct->credtext) {
195
StringCbCopy(d->nct->credtext, cb_size, buffer);
202
... // Handler other notifications
206
The text that is specified as the credentials text is formatted
207
hypertext. For more information about support for formatting
208
and hypertext and handling hyperlinks, see \ref khui_htwnd.
210
\note When this message is sent to the new credentials window,
211
the application will send the ::WMNC_UPDATE_CREDTEXT message to
212
all the credential type panels and update the credential text
216
/*!< A hyperlink was activated.
218
Sent to a panel dialog procedure when a user clicks an embedded
219
link in the credentials text that belongs to that panel. The \a
220
lParam parameter of the message is a pointer to a
221
::khui_htwnd_link structure describing the link.
225
\note The \a lParam parameter does not point to a
226
::khui_new_creds structure for this message.
229
WMNC_IDENTITY_CHANGE,
230
/*!< The primary identity has changed.
232
The ::khui_new_creds structure contains a list of identities to
233
which the current operation should be applied. In its current
234
implementation, only the first identity in this list is used.
235
Therefore, the list will contain at most one identity. It is
236
possible for the list to be empty (for example, if the user
237
hasn't selected an identity yet).
239
When handling this notification, the plug-in should check the \c
240
n_identities member of the ::khui_new_creds structure to see
241
whether there are any identities selected. This value would be
242
either zero or one. If it is non-zero, then a handle to the
243
selected identity will be in \c khui_new_creds::identities[0].
245
Plug-ins typically use this notfication to load identity
246
specific settings when a new identity is selected.
248
This notification is sent to all the credentials type panels.
252
/*!< Sent to the new creds window to clear any custom prompts.
254
Only sent to the new credentials window.
258
/*!< Sent to the new creds window to set custom prompts.
260
Only sent to the new credentials window. */
262
WMNC_DIALOG_PREPROCESS,
263
/*!< The credentials acquisition process is about to start.
265
Sent to all the credentials type panels to notify them that the
266
credentials acquisition process will start. Once all plug-ins
267
have handled the notification, the application will start
268
sending out <::KMSG_CRED, ::KMSG_CRED_PROCESS> messages to the
269
credentials providers which are participating in the new
270
credentials operation.
274
/*!< This notification is no longer used. */
275
#pragma deprecated(WMNC_DIALOG_PROCESS)
277
WMNC_DIALOG_PROCESS_COMPLETE,
278
/*!< Sent to the new creds window to indicate that the all the
279
threads have completed processing.*/
282
/*!< Sent to the new creds window as notification that a
283
particular credentials type has changed state from enabled to
284
disabled or vice versa. The LPARAM member of the message
285
specifies the credentials type identifier for the changed
288
WMNC_ADD_CONTROL_ROW,
289
/*!< Add a row of controls to a new cred dialog. This is an
293
/*!< Update the layout of a dialog or window. This is an internal
297
/*! \brief Plugins can use WMNC_NOTIFY message codes from here on up
299
\see ::KHUI_WM_NC_NOTIFY
301
#define WMNC_USER 2048
303
/*! \brief Notifications to the identity provider
305
These notifications are sent through to the identity provider's UI
306
callback that was obtained using a ::KMSG_IDENT_GET_UI_CB message.
308
The callback routine is called from the context of the UI thread
309
and is expected to not make any blocking calls. One of the
310
following commands will be passed in as the \a cmd parameter to
313
enum khui_wm_nc_ident_notify {
315
/*!< Initialize an identity selector for a new credentials
316
dialog. The \a lParam parameter contains a handle to the
317
dialog window which will contain the identity selector
318
controls. The identity provider may make use of the \a
319
ident_aux field of the ::khui_new_creds structure to hold any
320
data pertaining to the credentials acquisition dialog.*/
323
/*!< Windows message. Presumably sent from one of the controls
324
that was created by the identity provider. The callback is
325
expected to return TRUE if it processed the message or FALSE
326
if it did not. The \a uMsg, \a wParam and \a lParam
327
parameters are set to the values passed in by Windows. */
330
/*!< Terminate a credentials acquisition dialog. Sent just before
331
the dialog is terminated. */
333
WMNC_IDENT_PREPROCESS,
334
/*!< The identity is about to be fetched from the \a
335
::khui_new_creds structure. The callback is expected to ensure
336
that the primary identity listed in that structure is
337
consistent with the user selection. */
340
/*! \name Standard credtext link IDs
343
/*! \brief Switch the panel
345
The \a id attribute of the link specifies the ordinal of the panel
348
#define CTLINKID_SWITCH_PANEL L"SwitchPanel"
353
struct tag_khui_new_creds_by_type;
354
typedef struct tag_khui_new_creds_by_type khui_new_creds_by_type;
355
struct tag_khui_new_creds_prompt;
356
typedef struct tag_khui_new_creds_prompt khui_new_creds_prompt;
357
struct tag_khui_new_creds;
358
typedef struct tag_khui_new_creds khui_new_creds;
361
(KHMAPI *khui_ident_new_creds_cb)(khui_new_creds * nc,
368
/*! \brief New credentials acquisition blob
370
A pointer to an object of this type is passed in along with the
371
credentials acquisition messages.
373
\see \ref cred_acq for more information
375
typedef struct tag_khui_new_creds {
376
khm_int32 magic; /*!< Internal use */
378
khm_int32 subtype; /*!< Subtype of the request that is
379
being handled through this object.
380
One of ::KMSG_CRED_NEW_CREDS,
381
::KMSG_CRED_RENEW_CREDS or
382
::KMSG_CRED_PASSWORD */
384
CRITICAL_SECTION cs; /*!< Internal use */
386
khm_boolean set_default; /*!< After a successfull credentials
387
acquisition, set the primary
388
identity as the default. */
390
khm_handle *identities; /*!< The list of identities associated
391
with this request. The first
392
identity in this list (\a
393
identities[0]) is the primary
396
khm_size n_identities; /*!< Number of identities in the list
399
khm_size nc_identities; /*!< Internal use */
401
khui_action_context ctx; /*!< An action context specifying the
402
context in which the credentials
403
acquisition operation was
406
khm_int32 mode; /*!< The mode of the user interface.
407
One of ::KHUI_NC_MODE_MINI or
408
::KHUI_NC_MODE_EXPANDED. */
410
HWND hwnd; /*!< Handle to the new credentials
413
struct tag_khui_new_creds_by_type **types;
415
khm_handle *type_subs; /*!< Internal use */
416
khm_size n_types; /*!< Internal use */
417
khm_size nc_types; /*!< Internal use */
419
khm_int32 result; /*!< One of ::KHUI_NC_RESULT_CANCEL or
420
::KHUI_NC_RESULT_PROCESS indicating
421
the result of the dialog with the
424
khm_int32 response; /*!< Response. See individual message
425
documentation for info on what to do
428
wchar_t *password; /*!< Not used. */
432
wchar_t *banner; /*!< Internal use */
433
wchar_t *pname; /*!< Internal use */
434
khm_size n_prompts; /*!< Internal use */
435
khm_size nc_prompts; /*!< Internal use */
436
struct tag_khui_new_creds_prompt ** prompts; /*!< Internal use */
438
khui_ident_new_creds_cb ident_cb; /*!< Internal use */
440
wchar_t *window_title; /*!< Internal use */
442
LPARAM ident_aux; /*!< Auxilliary field which is
443
reserved for use by the identity
444
provider during the course of
445
conducting this dialog. */
449
#define KHUI_NC_MAGIC 0x84270427
451
/*!\name Result values for khui_new_creds_t::result
453
#define KHUI_NC_RESULT_PROCESS 0
454
#define KHUI_NC_RESULT_CANCEL 1
457
/*!\name Mode values for khui_new_creds_t::mode
459
#define KHUI_NC_MODE_MINI 0
460
#define KHUI_NC_MODE_EXPANDED 1
463
/*!\name Response values for khui_new_creds_t::response
465
/*!\brief No known response */
466
#define KHUI_NC_RESPONSE_NONE 0
468
/*!\brief It is okay to exit the dialog now
470
This is the default, which is why it has a value of zero. In
471
order to prevent the dialog from exiting, set the
472
KHUI_NC_RESPONSE_NOEXIT response bit. */
473
#define KHUI_NC_RESPONSE_EXIT 0
475
/*!\brief It is NOT okay to exit the dialog now
477
Used to indicate that further user-interaction is necessary to
478
process the dialog. Usually this is accompanied by setting
479
necessary custom prompts and notifications so the user knows why
480
the dialog is prompting for more information.
482
#define KHUI_NC_RESPONSE_NOEXIT 0x00000002
484
/*!\brief The dialog was processed successfully
486
Since this is the default response, the value is zero. Use one of
487
KHUI_NC_RESPONSE_FAILED or KHUI_NC_RESPONSE_PENDING to indicate an
488
error or pending status.
490
#define KHUI_NC_RESPONSE_SUCCESS 0
492
/*!\brief The processing of the dialog failed
494
Self explanatory. More information about the failure should have
495
been reported using the khlog API, however, this response value
496
indicates to other credential types that depend on this credential
497
type that whatever it was that this credential type was supposed
500
#define KHUI_NC_RESPONSE_FAILED 0x00000008
502
/*!\brief Further interaction required
504
Set along with KHUI_NC_RESPONSE_NOEXIT although it is not
505
required. Setting this bit will automatically add the
506
KHUI_NC_RESPONSE_NOEXIT.
508
If this bit is set, all dependent plugins will be set on hold
509
until another round of processing clears the pending bit.
511
#define KHUI_NC_RESPONSE_PENDING 0x00000010
515
This is automatically set if the plugin sets a response which does
516
not indicate either KHUI_NC_RESPONSE_NOEXIT or
517
KHUI_NC_RESPONSE_PENDING, which is considered to mean that the
518
plugin is completed processing.
520
This flag cannot be explicitly specified in a response.
522
#define KHUI_NC_RESPONSE_COMPLETED 0x00000020
524
/*! \brief Processing
526
This is an internal flag set while the credentials acquisition
527
process is executing.
529
#define KHUI_NC_RESPONSE_PROCESSING 0x00010000
531
#define KHUI_NCMASK_RESPONSE (KHUI_NC_RESPONSE_EXIT|KHUI_NC_RESPONSE_NOEXIT)
532
#define KHUI_NCMASK_RESULT (KHUI_NC_RESPONSE_SUCCESS|KHUI_NC_RESPONSE_FAILED|KHUI_NC_RESPONSE_PENDING)
535
/*!\brief Maximum number of dependencies for a credentials type */
536
#define KHUI_MAX_TYPE_DEPS 8
538
/*!\brief Maximum number of credential types for a new creds window */
539
#define KHUI_MAX_NCTYPES 16
541
/*!\brief Maximum number of characters in a password
543
Length includes the termininating NULL
545
#define KHUI_MAXCCH_PASSWORD 512
547
/*! \brief Maximum number of bytes in a password
549
Includes terminating NULL
551
#define KHUI_MAXCB_PASSWORD (KHUI_MAXCCH_PASSWORD * sizeof(wchar_t))
553
/*! \brief Maximum number of characters in a custom banner
555
Length includes terminating NULL
557
#define KHUI_MAXCCH_BANNER 256
560
/*! \brief Maximum number of bytes in a custom banner
562
Length includes terminating NULL
564
#define KHUI_MAXCB_BANNER (KHUI_MAXCCH_BANNER * sizeof(wchar_t))
566
/*! \brief Maximum number of characters in a panel name
568
Length includes terminating NULL
570
#define KHUI_MAXCCH_PNAME 256
572
/*! \brief Maximum number of bytes in a panel name
574
Length includes terminating NULL
576
#define KHUI_MAXCB_PNAME (KHUI_MAXCCH_PNAME * sizeof(wchar_t))
578
/*! \brief A descriptor of a panel in the new credentials acquisition tab
580
When processing certain credentials messages such as
581
::KMSG_CRED_PASSWORD, ::KMSG_CRED_NEW_CREDS,
582
::KMSG_CRED_RENEW_CREDS, a pointer to a ::khui_new_creds structure
583
will be passed in to the message handler. If the handler of the
584
message needs to add one or more credentials types as participants
585
of the operation, the handler will need to call khui_cw_add_type()
586
and specify a ::khui_new_creds_by_type structure.
588
Note that the memory address passed in to the call to
589
khui_cw_add_type() will not be copied. Therefore, the block of
590
memory should remain as-is for the lifetime of the
591
::khui_new_creds structure or until it is removed with a call to
594
Some of the credentials messages that require specifying a
595
::khui_new_creds_by_type structure require providing a
596
user-interface. In these cases, the fields marked for providing a
597
UI may be required to hold valid values. If the message does not
598
require providing a UI, these fields will be ignored.
600
typedef struct tag_khui_new_creds_by_type {
601
khui_new_creds * nc; /*!< Internal use. Do not set */
602
khm_int32 flags; /*!< Internal use. Do not set */
604
khm_int32 type; /*!< The identifier of the credentials
605
type. This is a credentials type
606
identifier allocated with a call to
607
kcdb_credtype_register(). */
609
khm_int32 type_deps[KHUI_MAX_TYPE_DEPS];
610
/*!< credentials types that this
611
credential type depends on. Each
612
element defines a credentials type
613
identifier that this type depends
614
on for this operation. The number
615
of valid values in this array
616
should be specified in the \a
617
n_type_deps field. */
619
khm_size n_type_deps; /*!< Number of dependencies listed
620
above. Should be between 0 and
621
::KHUI_MAX_TYPE_DEPS. Specify 0 if
622
there are no dependencies. */
624
khm_size ordinal; /*!< The requested ordinal. The UI
625
would attempt to place this panel at
626
the reqested order in the list of
627
panels. Set to -1 if the order does
628
not matter. Once the dialog is
629
activated this field will be updated
630
to reflect the actual ordinal of the
633
wchar_t *name; /*!< Name of the panel (localized,
634
optional). If NULL, the localized
635
name of the credentials type is
636
used. Only used if providing a
639
HICON icon; /*!< Icon for the panel (optional).
640
Only used if providing a
643
wchar_t *tooltip; /*!< Tooltip for the panel (localized,
644
optional). If NULL, no tooltip will
645
be assigned for the panel. Only
649
HMODULE h_module; /*!< Handle to the module containing
650
the dialog resource. Only used if
651
providing a user-interface. */
653
LPWSTR dlg_template; /*!< The dialog resource. Only used
654
if providing a user-interface. */
655
DLGPROC dlg_proc; /*!< The dialog procedure. Only used
656
if providing a user-interface. */
658
HWND hwnd_panel; /*!< The dialog window. Once the
659
dialog panel is created, a handle to
660
the panel will be assigned here.
661
Note that the handle is assigned
662
after a successful call to
663
CreateDialogParam and hence would
664
not be available when handling the
665
WM_INITDIALOG message from the
666
dialog procedure. Only used of
667
providing a user-interface. */
669
HWND hwnd_tc; /*!< Internal use. Do not set */
671
wchar_t *credtext; /*!< A brief description of the
672
current state of this cred
673
type. (localized, optional). Only
675
user-interface. If this field is
676
non-NULL, then it should point to a
677
NULL terminated string that does not
678
exceed ::KHUI_MAXCCH_LONG_DESC
679
characters in length including the
682
\see \ref khui_htwnd for information
683
on how to format the string for this
687
LPARAM aux; /*!< auxilliary field. For use by the
689
} khui_new_creds_by_type;
691
/*!\name Flags for khui_new_creds_by_type
693
Note that KHUI_NC_RESPONSE_SUCCESS, KHUI_NC_RESPONSE_FAILED,
694
KHUI_NC_RESPONSE_PENDING are also stored in the flags.
697
#define KHUI_NCT_FLAG_PROCESSED 1024
698
#define KHUI_NCT_FLAG_DISABLED 2048
701
/*! \brief Width of a new creds dialog panel in dialog units*/
702
#define NCDLG_WIDTH 300
703
/*! \brief Height of a new creds dialog panel in dialog units*/
704
#define NCDLG_HEIGHT 166
706
/*! \brief A custom prompt */
707
typedef struct tag_khui_new_creds_prompt {
708
khm_size index; /*!< Set to the zero based index
711
khm_int32 type; /*!< one of KHUI_NCPROMPT_TYPE_* */
712
wchar_t * prompt; /*!< prompt string. Cannot exceed
713
KHUI_MAXCCH_PROMPT */
714
wchar_t * def; /*!< default value. Cannot exceed
715
KHUI_MAXCCH_PROMPT_VALUE */
716
wchar_t * value; /*!< On completion, this is set to the
717
value that the user entered. Will
719
KHUI_MAXCCH_PROMPT_VALUE */
721
khm_int32 flags; /*!< Combination of
722
KHUI_NCPROMPT_FLAG_* */
724
HWND hwnd_static; /* internal use */
725
HWND hwnd_edit; /* internal use */
726
} khui_new_creds_prompt;
728
/*! \brief The prompt input is hidden
730
The input is hidden for prompts which accept passwords. The
731
control which represents the input will display an asterisk or a
732
small circle corresponding to each character typed in, but will
733
not show the actual character.
735
#define KHUI_NCPROMPT_FLAG_HIDDEN 1
737
/*! \brief Internal use */
738
#define KHUI_NCPROMPT_FLAG_STOCK 2
740
/*! \brief Maximum number of characters in a prompt
742
Refers to the prompt text that accompanies an input control. THe
743
length includes the terminating NULL.
745
#define KHUI_MAXCCH_PROMPT 256
747
/*! \brief Maximum number of bytes in a prompt
749
Refers to the prompt text that accompanies an input control. THe
750
length includes the terminating NULL.
752
#define KHUI_MAXCB_PROMPT (KHUI_MAXCCH_PROMPT * sizeof(wchar_t))
754
/*! \brief Maximum number of characters that can be entered in an input control
756
Refers to the input control of a prompt. The length includes the
759
#define KHUI_MAXCCH_PROMPT_VALUE 256
761
/*! \brief Maximum number of bytes that can be entered in an input control
763
Refers to the input control of a prompt. The length includes the
766
#define KHUI_MAXCB_PROMPT_VALUE (KHUI_MAXCCH_PROMPT_VALUE * sizeof(wchar_t))
768
/* from krb5.h. Redefining here because we don't want to depend on
769
krb5.h for all credential types */
771
/*! \brief A password control */
772
#define KHUI_NCPROMPT_TYPE_PASSWORD 1
774
/*! \brief New password control
776
Used when changing the password
778
#define KHUI_NCPROMPT_TYPE_NEW_PASSWORD 2
780
/*! \brief New password again control
782
Used when changing the password
784
#define KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN 3
786
/*! \brief Preauthentication (reserved) */
787
#define KHUI_NCPROMPT_TYPE_PREAUTH 4
789
/*! \brief Control sizes */
790
typedef enum tag_khui_control_size {
792
/*!< A small control fits in about 1/5 the width of the new
795
/*!< Half size controls fit in 1/2 the width of the new
798
/*!< Takes up the whole width of the crednetials panel */
801
/*! \brief Internal use */
802
typedef struct tag_khui_control_row {
805
khui_control_size size;
808
/*! \brief Create a ::khui_new_creds object
810
Creates and initializes a ::khui_new_creds object. The created
811
object must be destroyed using the khui_cw_destroy_cred_blob()
814
\note Plugins should not call this function directly. The
815
necessary ::khui_new_creds objects will be created by
818
\see khui_cw_destroy_cred_blob()
820
KHMEXP khm_int32 KHMAPI
821
khui_cw_create_cred_blob(khui_new_creds ** c);
823
/*! \brief Destroy a ::khui_new_creds object
825
Destroys a ::khui_new_creds object that was fomerly created using
826
a call to khui_cw_create_cred_blob().
828
\note Plugins should not call this function directly. The
829
necessary ::khui_new_creds objects will be created by
832
\see khui_cw_create_cred_blob()
834
KHMEXP khm_int32 KHMAPI
835
khui_cw_destroy_cred_blob(khui_new_creds *c);
837
/*! \brief Lock the new_creds object
839
When a plugin is accessing the fields of a ::khui_new_creds
840
object, it must first obtain a lock on the object so that other
841
threads will not modify the fields at the same time. Locking the
842
object ensures that the fields of the object will be consistent.
844
Use khui_cw_unlock_nc() to undo the lock obtained through a call
845
to khui_cw_lock_nc().
847
It is not necessary to lock a new credentials object when
848
modifying it using the NetIDMgr API.
850
KHMEXP khm_int32 KHMAPI
851
khui_cw_lock_nc(khui_new_creds * c);
853
/*! \brief Unlock a new_creds object
855
\see khui_cw_lock_nc()
857
KHMEXP khm_int32 KHMAPI
858
khui_cw_unlock_nc(khui_new_creds * c);
860
/*! \brief Add a new panel to a new credentials acquisition window
862
See the description of ::khui_new_cred_panel for information on
863
how to populate it to describe a credentials type panel.
865
Note that the structure pointed to by \a t is added by reference.
866
The memory pointed to by \a t is not copied. Hence, the block of
867
memory and any other blocks pointed to by the
868
::khui_new_creds_by_type structure located there should remain
869
intact for the lifetime of the ::khui_new_creds structure pointed
870
to by \a c or until the credentials type panel is removed from the
871
::khui_new_creds structure with a call to khui_cw_del_type().
873
Generally, a plug-in that calls this function should allocate a
874
block of memory to contain the ::khui_new_creds_by_type structure,
875
fill it in and then pass in the address in a call to
876
khui_cw_add_type() while handling a ::KMSG_CRED_PASSWORD,
877
::KMSG_CRED_NEW_CREDS or ::KMSG_CRED_RENEW_CREDS message. Then
878
the plug-in should remove the reference with a call to
879
khui_cw_del_type() while processing ::KMSG_CRED_END.
881
\see khui_cw_del_type()
882
\see \ref cred_acq_panel_spec
883
\see ::khui_new_cred_panel
884
\see ::khui_new_creds
886
KHMEXP khm_int32 KHMAPI
887
khui_cw_add_type(khui_new_creds * c,
888
khui_new_creds_by_type * t);
890
/*! \brief Remove a panel from a new credentials acquisition window
892
\see khui_cw_add_type()
894
KHMEXP khm_int32 KHMAPI
895
khui_cw_del_type(khui_new_creds * c,
898
/*! \brief Find the panel belonging to a particular credentials type
900
This panel would have been added to the new credentials window
901
using khui_cw_add_type().
903
\see khui_cw_add_type()
905
KHMEXP khm_int32 KHMAPI
906
khui_cw_find_type(khui_new_creds * c,
908
khui_new_creds_by_type **t);
910
/*! \brief Enable/disable a particular credentials type
912
Enables or disables the panel associated with a particular
913
credentials type. Does not preclude the credentials type from
914
participating in the new credentials acquisition. However, the
915
user will be prevented from interacting with the specific panel.
917
KHMEXP khm_int32 KHMAPI
918
khui_cw_enable_type(khui_new_creds * c,
922
/*! \brief Set the primary identity in a new credentials acuisition
924
The primary identity dictates many of the defaults and the
925
semantics associated with the credentials acquision process.
926
Setting the primary identity also triggers the
927
::WMNC_IDENTITY_CHANGE notification which will be sent to all the
928
credentials type panels.
930
Has no effect if the primary identity is already the same as the
931
one specified in \a id. Specify NULL for \a id if the current
932
primary identity is to be cleared.
934
If the primary identity is changed, then all the additional
935
identities associated with the new credentials acquisition dialog
936
will also be discarded.
938
KHMEXP khm_int32 KHMAPI
939
khui_cw_set_primary_id(khui_new_creds * c,
942
/*! \brief Add an additional identity to the new credentials acquisition
944
Individual plugins are free to decide how to handle additional
945
identities. Generally, they would attempt to obtain credentials
946
for the primary and additional identities, but would not consider
947
it an error if an additional identity failed to obtain
950
Calling this function with \a id of NULL does nothing.
952
KHMEXP khm_int32 KHMAPI
953
khui_cw_add_identity(khui_new_creds * c,
956
/*! \brief Clear all custom prompts
958
Removes all the custom prompts from the new credentials dialog.
960
KHMEXP khm_int32 KHMAPI
961
khui_cw_clear_prompts(khui_new_creds * c);
963
/*! \brief Synchronize custom prompt values
965
It is important to synchronize the values before accessing their
966
values. The controls associated with custom prompts update the
967
values in the ::khui_new_creds object periodically. However, the
968
values may lose sync intermittently.
970
KHMEXP khm_int32 KHMAPI
971
khui_cw_sync_prompt_values(khui_new_creds * c);
973
/*! \brief Begin custom prompting
975
Begins the process of defining custom prompts. Implicity removes
976
all the custom prompts that are currently being displayed. The \a
977
banner and \a name will be displayed in separate controls above
978
the set of new custom prompts.
980
The controls associated with the prompts will not actually be
981
created until all the prompts have been added using
982
khui_cw_add_prompt(). The number of promtps that can be added
983
will be exactly \a n_prompts.
985
KHMEXP khm_int32 KHMAPI
986
khui_cw_begin_custom_prompts(khui_new_creds * c,
991
/*! \brief Add a custom prompt
993
After khui_cw_begin_custom_prompts() is called, the plugin should
994
call khui_cw_add_prompt() to add the actual prompts. The number
995
of prompts that can be added is the \a n_prompts value specified
996
in the earlier call to \a khui_cw_begin_custom_prompts().
998
Once \a n_prompts prompts have been added, the new prompts will
999
automatically be created and shown in the user interface.
1000
However, if less than that prompts are added, nothing is displayed
1003
\param[in] c Pointer to ::khui_new_creds structure
1005
\param[in] type Type of prompt. One of
1006
::KHUI_NCPROMPT_TYPE_PREAUTH, ::KHUI_NCPROMPT_TYPE_PASSWORD,
1007
::KHUI_NCPROMPT_TYPE_NEW_PASSWORD,
1008
::KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN
1010
\param[in] prompt Text of the prompt. Constrained by
1011
::KHUI_MAXCCH_PROMPT. (Localized, required)
1013
\param[in] def Default value. (optional). Constrained by
1014
::KHUI_MAXCCH_PROMPT_VALUE. Set to NULL if not provided.
1016
\param[in] flags Flags. Combination of
1017
::KHUI_NCPROMPT_FLAG_HIDDEN
1019
KHMEXP khm_int32 KHMAPI
1020
khui_cw_add_prompt(khui_new_creds * c,
1026
/*! \brief Retrieve a custom prompt
1028
Retrieves an individual prompt. The \a idx parameter is a
1029
zero-based index of the prompt to retrieve. The ordering is the
1030
same as the order in which khui_cw_add_prompt() was called.
1032
KHMEXP khm_int32 KHMAPI
1033
khui_cw_get_prompt(khui_new_creds * c,
1035
khui_new_creds_prompt ** prompt);
1037
/*! \brief Get the number of custom prompts
1039
Retrieves the number of custom prompts currently displayed. If
1040
this function is called between calling
1041
khui_cw_begin_custom_prompts() and adding all the prompts, the
1042
number returned will be the number of prompts that is expected to
1043
be registered (i.e. the \a n_prompts parameter passed to
1044
khui_cw_begin_custom_prompts()).
1046
KHMEXP khm_int32 KHMAPI
1047
khui_cw_get_prompt_count(khui_new_creds * c,
1051
/*! \brief Get the value of a custom prompt
1053
Retrieve the value of a specific prompt. The value is the string
1054
that was typed into the input control associated with a custom
1055
prompt. The \a idx parameter is the zero-based index of the
1056
prompt from which to retrieve the value from. The ordering is the
1057
same as the order in which khui_cw_add_prompt() was called.
1059
It is important to call khui_cw_sync_prompt_values() before
1060
starting to call khui_cw_get_prompt_value() so that the values
1061
returned are up-to-date.
1063
KHMEXP khm_int32 KHMAPI
1064
khui_cw_get_prompt_value(khui_new_creds * c,
1069
/*! \brief Set the response for a plugin
1071
When handling ::KMSG_CRED_DIALOG_PROCESS from within the plugin
1072
thread, it is important to set the response by calling this
1073
function. The response can be used to signal whether the plugin
1074
successfully obtained credentials or whether further interaction
1075
is required, or the credentials acquisition failed.
1077
The response is a combination of :
1078
- ::KHUI_NC_RESPONSE_PENDING
1079
- ::KHUI_NC_RESPONSE_FAILED
1080
- ::KHUI_NC_RESPONSE_PENDING
1081
- ::KHUI_NC_RESPONSE_SUCCESS
1082
- ::KHUI_NC_RESPONSE_NOEXIT
1083
- ::KHUI_NC_RESPONSE_EXIT
1085
KHMEXP khm_int32 KHMAPI
1086
khui_cw_set_response(khui_new_creds * c,
1088
khm_int32 response);
1090
/*! \brief Check whether a specified credential type panel succeeded
1092
This is called during the processing of ::KMSG_CRED_DIALOG_PROCESS
1093
to determine whether a specified credential type succeeded in
1094
obtaining credentials. The credential type that is being queried
1095
should have also been listed as a dependency when adding the
1096
current credentials type, otherwise the type queried may not have
1099
\return TRUE iff the queried type has reported that it successfully
1100
completed the credentials acquision operation.
1102
KHMEXP khm_boolean KHMAPI
1103
khui_cw_type_succeeded(khui_new_creds * c,
1106
/*! \brief Add a row of controls to the identity specifier area
1108
Only for use by identity provider callbacks that wish to add an
1109
identity selector control. A row of controls consist of a label
1110
control and some input control.
1112
When the ::WMNC_IDENT_INIT message is sent to the identity
1113
provider, it receives a handle to the dialog panel in the \a
1114
lParam parameter which should be the parent window of both the
1115
windows specified here. The control ID for any controls created
1116
must fall within the ::KHUI_CW_ID_MIN and ::KHUI_CW_ID_MAX range.
1118
Both controls will be resized to fit in the row.
1120
If \a long_label is TRUE then the size of the label will be larger
1121
than normal and will accomodate more text.
1123
KHMEXP khm_int32 KHMAPI
1124
khui_cw_add_control_row(khui_new_creds * c,
1127
khui_control_size size);
1129
/*!@}*/ /* Credentials acquisition */
added
removed
src/windows/identity/uilib/khnewcred.h
