src/WINNT/kfw/inc/netidmgr/khalerts.h

   1 /*
   2  * Copyright (c) 2005 Massachusetts Institute of Technology
   3  *
   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:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  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
  22  * SOFTWARE.
  23  */
  24
  25 /* $Id$ */
  26
  27 #ifndef __KHIMAIRA_KHALERTS_H
  28 #define __KHIMAIRA_KHALERTS_H
  29
  30 /*********************************************************************
  31   Alerter and error reporting
  32 **********************************************************************/
  33
  34 /*! \addtogroup khui
  35 @{ */
  36
  37 /*!\defgroup khui_alert Alerter and Error Reporting
  38 @{*/
  39
  40 #define KHUI_MAX_ALERT_COMMANDS  4
  41
  42 /*! \brief An alert
  43
  44     Describes an alert message that will be shown to the user in a
  45     variety of ways depending on the state of the NetIDMgr
  46     application.
  47  */
  48 typedef struct tag_khui_alert {
  49     khm_int32           magic;  /*!< Magic number. Always set to
  50                                   KHUI_ALERT_MAGIC */
  51
  52     khm_int32           severity; /*!< The severity of the alert.  One
  53                                     of KHERR_ERROR, KHERR_WARNING or
  54                                     KHERR_INFO.  The default is
  55                                     KHERR_INFO.  Do not set directly.
  56                                     Use khui_alert_set_severity(). */
  57
  58     khm_int32           alert_commands[KHUI_MAX_ALERT_COMMANDS];
  59                                 /*!< The command buttons associated
  60                                   with the alert.  Use
  61                                   khui_alert_add_command() to add a
  62                                   command.  The buttons will appear in
  63                                   the order in which they were added.
  64                                   The first button will be the
  65                                   default.  Each command should be a
  66                                   known action identifier. */
  67     khm_int32           n_alert_commands;
  68
  69     wchar_t *           title;  /*!< The title of the alert.  Subject
  70                                   to ::KHUI_MAXCCH_TITLE.  Use
  71                                   khui_alert_set_title() to set.  Do
  72                                   not modify directly. */
  73
  74     wchar_t *           message; /*!< The main message of the alert.
  75                                    Subject to ::KHUI_MAXCCH_MESSAGE.
  76                                    Use khui_alert_set_message() to
  77                                    set.  Do not modify direcly. */
  78
  79     wchar_t *           suggestion; /*!< A suggestion.  Appears below
  80                                       the message text. Use
  81                                       khui_alert_set_suggestion() to
  82                                       set.  Do not modify directly. */
  83
  84 #ifdef _WIN32
  85     POINT               target;
  86 #endif
  87
  88     khm_int32           flags;  /*!< combination of
  89                                  ::khui_alert_flags.  Do not modify
  90                                  directly. */
  91
  92     kherr_context *     err_context;
  93                                 /*!< If non-NULL at the time the alert
  94                                   window is shown, this indicates that
  95                                   the alert window should provide an
  96                                   error viewer for the given error
  97                                   context. */
  98
  99     kherr_event *       err_event;
 100                                 /*!< If non-NULL at the time the alert
 101                                   window is shown, this indicates that
 102                                   the alert window should provide an
 103                                   error viewer for the given error
 104                                   event.  If an \a err_context is also
 105                                   given, the error viewer for the
 106                                   context will be below this error. */
 107
 108     khm_int32           response;
 109                                 /*!< Once the alert is displayed to
 110                                   the user, when the user clicks one
 111                                   of the command buttons, the command
 112                                   ID will be assigned here. */
 113
 114     int                 refcount; /* internal */
 115
 116     LDCL(struct tag_khui_alert); /* internal */
 117 } khui_alert;
 118
 119 #define KHUI_ALERT_MAGIC 0x48c39ce9
 120
 121 /*! \brief Maximum number of characters in title including terminating NULL
 122  */
 123 #define KHUI_MAXCCH_TITLE 256
 124
 125 /*! \brief Maximum number of bytes in title including terminating NULL
 126  */
 127 #define KHUI_MAXCB_TITLE (KHUI_MAXCCH_TITLE * sizeof(wchar_t))
 128
 129 /*! \brief Maximum number of characters in message including terminating NULL
 130  */
 131 #define KHUI_MAXCCH_MESSAGE 1024
 132
 133 /*! \brief Maximum number of bytes in message including terminating NULL
 134  */
 135 #define KHUI_MAXCB_MESSAGE (KHUI_MAXCCH_MESSAGE * sizeof(wchar_t))
 136
 137 /*! \brief Maxumum number of characters in a suggestion including terminating NULL */
 138 #define KHUI_MAXCCH_SUGGESTION 1024
 139
 140 /*! \brief Maximum number of bytes in a suggestion, including terminating NULL */
 141 #define KHUI_MAXCB_SUGGESTION (KHUI_MAXCCH_SUGGESTION * sizeof(wchar_t))
 142
 143 /*! \brief Flags for an alert */
 144 enum khui_alert_flags {
 145     KHUI_ALERT_FLAG_FREE_STRUCT     =0x00000001,
 146     /*!< Internal. Free the structure once the alert is done. */
 147
 148     KHUI_ALERT_FLAG_FREE_TITLE      =0x00000002,
 149     /*!< Internal. Free the \a title field when the alert is done.*/
 150
 151     KHUI_ALERT_FLAG_FREE_MESSAGE    =0x00000004,
 152     /*!< Internal. Free the \a message field when the alert is done. */
 153
 154     KHUI_ALERT_FLAG_FREE_SUGGEST    =0x00000008,
 155     /*!< Internal. Free the \a suggest field when the alert is done */
 156
 157     KHUI_ALERT_FLAG_DEFACTION       =0x00000010,
 158     /*!< If the message is displayed as a balloon prompt, then perform
 159       the default action when it is clicked.  The default action is
 160       the first action added to the alert.  Cannot be used if there
 161       are no actions or if ::KHUI_ALERT_FLAG_REQUEST_WINDOW is
 162       specified.*/
 163
 164     KHUI_ALERT_FLAG_VALID_TARGET    =0x00010000,
 165     /*!< There is a valid target for the alert */
 166
 167     KHUI_ALERT_FLAG_VALID_ERROR     =0x00020000,
 168     /*!< There is a valid error context associated with the alert */
 169
 170     KHUI_ALERT_FLAG_DISPLAY_WINDOW  =0x01000000,
 171     /*!< The alert has been displayed in a window */
 172
 173     KHUI_ALERT_FLAG_DISPLAY_BALLOON =0x02000000,
 174     /*!< The alert has been displayed in a ballon */
 175
 176     KHUI_ALERT_FLAG_REQUEST_WINDOW  =0x04000000,
 177     /*!< The alert should be displayed in a window */
 178
 179     KHUI_ALERT_FLAG_REQUEST_BALLOON =0x08000000,
 180     /*!< The alert should be displayed in a balloon */
 181
 182     KHUI_ALERT_FLAG_MODAL           =0x10000000,
 183     /*!< Modal alert.  Do not set direclty. */
 184
 185     KHUI_ALERT_FLAGMASK_RDWR        =0x0C000010,
 186     /*!< Bit mask of flags that can be set by khui_alert_set_flags() */
 187 };
 188
 189 /*! \brief Create an empty alert object
 190
 191     The returned result is a held pointer to a ::khui_alert object.
 192     Use khui_alert_release() to release the object.
 193  */
 194 KHMEXP khm_int32 KHMAPI
 195 khui_alert_create_empty(khui_alert ** result);
 196
 197 /*! \brief Create a simple alert object
 198
 199     The returned result is a held pointer to a ::khui_alert object.
 200     Use khui_alert_release() to release the object.
 201
 202     \param[in] title The title of the alert. (Required, Localized)
 203         Limited by ::KHUI_MAXCCH_TITLE.
 204
 205     \param[in] message The message.  (Required. Localized).  Limited
 206         by ::KHUI_MAXCCH_MESSAGE.
 207
 208     \param[in] severity One of ::tag_kherr_severity
 209
 210     \param[out] result Receives a held pointer to a ::khui_alert
 211         object upon successful completion.
 212  */
 213 KHMEXP khm_int32 KHMAPI
 214 khui_alert_create_simple(const wchar_t * title,
 215                          const wchar_t * message,
 216                          khm_int32 severity,
 217                          khui_alert ** result);
 218
 219 /*! \brief Set the title of an alert object
 220
 221     The title is limited by ::KHUI_MAXCCH_TITLE.
 222  */
 223 KHMEXP khm_int32 KHMAPI
 224 khui_alert_set_title(khui_alert * alert,
 225                      const wchar_t * title);
 226
 227 /*! \brief Set the message of an alert object
 228
 229     The message is limited by ::KHUI_MAXCCH_MESSAGE.
 230  */
 231 KHMEXP khm_int32 KHMAPI
 232 khui_alert_set_message(khui_alert * alert,
 233                        const wchar_t * message);
 234
 235 /*! \brief Set the suggestion of an alert object
 236
 237     The suggestion is limited by ::KHUI_MAXCCH_SUGGESTION
 238  */
 239 KHMEXP khm_int32 KHMAPI
 240 khui_alert_set_suggestion(khui_alert * alert,
 241                           const wchar_t * suggestion);
 242
 243 /*! \brief Set the severity of the alert object
 244
 245     The severity value is one of ::tag_kherr_severity
 246  */
 247 KHMEXP khm_int32 KHMAPI
 248 khui_alert_set_severity(khui_alert * alert,
 249                         khm_int32 severity);
 250
 251 /*! \brief Sets the flags of the alert
 252
 253     The flags are as defined in ::khui_alert_flags.  The bits that are
 254     on in \a mask will be set to the corresponding values in \a flags.
 255     Only the bits specified in ::KHUI_ALERT_FLAGMASK_RDWR can be
 256     specified in \a mask.
 257  */
 258 KHMEXP khm_int32 KHMAPI
 259 khui_alert_set_flags(khui_alert * alert, khm_int32 mask, khm_int32 flags);
 260
 261 /*! \brief Clear all the commands from an alert object
 262
 263     \see khui_alert_add_command()
 264  */
 265 KHMEXP khm_int32 KHMAPI
 266 khui_alert_clear_commands(khui_alert * alert);
 267
 268 /*! \brief Add a command to an alert object
 269
 270     The command ID should be a valid registered command.
 271  */
 272 KHMEXP khm_int32 KHMAPI
 273 khui_alert_add_command(khui_alert * alert,
 274                        khm_int32 command_id);
 275
 276 /*! \brief Display an alert
 277
 278     The alert must have a valid \a severity, \a title and a \a message
 279     to be displayed.  Otherwise the function immediately returns with
 280     a failure code.
 281
 282     The method used to display the alert is as follows:
 283
 284     - A balloon alert will be shown if one of the following is true:
 285       - The NetIDMgr application is minimized or in the background.
 286       - ::KHUI_ALERT_FLAG_REQUEST_BALLOON is specified in \a flags.
 287     - Otherwise an alert window will be shown.
 288
 289     If the message, title of the alert is too long to fit in a balloon
 290     prompt, there's a suggestion or if there are custom commands then
 291     a placeholder balloon prompt will be shown which when clicked on,
 292     shows the actual alert in an alert window.
 293
 294     An exception is when ::KHUI_ALERT_FLAG_DEFACTION is specified in
 295     flags.  In this case instead of a placeholder balloon prompt, one
 296     will be shown with the actual title and message (truncated if
 297     necessary).  Clicking on the balloon will have the same effect as
 298     choosing the first command in the action.
 299
 300     The placeholder balloon prompt will have a title derived from the
 301     first 63 characters of the \a title field in the alert and a
 302     message notifying the user that they should click the balloon
 303     prompt for more information.
 304
 305     To this end, it is beneficial to limit the length of the title to
 306     63 characters (64 counting the terminating NULL).  This limit is
 307     enforced on Windows.  Also, try to make the title descriptive.
 308  */
 309 KHMEXP khm_int32 KHMAPI
 310 khui_alert_show(khui_alert * alert);
 311
 312 /*! \brief Display a modal alert
 313
 314     Similar to khui_alert_show(), but shows a modal alert dialog.  The
 315     function does not return until the user has closed the alert.
 316
 317     This function always opens an alert window (never shows a
 318     balloon).
 319
 320     \note Should only be called from the UI thread.
 321  */
 322 KHMEXP khm_int32 KHMAPI
 323 khui_alert_show_modal(khui_alert * alert);
 324
 325 /*! \brief Queue an alert
 326
 327     Instead of displaying the alert immediately, the alert is queued
 328     and the status bar updated to notify the user that there is a
 329     pending alert.  Once the user activates the pending alert, it will
 330     be displayed as if khui_alert_show() was called.
 331  */
 332 KHMEXP khm_int32 KHMAPI
 333 khui_alert_queue(khui_alert * alert);
 334
 335 /*! \brief Display a simple alert
 336
 337     \see khui_alert_show()
 338  */
 339 KHMEXP khm_int32 KHMAPI
 340 khui_alert_show_simple(const wchar_t * title,
 341                        const wchar_t * message,
 342                        khm_int32 severity);
 343
 344 /*! \brief Obtain a hold on the alert
 345
 346     An alert structure is only considered valid for the duration that
 347     there is a hold on it.
 348
 349     Use khui_alert_release() to release the hold.
 350  */
 351 KHMEXP khm_int32 KHMAPI
 352 khui_alert_hold(khui_alert * alert);
 353
 354 /*! \brief Release the hold on the alert
 355
 356     Holds obtained on an alert using any of the functions that either
 357     return a held pointer to an alert or implicitly obtains a hold on
 358     it need to be undone through a call to khui_alert_release().
 359  */
 360 KHMEXP khm_int32 KHMAPI
 361 khui_alert_release(khui_alert * alert);
 362
 363 /*! \brief Lock an alert
 364
 365     Locking an alert disallows any other thread from accessing the
 366     alert at the same time.  NetIDMgr keeps a global list of all alert
 367     objects and the user interface may access any of them at various
 368     points in time.  Locking the alert allows a thread to modify an
 369     alert without causing another thread to be exposed to an
 370     inconsistent state.
 371
 372     Once a thread obtains a lock on the alert, it must call
 373     khui_alert_unlock() to unlock it.  Otherwise no other thread will
 374     be able to access the alert.
 375
 376     \note Currently the alert lock is global.  Locking one alert
 377         disallows access to all other alerts as well.
 378
 379     \note Calling khui_alert_lock() is only necessary if you are
 380         modifying the ::khui_alert structure directly.  Calling any of
 381         the khui_alert_* functions to modify the alert does not
 382         require obtaining a lock, as they perform synchronization
 383         internally.
 384 */
 385 KHMEXP void KHMAPI
 386 khui_alert_lock(khui_alert * alert);
 387
 388 /*! \brief Unlock an alert
 389
 390     \see khui_alert_lock()
 391 */
 392 KHMEXP void KHMAPI
 393 khui_alert_unlock(khui_alert * alert);
 394
 395 /*!@}*/
 396 /*!@}*/
 397
 398 #endif