Alerter and Error Reporting
[User Interface]


Data Structures

struct  tag_khui_alert

Defines

#define KHUI_ALERT_MAGIC   0x48c39ce9
#define KHUI_MAX_ALERT_COMMANDS   4
#define KHUI_MAXCCH_TITLE   256
 Maximum number of characters in title including terminating NULL.
#define KHUI_MAXCB_TITLE   (KHUI_MAXCCH_TITLE * sizeof(wchar_t))
 Maximum number of bytes in title including terminating NULL.
#define KHUI_MAXCCH_MESSAGE   1024
 Maximum number of characters in message including terminating NULL.
#define KHUI_MAXCB_MESSAGE   (KHUI_MAXCCH_MESSAGE * sizeof(wchar_t))
 Maximum number of bytes in message including terminating NULL.
#define KHUI_MAXCCH_SUGGESTION   1024
 Maxumum number of characters in a suggestion including terminating NULL.
#define KHUI_MAXCB_SUGGESTION   (KHUI_MAXCCH_SUGGESTION * sizeof(wchar_t))
 Maximum number of bytes in a suggestion, including terminating NULL.

Typedefs

typedef tag_khui_alert khui_alert
typedef tag_khui_alert khui_alert
typedef enum tag_khui_alert_types khui_alert_type
 Alert types.

Enumerations

enum  khui_alert_flags {
  KHUI_ALERT_FLAG_FREE_STRUCT = 0x00000001, KHUI_ALERT_FLAG_FREE_TITLE = 0x00000002, KHUI_ALERT_FLAG_FREE_MESSAGE = 0x00000004, KHUI_ALERT_FLAG_FREE_SUGGEST = 0x00000008,
  KHUI_ALERT_FLAG_DEFACTION = 0x00000010, KHUI_ALERT_FLAG_DISPATCH_CMD = 0x00000020, KHUI_ALERT_FLAG_VALID_TARGET = 0x00010000, KHUI_ALERT_FLAG_VALID_ERROR = 0x00020000,
  KHUI_ALERT_FLAG_DISPLAY_WINDOW = 0x01000000, KHUI_ALERT_FLAG_DISPLAY_BALLOON = 0x02000000, KHUI_ALERT_FLAG_REQUEST_WINDOW = 0x04000000, KHUI_ALERT_FLAG_REQUEST_BALLOON = 0x08000000,
  KHUI_ALERT_FLAG_MODAL = 0x10000000, KHUI_ALERT_FLAGMASK_RDWR = 0x0C000030
}
 Flags for an alert. More...
enum  tag_khui_alert_types {
  KHUI_ALERTTYPE_NONE = 0, KHUI_ALERTTYPE_PLUGIN, KHUI_ALERTTYPE_EXPIRE, KHUI_ALERTTYPE_RENEWFAIL,
  KHUI_ALERTTYPE_ACQUIREFAIL, KHUI_ALERTTYPE_CHPW
}
 Alert types. More...

Functions

KHMEXP khm_int32 KHMAPI khui_alert_create_empty (khui_alert **result)
 Create an empty alert object.
KHMEXP khm_int32 KHMAPI khui_alert_create_simple (const wchar_t *title, const wchar_t *message, khm_int32 severity, khui_alert **result)
 Create a simple alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_title (khui_alert *alert, const wchar_t *title)
 Set the title of an alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_message (khui_alert *alert, const wchar_t *message)
 Set the message of an alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_suggestion (khui_alert *alert, const wchar_t *suggestion)
 Set the suggestion of an alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_severity (khui_alert *alert, khm_int32 severity)
 Set the severity of the alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_flags (khui_alert *alert, khm_int32 mask, khm_int32 flags)
 Sets the flags of the alert.
KHMEXP khm_int32 KHMAPI khui_alert_clear_commands (khui_alert *alert)
 Clear all the commands from an alert object.
KHMEXP khm_int32 KHMAPI khui_alert_add_command (khui_alert *alert, khm_int32 command_id)
 Add a command to an alert object.
KHMEXP khm_int32 KHMAPI khui_alert_set_type (khui_alert *alert, khui_alert_type type)
 Set the type of alert.
KHMEXP khm_int32 KHMAPI khui_alert_set_ctx (khui_alert *alert, khui_scope scope, khm_handle identity, khm_int32 cred_type, khm_handle cred)
 Set the action context for the alert.
KHMEXP khm_int32 KHMAPI khui_alert_get_response (khui_alert *alert)
 Get the response code from an alert.
KHMEXP khm_int32 KHMAPI khui_alert_show (khui_alert *alert)
 Display an alert.
KHMEXP khm_int32 KHMAPI khui_alert_show_modal (khui_alert *alert)
 Display a modal alert.
KHMEXP khm_int32 KHMAPI khui_alert_queue (khui_alert *alert)
 Queue an alert.
