osfmk/UserNotification/KUNCUserNotifications.h

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