iOS Developer Library — Pre-Release

Developer

CoreFoundation Framework Reference CFError Reference

Options
Deployment Target:

On This Page
Language:

CFError Reference

A CFError object encapsulates more rich and extensible error information than is possible using only an error code or error string. The core attributes of a CFError object are an error domain (represented by a string), a domain-specific error code, and a “user info” dictionary containing application-specific information. Errors are required to have a domain and an error code within that domain. Several well-known domains are defined corresponding to Mach, POSIX, and OSStatus errors.

The optional “user info” dictionary may provide additional information that might be useful for the interpretation and reporting of the error, including a human-readable description for the error. The “user info” dictionary sometimes includes another CFError object that represents an error in a subsystem underlying the error represented by the containing CFError object. This underlying error object may provide more specific information about the cause of the error.

In general, a method should signal an error condition by returning, for example, false or NULL rather than by the simple presence of an error object. The method can then optionally return an CFError object by reference, in order to further describe the error.

CFError is toll-free bridged to NSError in the Foundation framework—for more details on toll-free bridging, see Toll-Free Bridged Types. NSError has some additional guidelines that make it easy to report errors automatically to users and attempt to recover from them. See Error Handling Programming Guide for more information on NSError programming guidelines.

Functions

  • Creates a new CFError object.

    Declaration

    Swift

    func CFErrorCreate(_ allocator: CFAllocator!, _ domain: CFString!, _ code: CFIndex, _ userInfo: CFDictionary!) -> CFError!

    Objective-C

    CFErrorRef CFErrorCreate ( CFAllocatorRef allocator, CFStringRef domain, CFIndex code, CFDictionaryRef userInfo );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    domain

    A CFString that identifies the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.

    code

    A CFIndex that identifies the error code. The code is interpreted within the context of the error domain.

    userInfo

    A CFDictionary created with kCFCopyStringDictionaryKeyCallBacks and kCFTypeDictionaryValueCallBacks. The dictionary is copied with CFDictionaryCreateCopy. If you do not want the userInfo dictionary, you can pass NULL, in which case an empty dictionary will be assigned.

    Return Value

    A new CFError object. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates a new CFError object using given keys and values to create the user info dictionary.

    Declaration

    Swift

    func CFErrorCreateWithUserInfoKeysAndValues(_ allocator: CFAllocator!, _ domain: CFString!, _ code: CFIndex, _ userInfoKeys: UnsafePointer<UnsafePointer<Void>>, _ userInfoValues: UnsafePointer<UnsafePointer<Void>>, _ numUserInfoValues: CFIndex) -> CFError!

    Objective-C

    CFErrorRef CFErrorCreateWithUserInfoKeysAndValues ( CFAllocatorRef allocator, CFStringRef domain, CFIndex code, const void *const *userInfoKeys, const void *const *userInfoValues, CFIndex numUserInfoValues );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    domain

    A CFString that identifies the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.

    code

    A CFIndex that identifies the error code. The code is interpreted within the context of the error domain.

    userInfoKeys

    An array of numUserInfoValues CFStrings used as keys in creating the userInfo dictionary. The value of this parameter can be NULL if numUserInfoValues is 0.

    userInfoValues

    An array of numUserInfoValues CF types used as values in creating the userInfo dictionary. The value of this parameter can be NULL if numUserInfoValues is 0.

    numUserInfoValues

    The number of keys and values in the userInfoKeys and userInfoValues arrays.

    Return Value

    A new CFError object. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the error domain for a given CFError.

    Declaration

    Swift

    func CFErrorGetDomain(_ err: CFError!) -> CFString!

    Objective-C

    CFStringRef CFErrorGetDomain ( CFErrorRef err );

    Parameters

    err

    The error to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    The error domain for err. Ownership follows the Get Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the error code for a given CFError.

    Declaration

    Swift

    func CFErrorGetCode(_ err: CFError!) -> CFIndex

    Objective-C

    CFIndex CFErrorGetCode ( CFErrorRef err );

    Parameters

    err

    The error to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    The error code of err.

    Discussion

    Note that this function returns the error code for the specified CFError, not an error return for the current call.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the user info dictionary for a given CFError.

    Declaration

    Swift

    func CFErrorCopyUserInfo(_ err: CFError!) -> CFDictionary!

    Objective-C

    CFDictionaryRef CFErrorCopyUserInfo ( CFErrorRef err );

    Parameters

    err

    The error to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    A dictionary containing the same keys and values as in the userInfo dictionary err was created with. Returns an empty dictionary if NULL was supplied to the create function. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a human-presentable description for a given error.

    Declaration

    Swift

    func CFErrorCopyDescription(_ err: CFError!) -> CFString!

    Objective-C

    CFStringRef CFErrorCopyDescription ( CFErrorRef err );

    Parameters

    err

    The CFError to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    A localized, human-presentable description of err. This function never returns NULL. Ownership follows the Create Rule.

    Discussion

    This is a complete sentence or two which says what failed and why it failed. The structure of the description depends on the details provided in the user info dictionary. The rules for computing the return value are as follows:

    1. If the value in the user info dictionary for kCFErrorLocalizedDescriptionKey is not NULL, returns that value as-is.

    2. If the value in the user info dictionary for kCFErrorLocalizedFailureReasonKey is not NULL, generate an error from that.

      The description is something like: "Operation could not be completed. " + kCFErrorLocalizedFailureReasonKey

    3. Generate as good a user-presentable string as possible from kCFErrorDescriptionKey, the domain, and code.

      The description is something like like: "Operation could not be completed. Error domain/code occurred. " or "Operation could not be completed. " + kCFErrorDescriptionKey + " (Error domain/code)"

    Toll-free bridged instances of NSError might provide additional behaviors for manufacturing a description string.

    You should not depend on the exact contents or format of the returned string, as it might change in different releases of the operating system.

    When you create a CFError, you should try to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedDescriptionKey in the user info dictionary.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a human-presentable failure reason for a given error.

    Declaration

    Swift

    func CFErrorCopyFailureReason(_ err: CFError!) -> CFString!

    Objective-C

    CFStringRef CFErrorCopyFailureReason ( CFErrorRef err );

    Parameters

    err

    The CFError to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    A localized, human-presentable failure reason for err, or NULL if no user-presentable string is available. Ownership follows the Create Rule.

    Discussion

    The failure reason 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). For example, an error description "Could not save file 'Letter' in folder 'Documents' because the volume 'MyDisk' doesn't have enough space." might have a corresponding failure reason, "The volume 'MyDisk' doesn't have enough space."

    By default, this function looks for a value for the kCFErrorLocalizedFailureReasonKey key in the user info dictionary. Toll-free bridged instances of NSError might provide additional behaviors for manufacturing this value.

    When you create a CFError, you should try to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedFailureReasonKey in the user info dictionary.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a human presentable recovery suggestion for a given error.

    Declaration

    Swift

    func CFErrorCopyRecoverySuggestion(_ err: CFError!) -> CFString!

    Objective-C

    CFStringRef CFErrorCopyRecoverySuggestion ( CFErrorRef err );

    Parameters

    err

    The CFError to examine. If this is not a valid CFError, the behavior is undefined.

    Return Value

    A localized, human-presentable recovery suggestion for err, or NULL if no user-presentable string is available. Ownership follows the Create Rule.

    Discussion

    This is the string that can be displayed as the “informative” (or “secondary”) message on an alert panel. For example, an error description “Could not save file ‘Letter’ in folder ‘Documents’ because the volume ‘MyDisk’ doesn’t have enough space.“ might have a corresponding recovery suggestion, “Remove some files from the volume and try again.“

    By default, this function looks for a value for the kCFErrorLocalizedRecoverySuggestionKey key in the user info dictionary. Toll-free bridged instances of NSError might provide additional behaviors for manufacturing this value.

    When you create a CFError, you should try to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedRecoverySuggestionKey in the user info dictionary.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier for the CFError opaque type.

    Declaration

    Swift

    func CFErrorGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFErrorGetTypeID ( void );

    Return Value

    The type identifier for the CFError opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Data Types

