iOS/Pods/Realm/include/RLMRealmConfiguration.h

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2015 Realm Inc.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the "License");
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 ////////////////////////////////////////////////////////////////////////////
  18
  19 #import <Foundation/Foundation.h>
  20 #import <Realm/RLMRealm.h>
  21
  22 NS_ASSUME_NONNULL_BEGIN
  23
  24 /**
  25  A block called when opening a Realm for the first time during the life
  26  of a process to determine if it should be compacted before being returned
  27  to the user. It is passed the total file size (data + free space) and the total
  28  bytes used by data in the file.
  29
  30  Return `YES` to indicate that an attempt to compact the file should be made.
  31  The compaction will be skipped if another process is accessing it.
  32  */
  33 typedef BOOL (^RLMShouldCompactOnLaunchBlock)(NSUInteger totalBytes, NSUInteger bytesUsed);
  34
  35 /**
  36  An `RLMRealmConfiguration` instance describes the different options used to
  37  create an instance of a Realm.
  38
  39  `RLMRealmConfiguration` instances are just plain `NSObject`s. Unlike `RLMRealm`s
  40  and `RLMObject`s, they can be freely shared between threads as long as you do not
  41  mutate them.
  42
  43  Creating configuration objects for class subsets (by setting the
  44  `objectClasses` property) can be expensive. Because of this, you will normally want to
  45  cache and reuse a single configuration object for each distinct configuration rather than
  46  creating a new object each time you open a Realm.
  47  */
  48 @interface RLMRealmConfiguration : NSObject<NSCopying>
  49
  50 #pragma mark - Default Configuration
  51
  52 /**
  53  Returns the default configuration used to create Realms when no other
  54  configuration is explicitly specified (i.e. `+[RLMRealm defaultRealm]`).
  55
  56  @return The default Realm configuration.
  57  */
  58 + (instancetype)defaultConfiguration;
  59
  60 /**
  61  Sets the default configuration to the given `RLMRealmConfiguration`.
  62
  63  @param configuration The new default Realm configuration.
  64  */
  65 + (void)setDefaultConfiguration:(RLMRealmConfiguration *)configuration;
  66
  67 #pragma mark - Properties
  68
  69 /// The local URL of the Realm file. Mutually exclusive with `inMemoryIdentifier` and `syncConfiguration`;
  70 /// setting any one of the three properties will automatically nil out the other two.
  71 @property (nonatomic, copy, nullable) NSURL *fileURL;
  72
  73 /// A string used to identify a particular in-memory Realm. Mutually exclusive with `fileURL` and `syncConfiguration`;
  74 /// setting any one of the three properties will automatically nil out the other two.
  75 @property (nonatomic, copy, nullable) NSString *inMemoryIdentifier;
  76
  77 /// A 64-byte key to use to encrypt the data, or `nil` if encryption is not enabled.
  78 @property (nonatomic, copy, nullable) NSData *encryptionKey;
  79
  80 /// Whether to open the Realm in read-only mode.
  81 ///
  82 /// This is required to be able to open Realm files which are not writeable or
  83 /// are in a directory which is not writeable. This should only be used on files
  84 /// which will not be modified by anyone while they are open, and not just to
  85 /// get a read-only view of a file which may be written to by another thread or
  86 /// process. Opening in read-only mode requires disabling Realm's reader/writer
  87 /// coordination, so committing a write transaction from another process will
  88 /// result in crashes.
  89 @property (nonatomic) BOOL readOnly;
  90
  91 /// The current schema version.
  92 @property (nonatomic) uint64_t schemaVersion;
  93
  94 /// The block which migrates the Realm to the current version.
  95 @property (nonatomic, copy, nullable) RLMMigrationBlock migrationBlock;
  96
  97 /**
  98  Whether to recreate the Realm file with the provided schema if a migration is required.
  99  This is the case when the stored schema differs from the provided schema or
 100  the stored schema version differs from the version on this configuration.
 101  Setting this property to `YES` deletes the file if a migration would otherwise be required or executed.
 102
 103  @note Setting this property to `YES` doesn't disable file format migrations.
 104  */
 105 @property (nonatomic) BOOL deleteRealmIfMigrationNeeded;
 106
 107 /**
 108  A block called when opening a Realm for the first time during the life
 109  of a process to determine if it should be compacted before being returned
 110  to the user. It is passed the total file size (data + free space) and the total
 111  bytes used by data in the file.
 112
 113  Return `YES` to indicate that an attempt to compact the file should be made.
 114  The compaction will be skipped if another process is accessing it.
 115  */
 116 @property (nonatomic, copy, nullable) RLMShouldCompactOnLaunchBlock shouldCompactOnLaunch;
 117
 118 /// The classes managed by the Realm.
 119 @property (nonatomic, copy, nullable) NSArray *objectClasses;
 120
 121 @end
 122
 123 NS_ASSUME_NONNULL_END