[apple/xnu.git] / osfmk / UserNotification / KUNCUserNotifications.h

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 *
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H
#define __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H

#include <sys/cdefs.h>


#include <mach/message.h>
#include <mach/kern_return.h>
#include <UserNotification/UNDTypes.h>

__BEGIN_DECLS

/*
 * non blocking notice call.
 */
kern_return_t
KUNCUserNotificationDisplayNotice(
	int		timeout,
	unsigned	flags,
	char		*iconPath,
	char		*soundPath,
	char		*localizationPath,
	char		*alertHeader,
	char		*alertMessage,
	char		*defaultButtonTitle);

/*
 * ***BLOCKING*** alert call, returned int value corresponds to the
 * pressed button, spin this off in a thread only, or expect your kext to block.
 */
kern_return_t
KUNCUserNotificationDisplayAlert(
	int		timeout,
	unsigned	flags,
	char		*iconPath,
	char		*soundPath,
	char		*localizationPath,
	char		*alertHeader,
	char		*alertMessage,
	char 		*defaultButtonTitle,
	char		*alternateButtonTitle,
	char		*otherButtonTitle,
	unsigned	*responseFlags);

/*
 * Execute a userland executable with the given path, user and type
 */
 
#define kOpenApplicationPath 	0	/* essentially executes the path */
#define kOpenPreferencePanel    1	/* runs the preferences with the foo.preference opened.  foo.preference must exist in /System/Library/Preferences */
#define kOpenApplication	2	/* essentially runs /usr/bin/open on the passed in application name */
 
 
#define kOpenAppAsRoot		0
#define kOpenAppAsConsoleUser	1 
 
kern_return_t
KUNCExecute(
	char	*executionPath,
	int	openAsUser,
	int	pathExecutionType);


/* KUNC User Notification XML Keys
 *
 * These are the keys used in the xml plist file passed in to the
 * KUNCUserNotitificationDisplayFrom* calls
 *
 * KUNC Notifications are completely dependent on CFUserNotifications in
 * user land.  The same restrictions apply, including the number of text fields,
 * types of information displayable, etc.
 *
 *  Key			Type
 * Header			string (header displayed on dialog)
 * Icon URL			string (url of the icon to display)
 * Sound URL			string (url of the sound to play on display)
 * Localization URL		string (url of bundle to retrieve localization
 *				info from, using Localizable.strings files)
 * Message			string (text of the message, can contain %@'s
 *				which are filled from tokenString passed in) 
 * OK Button Title 		string (title of the "main" button)
 * Alternate Button Title 	string (title of the "alternate" button -
 *				usually cancel)
 * Other Button Title	 	string (title of the "other" button)
 * Timeout			string (numeric, int - seconds until the dialog
 *				goes away on it's own)
 * Alert Level			string (Stop, Notice, Alert, 
 * Blocking Message		string (numeric, 1 or 0 - if 1, the dialog will
 *				have no buttons)
 * Text Field Strings		array of strings (each becomes a text field)
 * Password Fields		array of strings (numeric - each indicates a
 *				pwd field)
 * Popup Button Strings		array of strings (each entry becomes a popup
 *				button string)
 * Radio Button Strings		array of strings (each becomes a radio button)
 * Check Box Strings		array of strings (each becomes a check box)
 * Selected Radio		string (numeric - which radio is selected)
 * Checked Boxes		array of strings (numeric - each indicates a
 *				checked field)
 * Selected Popup		string (numeric - which popup entry is selected)
 */

/*
 * Bundle Calls
 *
 *	Arguments
 *
 *	bundleIdentifier
 *		path to the actual bundle (not inside of it)
 *	        (i.e. "/System/Library/Extensions/Foo.kext")
 *		***NOTE***
 *		This WILL change soon to expect the CFBundleIdentifier instead of a bundle path
 *	fileName
 *		filename in bundle to retrive the xml from (i.e. "Messages")
 *	fileExtension 
 *		if fileName has an extension, it goes here (i.e., "dict");
 *	messageKey
 *		name of the xml key in the dictionary in the file to retrieve
 *		the info from (i.e., "Error Message")
 *	tokenString
 *		a string in the form of "foo@bar" where each element is
 *		seperated by the @ character.  This string can be used to
 *		replace values of the form %@ in the message key in the provided
 *		dictionary in the xml plist
 *	specialKey
 *		user specified key for notification, use this to match return
 *		values with your requested notification, this value is passed
 *		back to the client in the callback pararmeter contextKey
 */

typedef int KUNCUserNotificationID;

/*
 * Reponse value checking & default setting
 *
 * The reponse value returned in the response Flags of the
 * KUNCUserNotificationCallBack can be tested against the following
 * enum and 2 defines to determine the state.
 */

enum {
    kKUNCDefaultResponse	= 0,
    kKUNCAlternateResponse	= 1,
    kKUNCOtherResponse		= 2,
    kKUNCCancelResponse		= 3
};

