CFError.h

   1 /*
   2  * Copyright (c) 2012 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-2012, 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
  59 CF_IMPLICIT_BRIDGING_ENABLED
  60 CF_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 */
  66 typedef struct __CFError * CFErrorRef;
  67
  68 /*!
  69         @function CFErrorGetTypeID
  70             Returns the type identifier of all CFError instances.
  71 */
  72 CF_EXPORT
  73 CFTypeID CFErrorGetTypeID(void) CF_AVAILABLE(10_5, 2_0);
  74
  75
  76 // Predefined domains; value of "code" will correspond to preexisting values in these domains.
  77 CF_EXPORT const CFStringRef kCFErrorDomainPOSIX             CF_AVAILABLE(10_5, 2_0);
  78 CF_EXPORT const CFStringRef kCFErrorDomainOSStatus          CF_AVAILABLE(10_5, 2_0);
  79 CF_EXPORT const CFStringRef kCFErrorDomainMach              CF_AVAILABLE(10_5, 2_0);
  80 CF_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.
  83 CF_EXPORT const CFStringRef kCFErrorLocalizedDescriptionKey         CF_AVAILABLE(10_5, 2_0);   // Key to identify the end user-presentable description in userInfo.
  84 CF_EXPORT const CFStringRef kCFErrorLocalizedFailureReasonKey       CF_AVAILABLE(10_5, 2_0);   // Key to identify the end user-presentable failure reason in userInfo.
  85 CF_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.
  88 CF_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.
  91 CF_EXPORT const CFStringRef kCFErrorUnderlyingErrorKey              CF_AVAILABLE(10_5, 2_0);   // Key to identify the underlying error in userInfo.
  92 CF_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.
  93 CF_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 */
 107 CF_EXPORT
 108 CFErrorRef 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 */
 122 CF_EXPORT
 123 CFErrorRef 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 */
 131 CF_EXPORT
 132 CFStringRef 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 */
 140 CF_EXPORT
 141 CFIndex 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 */
 150 CF_EXPORT
 151 CFDictionaryRef 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 */
 164 CF_EXPORT
 165 CFStringRef 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 */
 176 CF_EXPORT
 177 CFStringRef 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 */
 188 CF_EXPORT
 189 CFStringRef CFErrorCopyRecoverySuggestion(CFErrorRef err) CF_AVAILABLE(10_5, 2_0);
 190
 191
 192
 193 CF_EXTERN_C_END
 194 CF_IMPLICIT_BRIDGING_DISABLED
 195
 196 #endif /* ! __COREFOUNDATION_CFERROR__ */
 197