---

NSError

Overview

NSError encapsulates richer and more extensible error information than is possible using only an error code or error string. The core attributes of an NSError are an error domain (represented by a string), a domain-specific error code and a user info dictionary containing application specific information.

Several well-known domains are defined corresponding to Mach, POSIX, and OSStatus errors. In addition, NSError allows an arbitrary user info dictionary to be specified, and provides the means to return a human-readable description for the error.

NSError is not an abstract class, and can be used directly. Applications may choose to create subclasses of NSError to provide better localized error strings by overriding localizedDescription.

In general, the presence of an error should be indicated by other means, for example by returning false or null from the method. The method can then optionally return an NSError object by-reference, in order to further describe the error.

Tasks

Constructors

• NSError

Getting Error Properties

• code
• domain
• userInfo

Getting a Localized Error Description

• localizedDescription
• localizedRecoveryOptions
• localizedRecoverySuggestion
• localizedFailureReason

Getting the Error Recovery Attempter

• recoveryAttempter

Instance Methods

code

Returns the receiver’s error code.

public int code()

Discussion

Note that errors are domain specific.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• localizedDescription
• domain
• userInfo

domain

Returns a string containing the receiver’s error domain.

public String domain()

Availability

• Available in Mac OS X v10.3 and later.

See Also

• code
• localizedDescription
• userInfo

localizedDescription

Returns a string containing the localized description of the error.

public String localizedDescription()

Discussion

By default this method will attempt to return the object in the user info dictionary for the key LocalizedDescriptionKey. If the user info dictionary doesn’t contain a value for LocalizedDescriptionKey, a default string will be constructed from the domain and code.

This method can be overridden by subclasses to present customized error strings.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• code
• domain
• userInfo

localizedFailureReason

Returns a string containing the localized explanation of the reason for the error.

public String localizedFailureReason()

Discussion

By default this method will attempt to return the object in the user info dictionary for the key LocalizedFailureReasonErrorKey.

This method can be overridden by subclasses to present customized error strings.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• code
• domain
• userInfo

localizedRecoveryOptions

Returns an array containing the localized titles of buttons appropriate for displaying in an alert panel.

public Array localizedRecoveryOptions()

Discussion

The first string is the title of the right-most and default button, the second the one to the left, and so on. The recovery options should be appropriate for the recovery suggestion returned by localizedRecoverySuggestion. By default this method will attempt to return the object in the user info dictionary for the key LocalizedRecoveryOptionsErrorKey. If the user info dictionary doesn’t contain a value for LocalizedRecoveryOptionsErrorKey, null is returned and only an OK button is displayed..

This method can be overridden by subclasses to present customized recovery suggestion strings.

Availability

• Available in Mac OS X 10.4 and later.

localizedRecoverySuggestion

Returns a string containing the localized recovery suggestion for the error.

public String localizedRecoverySuggestion()

Discussion

This string is suitable for displaying as the secondary message in an alert panel. By default this method will attempt to return the object in the user info dictionary for the key LocalizedRecoverySuggestionErrorKey. If the user info dictionary doesn’t contain a value for LocalizedRecoverySuggestionErrorKey, null is returned.

This method can be overridden by subclasses to present customized recovery suggestion strings.

Availability

• Available in Mac OS X v10.4 and later.

recoveryAttempter

Returns an object that conforms to the NSErrorRecoveryAttempting informal protocol.

public Object recoverAttempter()

Discussion

The recovery attempter must be an object that can correctly interpret an index into the array returned by localizedRecoveryOptions. By default this method will attempt to return the object for the user info dictionary for the key RecoveryAttempterErrorKey. If the user info dictionary doesn’t contain a value for RecoveryAttempterErrorKey, null is returned.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• localizedRecoveryOptions

userInfo

Returns an NSDictionary containing the user info associated with the receiver or null if the user info dictionary has not been set.

public NSDictionary userInfo()

Availability

• Available in Mac OS X v10.3 and later.

See Also

• code
• domain
• localizedDescription

Constants

The following keys may exist in the user info dictionary:

The following error domains are predefined:

---