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