CFUserNotification.h

   1 /*
   2  * Copyright (c) 2008 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-2007, 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      = (1 << 5),
 139     kCFUserNotificationUseRadioButtonsFlag      = (1 << 6)
 140 };
 141
 142 CF_INLINE CFOptionFlags CFUserNotificationCheckBoxChecked(CFIndex i) {return ((CFOptionFlags)(1 << (8 + i)));}
 143 CF_INLINE CFOptionFlags CFUserNotificationSecureTextField(CFIndex i) {return ((CFOptionFlags)(1 << (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 CF_EXTERN_C_END
 194
 195 #endif /* ! __COREFOUNDATION_CFUSERNOTIFICATION__ */
 196