Note: The definitions shown here are not always the actual definitons and therefore might not compile.

NS_ERROR_ENUM / CF_ERROR_ENUM

Declares an error domain.

Availability (SDKs)

  • Mac OS X >= 10.13 High Sierra

  • swift-corelibs-foundation >= 4.1

Declaration

#define NS_ERROR_ENUM(...) CF_ENUM(__VA_ARGS__)
#define CF_ERROR_ENUM(_domain) /* ... */
#define CF_ERROR_ENUM(_domain, _name) /* ... */

Parameters

NSString* _domain
The name of the error domain.

identifier _name (optional)
The name of the generated typedef.

Equivalent attributes

__attribute__((ns_error_domain(_domain)))

where _domain is one of the paramaters.

Discussion

In Cocoa frameworks in Objective-C, one can group related error codes in enums and categorize these enums with error domains.

The ns_error_domain attribute indicates a global NSString or CFString constant representing the error domain that an error code belongs to. For pointer uniqueness and code size this is a constant symbol, not a literal.

The domain and error code need to be used together. The ns_error_domain attribute links error codes to their domain at the source level.

This metadata is useful for documentation purposes, for static analysis, and for improving interoperability between Objective-C and Swift. It is not used for code generation in Objective-C.

For example:

extern NSString *const MyErrorDomain;
typedef NS_ERROR_ENUM(unsigned char, MyErrorEnum, MyErrorDomain) {
    MyErrFirst,
    MyErrSecond,
};

CF_ERROR_ENUM and NS_ERROR_ENUM support the use of one or two arguments. The first argument (_domain) is always the domain specifier for the enum. The second argument (_name) is an optional type name for the macro.

When specifying a type name, you must precede the macro with typedef. This will result in a typename being produced with the type NSInteger or CFIndex and the name _name. For example:

typedef NS_ERROR_ENUM(MyErrorDomain, SomeErrorCodes) {
    ...
};

will produce a typedef:

typedef NSInteger SomeErrorCodes;

If you do not specify a type name, do not use typedef before the macro. For example:

NS_ENUM(NSInteger) {
    ...
};

will not produce a type name.

The macro adds compiler attributes and the underlying integer type to the enum declaration when using a recent version of Clang.

Importing into Swift

References

<CoreFoundation/CFAvailability.h>
<Foundation/NSObjCRuntime.h>
__attribute(ns_error_domain)__