CFUserNotification.h

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