#define KUNCCheckBoxChecked(i)	(1 << (8 + i))   /* can be used for radio's too */
#define KUNCPopUpSelection(n)	(n << 24)

/*
 * Callback function for KUNCNotifications
 */
typedef void
(*KUNCUserNotificationCallBack)(
	int	contextKey,
	int	responseFlags,
	void	*xmlData);

/*
 * Get a notification ID
 */
KUNCUserNotificationID KUNCGetNotificationID();


/* 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. */

kern_return_t
KUNCUserNotificationDisplayFromBundle(
	KUNCUserNotificationID		notificationID,
	char				*bundleIdentifier,
	char				*fileName,
	char				*fileExtension,
	char				*messageKey,
	char				*tokenString,
	KUNCUserNotificationCallBack	callback,
	int				contextKey);


kern_return_t
KUNCUserNotificationCancel(
	KUNCUserNotificationID	notification);


__END_DECLS

#endif  /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
de355530 A	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
1c79356b A	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
de355530 A	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	*
1c79356b A	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 timeout,
	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 timeout,
	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	* Icon URL string (url of the icon to display)
98	* Sound URL string (url of the sound to play on display)
99	* Localization URL string (url of bundle to retrieve localization
100	* info from, using Localizable.strings files)
101	* Message string (text of the message, can contain %@'s
102	* which are filled from tokenString passed in)
103	* OK Button Title string (title of the "main" button)
104	* Alternate Button Title string (title of the "alternate" button -
105	* usually cancel)
106	* Other Button Title string (title of the "other" button)
107	* Timeout string (numeric, int - seconds until the dialog
108	* goes away on it's own)
109	* Alert Level string (Stop, Notice, Alert,
110	* Blocking Message string (numeric, 1 or 0 - if 1, the dialog will
111	* have no buttons)
112	* Text Field Strings array of strings (each becomes a text field)
113	* Password Fields array of strings (numeric - each indicates a
114	* pwd field)
115	* Popup Button Strings array of strings (each entry becomes a popup
116	* button string)
117	* Radio Button Strings array of strings (each becomes a radio button)
118	* Check Box Strings array of strings (each becomes a check box)
119	* Selected Radio string (numeric - which radio is selected)
120	* Checked Boxes array of strings (numeric - each indicates a
121	* checked field)
122	* Selected Popup string (numeric - which popup entry is selected)
123	*/
124
125	/*
126	* Bundle Calls
127	*
128	* Arguments
129	*
130	* bundleIdentifier
131	* path to the actual bundle (not inside of it)
132	* (i.e. "/System/Library/Extensions/Foo.kext")
133	* *NOTE*
134	* This WILL change soon to expect the CFBundleIdentifier instead of a bundle path
135	* fileName
136	* filename in bundle to retrive the xml from (i.e. "Messages")
137	* fileExtension
138	* if fileName has an extension, it goes here (i.e., "dict");
139	* messageKey
140	* name of the xml key in the dictionary in the file to retrieve
141	* the info from (i.e., "Error Message")
142	* tokenString
143	* a string in the form of "foo@bar" where each element is
144	* seperated by the @ character. This string can be used to
145	* replace values of the form %@ in the message key in the provided
146	* dictionary in the xml plist
147	* specialKey
148	* user specified key for notification, use this to match return
149	* values with your requested notification, this value is passed
150	* back to the client in the callback pararmeter contextKey
151	*/
152
153	typedef int KUNCUserNotificationID;
154
155	/*
156	* Reponse value checking & default setting
157	*
158	* The reponse value returned in the response Flags of the
159	* KUNCUserNotificationCallBack can be tested against the following
160	* enum and 2 defines to determine the state.
161	*/
162
163	enum {
164	kKUNCDefaultResponse = 0,
165	kKUNCAlternateResponse = 1,
166	kKUNCOtherResponse = 2,
167	kKUNCCancelResponse = 3
168	};
169
170	#define KUNCCheckBoxChecked(i) (1 << (8 + i)) /* can be used for radio's too */
171	#define KUNCPopUpSelection(n) (n << 24)
172
173	/*
174	* Callback function for KUNCNotifications
175	*/
176	typedef void
177	(*KUNCUserNotificationCallBack)(
178	int contextKey,
179	int responseFlags,
180	void *xmlData);
181
182	/*
183	* Get a notification ID
184	*/
185	KUNCUserNotificationID KUNCGetNotificationID();
186
187
188	/* 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. */
189
190	kern_return_t
191	KUNCUserNotificationDisplayFromBundle(
192	KUNCUserNotificationID notificationID,
193	char *bundleIdentifier,
194	char *fileName,
195	char *fileExtension,
196	char *messageKey,
197	char *tokenString,
198	KUNCUserNotificationCallBack callback,
199	int contextKey);
200
201
202	kern_return_t
203	KUNCUserNotificationCancel(
204	KUNCUserNotificationID notification);
205
206
207	__END_DECLS
208
209	#endif /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */