GrabbaErrorCode Class Reference

Description

Representation of error codes and messages used throughout the iOS APIs.

For operations performing communications (directly or indirectly), or any other activities in which error cases are anticipated, this class is used to notify the caller whether the operation completed successfully or whether an error was detected.

Internally it stores an error code (or GrabbaNoError if everything is OK) plus an error message; these are both set when an error is detected and can be queried later on.

Most methods taking a parameter of this class support chaining - that is, they will check the state before proceeding, and then only proceed if it is GrabbaNoError. This allows chaining of consecutive operations without needing to check for errors after each one, by passing the same error code object to all of them.

The error property may be used to check whether an error occurred, for example:

GrabbaErrorCode err = [GrabbaErrorCode errorCode];
[MyObject DoSomething:err];
if (err.Error)
{
     [self HandleError:err.Details];
}

For cases requiring a more sophisticated approach, the value and description properties provide additional detail about the error code, the message property provides access to the error message if there is one, and the details property provides all available information in string form.

Note

All property values are passed by copy; a new copy of the value will be generated each time a property is read.

Thread safety:

• Concurrent accesses to distinct objects: safe
• Concurrent accesses to the same object: unsafe, unless all accesses are read-only (i.e. property reads)

Inheritance diagram for GrabbaErrorCode:

Instance Methods
(instancetype _Nullable)	- init
	Create an error code object in the default state - no error, empty message. More...
(instancetype _Nullable)	- initWithValue:message:
	Create an error code object with a given error value and message string. More...
(void)	- reset
	Reset the error code to the default state. More...
(void)	- set:message:
	Set the error code to a new state. More...
(NSError *_Nonnull)	- toNSError
	Generate a copy of the error code object in NSError format. More...

Class Methods
(NSString *_Nonnull)	+ defaultMessage
	Obtain the default message string. More...
(GrabbaErrorCodeValue)	+ defaultValue
	Obtain the default error code value. More...
(instancetype _Nullable)	+ errorCode
	Allocate and create an error code object in the default state - no error, empty message. More...
(instancetype _Nullable)	+ errorCodeWithValue:message:
	Allocate and create an error code object with a given error value and message string. More...
(NSString *const _Nonnull)	+ grabbaErrorDomain
	Grabba error domain name string, as used by toNSError. More...

Properties
NSString *_Nonnull	description
	Copy of current error description; this will be "No error" if no error condition has yet been flagged. More...
NSString *_Nonnull	details
	Copy of formatted error message, encoding both the error value and the message string. More...
BOOL	error
	Does this object represent an error condition? More...
NSString *_Nonnull	message
	Copy of current error message; this will be an empty string if no message has yet been set. More...
GrabbaErrorCodeValue	value
	Current error code ID; this will be GrabbaNoError if no error condition has yet been flagged. More...

Method Documentation

defaultMessage()

+ (NSString* _Nonnull) defaultMessage

Obtain the default message string.

defaultValue()

+ (GrabbaErrorCodeValue) defaultValue

Obtain the default error code value.

errorCode()

+ (instancetype _Nullable) errorCode

Allocate and create an error code object in the default state - no error, empty message.

This is a convenience wrapper for init, handling allocation as well as initialisation.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

errorCodeWithValue:message:()

+ (instancetype _Nullable) errorCodeWithValue:		(GrabbaErrorCodeValue)	value
message:		(NSString *_Nonnull)	message

Allocate and create an error code object with a given error value and message string.

This is a convenience wrapper for initWithValue, handling allocation as well as initialisation.

Parameters

value	Error code value - GrabbaNoError indicates all OK; other values indicate error conditions
message	Error message string

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

grabbaErrorDomain()

+ (NSString *const _Nonnull) grabbaErrorDomain

Grabba error domain name string, as used by toNSError.

Returns

Pointer to the error domain name string; all calls to this method will return the same address

init()

- (instancetype _Nullable) init

Create an error code object in the default state - no error, empty message.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

initWithValue:message:()

- (instancetype _Nullable) initWithValue:		(GrabbaErrorCodeValue)	value
message:		(NSString *_Nonnull)	message

Create an error code object with a given error value and message string.

Parameters

value	Error code value - GrabbaNoError indicates all OK; other values indicate error conditions
message	Error message string

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

reset()

- (void) reset

Reset the error code to the default state.

set:message:()

- (void) set:		(GrabbaErrorCodeValue)	value
message:		(NSString *_Nonnull)	message

Set the error code to a new state.

Parameters

value	Error code value; see GrabbaErrorCodeValue for the list of supported values
message	Error message string

toNSError()

- (NSError* _Nonnull) toNSError

Generate a copy of the error code object in NSError format.

The generated object will include the following information:

• Code - numeric equivalent to value property
• Domain - set to grabbaErrorDomain
• Error description - set to description property
• Failure reason - set to message property

Returns

Generated NSError object; note that a new object will be generated for each call to this method

Property Documentation

description

- (NSString* _Nonnull) description

readnonatomiccopy

Copy of current error description; this will be "No error" if no error condition has yet been flagged.

Note that this does not include the associated message; use the details property instead if you wish for that to be included.

details

- (NSString* _Nonnull) details

readnonatomiccopy

Copy of formatted error message, encoding both the error value and the message string.

error

- (BOOL) error

readnonatomicassign

Does this object represent an error condition?

This property will contain NO if the value property holds GrabbaNoError, or YES otherwise.

message

- (NSString* _Nonnull) message

readnonatomiccopy

Copy of current error message; this will be an empty string if no message has yet been set.

value

- (GrabbaErrorCodeValue) value

readnonatomicassign

Current error code ID; this will be GrabbaNoError if no error condition has yet been flagged.