1 /** Interface for NSError for GNUStep 2 Copyright (C) 2004,2006 Free Software Foundation, Inc. 3 4 Written by: Richard Frith-Macdonald <rfm@gnu.org> 5 Date: May 2004 6 7 This file is part of the GNUstep Base Library. 8 9 This library is free software; you can redistribute it and/or 10 modify it under the terms of the GNU Lesser General Public 11 License as published by the Free Software Foundation; either 12 version 2 of the License, or (at your option) any later version. 13 14 This library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free 21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 22 Boston, MA 02110 USA. 23 24 AutogsdocSource: NSError.m 25 */ 26 27 #ifndef __NSError_h_GNUSTEP_BASE_INCLUDE 28 #define __NSError_h_GNUSTEP_BASE_INCLUDE 29 #import <GNUstepBase/GSVersionMacros.h> 30 31 #import <Foundation/NSObject.h> 32 33 #if OS_API_VERSION(MAC_OS_X_VERSION_10_3,GS_API_LATEST) 34 35 #if defined(__cplusplus) 36 extern "C" { 37 #endif 38 39 @class NSArray, NSDictionary, NSString; 40 41 typedef NSString* NSErrorDomain; 42 43 /** 44 * Key for user info dictionary component which describes the error in 45 * a human readable format. 46 */ 47 GS_EXPORT NSString* const NSLocalizedDescriptionKey; 48 49 /** 50 * Where one error has caused another, the underlying error can be stored 51 * in the user info dictionary using this key. 52 */ 53 GS_EXPORT NSString* const NSUnderlyingErrorKey; 54 55 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) 56 /** 57 * This key can be used to store the file path of a resource involved 58 * in the error (eg unreadable file). 59 */ 60 GS_EXPORT NSString* const NSFilePathErrorKey; 61 /** 62 * Key for an [NSNumber] containing an NSStringEncoding value. 63 */ 64 GS_EXPORT NSString* const NSStringEncodingErrorKey; 65 /** 66 * This can be used to store the URLK involved in the error. 67 */ 68 GS_EXPORT NSString* const NSURLErrorKey; 69 /** 70 * Key to store a string describing what caused the error to occur. 71 */ 72 GS_EXPORT NSString* const NSLocalizedFailureReasonErrorKey; 73 /** 74 * Key to store an [NSArray] of strings suitable for use as the 75 * titles of buttons in an alert panel used to attempt error 76 * recovery in a GUI application. 77 */ 78 GS_EXPORT NSString* const NSLocalizedRecoveryOptionsErrorKey; 79 /** 80 * Key to store a string providing a hint on how to use the buttons 81 * in an alert panel. 82 */ 83 GS_EXPORT NSString* const NSLocalizedRecoverySuggestionErrorKey; 84 /** 85 * Key to store an object which can be used to attempt to recover from 86 * the error. 87 */ 88 GS_EXPORT NSString* const NSRecoveryAttempterErrorKey; 89 #endif 90 91 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6,GS_API_LATEST) 92 /** 93 * NSURL to indicate the URL which did not load, in the NSURLErrorDomain. 94 */ 95 GS_EXPORT NSString* const NSURLErrorFailingURLErrorKey; 96 97 /** 98 * NSString in the NSURLDomain to indicate the object for the URL that did not load. 99 * This supersedes NSErrorFailingURLStringKey 100 */ 101 GS_EXPORT NSString* const NSURLErrorFailingURLStringErrorKey; 102 103 #endif 104 105 /** 106 * Domain for system errors (on MACH). 107 */ 108 GS_EXPORT NSErrorDomain const NSMACHErrorDomain; 109 /** 110 * Domain for system errors. 111 */ 112 GS_EXPORT NSErrorDomain const NSOSStatusErrorDomain; 113 /** 114 * Domain for system and system library errors. 115 */ 116 GS_EXPORT NSErrorDomain const NSPOSIXErrorDomain; 117 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) 118 /** 119 * Domain for Foundation and AppKit (base and gui) errors. 120 */ 121 GS_EXPORT NSErrorDomain const NSCocoaErrorDomain; 122 #endif 123 124 /** 125 * Error information class.<br /> 126 * NSError instances are used to pass information about runtime errors 127 * from lower levels to higher levels of the program.<br /> 128 * These should be used instead of exceptions where an error is caused 129 * by external factors (such as a resource file not being present) 130 * rather than a programming error (where NSException should be used). 131 */ 132 @interface NSError : NSObject <NSCopying, NSCoding> 133 { 134 #if GS_EXPOSE(NSError) 135 @private 136 int _code; 137 NSString *_domain; 138 NSDictionary *_userInfo; 139 #endif 140 #if GS_NONFRAGILE 141 #else 142 /* Pointer to private additional data used to avoid breaking ABI 143 * when we don't have the non-fragile ABI available. 144 * Use this mechanism rather than changing the instance variable 145 * layout (see Source/GSInternal.h for details). 146 */ 147 @private id _internal GS_UNUSED_IVAR; 148 #endif 149 } 150 151 /** 152 * Creates and returns an autoreleased NSError instance by calling 153 * -initWithDomain:code:userInfo: 154 */ 155 + (id) errorWithDomain: (NSErrorDomain)aDomain 156 code: (NSInteger)aCode 157 userInfo: (NSDictionary*)aDictionary; 158 159 /** 160 * Return the error code ... which is not globally unique, just unique for 161 * a particular domain. 162 */ 163 - (NSInteger) code; 164 165 /** 166 * Return the domain for this instance. 167 */ 168 - (NSErrorDomain) domain; 169 170 /** <init /> 171 * Initialises the receiver using the supplied domain, code, and info.<br /> 172 * The domain must be non-nil. 173 */ 174 - (id) initWithDomain: (NSErrorDomain)aDomain 175 code: (NSInteger)aCode 176 userInfo: (NSDictionary*)aDictionary; 177 178 /** 179 * Return a human readable description for the error.<br /> 180 * The default implementation uses the value from the user info dictionary 181 * if it is available, otherwise it generates a generic one from domain 182 * and code. 183 */ 184 - (NSString *) localizedDescription; 185 186 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) 187 /** 188 * Return a human readable explanation of the reason for the error 189 * (if known). This should normally be a more discursive explanation 190 * then the short one provided by the -localizedDescription method.<br /> 191 * The default implementation uses the value from the user info dictionary 192 * if it is available, otherwise it returns nil. 193 */ 194 - (NSString *) localizedFailureReason; 195 196 /** 197 * Returns an array of strings to be used as titles of buttons in an 198 * alert panel when offering the user optionbs to try to recover from 199 * the error.<br /> 200 * The default implementation uses the value from the user info dictionary 201 * if it is available, otherwise it returns nil. 202 */ 203 - (NSArray *) localizedRecoveryOptions; 204 205 /** 206 * Returns a string used as the secondary text in an alert panel, 207 * suggesting how the user might select an option to attempt to 208 * recover from the error.<br /> 209 * The default implementation uses the value from the user info dictionary 210 * if it is available, otherwise it returns nil. 211 */ 212 - (NSString *) localizedRecoverySuggestion; 213 214 /** 215 * Not yet useful in GNUstep.<br /> 216 * The default implementation uses the value from the user info dictionary 217 * if it is available, otherwise it returns nil. 218 */ 219 - (id) recoveryAttempter; 220 #endif 221 222 /** 223 * Return the user info for this instance (or nil if none is set)<br /> 224 * The <code>NSLocalizedDescriptionKey</code> should locate a human readable 225 * description in the dictionary.<br /> 226 * The <code>NSUnderlyingErrorKey</code> key should locate an 227 * <code>NSError</code> instance if an error is available describing any 228 * underlying problem.<br /> 229 */ 230 - (NSDictionary*) userInfo; 231 @end 232 233 #if defined(__cplusplus) 234 } 235 #endif 236 237 #endif 238 239 #endif /* __NSError_h_GNUSTEP_BASE_INCLUDE*/ 240