AppServices.subproj/CFUserNotification.h

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