Every program must deal with errors as they occur at runtime. The program, for example, might not be able to open a file, or perhaps it cannot parse an XML document. Often errors such as these require the program to inform the user about them. And perhaps the program can attempt to get around the problem causing the error.
Cocoa (and Cocoa Touch) offer developers programmatic tools for these tasks: the NSError class in Foundation and new methods and mechanisms in the Application Kit to support error handling in applications. An NSError object encapsulates information specific to an error, including the domain (subsystem) originating the error and the localized strings to present in an error alert. With an application there is also an architecture allowing the various objects in an application to refine the information in an error object and perhaps to recover from the error. This document describes this API and architecture and explains how to use them.
Important: The NSError class is available on both Mac OS X and iPhone OS. However, the error-responder and error-recovery APIs and mechanisms are available only in the Application Kit (Mac OS X).
Although the NSError class was introduced in Mac OS X v10.3, several methods have been added to the class and to the Application Kit in Mac OS X v10.4 to support error handling as described in this document.
Error Handling Programming Guide for Cocoa has the following articles:
“Error Objects, Domains, and Codes” describes the attributes of an NSError object, particularly its domain and error code, and discusses the possible contents of an error object’s “user info” dictionary, including localized message strings and underlying errors.
“Using and Creating Error Objects” explains how to evaluate an error, how to display an error message using an NSError object, and how to implement methods that return an NSError object by reference.
“Error Responders and Error Recovery” describes the Application Kit architecture for passing error objects up a chain of objects in an application, giving each object a chance to customize the error before it is presented. It also discusses the role of the recovery attempter, an object designated to attempt a recovery from an error if the user requests it.
“Handling Received Errors” discusses how, in the chain of error-responder objects, you handle a received error and customize it.
“Recovering From Errors” explains the procedure for attempting a user-requested recovery from an error.
The two chapters relevant to iPhone OS are “Error Objects, Domains, and Codes” and “Using and Creating Error Objects.”
“Error Handling in the Document Architecture" in Document-Based Applications Overview offers valuable advice for subclasses that override methods with a by-reference NSError parameter (Mac OS X).
“Types of Dialogs and When to Use Them” in Apple Human Interface Guidelines offers advice on the form and content of alerts in Mac OS X. Alerts, Action Sheets, and Modal Views offers similar advice for alerts on iPhone OS. You should consult these guidelines before composing your error messages. Also take a look at the following documents discussing areas of Cocoa programming related to error handling and the presentation of error messages:
Assertions and Logging (both platforms)
Dialogs and Special Panels (alerts on Mac OS X))
Sheet Programming Topics for Cocoa (Mac OS X)
UIAlertView Class Reference (iPhone OS)
Exception Programming Topics for Cocoa discusses how to raise and handle exceptions. Exception Handling in The Objective-C Programming Language describes the compiler directives @try, @catch, @throw, and @finally, which are used in exception handling.
Last updated: 2009-08-18