KHMEXP khm_int32 KHMAPI khui_alert_show_simple (const wchar_t *title, const wchar_t *message, khm_int32 severity)
 Display a simple alert.
KHMEXP khm_int32 KHMAPI khui_alert_hold (khui_alert *alert)
 Obtain a hold on the alert.
KHMEXP khm_int32 KHMAPI khui_alert_release (khui_alert *alert)
 Release the hold on the alert.
KHMEXP void KHMAPI khui_alert_lock (khui_alert *alert)
 Lock an alert.
KHMEXP void KHMAPI khui_alert_unlock (khui_alert *alert)
 Unlock an alert.

Typedef Documentation

typedef enum tag_khui_alert_types khui_alert_type

Alert types.

These types can be set with khui_alert_set_type() to indicate which type of alert this is. The types defined here are identified by the Network Identity Manager and will receive special handling whereever appropriate.

The type is a hint to the application and will not guarantee a particular behavior.

Enumeration Type Documentation

enum khui_alert_flags

Flags for an alert.

Enumerator:
KHUI_ALERT_FLAG_FREE_STRUCT  Internal. Free the structure once the alert is done.
KHUI_ALERT_FLAG_FREE_TITLE  Internal. Free the title field when the alert is done.
KHUI_ALERT_FLAG_FREE_MESSAGE  Internal. Free the message field when the alert is done.
KHUI_ALERT_FLAG_FREE_SUGGEST  Internal. Free the suggest field when the alert is done
KHUI_ALERT_FLAG_DEFACTION  If the message is displayed as a balloon prompt, then perform the default action when it is clicked. The default action is the first action added to the alert. Cannot be used if there are no actions or if KHUI_ALERT_FLAG_REQUEST_WINDOW is specified.
KHUI_ALERT_FLAG_DISPATCH_CMD  If the message has commands, when the user clicks on one of the command buttons, the corresponding command will be immediately dispatched as if khui_action_trigger() is called with a NULL UI context. Otherwise, the selected command will be stored in the alert and can be retrieved via a call to khui_alert_get_response().
KHUI_ALERT_FLAG_VALID_TARGET  Internal. There is a valid target for the alert
KHUI_ALERT_FLAG_VALID_ERROR  Internal. There is a valid error context associated with the alert
KHUI_ALERT_FLAG_DISPLAY_WINDOW  The alert has been displayed in a window
KHUI_ALERT_FLAG_DISPLAY_BALLOON  The alert has been displayed in a ballon
KHUI_ALERT_FLAG_REQUEST_WINDOW  The alert should be displayed in a window
KHUI_ALERT_FLAG_REQUEST_BALLOON  The alert should be displayed in a balloon
KHUI_ALERT_FLAG_MODAL  Internal. Modal alert. Do not set direclty.
KHUI_ALERT_FLAGMASK_RDWR  Bit mask of flags that can be set by khui_alert_set_flags()

enum tag_khui_alert_types

Alert types.

These types can be set with khui_alert_set_type() to indicate which type of alert this is. The types defined here are identified by the Network Identity Manager and will receive special handling whereever appropriate.

The type is a hint to the application and will not guarantee a particular behavior.

Enumerator:
KHUI_ALERTTYPE_NONE  No specific alert type
KHUI_ALERTTYPE_PLUGIN  Plug-in or module load related alert
KHUI_ALERTTYPE_EXPIRE  Credential or identity expiration warning
KHUI_ALERTTYPE_RENEWFAIL  Failed to renew credentials
KHUI_ALERTTYPE_ACQUIREFAIL  Failed to acquire credentials
KHUI_ALERTTYPE_CHPW  Failed to change password

Function Documentation

KHMEXP khm_int32 KHMAPI khui_alert_add_command ( khui_alert *  alert,
khm_int32  command_id 
)

Add a command to an alert object.

The command ID should be a valid registered action.

KHMEXP khm_int32 KHMAPI khui_alert_clear_commands ( khui_alert *  alert  ) 

Clear all the commands from an alert object.

See also:
khui_alert_add_command()

KHMEXP khm_int32 KHMAPI khui_alert_create_empty ( khui_alert **  result  ) 

Create an empty alert object.

The returned result is a held pointer to a khui_alert object. Use khui_alert_release() to release the object.

KHMEXP khm_int32 KHMAPI khui_alert_create_simple ( const wchar_t *  title,
const wchar_t *  message,
khm_int32  severity,
khui_alert **  result 
)

Create a simple alert object.

The returned result is a held pointer to a khui_alert object. Use khui_alert_release() to release the object.

Parameters:
[in] title The title of the alert. (Required, Localized) Limited by KHUI_MAXCCH_TITLE.
[in] message The message. (Required. Localized). Limited by KHUI_MAXCCH_MESSAGE.
[in] severity One of tag_kherr_severity
[out] result Receives a held pointer to a khui_alert object upon successful completion.

KHMEXP khm_int32 KHMAPI khui_alert_get_response ( khui_alert *  alert  ) 

