1 /* Interface for <NSUserDefaults> for GNUStep 2 Copyright (C) 1995, 1996 Free Software Foundation, Inc. 3 4 Written by: Georg Tuparev, EMBL & Academia Naturalis, 5 Heidelberg, Germany 6 Tuparev@EMBL-Heidelberg.de 7 8 This file is part of the GNUstep Base Library. 9 10 This library is free software; you can redistribute it and/or 11 modify it under the terms of the GNU Lesser General Public 12 License as published by the Free Software Foundation; either 13 version 2 of the License, or (at your option) any later version. 14 15 This library is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 Lesser General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with this library; if not, write to the Free 22 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 23 MA 02111 USA. 24 */ 25 26 #ifndef __NSUserDefaults_h_OBJECTS_INCLUDE 27 #define __NSUserDefaults_h_OBJECTS_INCLUDE 28 #import <GNUstepBase/GSVersionMacros.h> 29 30 #import <Foundation/NSObject.h> 31 #import <Foundation/NSString.h> 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 @class NSArray; 38 @class NSMutableArray; 39 @class NSDictionary; 40 @class NSMutableDictionary; 41 @class NSData; 42 @class NSTimer; 43 @class NSRecursiveLock; 44 @class NSDistributedLock; 45 46 /* Standard domains */ 47 48 /** 49 * User defaults domain for process arguments. Command-line arguments 50 * (key-value pairs, as in "-NSFoo bar") are placed in this domain.<br /> 51 * Where there is a sequence of arguments beginning with '-', only the 52 * last one is used (so "-a -b -c d" will produce a single user default 53 * 'c' with value 'd').<br /> 54 * NB. On OSX the argument "-" means a key consisting of an empty string 55 * (so you can't use a '-' as a default value), while in GNUstep a "-" is 56 * a special case which does not mean a default key (so '-' may be used 57 * as a value).<br /> 58 */ 59 GS_EXPORT NSString* const NSArgumentDomain; 60 61 /** 62 * User defaults domain for system defaults. 63 */ 64 GS_EXPORT NSString* const NSGlobalDomain; 65 66 /** 67 * User defaults domain for application-registered "default defaults". 68 */ 69 GS_EXPORT NSString* const NSRegistrationDomain; 70 71 #if !NO_GNUSTEP 72 /** 73 * User defaults domain for GNUstep config file and for any defaults 74 * stored in the GlobalDefaults.plist file alongside the config file. 75 */ 76 GS_EXPORT NSString* const GSConfigDomain; 77 #endif 78 79 80 /* Public notification */ 81 82 /** 83 * Notification posted when a defaults synchronize has been performed (see 84 * [NSUserDefaults-synchronize]) and changes have been loaded in from disk. 85 */ 86 GS_EXPORT NSString* const NSUserDefaultsDidChangeNotification; 87 88 /* Backwards compatibility */ 89 #define NSUserDefaultsChanged NSUserDefaultsDidChangeNotification 90 91 /* Keys for language-dependent information */ 92 93 /** Key for locale dictionary: names of days of week. */ 94 GS_EXPORT NSString* const NSWeekDayNameArray; 95 96 /** Key for locale dictionary: abbreviations of days of week. */ 97 GS_EXPORT NSString* const NSShortWeekDayNameArray; 98 99 /** Key for locale dictionary: names of months of year. */ 100 GS_EXPORT NSString* const NSMonthNameArray; 101 102 /** Key for locale dictionary: abbreviations of months of year. */ 103 GS_EXPORT NSString* const NSShortMonthNameArray; 104 105 /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ 106 GS_EXPORT NSString* const NSTimeFormatString; 107 108 /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ 109 GS_EXPORT NSString* const NSDateFormatString; 110 111 /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ 112 GS_EXPORT NSString* const NSShortDateFormatString; 113 114 /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ 115 GS_EXPORT NSString* const NSTimeDateFormatString; 116 117 /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ 118 GS_EXPORT NSString* const NSShortTimeDateFormatString; 119 120 /** Key for locale dictionary: currency symbol. */ 121 GS_EXPORT NSString* const NSCurrencySymbol; 122 123 /** Key for locale dictionary: decimal separator. */ 124 GS_EXPORT NSString* const NSDecimalSeparator; 125 126 /** Key for locale dictionary: thousands separator. */ 127 GS_EXPORT NSString* const NSThousandsSeparator; 128 129 /** Key for locale dictionary: three-letter ISO 4217 currency abbreviation. */ 130 GS_EXPORT NSString* const NSInternationalCurrencyString; 131 132 /** Key for locale dictionary: text formatter string for monetary amounts. */ 133 GS_EXPORT NSString* const NSCurrencyString; 134 135 /** Key for locale dictionary: array of strings for 0-9. */ 136 GS_EXPORT NSString* const NSDecimalDigits; 137 138 /** Key for locale dictionary: array of strings for AM and PM. */ 139 GS_EXPORT NSString* const NSAMPMDesignation; 140 141 #if OS_API_VERSION(GSAPI_MACOSX, GS_API_LATEST) 142 143 /** 144 * Array of arrays of NSStrings, first member of each specifying a time, 145 * followed by one or more colloquial names for the time, as in "(0, 146 * midnight), (12, noon, lunch)". 147 */ 148 GS_EXPORT NSString* const NSHourNameDesignations; 149 150 /** Strings for "year", "month", "week". */ 151 GS_EXPORT NSString* const NSYearMonthWeekDesignations; 152 153 /** Key for locale dictionary: adjectives that modify values in 154 NSYearMonthWeekDesignations, as in "last", "previous", etc.. */ 155 GS_EXPORT NSString* const NSEarlierTimeDesignations; 156 157 /** Key for locale dictionary: adjectives that modify values in 158 NSYearMonthWeekDesignations, as in "next", "subsequent", etc.. */ 159 GS_EXPORT NSString* const NSLaterTimeDesignations; 160 161 /** Key for locale dictionary: one or more strings designating the current 162 day, such as "today". */ 163 GS_EXPORT NSString* const NSThisDayDesignations; 164 165 /** Key for locale dictionary: one or more strings designating the next 166 day, such as "tomorrow". */ 167 GS_EXPORT NSString* const NSNextDayDesignations; 168 169 /** Key for locale dictionary: one or more strings designating the next 170 day, such as "day after tomorrow". */ 171 GS_EXPORT NSString* const NSNextNextDayDesignations; 172 173 /** Key for locale dictionary: one or more strings designating the previous 174 day, such as "yesterday". */ 175 GS_EXPORT NSString* const NSPriorDayDesignations; 176 177 /** Key for locale dictionary: string with 'Y', 'M', 'D', and 'H' designating 178 the default method of writing dates, as in "MDYH" for the U.S.. */ 179 GS_EXPORT NSString* const NSDateTimeOrdering; 180 181 /** Key for locale dictionary: name of language. */ 182 GS_EXPORT NSString* const NSLanguageName; 183 184 /** Key for locale dictionary: two-letter ISO code. */ 185 GS_EXPORT NSString* const NSLanguageCode; 186 187 /** Key for locale dictionary: formal name of language. */ 188 GS_EXPORT NSString* const NSFormalName; 189 #if !NO_GNUSTEP 190 /** Key for locale dictionary: name of locale. */ 191 GS_EXPORT NSString* const GSLocale; 192 #endif 193 #endif 194 195 /* General implementation notes: 196 197 OpenStep spec currently is neither complete nor consistent. Therefore 198 we had to make several implementation decisions which may vary in 199 other OpenStep implementations. 200 201 - We add two new class methods for getting and setting a list of 202 user languages (userLanguages and setUserLanguages: ). They are 203 somehow equivalent to the NS3.x Application's systemLanguages 204 method. 205 206 - Definition of argument (command line parameters) 207 (-GSxxxx || --GSxxx) [value] 208 209 To Do: 210 - polish & optimize; 211 - when tested, fix NSBundle (the system languages stuff); 212 - write docs : -( 213 */ 214 215 @interface NSUserDefaults : NSObject 216 { 217 #if GS_EXPOSE(NSUserDefaults) 218 @private 219 NSMutableArray *_searchList; // Current search list; 220 NSMutableDictionary *_persDomains; // Contains persistent defaults info; 221 NSMutableDictionary *_tempDomains; // Contains volatile defaults info; 222 NSMutableArray *_changedDomains; /* ..after first time that persistent 223 user defaults are changed */ 224 NSDictionary *_dictionaryRep; // Cached dictionary representation 225 NSString *_defaultsDatabase; 226 NSDate *_lastSync; 227 NSRecursiveLock *_lock; 228 NSDistributedLock *_fileLock; 229 #endif 230 #if GS_NONFRAGILE 231 #else 232 /* Pointer to private additional data used to avoid breaking ABI 233 * when we don't have the non-fragile ABI available. 234 * Use this mechanism rather than changing the instance variable 235 * layout (see Source/GSInternal.h for details). 236 */ 237 @private id _internal GS_UNUSED_IVAR; 238 #endif 239 } 240 241 /** 242 * Returns the shared defaults object. If it doesn't exist yet, it's 243 * created. The defaults are initialized for the current user. 244 * The search list is guaranteed to be standard only the first time 245 * this method is invoked. The shared instance is provided as a 246 * convenience; other instances may also be created. 247 */ 248 + (NSUserDefaults*) standardUserDefaults; 249 250 #if OS_API_VERSION(GSAPI_MACOSX, GS_API_LATEST) 251 /** 252 * Resets the shared user defaults object to reflect the current 253 * user ID. Needed by setuid processes which change the user they 254 * are running as.<br /> 255 * In GNUstep you should call GSSetUserName() when changing your 256 * effective user ID, and that function will call this function for you. 257 */ 258 + (void) resetStandardUserDefaults; 259 #endif 260 261 #if OS_API_VERSION(GSAPI_NONE, GSAPI_NONE) 262 /** 263 * Returns the array of user languages preferences. Uses the 264 * <em>NSLanguages</em> user default if available, otherwise 265 * tries to infer setup from operating system information etc 266 * (in particular, uses the <em>LANGUAGES</em> environment variable). 267 */ 268 + (NSArray*) userLanguages; 269 270 /** 271 * Sets the array of user languages preferences. Places the specified 272 * array in the <em>NSLanguages</em> user default. 273 */ 274 + (void) setUserLanguages: (NSArray*)languages; 275 #endif 276 277 #if OS_API_VERSION(GSAPI_MACOSX, GS_API_LATEST) 278 /** 279 * Adds the domain names aName to the search list of the receiver.<br /> 280 * The domain is added after the application domain.<br /> 281 * Suites may be removed using the -removeSuiteNamed: method. 282 */ 283 - (void) addSuiteNamed: (NSString*)aName; 284 #endif 285 286 /** 287 * Looks up a value for a specified default using -objectForKey: 288 * and checks that it is an NSArray object. Returns nil if it is not. 289 */ 290 - (NSArray*) arrayForKey: (NSString*)defaultName; 291 292 /** 293 * Looks up a value for a specified default using -objectForKey: 294 * and returns its boolean representation.<br /> 295 * Returns NO if it is not a boolean.<br /> 296 * The text 'yes' or 'true' or any non zero numeric value is considered 297 * to be a boolean YES. Other string values are NO.<br /> 298 * NB. This differs slightly from the documented behavior for MacOS-X 299 * (August 2002) in that the GNUstep version accepts the string 'TRUE' 300 * as equivalent to 'YES'. 301 */ 302 - (BOOL) boolForKey: (NSString*)defaultName; 303 304 /** 305 * Looks up a value for a specified default using -objectForKey: 306 * and checks that it is an NSData object. Returns nil if it is not. 307 */ 308 - (NSData*) dataForKey: (NSString*)defaultName; 309 310 /** 311 * Looks up a value for a specified default using -objectForKey: 312 * and checks that it is an NSDictionary object. Returns nil if it is not. 313 */ 314 - (NSDictionary*) dictionaryForKey: (NSString*)defaultName; 315 316 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST) 317 /** 318 * Looks up a value for a specified default using -objectForKey: 319 * and checks that it is a double. Returns 0.0 if it is not. 320 */ 321 - (double) doubleForKey: (NSString*)defaultName; 322 #endif 323 324 /** 325 * Looks up a value for a specified default using -objectForKey: 326 * and checks that it is a float. Returns 0.0 if it is not. 327 */ 328 - (float) floatForKey: (NSString*)defaultName; 329 330 /** 331 * Initializes defaults for current user calling initWithUser: 332 */ 333 - (id) init; 334 335 /** <init /> 336 * Initializes defaults for the specified user.<br /> 337 * Returns an object with an empty search list. 338 */ 339 - (id) initWithUser: (NSString*)userName; 340 341 /** 342 * Looks up a value for a specified default using -objectForKey: 343 * and returns its integer value or 0 if it is not representable 344 * as an integer. 345 */ 346 - (NSInteger) integerForKey: (NSString*)defaultName; 347 348 /** 349 * Looks up a value for a specified default using. 350 * The lookup is performed by accessing the domains in the order 351 * given in the search list. 352 * <br />Returns nil if defaultName cannot be found. 353 */ 354 - (id) objectForKey: (NSString*)defaultName; 355 356 /** 357 * Removes the default with the specified name from the application 358 * domain. 359 */ 360 - (void) removeObjectForKey: (NSString*)defaultName; 361 362 #if OS_API_VERSION(GSAPI_MACOSX, GS_API_LATEST) 363 /** 364 * Removes the named domain from the search list of the receiver.<br /> 365 * Suites may be added using the -addSuiteNamed: method. 366 */ 367 - (void) removeSuiteNamed: (NSString*)aName; 368 #endif 369 370 /** 371 * Returns an array listing the domains searched in order to look up 372 * a value in the defaults system. The order of the names in the 373 * array is the order in which the domains are searched. 374 */ 375 - (NSArray*) searchList; 376 377 /** 378 * Sets a boolean value for defaultName in the application domain.<br /> 379 * Calls -setObject:forKey: to make the change by storing a string 380 * containing either the word YES or NO. 381 */ 382 - (void) setBool: (BOOL)value forKey: (NSString*)defaultName; 383 384 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST) 385 /** 386 * Sets a double value for defaultName in the application domain.<br /> 387 * Calls -setObject:forKey: to make the change by storing a double 388 * [NSNumber] instance. 389 */ 390 - (void) setDouble: (double)value forKey: (NSString*)defaultName; 391 #endif 392 393 /** 394 * Sets a float value for defaultName in the application domain.<br /> 395 * Calls -setObject:forKey: to make the change by storing a float 396 * [NSNumber] instance. 397 */ 398 - (void) setFloat: (float)value forKey: (NSString*)defaultName; 399 400 /** 401 * Sets an integer value for defaultName in the application domain.<br /> 402 * Calls -setObject:forKey: to make the change by storing an intege 403 * [NSNumber] instance. 404 */ 405 - (void) setInteger: (NSInteger)value forKey: (NSString*)defaultName; 406 407 /** 408 * Sets a copy of an object value for defaultName in the 409 * application domain.<br /> 410 * The defaultName must be a non-empty string.<br /> 411 * The value to be copied into the domain must be an instance 412 * of one of the [NSString-propertyList] classes.<br /> 413 * <p>Causes a NSUserDefaultsDidChangeNotification to be posted 414 * if this is the first change to a persistent-domain since the 415 * last -synchronize. 416 * </p> 417 * If value is nil, this is equivalent to the -removeObjectForKey: method. 418 */ 419 - (void) setObject: (id)value forKey: (NSString*)defaultName; 420 421 /** 422 * Sets the list of the domains searched in order to look up 423 * a value in the defaults system. The order of the names in the 424 * array is the order in which the domains are searched.<br /> 425 * On lookup, the first match is used. 426 */ 427 - (void) setSearchList: (NSArray*)newList; 428 429 /** 430 * Calls -arrayForKey: to get an array value for defaultName and checks 431 * that the array contents are string objects ... if not, returns nil. 432 */ 433 - (NSArray*) stringArrayForKey: (NSString*)defaultName; 434 435 /** 436 * Looks up a value for a specified default using -objectForKey: 437 * and checks that it is an NSString. Returns nil if it is not. 438 */ 439 - (NSString*) stringForKey: (NSString*)defaultName; 440 441 /** 442 * Returns the persistent domain specified by domainName. 443 */ 444 - (NSDictionary*) persistentDomainForName: (NSString*)domainName; 445 446 /** 447 * Returns an array listing the name of all the persistent domains. 448 */ 449 - (NSArray*) persistentDomainNames; 450 451 /** 452 * Removes the persistent domain specified by domainName from the 453 * user defaults. 454 * <br />Causes a NSUserDefaultsDidChangeNotification to be posted 455 * if this is the first change to a persistent-domain since the 456 * last -synchronize. 457 */ 458 - (void) removePersistentDomainForName: (NSString*)domainName; 459 460 /** 461 * Replaces the persistent-domain specified by domainName with 462 * domain ... a dictionary containing keys and defaults values. 463 * <br />Raises an NSInvalidArgumentException if domainName already 464 * exists as a volatile-domain. 465 * <br />Causes a NSUserDefaultsDidChangeNotification to be posted 466 * if this is the first change to a persistent-domain since the 467 * last -synchronize. 468 */ 469 - (void) setPersistentDomain: (NSDictionary*)domain 470 forName: (NSString*)domainName; 471 472 /** 473 * Ensures that the in-memory and on-disk representations of the defaults 474 * are in sync. You may call this yourself, but probably don't need to 475 * since it is invoked at intervals whenever a runloop is running.<br /> 476 * If any persistent domain is changed by reading new values from disk, 477 * an NSUserDefaultsDidChangeNotification is posted. 478 */ 479 - (BOOL) synchronize; 480 481 /** 482 * Removes the volatile domain specified by domainName from the 483 * user defaults. 484 */ 485 - (void) removeVolatileDomainForName: (NSString*)domainName; 486 487 /** 488 * Sets the volatile-domain specified by domainName to 489 * domain ... a dictionary containing keys and defaults values.<br /> 490 * Raises an NSInvalidArgumentException if domainName already 491 * exists as either a volatile-domain or a persistent-domain. 492 */ 493 - (void) setVolatileDomain: (NSDictionary*)domain 494 forName: (NSString*)domainName; 495 496 /** 497 * Returns the volatile domain specified by domainName. 498 */ 499 - (NSDictionary*) volatileDomainForName: (NSString*)domainName; 500 501 /** 502 * Returns an array listing the name of all the volatile domains. 503 */ 504 - (NSArray*) volatileDomainNames; 505 506 /** 507 * Returns a dictionary representing the current state of the defaults 508 * system ... this is a merged version of all the domains in the 509 * search list. 510 */ 511 - (NSDictionary*) dictionaryRepresentation; 512 513 /** 514 * Merges the contents of the dictionary newVals into the registration 515 * domain. Registration defaults may be added to or replaced using this 516 * method, but may never be removed. Thus, setting registration defaults 517 * at any point in your program guarantees that the defaults will be 518 * available thereafter. 519 */ 520 - (void) registerDefaults: (NSDictionary*)newVals; 521 @end 522 523 #if defined(__cplusplus) 524 } 525 #endif 526 527 #endif /* __NSUserDefaults_h_OBJECTS_INCLUDE */ 528