iOS/Pods/Realm/include/core/realm/group_shared_options.hpp

   1 /*************************************************************************
   2  *
   3  * Copyright 2016 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 #ifndef REALM_GROUP_SHARED_OPTIONS_HPP
  20 #define REALM_GROUP_SHARED_OPTIONS_HPP
  21
  22 #include <functional>
  23 #include <string>
  24
  25 namespace realm {
  26
  27 struct SharedGroupOptions {
  28
  29     /// The persistence level of the SharedGroup.
  30     /// uint16_t is the type of SharedGroup::SharedInfo::durability
  31     enum class Durability : uint16_t {
  32         Full,
  33         MemOnly,
  34         Async ///< Not yet supported on windows.
  35     };
  36
  37     explicit SharedGroupOptions(Durability level = Durability::Full, const char* key = nullptr,
  38                                 bool allow_upgrade = true,
  39                                 std::function<void(int, int)> file_upgrade_callback = std::function<void(int, int)>(),
  40                                 std::string temp_directory = sys_tmp_dir,
  41                                 bool track_metrics = false)
  42         : durability(level)
  43         , encryption_key(key)
  44         , allow_file_format_upgrade(allow_upgrade)
  45         , upgrade_callback(file_upgrade_callback)
  46         , temp_dir(temp_directory)
  47         , enable_metrics(track_metrics)
  48
  49     {
  50     }
  51
  52     explicit SharedGroupOptions(const char* key)
  53         : durability(Durability::Full)
  54         , encryption_key(key)
  55         , allow_file_format_upgrade(true)
  56         , upgrade_callback(std::function<void(int, int)>())
  57         , temp_dir(sys_tmp_dir)
  58         , enable_metrics(false)
  59     {
  60     }
  61
  62     /// The persistence level of the Realm file. See Durability.
  63     Durability durability;
  64
  65     /// The key to encrypt and decrypt the Realm file with, or nullptr to
  66     /// indicate that encryption should not be used.
  67     const char* encryption_key;
  68
  69     /// If \a allow_file_format_upgrade is set to `true`, this function will
  70     /// automatically upgrade the file format used in the specified Realm file
  71     /// if necessary (and if it is possible). In order to prevent this, set \a
  72     /// allow_upgrade to `false`.
  73     ///
  74     /// If \a allow_upgrade is set to `false`, only two outcomes are possible:
  75     ///
  76     /// - the specified Realm file is already using the latest file format, and
  77     ///   can be used, or
  78     ///
  79     /// - the specified Realm file uses a deprecated file format, resulting a
  80     ///   the throwing of FileFormatUpgradeRequired.
  81     bool allow_file_format_upgrade;
  82
  83     /// Optionally allows a custom function to be called immediately after the
  84     /// Realm file is upgraded. The two parameters in the function are the
  85     /// previous version and the version just upgraded to, respectively.
  86     /// If the callback function throws, the Realm file will safely abort the
  87     /// upgrade (rollback the transaction) but the SharedGroup will not be opened.
  88     std::function<void(int, int)> upgrade_callback;
  89
  90     /// A path to a directory where Realm can write temporary files or pipes to.
  91     /// This string should include a trailing slash '/'.
  92     std::string temp_dir;
  93
  94     /// Controls the feature of collecting various metrics to the SharedGroup.
  95     /// A prerequisite is compiling with REALM_METRICS=ON.
  96     bool enable_metrics;
  97
  98     /// sys_tmp_dir will be used if the temp_dir is empty when creating SharedGroupOptions.
  99     /// It must be writable and allowed to create pipe/fifo file on it.
 100     /// set_sys_tmp_dir is not a thread-safe call and it is only supposed to be called once
 101     //  when process starts.
 102     static void set_sys_tmp_dir(const std::string& dir) noexcept { sys_tmp_dir = dir; }
 103     static std::string get_sys_tmp_dir() noexcept { return sys_tmp_dir; }
 104
 105 private:
 106     static std::string sys_tmp_dir;
 107 };
 108
 109 } // end namespace realm
 110
 111 #endif // REALM_GROUP_SHARED_OPTIONS_HPP