/* * 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_KHNEWCRED_H #define __KHIMAIRA_KHNEWCRED_H /******************************************************************** New credentials windows *********************************************************************/ /*! \addtogroup khui @{ */ /*! \defgroup khui_cred Credentials acquisition Declarations associated with credentials acquisition. @{ */ /*! \brief Window message sent to credentials type panels This message is sent to the child windows. The format of the message is : - uMsg : KHUI_WM_NC_NOTIFY - HIWORD(wParam) : one of ::khui_wm_nc_notifications - LPARAM : pointer to the ::khui_new_creds structure (except where noted) */ #define KHUI_WM_NC_NOTIFY (WM_APP + 0x101) /*! \brief The first control ID that may be used by an identity provider */ #define KHUI_CW_ID_MIN 8016 /*! \brief The maximum number of controls that may be created by an identity provider*/ #define KHUI_CW_MAX_CTRLS 8 /*! \brief The maximum control ID that may be used by an identity provider */ #define KHUI_CW_ID_MAX (KHUI_CW_ID_MIN + KHUI_CW_MAX_CTRLS - 1) /*! \brief Credentials dialog notifications These notifications will be sent to the individual dialog procedures of the credential type panels or to the new credentials window as a ::KHUI_WM_NC_NOTIFY message. */ enum khui_wm_nc_notifications { WMNC_DIALOG_EXPAND = 1, /*!< The dialog is switching from basic to advanced mode or vice versa. In expanded mode, all credentials type panels are visible as opposed to the compressed mode where they are not visible. The message is not sent to credentials type panels. Only sent to the new credentials window. */ WMNC_DIALOG_SETUP, /*!< Sent to the new creds window to notify it that the dialog should create all the type configuration panels. Until this message is issued, none of the credentials type panels exist. The credentials type panels will receive WM_INITDIALOG etc as per the normal dialog creation process. Only sent to the new credentials window. */ WMNC_DIALOG_ACTIVATE, /*!< Sent to the new creds window to notify it that the dialog should do final initialization work and activate. Only sent to the new credentials window. */ WMNC_DIALOG_MOVE, /*!< The new credentials window has moved. This message is sent to all the credentials type panels when the new credentials window is being moved. It will be sent continuously if the user is dragging the window. Plug-ins rarely need to know their position on the screen. However, if there are any other windows that were created by the plug-in, such as floating controls or tooltips, they may need to be repositioned in response to this message. Sent to all the credentials type panels. */ WMNC_DIALOG_SWITCH_PANEL, /*!< Sent to the new creds window to cause it to switch to the panel identified by LOWORD(wParam). Does nothing if the specified panel is already the current panel. If the dialog is in compact mode and making the specified panel visible requires switching to expanded mode, the dialog will do so. Only sent to the new credentials window. */ WMNC_UPDATE_CREDTEXT, /*!< Update the credentials text associated with a panel. During the new credentials operation, each plug-in is expected to maintain a textual representation of the credentials that the plug-in expects to obtain for the selected identity. It can, alternatively, be used to indicate the state of the credentials type in respect to the selected identity (for example, whether the credentials type is disabled for the identity and why). This text is not visible when the new credentials window is in basic mode, but it is visible when the window is in advanced mode. The following image shows the expanded new credentials window including the credentials text from a several plug-ins: \image html new_creds_expanded.png Once this message is received, each plug-in should construct its credentials text string and store it in the \c credtext member of its ::khui_new_creds_by_type structure as shown in the sample code below: \code // Handler for window message WM_NC_NOTIFY with // HWND hwnd, WPARAM wParam and LPARAM lParam // This structure holds the dialog data for the panel. We // assume it has 'nc' and 'nct' fields that point to the // khui_new_creds and khui_new_creds_by_type structures // respectively. ... struct nc_dialog_data * d; ... // Retrieve the data structure from the dialog user data. d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER); switch (HIWORD(wParam)) { case WMNC_UPDATE_CREDTEXT: { wchar_t buffer[KHUI_MAXCCH_LONG_DESC]; size_t cb_size; // we are being requested to update the credentials text. We // already allocated a buffer when we created the nct // structure. So we can just set the text here. // The credentials text should reflect the credentials that // will be obtained when the new credentials operation // completes. assert(d && d->nc && d->nct); if (d->nct->credtext) { free(d->nct->credtext); d->nct->credtext = NULL; } // We only display something if there is a selected identity if (d->nc->n_identities > 0) { StringCbPrintf(buffer, sizeof(buffer), L"<p>My Credentials<tab>: %s</p>", get_credential_name(d)); StringCbLength(buffer, sizeof(buffer), &cb_size); cb_size += sizeof(wchar_t); // account for the terminating NULL d->nct->credtext = malloc(cb_size); if (d->nct->credtext) { StringCbCopy(d->nct->credtext, cb_size, buffer); } } break; } ... // Handler other notifications } \endcode The text that is specified as the credentials text is formatted hypertext. For more information about support for formatting and hypertext and handling hyperlinks, see \ref khui_htwnd. \note When this message is sent to the new credentials window, the application will send the ::WMNC_UPDATE_CREDTEXT message to all the credential type panels and update the credential text window. */ WMNC_CREDTEXT_LINK, /*!< A hyperlink was activated. Sent to a panel dialog procedure when a user clicks an embedded link in the credentials text that belongs to that panel. The \a lParam parameter of the message is a pointer to a ::khui_htwnd_link structure describing the link. \see \ref khui_htwnd \note The \a lParam parameter does not point to a ::khui_new_creds structure for this message. */ WMNC_IDENTITY_CHANGE, /*!< The primary identity has changed. The ::khui_new_creds structure contains a list of identities to which the current operation should be applied. In its current implementation, only the first identity in this list is used. Therefore, the list will contain at most one identity. It is possible for the list to be empty (for example, if the user hasn't selected an identity yet). When handling this notification, the plug-in should check the \c n_identities member of the ::khui_new_creds structure to see whether there are any identities selected. This value would be either zero or one. If it is non-zero, then a handle to the selected identity will be in \c khui_new_creds::identities[0]. Plug-ins typically use this notfication to load identity specific settings when a new identity is selected. This notification is sent to all the credentials type panels. */ WMNC_CLEAR_PROMPTS, /*!< Sent to the new creds window to clear any custom prompts. Only sent to the new credentials window. */ WMNC_SET_PROMPTS, /*!< Sent to the new creds window to set custom prompts. Only sent to the new credentials window. */ WMNC_DIALOG_PREPROCESS, /*!< The credentials acquisition process is about to start. Sent to all the credentials type panels to notify them that the credentials acquisition process will start. Once all plug-ins have handled the notification, the application will start sending out <::KMSG_CRED, ::KMSG_CRED_PROCESS> messages to the credentials providers which are participating in the new credentials operation. */ WMNC_DIALOG_PROCESS, /*!< This notification is no longer used. */ #pragma deprecated(WMNC_DIALOG_PROCESS) WMNC_DIALOG_PROCESS_COMPLETE, /*!< Sent to the new creds window to indicate that the all the threads have completed processing.*/ WMNC_TYPE_STATE, /*!< Sent to the new creds window as notification that a particular credentials type has changed state from enabled to disabled or vice versa. The LPARAM member of the message specifies the credentials type identifier for the changed type */ WMNC_ADD_CONTROL_ROW, /*!< Add a row of controls to a new cred dialog. This is an internal message. */ WMNC_UPDATE_LAYOUT, /*!< Update the layout of a dialog or window. This is an internal message. */ }; /*! \brief Plugins can use WMNC_NOTIFY message codes from here on up \see ::KHUI_WM_NC_NOTIFY */ #define WMNC_USER 2048 /*! \brief Notifications to the identity provider These notifications are sent through to the identity provider's UI callback that was obtained using a ::KMSG_IDENT_GET_UI_CB message. The callback routine is called from the context of the UI thread and is expected to not make any blocking calls. One of the following commands will be passed in as the \a cmd parameter to the callback. */ enum khui_wm_nc_ident_notify { WMNC_IDENT_INIT, /*!< Initialize an identity selector for a new credentials dialog. The \a lParam parameter contains a handle to the dialog window which will contain the identity selector controls. The identity provider may make use of the \a ident_aux field of the ::khui_new_creds structure to hold any data pertaining to the credentials acquisition dialog.*/ WMNC_IDENT_WMSG, /*!< Windows message. Presumably sent from one of the controls that was created by the identity provider. The callback is expected to return TRUE if it processed the message or FALSE if it did not. The \a uMsg, \a wParam and \a lParam parameters are set to the values passed in by Windows. */ WMNC_IDENT_EXIT, /*!< Terminate a credentials acquisition dialog. Sent just before the dialog is terminated. */ WMNC_IDENT_PREPROCESS, /*!< The identity is about to be fetched from the \a ::khui_new_creds structure. The callback is expected to ensure that the primary identity listed in that structure is consistent with the user selection. */ }; /*! \name Standard credtext link IDs @{*/ /*! \brief Switch the panel The \a id attribute of the link specifies the ordinal of the panel to switch to. */ #define CTLINKID_SWITCH_PANEL L"SwitchPanel" /*@}*/ /*forward dcl*/ struct tag_khui_new_creds_by_type; typedef struct tag_khui_new_creds_by_type khui_new_creds_by_type; struct tag_khui_new_creds_prompt; typedef struct tag_khui_new_creds_prompt khui_new_creds_prompt; struct tag_khui_new_creds; typedef struct tag_khui_new_creds khui_new_creds; typedef LRESULT (KHMAPI *khui_ident_new_creds_cb)(khui_new_creds * nc, UINT cmd, HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam); /*! \brief New credentials acquisition blob A pointer to an object of this type is passed in along with the credentials acquisition messages. \see \ref cred_acq for more information */ typedef struct tag_khui_new_creds { khm_int32 magic; /*!< Internal use */ khm_int32 subtype; /*!< Subtype of the request that is being handled through this object. One of ::KMSG_CRED_NEW_CREDS, ::KMSG_CRED_RENEW_CREDS or ::KMSG_CRED_PASSWORD */ CRITICAL_SECTION cs; /*!< Internal use */ khm_boolean set_default; /*!< After a successfull credentials acquisition, set the primary identity as the default. */ khm_handle *identities; /*!< The list of identities associated with this request. The first identity in this list (\a identities[0]) is the primary identity. */ khm_size n_identities; /*!< Number of identities in the list \a identities */ khm_size nc_identities; /*!< Internal use */ khui_action_context ctx; /*!< An action context specifying the context in which the credentials acquisition operation was launced. */ khm_int32 mode; /*!< The mode of the user interface. One of ::KHUI_NC_MODE_MINI or ::KHUI_NC_MODE_EXPANDED. */ HWND hwnd; /*!< Handle to the new credentials window. */ struct tag_khui_new_creds_by_type **types; /*!< Internal use */ khm_handle *type_subs; /*!< Internal use */ khm_size n_types; /*!< Internal use */ khm_size nc_types; /*!< Internal use */ khm_int32 result; /*!< One of ::KHUI_NC_RESULT_CANCEL or ::KHUI_NC_RESULT_PROCESS indicating the result of the dialog with the user */ khm_int32 response; /*!< Response. See individual message documentation for info on what to do with this field */ wchar_t *password; /*!< Not used. */ /* UI stuff */ wchar_t *banner; /*!< Internal use */ wchar_t *pname; /*!< Internal use */ khm_size n_prompts; /*!< Internal use */ khm_size nc_prompts; /*!< Internal use */ struct tag_khui_new_creds_prompt ** prompts; /*!< Internal use */ khui_ident_new_creds_cb ident_cb; /*!< Internal use */ wchar_t *window_title; /*!< Internal use */ LPARAM ident_aux; /*!< Auxilliary field which is reserved for use by the identity provider during the course of conducting this dialog. */ } khui_new_creds; #define KHUI_NC_MAGIC 0x84270427 /*!\name Result values for khui_new_creds_t::result @{*/ #define KHUI_NC_RESULT_PROCESS 0 #define KHUI_NC_RESULT_CANCEL 1 /*@}*/ /*!\name Mode values for khui_new_creds_t::mode @{*/ #define KHUI_NC_MODE_MINI 0 #define KHUI_NC_MODE_EXPANDED 1 /*@}*/ /*!\name Response values for khui_new_creds_t::response @{*/ /*!\brief No known response */ #define KHUI_NC_RESPONSE_NONE 0 /*!\brief It is okay to exit the dialog now This is the default, which is why it has a value of zero. In order to prevent the dialog from exiting, set the KHUI_NC_RESPONSE_NOEXIT response bit. */ #define KHUI_NC_RESPONSE_EXIT 0 /*!\brief It is NOT okay to exit the dialog now Used to indicate that further user-interaction is necessary to process the dialog. Usually this is accompanied by setting necessary custom prompts and notifications so the user knows why the dialog is prompting for more information. */ #define KHUI_NC_RESPONSE_NOEXIT 0x00000002 /*!\brief The dialog was processed successfully Since this is the default response, the value is zero. Use one of KHUI_NC_RESPONSE_FAILED or KHUI_NC_RESPONSE_PENDING to indicate an error or pending status. */ #define KHUI_NC_RESPONSE_SUCCESS 0 /*!\brief The processing of the dialog failed Self explanatory. More information about the failure should have been reported using the khlog API, however, this response value indicates to other credential types that depend on this credential type that whatever it was that this credential type was supposed to do didn't happen. */ #define KHUI_NC_RESPONSE_FAILED 0x00000008 /*!\brief Further interaction required Set along with KHUI_NC_RESPONSE_NOEXIT although it is not required. Setting this bit will automatically add the KHUI_NC_RESPONSE_NOEXIT. If this bit is set, all dependent plugins will be set on hold until another round of processing clears the pending bit. */ #define KHUI_NC_RESPONSE_PENDING 0x00000010 /*! \brief Completed This is automatically set if the plugin sets a response which does not indicate either KHUI_NC_RESPONSE_NOEXIT or KHUI_NC_RESPONSE_PENDING, which is considered to mean that the plugin is completed processing. This flag cannot be explicitly specified in a response. */ #define KHUI_NC_RESPONSE_COMPLETED 0x00000020 /*! \brief Processing This is an internal flag set while the credentials acquisition process is executing. */ #define KHUI_NC_RESPONSE_PROCESSING 0x00010000 #define KHUI_NCMASK_RESPONSE (KHUI_NC_RESPONSE_EXIT|KHUI_NC_RESPONSE_NOEXIT) #define KHUI_NCMASK_RESULT (KHUI_NC_RESPONSE_SUCCESS|KHUI_NC_RESPONSE_FAILED|KHUI_NC_RESPONSE_PENDING) /*@}*/ /*!\brief Maximum number of dependencies for a credentials type */ #define KHUI_MAX_TYPE_DEPS 8 /*!\brief Maximum number of credential types for a new creds window */ #define KHUI_MAX_NCTYPES 16 /*!\brief Maximum number of characters in a password Length includes the termininating NULL */ #define KHUI_MAXCCH_PASSWORD 512 /*! \brief Maximum number of bytes in a password Includes terminating NULL */ #define KHUI_MAXCB_PASSWORD (KHUI_MAXCCH_PASSWORD * sizeof(wchar_t)) /*! \brief Maximum number of characters in a custom banner Length includes terminating NULL */ #define KHUI_MAXCCH_BANNER 256 /*! \brief Maximum number of bytes in a custom banner Length includes terminating NULL */ #define KHUI_MAXCB_BANNER (KHUI_MAXCCH_BANNER * sizeof(wchar_t)) /*! \brief Maximum number of characters in a panel name Length includes terminating NULL */ #define KHUI_MAXCCH_PNAME 256 /*! \brief Maximum number of bytes in a panel name Length includes terminating NULL */ #define KHUI_MAXCB_PNAME (KHUI_MAXCCH_PNAME * sizeof(wchar_t)) /*! \brief A descriptor of a panel in the new credentials acquisition tab When processing certain credentials messages such as ::KMSG_CRED_PASSWORD, ::KMSG_CRED_NEW_CREDS, ::KMSG_CRED_RENEW_CREDS, a pointer to a ::khui_new_creds structure will be passed in to the message handler. If the handler of the message needs to add one or more credentials types as participants of the operation, the handler will need to call khui_cw_add_type() and specify a ::khui_new_creds_by_type structure. Note that the memory address passed in to the call to khui_cw_add_type() will not be copied. Therefore, the block of memory should remain as-is for the lifetime of the ::khui_new_creds structure or until it is removed with a call to khui_cw_del_type(). Some of the credentials messages that require specifying a ::khui_new_creds_by_type structure require providing a user-interface. In these cases, the fields marked for providing a UI may be required to hold valid values. If the message does not require providing a UI, these fields will be ignored. */ typedef struct tag_khui_new_creds_by_type { khui_new_creds * nc; /*!< Internal use. Do not set */ khm_int32 flags; /*!< Internal use. Do not set */ khm_int32 type; /*!< The identifier of the credentials type. This is a credentials type identifier allocated with a call to kcdb_credtype_register(). */ khm_int32 type_deps[KHUI_MAX_TYPE_DEPS]; /*!< credentials types that this credential type depends on. Each element defines a credentials type identifier that this type depends on for this operation. The number of valid values in this array should be specified in the \a n_type_deps field. */ khm_size n_type_deps; /*!< Number of dependencies listed above. Should be between 0 and ::KHUI_MAX_TYPE_DEPS. Specify 0 if there are no dependencies. */ khm_size ordinal; /*!< The requested ordinal. The UI would attempt to place this panel at the reqested order in the list of panels. Set to -1 if the order does not matter. Once the dialog is activated this field will be updated to reflect the actual ordinal of the panel. */ wchar_t *name; /*!< Name of the panel (localized, optional). If NULL, the localized name of the credentials type is used. Only used if providing a user-interface. */ HICON icon; /*!< Icon for the panel (optional). Only used if providing a user-interface. */ wchar_t *tooltip; /*!< Tooltip for the panel (localized, optional). If NULL, no tooltip will be assigned for the panel. Only used if providing a user-interface. */ HMODULE h_module; /*!< Handle to the module containing the dialog resource. Only used if providing a user-interface. */ LPWSTR dlg_template; /*!< The dialog resource. Only used if providing a user-interface. */ DLGPROC dlg_proc; /*!< The dialog procedure. Only used if providing a user-interface. */ HWND hwnd_panel; /*!< The dialog window. Once the dialog panel is created, a handle to the panel will be assigned here. Note that the handle is assigned after a successful call to CreateDialogParam and hence would not be available when handling the WM_INITDIALOG message from the dialog procedure. Only used of providing a user-interface. */ HWND hwnd_tc; /*!< Internal use. Do not set */ wchar_t *credtext; /*!< A brief description of the current state of this cred type. (localized, optional). Only used if providing a user-interface. If this field is non-NULL, then it should point to a NULL terminated string that does not exceed ::KHUI_MAXCCH_LONG_DESC characters in length including the terminating NULL. \see \ref khui_htwnd for information on how to format the string for this field. */ LPARAM aux; /*!< auxilliary field. For use by the plug-in. */ } khui_new_creds_by_type; /*!\name Flags for khui_new_creds_by_type Note that KHUI_NC_RESPONSE_SUCCESS, KHUI_NC_RESPONSE_FAILED, KHUI_NC_RESPONSE_PENDING are also stored in the flags. @{*/ #define KHUI_NCT_FLAG_PROCESSED 1024 #define KHUI_NCT_FLAG_DISABLED 2048 /*@}*/ /*! \brief Width of a new creds dialog panel in dialog units*/ #define NCDLG_WIDTH 300 /*! \brief Height of a new creds dialog panel in dialog units*/ #define NCDLG_HEIGHT 166 /*! \brief A custom prompt */ typedef struct tag_khui_new_creds_prompt { khm_size index; /*!< Set to the zero based index of this prompt. */ khm_int32 type; /*!< one of KHUI_NCPROMPT_TYPE_* */ wchar_t * prompt; /*!< prompt string. Cannot exceed KHUI_MAXCCH_PROMPT */ wchar_t * def; /*!< default value. Cannot exceed KHUI_MAXCCH_PROMPT_VALUE */ wchar_t * value; /*!< On completion, this is set to the value that the user entered. Will not exceed KHUI_MAXCCH_PROMPT_VALUE */ khm_int32 flags; /*!< Combination of KHUI_NCPROMPT_FLAG_* */ HWND hwnd_static; /* internal use */ HWND hwnd_edit; /* internal use */ } khui_new_creds_prompt; /*! \brief The prompt input is hidden The input is hidden for prompts which accept passwords. The control which represents the input will display an asterisk or a small circle corresponding to each character typed in, but will not show the actual character. */ #define KHUI_NCPROMPT_FLAG_HIDDEN 1 /*! \brief Internal use */ #define KHUI_NCPROMPT_FLAG_STOCK 2 /*! \brief Maximum number of characters in a prompt Refers to the prompt text that accompanies an input control. THe length includes the terminating NULL. */ #define KHUI_MAXCCH_PROMPT 256 /*! \brief Maximum number of bytes in a prompt Refers to the prompt text that accompanies an input control. THe length includes the terminating NULL. */ #define KHUI_MAXCB_PROMPT (KHUI_MAXCCH_PROMPT * sizeof(wchar_t)) /*! \brief Maximum number of characters that can be entered in an input control Refers to the input control of a prompt. The length includes the terminating NULL. */ #define KHUI_MAXCCH_PROMPT_VALUE 256 /*! \brief Maximum number of bytes that can be entered in an input control Refers to the input control of a prompt. The length includes the terminating NULL. */ #define KHUI_MAXCB_PROMPT_VALUE (KHUI_MAXCCH_PROMPT_VALUE * sizeof(wchar_t)) /* from krb5.h. Redefining here because we don't want to depend on krb5.h for all credential types */ /*! \brief A password control */ #define KHUI_NCPROMPT_TYPE_PASSWORD 1 /*! \brief New password control Used when changing the password */ #define KHUI_NCPROMPT_TYPE_NEW_PASSWORD 2 /*! \brief New password again control Used when changing the password */ #define KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN 3 /*! \brief Preauthentication (reserved) */ #define KHUI_NCPROMPT_TYPE_PREAUTH 4 /*! \brief Control sizes */ typedef enum tag_khui_control_size { KHUI_CTRLSIZE_SMALL, /*!< A small control fits in about 1/5 the width of the new credentials panel */ KHUI_CTRLSIZE_HALF, /*!< Half size controls fit in 1/2 the width of the new credentials panel */ KHUI_CTRLSIZE_FULL, /*!< Takes up the whole width of the crednetials panel */ } khui_control_size; /*! \brief Internal use */ typedef struct tag_khui_control_row { HWND label; HWND input; khui_control_size size; } khui_control_row; /*! \brief Create a ::khui_new_creds object Creates and initializes a ::khui_new_creds object. The created object must be destroyed using the khui_cw_destroy_cred_blob() function. \note Plugins should not call this function directly. The necessary ::khui_new_creds objects will be created by NetIDMgr. \see khui_cw_destroy_cred_blob() */ KHMEXP khm_int32 KHMAPI khui_cw_create_cred_blob(khui_new_creds ** c); /*! \brief Destroy a ::khui_new_creds object Destroys a ::khui_new_creds object that was fomerly created using a call to khui_cw_create_cred_blob(). \note Plugins should not call this function directly. The necessary ::khui_new_creds objects will be created by NetIDMgr. \see khui_cw_create_cred_blob() */ KHMEXP khm_int32 KHMAPI khui_cw_destroy_cred_blob(khui_new_creds *c); /*! \brief Lock the new_creds object When a plugin is accessing the fields of a ::khui_new_creds object, it must first obtain a lock on the object so that other threads will not modify the fields at the same time. Locking the object ensures that the fields of the object will be consistent. Use khui_cw_unlock_nc() to undo the lock obtained through a call to khui_cw_lock_nc(). It is not necessary to lock a new credentials object when modifying it using the NetIDMgr API. */ KHMEXP khm_int32 KHMAPI khui_cw_lock_nc(khui_new_creds * c); /*! \brief Unlock a new_creds object \see khui_cw_lock_nc() */ KHMEXP khm_int32 KHMAPI khui_cw_unlock_nc(khui_new_creds * c); /*! \brief Add a new panel to a new credentials acquisition window See the description of ::khui_new_cred_panel for information on how to populate it to describe a credentials type panel. Note that the structure pointed to by \a t is added by reference. The memory pointed to by \a t is not copied. Hence, the block of memory and any other blocks pointed to by the ::khui_new_creds_by_type structure located there should remain intact for the lifetime of the ::khui_new_creds structure pointed to by \a c or until the credentials type panel is removed from the ::khui_new_creds structure with a call to khui_cw_del_type(). Generally, a plug-in that calls this function should allocate a block of memory to contain the ::khui_new_creds_by_type structure, fill it in and then pass in the address in a call to khui_cw_add_type() while handling a ::KMSG_CRED_PASSWORD, ::KMSG_CRED_NEW_CREDS or ::KMSG_CRED_RENEW_CREDS message. Then the plug-in should remove the reference with a call to khui_cw_del_type() while processing ::KMSG_CRED_END. \see khui_cw_del_type() \see \ref cred_acq_panel_spec \see ::khui_new_cred_panel \see ::khui_new_creds */ KHMEXP khm_int32 KHMAPI khui_cw_add_type(khui_new_creds * c, khui_new_creds_by_type * t); /*! \brief Remove a panel from a new credentials acquisition window \see khui_cw_add_type() */ KHMEXP khm_int32 KHMAPI khui_cw_del_type(khui_new_creds * c, khm_int32 type); /*! \brief Find the panel belonging to a particular credentials type This panel would have been added to the new credentials window using khui_cw_add_type(). \see khui_cw_add_type() */ KHMEXP khm_int32 KHMAPI khui_cw_find_type(khui_new_creds * c, khm_int32 type, khui_new_creds_by_type **t); /*! \brief Enable/disable a particular credentials type Enables or disables the panel associated with a particular credentials type. Does not preclude the credentials type from participating in the new credentials acquisition. However, the user will be prevented from interacting with the specific panel. */ KHMEXP khm_int32 KHMAPI khui_cw_enable_type(khui_new_creds * c, khm_int32 type, khm_boolean enable); /*! \brief Set the primary identity in a new credentials acuisition The primary identity dictates many of the defaults and the semantics associated with the credentials acquision process. Setting the primary identity also triggers the ::WMNC_IDENTITY_CHANGE notification which will be sent to all the credentials type panels. Has no effect if the primary identity is already the same as the one specified in \a id. Specify NULL for \a id if the current primary identity is to be cleared. If the primary identity is changed, then all the additional identities associated with the new credentials acquisition dialog will also be discarded. */ KHMEXP khm_int32 KHMAPI khui_cw_set_primary_id(khui_new_creds * c, khm_handle id); /*! \brief Add an additional identity to the new credentials acquisition Individual plugins are free to decide how to handle additional identities. Generally, they would attempt to obtain credentials for the primary and additional identities, but would not consider it an error if an additional identity failed to obtain credentials. Calling this function with \a id of NULL does nothing. */ KHMEXP khm_int32 KHMAPI khui_cw_add_identity(khui_new_creds * c, khm_handle id); /*! \brief Clear all custom prompts Removes all the custom prompts from the new credentials dialog. */ KHMEXP khm_int32 KHMAPI khui_cw_clear_prompts(khui_new_creds * c); /*! \brief Synchronize custom prompt values It is important to synchronize the values before accessing their values. The controls associated with custom prompts update the values in the ::khui_new_creds object periodically. However, the values may lose sync intermittently. */ KHMEXP khm_int32 KHMAPI khui_cw_sync_prompt_values(khui_new_creds * c); /*! \brief Begin custom prompting Begins the process of defining custom prompts. Implicity removes all the custom prompts that are currently being displayed. The \a banner and \a name will be displayed in separate controls above the set of new custom prompts. The controls associated with the prompts will not actually be created until all the prompts have been added using khui_cw_add_prompt(). The number of promtps that can be added will be exactly \a n_prompts. */ KHMEXP khm_int32 KHMAPI khui_cw_begin_custom_prompts(khui_new_creds * c, khm_size n_prompts, wchar_t * banner, wchar_t * name); /*! \brief Add a custom prompt After khui_cw_begin_custom_prompts() is called, the plugin should call khui_cw_add_prompt() to add the actual prompts. The number of prompts that can be added is the \a n_prompts value specified in the earlier call to \a khui_cw_begin_custom_prompts(). Once \a n_prompts prompts have been added, the new prompts will automatically be created and shown in the user interface. However, if less than that prompts are added, nothing is displayed to the user. \param[in] c Pointer to ::khui_new_creds structure \param[in] type Type of prompt. One of ::KHUI_NCPROMPT_TYPE_PREAUTH, ::KHUI_NCPROMPT_TYPE_PASSWORD, ::KHUI_NCPROMPT_TYPE_NEW_PASSWORD, ::KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN \param[in] prompt Text of the prompt. Constrained by ::KHUI_MAXCCH_PROMPT. (Localized, required) \param[in] def Default value. (optional). Constrained by ::KHUI_MAXCCH_PROMPT_VALUE. Set to NULL if not provided. \param[in] flags Flags. Combination of ::KHUI_NCPROMPT_FLAG_HIDDEN */ KHMEXP khm_int32 KHMAPI khui_cw_add_prompt(khui_new_creds * c, khm_int32 type, wchar_t * prompt, wchar_t * def, khm_int32 flags); /*! \brief Retrieve a custom prompt Retrieves an individual prompt. The \a idx parameter is a zero-based index of the prompt to retrieve. The ordering is the same as the order in which khui_cw_add_prompt() was called. */ KHMEXP khm_int32 KHMAPI khui_cw_get_prompt(khui_new_creds * c, khm_size idx, khui_new_creds_prompt ** prompt); /*! \brief Get the number of custom prompts Retrieves the number of custom prompts currently displayed. If this function is called between calling khui_cw_begin_custom_prompts() and adding all the prompts, the number returned will be the number of prompts that is expected to be registered (i.e. the \a n_prompts parameter passed to khui_cw_begin_custom_prompts()). */ KHMEXP khm_int32 KHMAPI khui_cw_get_prompt_count(khui_new_creds * c, khm_size * np); /*! \brief Get the value of a custom prompt Retrieve the value of a specific prompt. The value is the string that was typed into the input control associated with a custom prompt. The \a idx parameter is the zero-based index of the prompt from which to retrieve the value from. The ordering is the same as the order in which khui_cw_add_prompt() was called. It is important to call khui_cw_sync_prompt_values() before starting to call khui_cw_get_prompt_value() so that the values returned are up-to-date. */ KHMEXP khm_int32 KHMAPI khui_cw_get_prompt_value(khui_new_creds * c, khm_size idx, wchar_t * buf, khm_size *cbbuf); /*! \brief Set the response for a plugin When handling ::KMSG_CRED_DIALOG_PROCESS from within the plugin thread, it is important to set the response by calling this function. The response can be used to signal whether the plugin successfully obtained credentials or whether further interaction is required, or the credentials acquisition failed. The response is a combination of : - ::KHUI_NC_RESPONSE_PENDING - ::KHUI_NC_RESPONSE_FAILED - ::KHUI_NC_RESPONSE_PENDING - ::KHUI_NC_RESPONSE_SUCCESS - ::KHUI_NC_RESPONSE_NOEXIT - ::KHUI_NC_RESPONSE_EXIT */ KHMEXP khm_int32 KHMAPI khui_cw_set_response(khui_new_creds * c, khm_int32 type, khm_int32 response); /*! \brief Check whether a specified credential type panel succeeded This is called during the processing of ::KMSG_CRED_DIALOG_PROCESS to determine whether a specified credential type succeeded in obtaining credentials. The credential type that is being queried should have also been listed as a dependency when adding the current credentials type, otherwise the type queried may not have been invoked yet. \return TRUE iff the queried type has reported that it successfully completed the credentials acquision operation. */ KHMEXP khm_boolean KHMAPI khui_cw_type_succeeded(khui_new_creds * c, khm_int32 type); /*! \brief Add a row of controls to the identity specifier area Only for use by identity provider callbacks that wish to add an identity selector control. A row of controls consist of a label control and some input control. When the ::WMNC_IDENT_INIT message is sent to the identity provider, it receives a handle to the dialog panel in the \a lParam parameter which should be the parent window of both the windows specified here. The control ID for any controls created must fall within the ::KHUI_CW_ID_MIN and ::KHUI_CW_ID_MAX range. Both controls will be resized to fit in the row. If \a long_label is TRUE then the size of the label will be larger than normal and will accomodate more text. */ KHMEXP khm_int32 KHMAPI khui_cw_add_control_row(khui_new_creds * c, HWND label, HWND input, khui_control_size size); /*!@}*/ /* Credentials acquisition */ /*!@}*/ #endif