CFError Reference

Derived from	CFType Reference
Framework	CoreFoundation/CoreFoundation.h
Companion guide	Error Handling Programming Guide
Declared in	CFError.h

Overview

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 by Task

Creating a CFError

Getting Information About an Error

Getting the CFError Type ID

Functions

CFErrorCopyDescription

Returns a human-presentable description for a given error.

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:

If the value in the user info dictionary for kCFErrorLocalizedDescriptionKey is not NULL, returns that value as-is.
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
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.

Availability

Available in OS X v10.5 and later.

Related Sample Code

Declared In

CFError.h

CFErrorCopyFailureReason

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

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorCopyRecoverySuggestion

Returns a human presentable recovery suggestion for a given error.

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorCopyUserInfo

Returns the user info dictionary for a given CFError.

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorCreate

Creates a new CFError object.

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorCreateWithUserInfoKeysAndValues

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

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorGetCode

Returns the error code for a given CFError.

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorGetDomain

Returns the error domain for a given CFError.

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.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

CFErrorGetTypeID

Returns the type identifier for the CFError opaque type.

CFTypeID CFErrorGetTypeID (
   void
);

Return Value

The type identifier for the CFError opaque type.

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

Data Types

CFErrorRef

A reference to a CFError object.

typedef struct __CFError * CFErrorRef;

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

Constants

Error domains

These constants define domains for CFError objects.

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

Constants

kCFErrorDomainPOSIX

A constant that specified the POSIX domain.

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorDomainOSStatus

A constant that specified the OS domain.

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorDomainMach

A constant that specified the Mach domain.

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorDomainCocoa

A constant that specified the Cocoa domain.

Available in OS X v10.5 and later.

Declared in CFError.h.

Discussion

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

Availability

Available in OS X v10.5 and later.

Declared In

CFError.h

Keys for the user info dictionary

Keys in the userInfo dictionary.

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

Constants

kCFErrorLocalizedDescriptionKey

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

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorLocalizedFailureReasonKey

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

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorLocalizedRecoverySuggestionKey

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

Available in OS X v10.5 and later.

Declared in CFError.h.

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 OS X v10.5 and later.

Declared in CFError.h.

kCFErrorUnderlyingErrorKey

Key to identify the underlying error in the userInfo dictionary.

Available in OS X v10.5 and later.

Declared in CFError.h.

kCFErrorURLKey

Key to identify associated URL in the userInfo dictionary.

Available in OS X v10.7 and later.

Declared in CFError.h.

kCFErrorFilePathKey

Key to identify associated file path in the userInfo dictionary.

Available in OS X v10.7 and later.

Declared in CFError.h.

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.

Declared In

CFError.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.