CFUserNotification.h

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