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/* CFError.h 25 Copyright (c) 2006-2013, Apple Inc. All rights reserved. 26*/ 27 28/*! 29 @header CFError 30 @discussion 31 CFErrors are used to encompass information about errors. At minimum, errors are identified by their domain (a string) and an error code within that domain. In addition a "userInfo" dictionary supplied at creation time enables providing additional info that might be useful for the interpretation and reporting of the error. This dictionary can even contain an "underlying" error, which is wrapped as an error bubbles up through various layers. 32 33 CFErrors have the ability to provide human-readable descriptions for the errors; in fact, they are designed to provide localizable, end-user presentable errors that can appear in the UI. CFError has a number of predefined userInfo keys to enable developers to supply the info. 34 35 Usage recommendation for CFErrors is to return them as by-ref parameters in functions. This enables the caller to pass NULL in when they don't actually want information about the error. The presence of an error should be reported by other means, for instance a NULL or false return value from the function call proper: 36 37 CFError *error; 38 if (!ReadFromFile(fd, &error)) { 39 ... process error ... 40 CFRelease(error); // If an error occurs, the returned CFError must be released. 41 } 42 43 It is the responsibility of anyone returning CFErrors this way to: 44 - Not touch the error argument if no error occurs 45 - Create and assign the error for return only if the error argument is non-NULL 46 47 In addition, it's recommended that CFErrors be used in error situations only (not status), and where there are multiple possible errors to distinguish between. For instance there is no plan to add CFErrors to existing APIs in CF which currently don't return errors; in many cases, there is one possible reason for failure, and a false or NULL return is enough to indicate it. 48 49 CFError is toll-free bridged to NSError in Foundation. NSError in Foundation has some additional guidelines which makes it easy to automatically report errors to users and even try to recover from them. See http://developer.apple.com/documentation/Cocoa/Conceptual/ErrorHandlingCocoa/ErrorHandling/chapter_1_section_1.html for more info on NSError programming guidelines. 50*/ 51 52#if !defined(__COREFOUNDATION_CFERROR__) 53#define __COREFOUNDATION_CFERROR__ 1 54 55#include <CoreFoundation/CFBase.h> 56#include <CoreFoundation/CFString.h> 57#include <CoreFoundation/CFDictionary.h> 58 59CF_IMPLICIT_BRIDGING_ENABLED 60CF_EXTERN_C_BEGIN 61 62/*! 63 @typedef CFErrorRef 64 This is the type of a reference to CFErrors. CFErrorRef is toll-free bridged with NSError. 65*/ 66typedef struct __CFError * CFErrorRef; 67 68/*! 69 @function CFErrorGetTypeID 70 Returns the type identifier of all CFError instances. 71*/ 72CF_EXPORT 73CFTypeID CFErrorGetTypeID(void) CF_AVAILABLE(10_5, 2_0); 74 75 76// Predefined domains; value of "code" will correspond to preexisting values in these domains. 77CF_EXPORT const CFStringRef kCFErrorDomainPOSIX CF_AVAILABLE(10_5, 2_0); 78CF_EXPORT const CFStringRef kCFErrorDomainOSStatus CF_AVAILABLE(10_5, 2_0); 79CF_EXPORT const CFStringRef kCFErrorDomainMach CF_AVAILABLE(10_5, 2_0); 80CF_EXPORT const CFStringRef kCFErrorDomainCocoa CF_AVAILABLE(10_5, 2_0); 81 82// Keys in userInfo for localizable, end-user presentable error messages. At minimum provide one of first two; ideally provide all three. 83CF_EXPORT const CFStringRef kCFErrorLocalizedDescriptionKey CF_AVAILABLE(10_5, 2_0); // Key to identify the end user-presentable description in userInfo. 84CF_EXPORT const CFStringRef kCFErrorLocalizedFailureReasonKey CF_AVAILABLE(10_5, 2_0); // Key to identify the end user-presentable failure reason in userInfo. 85CF_EXPORT const CFStringRef kCFErrorLocalizedRecoverySuggestionKey CF_AVAILABLE(10_5, 2_0); // Key to identify the end user-presentable recovery suggestion in userInfo. 86 87// If you do not have localizable error strings, you can provide a value for this key instead. 88CF_EXPORT const CFStringRef kCFErrorDescriptionKey CF_AVAILABLE(10_5, 2_0); // Key to identify the description in the userInfo dictionary. Should be a complete sentence if possible. Should not contain domain name or error code. 89 90// Other keys in userInfo. 91CF_EXPORT const CFStringRef kCFErrorUnderlyingErrorKey CF_AVAILABLE(10_5, 2_0); // Key to identify the underlying error in userInfo. 92CF_EXPORT const CFStringRef kCFErrorURLKey CF_AVAILABLE(10_7, 5_0); // Key to identify associated URL in userInfo. Typically one of this or kCFErrorFilePathKey is provided. 93CF_EXPORT const CFStringRef kCFErrorFilePathKey CF_AVAILABLE(10_7, 5_0); // Key to identify associated file path in userInfo. Typically one of this or kCFErrorURLKey is provided. 94 95 96/*! 97 @function CFErrorCreate 98 @abstract Creates a new CFError. 99 @param allocator The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the 100 current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined. 101 @param domain A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined. 102 @param code A CFIndex identifying the error code. The code is interpreted within the context of the error domain. 103 @param userInfo A CFDictionary created with kCFCopyStringDictionaryKeyCallBacks and kCFTypeDictionaryValueCallBacks. It will be copied with CFDictionaryCreateCopy(). 104 If no userInfo dictionary is desired, NULL may be passed in as a convenience, in which case an empty userInfo dictionary will be assigned. 105 @result A reference to the new CFError. 106*/ 107CF_EXPORT 108CFErrorRef CFErrorCreate(CFAllocatorRef allocator, CFStringRef domain, CFIndex code, CFDictionaryRef userInfo) CF_AVAILABLE(10_5, 2_0); 109 110/*! 111 @function CFErrorCreateWithUserInfoKeysAndValues 112 @abstract Creates a new CFError without having to create an intermediate userInfo dictionary. 113 @param allocator The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the 114 current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined. 115 @param domain A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined. 116 @param code A CFIndex identifying the error code. The code is interpreted within the context of the error domain. 117 @param userInfoKeys An array of numUserInfoValues CFStrings used as keys in creating the userInfo dictionary. NULL is valid only if numUserInfoValues is 0. 118 @param userInfoValues An array of numUserInfoValues CF types used as values in creating the userInfo dictionary. NULL is valid only if numUserInfoValues is 0. 119 @param numUserInfoValues CFIndex representing the number of keys and values in the userInfoKeys and userInfoValues arrays. 120 @result A reference to the new CFError. numUserInfoValues CF types are gathered from each of userInfoKeys and userInfoValues to create the userInfo dictionary. 121*/ 122CF_EXPORT 123CFErrorRef CFErrorCreateWithUserInfoKeysAndValues(CFAllocatorRef allocator, CFStringRef domain, CFIndex code, const void *const *userInfoKeys, const void *const *userInfoValues, CFIndex numUserInfoValues) CF_AVAILABLE(10_5, 2_0); 124 125/*! 126 @function CFErrorGetDomain 127 @abstract Returns the error domain the CFError was created with. 128 @param err The CFError whose error domain is to be returned. If this reference is not a valid CFError, the behavior is undefined. 129 @result The error domain of the CFError. Since this is a "Get" function, the caller shouldn't CFRelease the return value. 130*/ 131CF_EXPORT 132CFStringRef CFErrorGetDomain(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 133 134/*! 135 @function CFErrorGetCode 136 @abstract Returns the error code the CFError was created with. 137 @param err The CFError whose error code is to be returned. If this reference is not a valid CFError, the behavior is undefined. 138 @result The error code of the CFError (not an error return for the current call). 139*/ 140CF_EXPORT 141CFIndex CFErrorGetCode(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 142 143/*! 144 @function CFErrorCopyUserInfo 145 @abstract Returns CFError userInfo dictionary. 146 @discussion Returns a dictionary containing the same keys and values as in the userInfo dictionary the CFError was created with. Returns an empty dictionary if NULL was supplied to CFErrorCreate(). 147 @param err The CFError whose error user info is to be returned. If this reference is not a valid CFError, the behavior is undefined. 148 @result The user info of the CFError. 149*/ 150CF_EXPORT 151CFDictionaryRef CFErrorCopyUserInfo(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 152 153/*! 154 @function CFErrorCopyDescription 155 @abstract Returns a human-presentable description for the error. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedDescriptionKey at the time of CFError creation. 156 @discussion This is a complete sentence or two which says what failed and why it failed. Rules for computing the return value: 157 - Look for kCFErrorLocalizedDescriptionKey in the user info and if not NULL, returns that as-is. 158 - Otherwise, if there is a kCFErrorLocalizedFailureReasonKey in the user info, generate an error from that. Something like: "Operation code not be completed. " + kCFErrorLocalizedFailureReasonKey 159 - Otherwise, generate a semi-user presentable string from kCFErrorDescriptionKey, the domain, and code. Something like: "Operation could not be completed. Error domain/code occurred. " or "Operation could not be completed. " + kCFErrorDescriptionKey + " (Error domain/code)" 160 Toll-free bridged NSError instances might provide additional behaviors for manufacturing a description string. Do not count on the exact contents or format of the returned string, it might change. 161 @param err The CFError whose description is to be returned. If this reference is not a valid CFError, the behavior is undefined. 162 @result A CFString with human-presentable description of the CFError. Never NULL. 163*/ 164CF_EXPORT 165CFStringRef CFErrorCopyDescription(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 166 167/*! 168 @function CFErrorCopyFailureReason 169 @abstract Returns a human-presentable failure reason for the error. May return NULL. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedFailureReasonKey at the time of CFError creation. 170 @discussion This is a complete sentence which describes why the operation failed. In many cases this will be just the "because" part of the description (but as a complete sentence, which makes localization easier). By default this looks for kCFErrorLocalizedFailureReasonKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL. 171 Example Description: "Could not save file 'Letter' in folder 'Documents' because the volume 'MyDisk' doesn't have enough space." 172 Corresponding FailureReason: "The volume 'MyDisk' doesn't have enough space." 173 @param err The CFError whose failure reason is to be returned. If this reference is not a valid CFError, the behavior is undefined. 174 @result A CFString with the localized, end-user presentable failure reason of the CFError, or NULL. 175*/ 176CF_EXPORT 177CFStringRef CFErrorCopyFailureReason(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 178 179/*! 180 @function CFErrorCopyRecoverySuggestion 181 @abstract Returns a human presentable recovery suggestion for the error. May return NULL. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedRecoverySuggestionKey at the time of CFError creation. 182 @discussion This is the string that can be displayed as the "informative" (aka "secondary") message on an alert panel. By default this looks for kCFErrorLocalizedRecoverySuggestionKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL. 183 Example Description: "Could not save file 'Letter' in folder 'Documents' because the volume 'MyDisk' doesn't have enough space." 184 Corresponding RecoverySuggestion: "Remove some files from the volume and try again." 185 @param err The CFError whose recovery suggestion is to be returned. If this reference is not a valid CFError, the behavior is undefined. 186 @result A CFString with the localized, end-user presentable recovery suggestion of the CFError, or NULL. 187*/ 188CF_EXPORT 189CFStringRef CFErrorCopyRecoverySuggestion(CFErrorRef err) CF_AVAILABLE(10_5, 2_0); 190 191 192 193CF_EXTERN_C_END 194CF_IMPLICIT_BRIDGING_DISABLED 195 196#endif /* ! __COREFOUNDATION_CFERROR__ */ 197 198