1/*
2 * Copyright (c) 2000-2004 Apple Computer, 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 */
44kern_return_t
45KUNCUserNotificationDisplayNotice(
46	int		noticeTimeout,
47	unsigned	flags,
48	char		*iconPath,
49	char		*soundPath,
50	char		*localizationPath,
51	char		*alertHeader,
52	char		*alertMessage,
53	char		*defaultButtonTitle);
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 */
59kern_return_t
60KUNCUserNotificationDisplayAlert(
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);
72
73/*
74 * Execute a userland executable with the given path, user and type
75 */
76
77#define kOpenApplicationPath 	0	/* essentially executes the path */
78#define kOpenPreferencePanel    1	/* runs the preferences with the foo.preference opened.  foo.preference must exist in /System/Library/Preferences */
79#define kOpenApplication	2	/* essentially runs /usr/bin/open on the passed in application name */
80
81
82#define kOpenAppAsRoot		0
83#define kOpenAppAsConsoleUser	1
84
85kern_return_t
86KUNCExecute(
87	char	*executionPath,
88	int	openAsUser,
89	int	pathExecutionType);
90
91
92/* KUNC User Notification XML Keys
93 *
94 * These are the keys used in the xml plist file passed in to the
95 * KUNCUserNotitificationDisplayFrom* calls
96 *
97 * KUNC Notifications are completely dependent on CFUserNotifications in
98 * user land.  The same restrictions apply, including the number of text fields,
99 * types of information displayable, etc.
100 *
101 *  Key			Type
102 * Header			string (header displayed on dialog)
103 * 				corresponds to kCFUserNotificationAlertHeaderKey
104 *
105 * Icon URL			string (url of the icon to display)
106 * 				corresponds to kCFUserNotificationIconURLKey
107 *
108 * Sound URL			string (url of the sound to play on display)
109 * 				corresponds to kCFUserNotificationSoundURLKey
110 *
111 * Localization URL		string (url of bundle to retrieve localization
112 *				info from, using Localizable.strings files)
113 * 				corresponds to kCFUserNotificationLocalizationURLKey
114 *
115 * Message			string (text of the message, can contain %@'s
116 *				which are filled from tokenString passed in)
117 * 				corresponds to kCFUserNotificationAlertMessageKey
118 *
119 * OK Button Title 		string (title of the "main" button)
120 * 				corresponds to kCFUserNotificationDefaultButtonTitleKey
121 *
122 * Alternate Button Title 	string (title of the "alternate" button,  usually cancel)
123 * 				corresponds to kCFUserNotificationAlternateButtonTitleKey
124 *
125 * Other Button Title	 	string (title of the "other" button)
126 * 				corresponds to kCFUserNotificationOtherButtonTitleKey
127 *
128 * Timeout			string (numeric, int - seconds until the dialog
129 *				goes away on it's own)
130 *
131 * Alert Level			string (Stop, Notice, Alert)
132 *
133 * Blocking Message		string (numeric, 1 or 0 - if 1, the dialog will
134 *				have no buttons)
135 *
136 * Text Field Strings		array of strings (each becomes a text field)
137 * 				corresponds to kCFUserNotificationTextFieldTitlesKey
138 *
139 * Password Fields		array of strings (numeric - each indicates a
140 *				pwd field)
141 *
142 * Popup Button Strings		array of strings (each entry becomes a popup
143 *				button string)
144 *
145 * Radio Button Strings		array of strings (each becomes a radio button)
146 *
147 * Check Box Strings		array of strings (each becomes a check box)
148 * 				corresponds to kCFUserNotificationCheckBoxTitlesKey
149 *
150 * Selected Radio		string (numeric - which radio is selected)
151 *
152 * Checked Boxes		array of strings (numeric - each indicates a
153 *				checked field)
154 *
155 * Selected Popup		string (numeric - which popup entry is selected)
156 *
157 */
158
159/*
160 * Bundle Calls
161 *
162 *	Arguments
163 *
164 *	bundleIdentifier
165 *		path to the actual bundle (not inside of it)
166 *	        (i.e. "/System/Library/Extensions/Foo.kext")
167 *		***NOTE***
168 *		This WILL change soon to expect the CFBundleIdentifier instead of a bundle path
169 *	fileName
170 *		filename in bundle to retrive the xml from (i.e. "Messages")
171 *	fileExtension
172 *		if fileName has an extension, it goes here (i.e., "dict");
173 *	messageKey
174 *		name of the xml key in the dictionary in the file to retrieve
175 *		the info from (i.e., "Error Message")
176 *	tokenString
177 *		a string in the form of "foo@bar" where each element is
178 *		seperated by the @ character.  This string can be used to
179 *		replace values of the form %@ in the message key in the provided
180 *		dictionary in the xml plist
181 *	specialKey
182 *		user specified key for notification, use this to match return
183 *		values with your requested notification, this value is passed
184 *		back to the client in the callback pararmeter contextKey
185 */
186
187typedef int KUNCUserNotificationID;
188
189/*
190 * Reponse value checking & default setting
191 *
192 * The reponse value returned in the response Flags of the
193 * KUNCUserNotificationCallBack can be tested against the following
194 * enum and 2 defines to determine the state.
195 */
196
197enum {
198    kKUNCDefaultResponse	= 0,
199    kKUNCAlternateResponse	= 1,
200    kKUNCOtherResponse		= 2,
201    kKUNCCancelResponse		= 3
202};
203
204#define KUNCCheckBoxChecked(i)	(1 << (8 + i))   /* can be used for radio's too */
205#define KUNCPopUpSelection(n)	(n << 24)
206
207/*
208 * Callback function for KUNCNotifications
209 */
210typedef void
211(*KUNCUserNotificationCallBack)(
212	int		contextKey,
213	int		responseFlags,
214	const void	*xmlData);
215
216/*
217 * Get a notification ID
218 */
219KUNCUserNotificationID KUNCGetNotificationID(void);
220
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
224kern_return_t
225KUNCUserNotificationDisplayFromBundle(
226	KUNCUserNotificationID		notificationID,
227	char				*bundleIdentifier,
228	char				*fileName,
229	char				*fileExtension,
230	char				*messageKey,
231	char				*tokenString,
232	KUNCUserNotificationCallBack	callback,
233	int				contextKey);
234
235
236kern_return_t
237KUNCUserNotificationCancel(
238	KUNCUserNotificationID	notification);
239
240
241__END_DECLS
242
243#endif  /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */
244