osfmk/UserNotification/KUNCUserNotifications.h

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