1/*
2 * Copyright (c) 2014 Apple Inc. All rights reserved.
3 *
4 * @APPLE_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. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24/*	CFUserNotification.h
25	Copyright (c) 2000-2013, Apple Inc.  All rights reserved.
26*/
27
28#if !defined(__COREFOUNDATION_CFUSERNOTIFICATION__)
29#define __COREFOUNDATION_CFUSERNOTIFICATION__ 1
30
31#include <CoreFoundation/CFBase.h>
32#include <CoreFoundation/CFDate.h>
33#include <CoreFoundation/CFDictionary.h>
34#include <CoreFoundation/CFString.h>
35#include <CoreFoundation/CFURL.h>
36#include <CoreFoundation/CFRunLoop.h>
37
38CF_EXTERN_C_BEGIN
39
40typedef struct __CFUserNotification * CFUserNotificationRef;
41
42/* A CFUserNotification is a notification intended to be presented to a
43user at the console (if one is present).  This is for the use of processes
44that do not otherwise have user interfaces, but may need occasional
45interaction with a user.  There is a parallel API for this functionality
46at the System framework level, described in UNCUserNotification.h.
47
48The contents of the notification can include a header, a message, textfields,
49a popup button, radio buttons or checkboxes, a progress indicator, and up to
50three ordinary buttons.  All of these items are optional, but a default
51button will be supplied even if not specified unless the
52kCFUserNotificationNoDefaultButtonFlag is set.
53
54The contents of the notification are specified in the dictionary used to
55create the notification, whose keys should be taken from the list of constants
56below, and whose values should be either strings or arrays of strings
57(except for kCFUserNotificationProgressIndicatorValueKey, in which case the
58value should be a number between 0 and 1, for a "definite" progress indicator,
59or a boolean, for an "indefinite" progress indicator).  Additionally, URLs can
60optionally be supplied for an icon, a sound, and a bundle whose Localizable.strings
61files will be used to localize strings.
62
63Certain request flags are specified when a notification is created.
64These specify an alert level for the notification, determine whether
65radio buttons or check boxes are to be used, specify which if any of these
66are checked by default, specify whether any of the textfields are to
67be secure textfields, and determine which popup item should be selected
68by default.  A timeout is also specified, which determines how long the
69notification should be supplied to the user (if zero, it will not timeout).
70
71A CFUserNotification is dispatched for presentation when it is created.
72If any reply is required, it may be awaited in one of two ways:  either
73synchronously, using CFUserNotificationReceiveResponse, or asynchronously,
74using a run loop source.  CFUserNotificationReceiveResponse has a timeout
75parameter that determines how long it will block (zero meaning indefinitely)
76and it may be called as many times as necessary until a response arrives.
77If a notification has not yet received a response, it may be updated with
78new information, or it may be cancelled.  Notifications may not be reused.
79
80When a response arrives, it carries with it response flags that describe
81which button was used to dismiss the notification, which checkboxes or
82radio buttons were checked, and what the selection of the popup was.
83It also carries a response dictionary, which describes the contents
84of the textfields.  */
85
86typedef void (*CFUserNotificationCallBack)(CFUserNotificationRef userNotification, CFOptionFlags responseFlags);
87
88CF_EXPORT
89CFTypeID CFUserNotificationGetTypeID(void);
90
91CF_EXPORT
92CFUserNotificationRef CFUserNotificationCreate(CFAllocatorRef allocator, CFTimeInterval timeout, CFOptionFlags flags, SInt32 *error, CFDictionaryRef dictionary);
93
94CF_EXPORT
95SInt32 CFUserNotificationReceiveResponse(CFUserNotificationRef userNotification, CFTimeInterval timeout, CFOptionFlags *responseFlags);
96
97CF_EXPORT
98CFStringRef CFUserNotificationGetResponseValue(CFUserNotificationRef userNotification, CFStringRef key, CFIndex idx);
99
100CF_EXPORT
101CFDictionaryRef CFUserNotificationGetResponseDictionary(CFUserNotificationRef userNotification);
102
103CF_EXPORT
104SInt32 CFUserNotificationUpdate(CFUserNotificationRef userNotification, CFTimeInterval timeout, CFOptionFlags flags, CFDictionaryRef dictionary);
105
106CF_EXPORT
107SInt32 CFUserNotificationCancel(CFUserNotificationRef userNotification);
108
109CF_EXPORT
110CFRunLoopSourceRef CFUserNotificationCreateRunLoopSource(CFAllocatorRef allocator, CFUserNotificationRef userNotification, CFUserNotificationCallBack callout, CFIndex order);
111
112/* Convenience functions for handling the simplest and most common cases:
113a one-way notification, and a notification with up to three buttons. */
114
115CF_EXPORT
116SInt32 CFUserNotificationDisplayNotice(CFTimeInterval timeout, CFOptionFlags flags, CFURLRef iconURL, CFURLRef soundURL, CFURLRef localizationURL, CFStringRef alertHeader, CFStringRef alertMessage, CFStringRef defaultButtonTitle);
117
118CF_EXPORT
119SInt32 CFUserNotificationDisplayAlert(CFTimeInterval timeout, CFOptionFlags flags, CFURLRef iconURL, CFURLRef soundURL, CFURLRef localizationURL, CFStringRef alertHeader, CFStringRef alertMessage, CFStringRef defaultButtonTitle, CFStringRef alternateButtonTitle, CFStringRef otherButtonTitle, CFOptionFlags *responseFlags);
120
121
122/* Flags */
123
124enum {
125    kCFUserNotificationStopAlertLevel 		= 0,
126    kCFUserNotificationNoteAlertLevel 		= 1,
127    kCFUserNotificationCautionAlertLevel 	= 2,
128    kCFUserNotificationPlainAlertLevel		= 3
129};
130
131enum {
132    kCFUserNotificationDefaultResponse		= 0,
133    kCFUserNotificationAlternateResponse	= 1,
134    kCFUserNotificationOtherResponse		= 2,
135    kCFUserNotificationCancelResponse		= 3
136};
137
138enum {
139    kCFUserNotificationNoDefaultButtonFlag 	= (1UL << 5),
140    kCFUserNotificationUseRadioButtonsFlag 	= (1UL << 6)
141};
142
143CF_INLINE CFOptionFlags CFUserNotificationCheckBoxChecked(CFIndex i) {return ((CFOptionFlags)(1UL << (8 + i)));}
144CF_INLINE CFOptionFlags CFUserNotificationSecureTextField(CFIndex i) {return ((CFOptionFlags)(1UL << (16 + i)));}
145CF_INLINE CFOptionFlags CFUserNotificationPopUpSelection(CFIndex n) {return ((CFOptionFlags)(n << 24));}
146
147
148/* Keys */
149
150CF_EXPORT
151const CFStringRef kCFUserNotificationIconURLKey;
152
153CF_EXPORT
154const CFStringRef kCFUserNotificationSoundURLKey;
155
156CF_EXPORT
157const CFStringRef kCFUserNotificationLocalizationURLKey;
158
159CF_EXPORT
160const CFStringRef kCFUserNotificationAlertHeaderKey;
161
162CF_EXPORT
163const CFStringRef kCFUserNotificationAlertMessageKey;
164
165CF_EXPORT
166const CFStringRef kCFUserNotificationDefaultButtonTitleKey;
167
168CF_EXPORT
169const CFStringRef kCFUserNotificationAlternateButtonTitleKey;
170
171CF_EXPORT
172const CFStringRef kCFUserNotificationOtherButtonTitleKey;
173
174CF_EXPORT
175const CFStringRef kCFUserNotificationProgressIndicatorValueKey;
176
177CF_EXPORT
178const CFStringRef kCFUserNotificationPopUpTitlesKey;
179
180CF_EXPORT
181const CFStringRef kCFUserNotificationTextFieldTitlesKey;
182
183CF_EXPORT
184const CFStringRef kCFUserNotificationCheckBoxTitlesKey;
185
186CF_EXPORT
187const CFStringRef kCFUserNotificationTextFieldValuesKey;
188
189CF_EXPORT
190const CFStringRef kCFUserNotificationPopUpSelectionKey	CF_AVAILABLE(10_3, NA);
191
192#if (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
193CF_EXPORT
194const CFStringRef kCFUserNotificationAlertTopMostKey;
195
196CF_EXPORT
197const CFStringRef kCFUserNotificationKeyboardTypesKey;
198#endif
199
200CF_EXTERN_C_END
201
202#endif /* ! __COREFOUNDATION_CFUSERNOTIFICATION__ */
203
204