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