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

/*
 * Copyright (c) 2000-2004 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The 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, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_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             noticeTimeout,
	unsigned        flags,
	char            *iconPath,
	char            *soundPath,
	char            *localizationPath,
	char            *alertHeader,
	char            *alertMessage,
	char            *defaultButtonTitle) __attribute__((deprecated));

/*
 * ***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             alertTimeout,
	unsigned        flags,
	char            *iconPath,
	char            *soundPath,
	char            *localizationPath,
	char            *alertHeader,
	char            *alertMessage,
	char            *defaultButtonTitle,
	char            *alternateButtonTitle,
	char            *otherButtonTitle,
	unsigned        *responseFlags) __attribute__((deprecated));


/*
 * 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) __attribute__((deprecated));


/* 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)
 *                              corresponds to kCFUserNotificationAlertHeaderKey
 *
 * Icon URL			string (url of the icon to display)
 *                              corresponds to kCFUserNotificationIconURLKey
 *
 * Sound URL			string (url of the sound to play on display)
 *                              corresponds to kCFUserNotificationSoundURLKey
 *
 * Localization URL		string (url of bundle to retrieve localization
 *				info from, using Localizable.strings files)
 *                              corresponds to kCFUserNotificationLocalizationURLKey
 *
 * Message			string (text of the message, can contain %@'s
 *				which are filled from tokenString passed in)
 *                              corresponds to kCFUserNotificationAlertMessageKey
 *
 * OK Button Title              string (title of the "main" button)
 *                              corresponds to kCFUserNotificationDefaultButtonTitleKey
 *
 * Alternate Button Title       string (title of the "alternate" button,  usually cancel)
 *                              corresponds to kCFUserNotificationAlternateButtonTitleKey
 *
 * Other Button Title	        string (title of the "other" button)
 *                              corresponds to kCFUserNotificationOtherButtonTitleKey
 *
 * 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)
 *                              corresponds to kCFUserNotificationTextFieldTitlesKey
 *
 * 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)
 *                              corresponds to kCFUserNotificationCheckBoxTitlesKey
 *
 * 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 uintptr_t 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,
	const void      *xmlData);

/*
 * Get a notification ID
 */
KUNCUserNotificationID KUNCGetNotificationID(void) __attribute__((deprecated));

/* 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) __attribute__((deprecated));


kern_return_t
KUNCUserNotificationCancel(
	KUNCUserNotificationID  notification) __attribute__((deprecated));


__END_DECLS

#endif  /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */
Commit	Line	Data
1c79356b	1	/*
b0d623f7	2	* Copyright (c) 2000-2004 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745	5	*
2d21ac55 A	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.
0a7de745	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
2d21ac55 A	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745	17	*
2d21ac55 A	18	* The Original Code and all software distributed under the License are
2d21ac55 A	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
0a7de745	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	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(
0a7de745 A	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));
1c79356b A	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(
0a7de745 A	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));
b0d623f7	72
1c79356b A	73
	74	/*
	75	* Execute a userland executable with the given path, user and type
	76	*/
0a7de745 A	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
1c79356b A	86	kern_return_t
1c79356b A	87	KUNCExecute(
0a7de745 A	88	char *executionPath,
	89	int openAsUser,
	90	int pathExecutionType) __attribute__((deprecated));