Get the response code from an alert.

Once an alert has been displayed to the user, the user may choose a command from the list of commands provided in the alert (see khui_alert_add_command() ). This function can retrieve the selected command from the alert.

Returns:
The selected command or 0 if no commands were selected.

KHMEXP khm_int32 KHMAPI khui_alert_hold ( khui_alert *  alert  ) 

Obtain a hold on the alert.

An alert structure is only considered valid for the duration that there is a hold on it.

Use khui_alert_release() to release the hold.

KHMEXP void KHMAPI khui_alert_lock ( khui_alert *  alert  ) 

Lock an alert.

Locking an alert disallows any other thread from accessing the alert at the same time. NetIDMgr keeps a global list of all alert objects and the user interface may access any of them at various points in time. Locking the alert allows a thread to modify an alert without causing another thread to be exposed to an inconsistent state.

Once a thread obtains a lock on the alert, it must call khui_alert_unlock() to unlock it. Otherwise no other thread will be able to access the alert.

Note:
Currently the alert lock is global. Locking one alert disallows access to all other alerts as well.

Calling khui_alert_lock() is only necessary if you are accessing the khui_alert structure directly. Calling any of the khui_alert_* functions to modify the alert does not require obtaining a lock, as they perform synchronization internally.

KHMEXP khm_int32 KHMAPI khui_alert_queue ( khui_alert *  alert  ) 

Queue an alert.

Instead of displaying the alert immediately, the alert is queued and the status bar updated to notify the user that there is a pending alert. Once the user activates the pending alert, it will be displayed as if khui_alert_show() was called.

KHMEXP khm_int32 KHMAPI khui_alert_release ( khui_alert *  alert  ) 

Release the hold on the alert.

Holds obtained on an alert using any of the functions that either return a held pointer to an alert or implicitly obtains a hold on it need to be undone through a call to khui_alert_release().

KHMEXP khm_int32 KHMAPI khui_alert_set_flags ( khui_alert *  alert,
khm_int32  mask,
khm_int32  flags 
)

Sets the flags of the alert.

The flags are as defined in khui_alert_flags. The bits that are on in mask will be set to the corresponding values in flags. Only the bits specified in KHUI_ALERT_FLAGMASK_RDWR can be specified in mask.

KHMEXP khm_int32 KHMAPI khui_alert_set_message ( khui_alert *  alert,
const wchar_t *  message 
)

Set the message of an alert object.

The message is limited by KHUI_MAXCCH_MESSAGE.

KHMEXP khm_int32 KHMAPI khui_alert_set_severity ( khui_alert *  alert,
khm_int32  severity 
)

Set the severity of the alert object.

The severity value is one of tag_kherr_severity

KHMEXP khm_int32 KHMAPI khui_alert_set_suggestion ( khui_alert *  alert,
const wchar_t *  suggestion 
)

Set the suggestion of an alert object.

The suggestion is limited by KHUI_MAXCCH_SUGGESTION

KHMEXP khm_int32 KHMAPI khui_alert_set_title ( khui_alert *  alert,
const wchar_t *  title 
)

Set the title of an alert object.

The title is limited by KHUI_MAXCCH_TITLE.

KHMEXP khm_int32 KHMAPI khui_alert_show ( khui_alert *  alert  ) 

Display an alert.

The alert must have a valid severity, title and a message to be displayed. Otherwise the function immediately returns with a failure code.

The method used to display the alert is as follows:

If the message, title of the alert is too long to fit in a balloon prompt, there's a suggestion or if there are custom commands then a placeholder balloon prompt will be shown which when clicked on, shows the actual alert in an alert window.

An exception is when KHUI_ALERT_FLAG_DEFACTION is specified in flags. In this case instead of a placeholder balloon prompt, one will be shown with the actual title and message (truncated if necessary). Clicking on the balloon will cause the first command in the command list to be performed.

The placeholder balloon prompt will have a title derived from the first 63 characters of the title field in the alert and a message notifying the user that they should click the balloon prompt for more information.

To this end, it is beneficial to limit the length of the title to 63 characters (64 counting the terminating NULL). This limit is enforced on Windows. Also, try to make the title descriptive.

User interaction with the alert will be as follows:

KHMEXP khm_int32 KHMAPI khui_alert_show_modal ( khui_alert *  alert  ) 

Display a modal alert.

Similar to khui_alert_show(), but shows a modal alert dialog. The function does not return until the user has closed the alert.

This function always opens an alert window (never shows a balloon).

KHMEXP khm_int32 KHMAPI khui_alert_show_simple ( const wchar_t *  title,
const wchar_t *  message,
khm_int32  severity 
)

Display a simple alert.

See also:
khui_alert_show()

KHMEXP void KHMAPI khui_alert_unlock ( khui_alert *  alert  ) 

Unlock an alert.

See also:
khui_alert_lock()

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