Miscellaneous

  • A reference to a CFError object.

    Declaration

    Swift

    typealias CFErrorRef = CFError

    Objective-C

    typedef struct __CFError * CFErrorRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Constants

  • These constants define domains for CFError objects.

    Declaration

    Swift

    let kCFErrorDomainPOSIX: CFString! let kCFErrorDomainOSStatus: CFString! let kCFErrorDomainMach: CFString! let kCFErrorDomainCocoa: CFString!

    Objective-C

    const CFStringRef kCFErrorDomainPOSIX; const CFStringRef kCFErrorDomainOSStatus; const CFStringRef kCFErrorDomainMach; const CFStringRef kCFErrorDomainCocoa;

    Constants

    • kCFErrorDomainPOSIX

      kCFErrorDomainPOSIX

      A constant that specified the POSIX domain.

      Available in iOS 2.0 and later.

    • kCFErrorDomainOSStatus

      kCFErrorDomainOSStatus

      A constant that specified the OS domain.

      Available in iOS 2.0 and later.

    • kCFErrorDomainMach

      kCFErrorDomainMach

      A constant that specified the Mach domain.

      Available in iOS 2.0 and later.

    • kCFErrorDomainCocoa

      kCFErrorDomainCocoa

      A constant that specified the Cocoa domain.

      Available in iOS 2.0 and later.

    Discussion

    The value of "code" will correspond to preexisting values in these domains.

  • Keys in the userInfo dictionary.

    Declaration

    Swift

    let kCFErrorLocalizedDescriptionKey: CFString! let kCFErrorLocalizedFailureReasonKey: CFString! let kCFErrorLocalizedRecoverySuggestionKey: CFString! let kCFErrorDescriptionKey: CFString! let kCFErrorUnderlyingErrorKey: CFString! let kCFErrorURLKey: CFString! let kCFErrorFilePathKey: CFString!

    Objective-C

    const CFStringRef kCFErrorLocalizedDescriptionKey; const CFStringRef kCFErrorLocalizedFailureReasonKey; const CFStringRef kCFErrorLocalizedRecoverySuggestionKey; const CFStringRef kCFErrorDescriptionKey; const CFStringRef kCFErrorUnderlyingErrorKey; const CFStringRef kCFErrorURLKey; const CFStringRef kCFErrorFilePathKey;

    Constants

    • kCFErrorLocalizedDescriptionKey

      kCFErrorLocalizedDescriptionKey

      Key to identify the end user-presentable description in the userInfo dictionary.

      Available in iOS 2.0 and later.

    • kCFErrorLocalizedFailureReasonKey

      kCFErrorLocalizedFailureReasonKey

      Key to identify the end user-presentable failure reason in the userInfo dictionary.

      Available in iOS 2.0 and later.

    • kCFErrorLocalizedRecoverySuggestionKey

      kCFErrorLocalizedRecoverySuggestionKey

      Key to identify the end user-presentable recovery suggestion in the userInfo dictionary.

      Available in iOS 2.0 and later.

    • kCFErrorDescriptionKey

      kCFErrorDescriptionKey

      Key to identify the description in the userInfo dictionary.

      When you create a CFError object, you can provide a value for this key if you do not have localizable error strings. The description should be a complete sentence if possible, and should not contain the domain name or error code.

      Available in iOS 2.0 and later.

    • kCFErrorUnderlyingErrorKey

      kCFErrorUnderlyingErrorKey

      Key to identify the underlying error in the userInfo dictionary.

      Available in iOS 2.0 and later.

    • kCFErrorURLKey

      kCFErrorURLKey

      Key to identify associated URL in the userInfo dictionary.

      Available in iOS 5.0 and later.

    • kCFErrorFilePathKey

      kCFErrorFilePathKey

      Key to identify associated file path in the userInfo dictionary.

      Available in iOS 5.0 and later.

    Discussion

    When you create a user info dictionary, at a minimum you should provide values for one of kCFErrorLocalizedDescriptionKey and kCFErrorLocalizedFailureReasonKey; ideally you should provide values for kCFErrorLocalizedDescriptionKey, kCFErrorLocalizedFailureReasonKey, and kCFErrorLocalizedRecoverySuggestionKey. Typically, you should provide a value for one of either kCFErrorURLKey or kCFErrorFilePathKey.