1c79356b A	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)
0a7de745	104	* corresponds to kCFUserNotificationAlertHeaderKey
91447636	105	*
1c79356b	106	* Icon URL string (url of the icon to display)
0a7de745	107	* corresponds to kCFUserNotificationIconURLKey
91447636	108	*
1c79356b	109	* Sound URL string (url of the sound to play on display)
0a7de745	110	* corresponds to kCFUserNotificationSoundURLKey
91447636	111	*
1c79356b A	112	* Localization URL string (url of bundle to retrieve localization
1c79356b A	113	* info from, using Localizable.strings files)
0a7de745	114	* corresponds to kCFUserNotificationLocalizationURLKey
91447636	115	*
1c79356b	116	* Message string (text of the message, can contain %@'s
0a7de745 A	117	* which are filled from tokenString passed in)
0a7de745 A	118	* corresponds to kCFUserNotificationAlertMessageKey
91447636	119	*
0a7de745 A	120	* OK Button Title string (title of the "main" button)
0a7de745 A	121	* corresponds to kCFUserNotificationDefaultButtonTitleKey
91447636	122	*
0a7de745 A	123	* Alternate Button Title string (title of the "alternate" button, usually cancel)
0a7de745 A	124	* corresponds to kCFUserNotificationAlternateButtonTitleKey
91447636	125	*
0a7de745 A	126	* Other Button Title string (title of the "other" button)
0a7de745 A	127	* corresponds to kCFUserNotificationOtherButtonTitleKey
91447636	128	*
1c79356b A	129	* Timeout string (numeric, int - seconds until the dialog
1c79356b A	130	* goes away on it's own)
91447636 A	131	*
	132	* Alert Level string (Stop, Notice, Alert)
	133	*
1c79356b A	134	* Blocking Message string (numeric, 1 or 0 - if 1, the dialog will
1c79356b A	135	* have no buttons)
91447636	136	*
1c79356b	137	* Text Field Strings array of strings (each becomes a text field)
0a7de745	138	* corresponds to kCFUserNotificationTextFieldTitlesKey
91447636	139	*
1c79356b A	140	* Password Fields array of strings (numeric - each indicates a
1c79356b A	141	* pwd field)
91447636	142	*
1c79356b A	143	* Popup Button Strings array of strings (each entry becomes a popup
1c79356b A	144	* button string)
91447636	145	*
1c79356b	146	* Radio Button Strings array of strings (each becomes a radio button)
91447636	147	*
1c79356b	148	* Check Box Strings array of strings (each becomes a check box)
0a7de745	149	* corresponds to kCFUserNotificationCheckBoxTitlesKey
91447636	150	*
1c79356b	151	* Selected Radio string (numeric - which radio is selected)
91447636	152	*
1c79356b A	153	* Checked Boxes array of strings (numeric - each indicates a
1c79356b A	154	* checked field)
91447636	155	*
1c79356b	156	* Selected Popup string (numeric - which popup entry is selected)
91447636	157	*
1c79356b A	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")
0a7de745	172	* fileExtension
1c79356b A	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
b0d623f7	188	typedef uintptr_t KUNCUserNotificationID;
1c79356b A	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 {
0a7de745 A	199	kKUNCDefaultResponse = 0,
	200	kKUNCAlternateResponse = 1,
	201	kKUNCOtherResponse = 2,
	202	kKUNCCancelResponse = 3
1c79356b A	203	};
1c79356b A	204
0a7de745 A	205	#define KUNCCheckBoxChecked(i) (1 << (8 + i)) /* can be used for radio's too */
0a7de745 A	206	#define KUNCPopUpSelection(n) (n << 24)
1c79356b A	207
	208	/*
	209	* Callback function for KUNCNotifications
	210	*/
	211	typedef void
	212	(*KUNCUserNotificationCallBack)(
0a7de745 A	213	int contextKey,
	214	int responseFlags,
	215	const void *xmlData);
1c79356b A	216
	217	/*
	218	* Get a notification ID
	219	*/
b0d623f7	220	KUNCUserNotificationID KUNCGetNotificationID(void) __attribute__((deprecated));
1c79356b A	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(
0a7de745 A	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));
1c79356b A	234
	235
	236	kern_return_t
	237	KUNCUserNotificationCancel(
0a7de745	238	KUNCUserNotificationID notification) __attribute__((deprecated));
1c79356b A	239
	240
	241	__END_DECLS
	242
	243	#endif /* __USERNOTIFICATION_KUNCUSERNOTIFICATIONS_H */