osfmk/UserNotification/KUNCUserNotifications.h

   1 /*
   2  * Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H
  25 #define __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H
  26
  27 #include <sys/cdefs.h>
  28
  29
  30 #include <mach/message.h>
  31 #include <mach/kern_return.h>
  32 #include <UserNotification/UNDTypes.h>
  33
  34 __BEGIN_DECLS
  35
  36 /*
  37  * non blocking notice call.
  38  */
  39 kern_return_t
  40 KUNCUserNotificationDisplayNotice(
  41         int             noticeTimeout,
  42         unsigned        flags,
  43         char            *iconPath,
  44         char            *soundPath,
  45         char            *localizationPath,
  46         char            *alertHeader,
  47         char            *alertMessage,
  48         char            *defaultButtonTitle);
  49
  50 /*
  51  * ***BLOCKING*** alert call, returned int value corresponds to the
  52  * pressed button, spin this off in a thread only, or expect your kext to block.
  53  */
  54 kern_return_t
  55 KUNCUserNotificationDisplayAlert(
  56         int             alertTimeout,
  57         unsigned        flags,
  58         char            *iconPath,
  59         char            *soundPath,
  60         char            *localizationPath,
  61         char            *alertHeader,
  62         char            *alertMessage,
  63         char            *defaultButtonTitle,
  64         char            *alternateButtonTitle,
  65         char            *otherButtonTitle,
  66         unsigned        *responseFlags);
  67
  68 /*
  69  * Execute a userland executable with the given path, user and type
  70  */
  71
  72 #define kOpenApplicationPath    0       /* essentially executes the path */
  73 #define kOpenPreferencePanel    1       /* runs the preferences with the foo.preference opened.  foo.preference must exist in /System/Library/Preferences */
  74 #define kOpenApplication        2       /* essentially runs /usr/bin/open on the passed in application name */
  75
  76
  77 #define kOpenAppAsRoot          0
  78 #define kOpenAppAsConsoleUser   1
  79
  80 kern_return_t
  81 KUNCExecute(
  82         char    *executionPath,
  83         int     openAsUser,
  84         int     pathExecutionType);
  85
  86
  87 /* KUNC User Notification XML Keys
  88  *
  89  * These are the keys used in the xml plist file passed in to the
  90  * KUNCUserNotitificationDisplayFrom* calls
  91  *
  92  * KUNC Notifications are completely dependent on CFUserNotifications in
  93  * user land.  The same restrictions apply, including the number of text fields,
  94  * types of information displayable, etc.
  95  *
  96  *  Key                 Type
  97  * Header                       string (header displayed on dialog)
  98  *                              corresponds to kCFUserNotificationAlertHeaderKey
  99  *
 100  * Icon URL                     string (url of the icon to display)
 101  *                              corresponds to kCFUserNotificationIconURLKey
 102  *
 103  * Sound URL                    string (url of the sound to play on display)
 104  *                              corresponds to kCFUserNotificationSoundURLKey
 105  *
 106  * Localization URL             string (url of bundle to retrieve localization
 107  *                              info from, using Localizable.strings files)
 108  *                              corresponds to kCFUserNotificationLocalizationURLKey
 109  *
 110  * Message                      string (text of the message, can contain %@'s
 111  *                              which are filled from tokenString passed in)
 112  *                              corresponds to kCFUserNotificationAlertMessageKey
 113  *
 114  * OK Button Title              string (title of the "main" button)
 115  *                              corresponds to kCFUserNotificationDefaultButtonTitleKey
 116  *
 117  * Alternate Button Title       string (title of the "alternate" button,  usually cancel)
 118  *                              corresponds to kCFUserNotificationAlternateButtonTitleKey
 119  *
 120  * Other Button Title           string (title of the "other" button)
 121  *                              corresponds to kCFUserNotificationOtherButtonTitleKey
 122  *
 123  * Timeout                      string (numeric, int - seconds until the dialog
 124  *                              goes away on it's own)
 125  *
 126  * Alert Level                  string (Stop, Notice, Alert)
 127  *
 128  * Blocking Message             string (numeric, 1 or 0 - if 1, the dialog will
 129  *                              have no buttons)
 130  *
 131  * Text Field Strings           array of strings (each becomes a text field)
 132  *                              corresponds to kCFUserNotificationTextFieldTitlesKey
 133  *
 134  * Password Fields              array of strings (numeric - each indicates a
 135  *                              pwd field)
 136  *
 137  * Popup Button Strings         array of strings (each entry becomes a popup
 138  *                              button string)
 139  *
 140  * Radio Button Strings         array of strings (each becomes a radio button)
 141  *
 142  * Check Box Strings            array of strings (each becomes a check box)
 143  *                              corresponds to kCFUserNotificationCheckBoxTitlesKey
 144  *
 145  * Selected Radio               string (numeric - which radio is selected)
 146  *
 147  * Checked Boxes                array of strings (numeric - each indicates a
 148  *                              checked field)
 149  *
 150  * Selected Popup               string (numeric - which popup entry is selected)
 151  *
 152  */
 153
 154 /*
 155  * Bundle Calls
 156  *
 157  *      Arguments
 158  *
 159  *      bundleIdentifier
 160  *              path to the actual bundle (not inside of it)
 161  *              (i.e. "/System/Library/Extensions/Foo.kext")
 162  *              ***NOTE***
 163  *              This WILL change soon to expect the CFBundleIdentifier instead of a bundle path
 164  *      fileName
 165  *              filename in bundle to retrive the xml from (i.e. "Messages")
 166  *      fileExtension
 167  *              if fileName has an extension, it goes here (i.e., "dict");
 168  *      messageKey
 169  *              name of the xml key in the dictionary in the file to retrieve
 170  *              the info from (i.e., "Error Message")
 171  *      tokenString
 172  *              a string in the form of "foo@bar" where each element is
 173  *              seperated by the @ character.  This string can be used to
 174  *              replace values of the form %@ in the message key in the provided
 175  *              dictionary in the xml plist
 176  *      specialKey
 177  *              user specified key for notification, use this to match return
 178  *              values with your requested notification, this value is passed
 179  *              back to the client in the callback pararmeter contextKey
 180  */
 181
 182 typedef int KUNCUserNotificationID;
 183
 184 /*
 185  * Reponse value checking & default setting
 186  *
 187  * The reponse value returned in the response Flags of the
 188  * KUNCUserNotificationCallBack can be tested against the following
 189  * enum and 2 defines to determine the state.
 190  */
 191
 192 enum {
 193     kKUNCDefaultResponse        = 0,
 194     kKUNCAlternateResponse      = 1,
 195     kKUNCOtherResponse          = 2,
 196     kKUNCCancelResponse         = 3
 197 };
 198
 199 #define KUNCCheckBoxChecked(i)  (1 << (8 + i))   /* can be used for radio's too */
 200 #define KUNCPopUpSelection(n)   (n << 24)
 201
 202 /*
 203  * Callback function for KUNCNotifications
 204  */
 205 typedef void
 206 (*KUNCUserNotificationCallBack)(
 207         int             contextKey,
 208         int             responseFlags,
 209         void            *xmlData);
 210
 211 /*
 212  * Get a notification ID
 213  */
 214 KUNCUserNotificationID KUNCGetNotificationID(void);
 215
 216
 217 /* This function currently requires a bundle path, which kexts cannot currently get.  In the future, the CFBundleIdentiofier of the kext will be pass in in place of the bundlePath. */
 218
 219 kern_return_t
 220 KUNCUserNotificationDisplayFromBundle(
 221         KUNCUserNotificationID          notificationID,
 222         char                            *bundleIdentifier,
 223         char                            *fileName,
 224         char                            *fileExtension,
 225         char                            *messageKey,
 226         char                            *tokenString,
 227         KUNCUserNotificationCallBack    callback,
 228         int                             contextKey);
 229
 230
 231 kern_return_t
 232 KUNCUserNotificationCancel(
 233         KUNCUserNotificationID  notification);
 234
 235
 236 __END_DECLS
 237
 238 #endif  /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */