osfmk/UserNotification/KUNCUserNotifications.h

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