react-native-mmkv 1.6.2 → 2.1.0

package/MMKV/CHANGELOG.md

@@ -1,5 +1,35 @@
 # MMKV Change Log
 
+## v1.2.12 / 2022-01-17
+### Changes for All platforms
+* Fix a bug that a subsequential `clearAll()` call may fail to take effect in multi-process mode.
+* Hide some OpenSSL symbols to prevent link-time symbol conflict, when an App somehow also static linking OpenSSL.
+
+### Android
+* Upgrade `compileSdkVersion` & `targetSdkVersion` from `30` to `31`.
+
+## v1.2.11 / 2021-10-26
+
+### Android
+* Due to increasing report about crash inside STL, we have decided to make MMKV **static linking** `libc++` **by default**. Starting from v1.2.11, `com.tencent:mmkv-static` is the same as `com.tencent:mmkv`.
+* For those still in need of MMKV with shared linking of `libc++_shared`, you could use `com.tencent:mmkv-shared` instead.
+* Add backup & restore ability.
+
+### iOS / macOS
+* Add backup & restore ability.
+* Support tvOS.
+* Fix a compile error on some old Xcode.
+
+### Flutter (v1.2.12)
+* Add backup & restore ability.
+
+### POSIX / golang / Python
+* Add backup & restore ability.
+* Fix a compile error on Gentoo.
+
+### Win32
+* Add backup & restore ability.
+
 ## v1.2.10 / 2021-06-25
 This version is mainly for Android & Flutter.  
 

package/MMKV/Core/CMakeLists.txt

@@ -20,7 +20,7 @@
 
 # Sets the minimum version of CMake required to build the native library.
 
-cmake_minimum_required(VERSION 3.8.0)
+cmake_minimum_required(VERSION 3.10.0)
 
 IF(APPLE)
     # tell ranlib to ignore empty compilation units
@@ -102,6 +102,7 @@ add_library(core
         MemoryFile.h
         MemoryFile.cpp
         MemoryFile_Android.cpp
+        MemoryFile_Linux.cpp
         MemoryFile_Win32.cpp
         MemoryFile_OSX.cpp
         ThreadLock.h

package/MMKV/Core/CodedInputDataCrypt.cpp

@@ -108,7 +108,7 @@ void CodedInputDataCrypt::consumeBytes(size_t length, bool discardPreData) {
             bytesLeftInBuffer = m_decryptBufferSize - m_decryptBufferDecryptLength;
         }
     }
-    // still no enough sapce, try realloc()
+    // still no enough space, try realloc()
     if (bytesLeftInBuffer < length) {
         auto newSize = m_decryptBufferSize + length;
         auto newBuffer = realloc(m_decryptBuffer, newSize);

package/MMKV/Core/Core.xcodeproj/project.pbxproj

@@ -256,6 +256,7 @@
 				CB58B3FE23AB3035002457F1 /* Frameworks */,
 				CB9563D923AB2D9500ACCD39 /* Products */,
 			);
+			indentWidth = 4;
 			sourceTree = "<group>";
 		};
 		CB9563D923AB2D9500ACCD39 /* Products */ = {
@@ -576,8 +577,9 @@
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = "";
 				SKIP_INSTALL = YES;
-				SUPPORTED_PLATFORMS = "iphonesimulator iphoneos macosx";
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphonesimulator iphoneos macosx appletvsimulator appletvos";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 13.0;
 			};
 			name = Debug;
 		};
@@ -603,8 +605,9 @@
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = "";
 				SKIP_INSTALL = YES;
-				SUPPORTED_PLATFORMS = "iphonesimulator iphoneos macosx";
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphonesimulator iphoneos macosx appletvsimulator appletvos";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 13.0;
 			};
 			name = Release;
 		};

package/MMKV/Core/InterProcessLock_Win32.cpp

@@ -50,7 +50,10 @@ bool FileLock::platformLock(LockType lockType, bool wait, bool unLockFirstIfNeed
         // let's be gentleman: unlock my shared-lock to prevent deadlock
         auto ret = UnlockFileEx(m_fd, 0, 1, 0, &m_overLapped);
         if (!ret) {
-            MMKVError("fail to try unlock first fd=%p, error:%d", m_fd, GetLastError());
+            auto lastError = GetLastError();
+            if (lastError != ERROR_NOT_LOCKED) {
+                MMKVError("fail to try unlock first fd=%p, error:%d", m_fd, lastError);
+            }
         }
     }
 
@@ -91,11 +94,13 @@ bool FileLock::platformUnLock(bool unlockToSharedLock) {
     }
     auto ret = UnlockFileEx(m_fd, 0, 1, 0, &m_overLapped);
     if (!ret) {
-        MMKVError("fail to unlock fd=%p, error:%d", m_fd, GetLastError());
-        return false;
-    } else {
-        return true;
+        auto lastError = GetLastError();
+        if (lastError != ERROR_NOT_LOCKED) {
+            MMKVError("fail to unlock fd=%p, error:%d", m_fd, lastError);
+            return false;
+        }
     }
+    return true;
 }
 
 } // namespace mmkv

package/MMKV/Core/MMBuffer.h

@@ -26,6 +26,7 @@
 
 #include <cstdint>
 #include <cstdlib>
+#include <cstddef>
 
 namespace mmkv {
 

package/MMKV/Core/MMKV.cpp

@@ -38,6 +38,8 @@
 #include <algorithm>
 #include <cstdio>
 #include <cstring>
+#include <unordered_set>
+//#include <unistd.h>
 
 #if defined(__aarch64__) && defined(__linux)
 #    include <asm/hwcap.h>
@@ -53,7 +55,7 @@
 using namespace std;
 using namespace mmkv;
 
-unordered_map<std::string, MMKV *> *g_instanceDic;
+unordered_map<string, MMKV *> *g_instanceDic;
 ThreadLock *g_instanceLock;
 MMKVPath_t g_rootDir;
 static mmkv::ErrorHandler g_errorHandler;
@@ -61,15 +63,22 @@ size_t mmkv::DEFAULT_MMAP_SIZE;
 
 #ifndef MMKV_WIN32
 constexpr auto SPECIAL_CHARACTER_DIRECTORY_NAME = "specialCharacter";
+constexpr auto CRC_SUFFIX = ".crc";
 #else
 constexpr auto SPECIAL_CHARACTER_DIRECTORY_NAME = L"specialCharacter";
+constexpr auto CRC_SUFFIX = L".crc";
 #endif
+
 constexpr uint32_t Fixed32Size = pbFixed32Size();
 
 MMKV_NAMESPACE_BEGIN
 
+static MMKVPath_t encodeFilePath(const string &mmapID, const MMKVPath_t &rootDir);
+bool endsWith(const MMKVPath_t &str, const MMKVPath_t &suffix);
+MMKVPath_t filename(const MMKVPath_t &path);
+
 #ifndef MMKV_ANDROID
-MMKV::MMKV(const std::string &mmapID, MMKVMode mode, string *cryptKey, MMKVPath_t *rootPath)
+MMKV::MMKV(const string &mmapID, MMKVMode mode, string *cryptKey, MMKVPath_t *rootPath)
     : m_mmapID(mmapID)
     , m_path(mappedKVPathWithID(m_mmapID, mode, rootPath))
     , m_crcPath(crcPathWithID(m_mmapID, mode, rootPath))
@@ -160,10 +169,10 @@ void initialize() {
     auto hwcaps = getauxval(AT_HWCAP);
 #    ifndef MMKV_DISABLE_CRYPT
     if (hwcaps & HWCAP_AES) {
-        AES_set_encrypt_key = openssl_aes_armv8_set_encrypt_key;
-        AES_set_decrypt_key = openssl_aes_armv8_set_decrypt_key;
-        AES_encrypt = openssl_aes_armv8_encrypt;
-        AES_decrypt = openssl_aes_armv8_decrypt;
+        openssl::AES_set_encrypt_key = openssl_aes_armv8_set_encrypt_key;
+        openssl::AES_set_decrypt_key = openssl_aes_armv8_set_decrypt_key;
+        openssl::AES_encrypt = openssl_aes_armv8_encrypt;
+        openssl::AES_decrypt = openssl_aes_armv8_decrypt;
         MMKVInfo("armv8 AES instructions is supported");
     } else {
         MMKVInfo("armv8 AES instructions is not supported");
@@ -198,6 +207,10 @@ void MMKV::initializeMMKV(const MMKVPath_t &rootDir, MMKVLogLevel logLevel) {
     MMKVInfo("root dir: " MMKV_PATH_FORMAT, g_rootDir.c_str());
 }
 
+const MMKVPath_t &MMKV::getRootDir() {
+    return g_rootDir;
+}
+
 #ifndef MMKV_ANDROID
 MMKV *MMKV::mmkvWithID(const string &mmapID, MMKVMode mode, string *cryptKey, MMKVPath_t *rootPath) {
 
@@ -321,7 +334,7 @@ string MMKV::cryptKey() const {
     if (m_crypter) {
         char key[AES_KEY_LEN];
         m_crypter->getKey(key);
-        return string(key, strnlen(key, AES_KEY_LEN));
+        return {key, strnlen(key, AES_KEY_LEN)};
     }
     return "";
 }
@@ -895,6 +908,320 @@ bool MMKV::try_lock() {
     return m_exclusiveProcessLock->try_lock();
 }
 
+// backup
+
+static bool backupOneToDirectoryByFilePath(const string &mmapKey, const MMKVPath_t &srcPath, const MMKVPath_t &dstPath) {
+    File crcFile(srcPath, OpenFlag::ReadOnly);
+    if (!crcFile.isFileValid()) {
+        return false;
+    }
+
+    bool ret = false;
+    {
+#ifdef MMKV_WIN32
+        MMKVInfo("backup one mmkv[%s] from [%ws] to [%ws]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#else
+        MMKVInfo("backup one mmkv[%s] from [%s] to [%s]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#endif
+        FileLock fileLock(crcFile.getFd());
+        InterProcessLock lock(&fileLock, SharedLockType);
+        SCOPED_LOCK(&lock);
+
+        ret = copyFile(srcPath, dstPath);
+        if (ret) {
+            auto srcCRCPath = srcPath + CRC_SUFFIX;
+            auto dstCRCPath = dstPath + CRC_SUFFIX;
+            ret = copyFile(srcCRCPath, dstCRCPath);
+        }
+        MMKVInfo("finish backup one mmkv[%s]", mmapKey.c_str());
+    }
+    return ret;
+}
+
+bool MMKV::backupOneToDirectory(const string &mmapKey, const MMKVPath_t &dstPath, const MMKVPath_t &srcPath, bool compareFullPath) {
+    // we have to lock the creation of MMKV instance, regardless of in cache or not
+    SCOPED_LOCK(g_instanceLock);
+    MMKV *kv = nullptr;
+    if (!compareFullPath) {
+        auto itr = g_instanceDic->find(mmapKey);
+        if (itr != g_instanceDic->end()) {
+            kv = itr->second;
+        }
+    } else {
+        // mmapKey is actually filename, we can't simply call find()
+        for (auto &pair : *g_instanceDic) {
+            if (pair.second->m_path == srcPath) {
+                kv = pair.second;
+                break;
+            }
+        }
+    }
+    // get one in cache, do it the easy way
+    if (kv) {
+#ifdef MMKV_WIN32
+        MMKVInfo("backup one cached mmkv[%s] from [%ws] to [%ws]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#else
+        MMKVInfo("backup one cached mmkv[%s] from [%s] to [%s]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#endif
+        SCOPED_LOCK(kv->m_lock);
+        SCOPED_LOCK(kv->m_sharedProcessLock);
+
+        kv->sync();
+        auto ret = copyFile(kv->m_path, dstPath);
+        if (ret) {
+            auto dstCRCPath = dstPath + CRC_SUFFIX;
+            ret = copyFile(kv->m_crcPath, dstCRCPath);
+        }
+        MMKVInfo("finish backup one mmkv[%s], ret: %d", mmapKey.c_str(), ret);
+        return ret;
+    }
+
+    // no luck with cache, do it the hard way
+    bool ret = backupOneToDirectoryByFilePath(mmapKey, srcPath, dstPath);
+    return ret;
+}
+
+bool MMKV::backupOneToDirectory(const string &mmapID, const MMKVPath_t &dstDir, const MMKVPath_t *srcDir) {
+    auto rootPath = srcDir ? srcDir : &g_rootDir;
+    if (*rootPath == dstDir) {
+        return true;
+    }
+    mkPath(dstDir);
+    auto encodePath = encodeFilePath(mmapID, dstDir);
+    auto dstPath = dstDir + MMKV_PATH_SLASH + encodePath;
+    auto mmapKey = mmapedKVKey(mmapID, rootPath);
+#ifdef MMKV_ANDROID
+    // historically Android mistakenly use mmapKey as mmapID
+    auto srcPath = *rootPath + MMKV_PATH_SLASH + encodeFilePath(mmapKey, *rootPath);
+#else
+    auto srcPath = *rootPath + MMKV_PATH_SLASH + encodePath;
+#endif
+    return backupOneToDirectory(mmapKey, dstPath, srcPath, false);
+}
+
+bool endsWith(const MMKVPath_t &str, const MMKVPath_t &suffix) {
+    if (str.length() >= suffix.length()) {
+        return str.compare(str.length() - suffix.length(), suffix.length(), suffix) == 0;
+    } else {
+        return false;
+    }
+}
+
+MMKVPath_t filename(const MMKVPath_t &path) {
+    auto startPos = path.rfind(MMKV_PATH_SLASH);
+    startPos++; // don't need to check for npos, because npos+1 == 0
+    auto filename = path.substr(startPos);
+    return filename;
+}
+
+size_t MMKV::backupAllToDirectory(const MMKVPath_t &dstDir, const MMKVPath_t &srcDir, bool isInSpecialDir) {
+    unordered_set<MMKVPath_t> mmapIDSet;
+    unordered_set<MMKVPath_t> mmapIDCRCSet;
+    walkInDir(srcDir, WalkFile, [&](const MMKVPath_t &filePath, WalkType) {
+        if (endsWith(filePath, CRC_SUFFIX)) {
+            mmapIDCRCSet.insert(filePath);
+        } else {
+            mmapIDSet.insert(filePath);
+        }
+    });
+
+    size_t count = 0;
+    if (!mmapIDSet.empty()) {
+        mkPath(dstDir);
+        auto compareFullPath = isInSpecialDir;
+        for (auto &srcPath : mmapIDSet) {
+            auto srcCRCPath = srcPath + CRC_SUFFIX;
+            if (mmapIDCRCSet.find(srcCRCPath) == mmapIDCRCSet.end()) {
+#ifdef MMKV_WIN32
+                MMKVWarning("crc not exist [%ws]", srcCRCPath.c_str());
+#else
+                MMKVWarning("crc not exist [%s]", srcCRCPath.c_str());
+#endif
+                continue;
+            }
+            auto basename = filename(srcPath);
+            const auto &strBasename = MMKVPath_t2String(basename);
+            auto mmapKey = isInSpecialDir ? strBasename : mmapedKVKey(strBasename, &srcDir);
+            auto dstPath = dstDir + MMKV_PATH_SLASH + basename;
+            if (backupOneToDirectory(mmapKey, dstPath, srcPath, compareFullPath)) {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+
+size_t MMKV::backupAllToDirectory(const MMKVPath_t &dstDir, const MMKVPath_t *srcDir) {
+    auto rootPath = srcDir ? srcDir : &g_rootDir;
+    if (*rootPath == dstDir) {
+        return true;
+    }
+    auto count = backupAllToDirectory(dstDir, *rootPath, false);
+
+    auto specialSrcDir = *rootPath + MMKV_PATH_SLASH + SPECIAL_CHARACTER_DIRECTORY_NAME;
+    if (isFileExist(specialSrcDir)) {
+        auto specialDstDir = dstDir + MMKV_PATH_SLASH + SPECIAL_CHARACTER_DIRECTORY_NAME;
+        count += backupAllToDirectory(specialDstDir, specialSrcDir, true);
+    }
+    return count;
+}
+
+// restore
+
+static bool restoreOneFromDirectoryByFilePath(const string &mmapKey, const MMKVPath_t &srcPath, const MMKVPath_t &dstPath) {
+    auto dstCRCPath = dstPath + CRC_SUFFIX;
+    File dstCRCFile(move(dstCRCPath), OpenFlag::ReadWrite | OpenFlag::Create);
+    if (!dstCRCFile.isFileValid()) {
+        return false;
+    }
+
+    bool ret = false;
+    {
+#ifdef MMKV_WIN32
+        MMKVInfo("restore one mmkv[%s] from [%ws] to [%ws]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#else
+        MMKVInfo("restore one mmkv[%s] from [%s] to [%s]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#endif
+        FileLock fileLock(dstCRCFile.getFd());
+        InterProcessLock lock(&fileLock, ExclusiveLockType);
+        SCOPED_LOCK(&lock);
+
+        ret = copyFileContent(srcPath, dstPath);
+        if (ret) {
+            auto srcCRCPath = srcPath + CRC_SUFFIX;
+            ret = copyFileContent(srcCRCPath, dstCRCFile.getFd());
+        }
+        MMKVInfo("finish restore one mmkv[%s]", mmapKey.c_str());
+    }
+    return ret;
+}
+
+// We can't simply replace the existing file, because other processes might have already open it.
+// They won't know a difference when the file has been replaced.
+// We have to let them know by overriding the existing file with new content.
+bool MMKV::restoreOneFromDirectory(const string &mmapKey, const MMKVPath_t &srcPath, const MMKVPath_t &dstPath, bool compareFullPath) {
+    // we have to lock the creation of MMKV instance, regardless of in cache or not
+    SCOPED_LOCK(g_instanceLock);
+    MMKV *kv = nullptr;
+    if (!compareFullPath) {
+        auto itr = g_instanceDic->find(mmapKey);
+        if (itr != g_instanceDic->end()) {
+            kv = itr->second;
+        }
+    } else {
+        // mmapKey is actually filename, we can't simply call find()
+        for (auto &pair : *g_instanceDic) {
+            if (pair.second->m_path == dstPath) {
+                kv = pair.second;
+                break;
+            }
+        }
+    }
+    // get one in cache, do it the easy way
+    if (kv) {
+#ifdef MMKV_WIN32
+        MMKVInfo("restore one cached mmkv[%s] from [%ws] to [%ws]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#else
+        MMKVInfo("restore one cached mmkv[%s] from [%s] to [%s]", mmapKey.c_str(), srcPath.c_str(), dstPath.c_str());
+#endif
+        SCOPED_LOCK(kv->m_lock);
+        SCOPED_LOCK(kv->m_exclusiveProcessLock);
+
+        kv->sync();
+        auto ret = copyFileContent(srcPath, kv->m_file->getFd());
+        if (ret) {
+            auto srcCRCPath = srcPath + CRC_SUFFIX;
+            ret = copyFileContent(srcCRCPath, kv->m_metaFile->getFd());
+        }
+
+        // reload data after restore
+        kv->clearMemoryCache();
+        kv->loadFromFile();
+        if (kv->m_isInterProcess) {
+            kv->notifyContentChanged();
+        }
+
+        MMKVInfo("finish restore one mmkv[%s], ret: %d", mmapKey.c_str(), ret);
+        return ret;
+    }
+
+    // no luck with cache, do it the hard way
+    bool ret = restoreOneFromDirectoryByFilePath(mmapKey, srcPath, dstPath);
+    return ret;
+}
+
+bool MMKV::restoreOneFromDirectory(const string &mmapID, const MMKVPath_t &srcDir, const MMKVPath_t *dstDir) {
+    auto rootPath = dstDir ? dstDir : &g_rootDir;
+    if (*rootPath == srcDir) {
+        return true;
+    }
+    mkPath(*rootPath);
+    auto encodePath = encodeFilePath(mmapID, *rootPath);
+    auto srcPath = srcDir + MMKV_PATH_SLASH + encodePath;
+    auto mmapKey = mmapedKVKey(mmapID, rootPath);
+#ifdef MMKV_ANDROID
+    // historically Android mistakenly use mmapKey as mmapID
+    auto dstPath = *rootPath + MMKV_PATH_SLASH + encodeFilePath(mmapKey, *rootPath);
+#else
+    auto dstPath = *rootPath + MMKV_PATH_SLASH + encodePath;
+#endif
+    return restoreOneFromDirectory(mmapKey, srcPath, dstPath, false);
+}
+
+size_t MMKV::restoreAllFromDirectory(const MMKVPath_t &srcDir, const MMKVPath_t &dstDir, bool isInSpecialDir) {
+    unordered_set<MMKVPath_t> mmapIDSet;
+    unordered_set<MMKVPath_t> mmapIDCRCSet;
+    walkInDir(srcDir, WalkFile, [&](const MMKVPath_t &filePath, WalkType) {
+        if (endsWith(filePath, CRC_SUFFIX)) {
+            mmapIDCRCSet.insert(filePath);
+        } else {
+            mmapIDSet.insert(filePath);
+        }
+    });
+
+    size_t count = 0;
+    if (!mmapIDSet.empty()) {
+        mkPath(dstDir);
+        auto compareFullPath = isInSpecialDir;
+        for (auto &srcPath : mmapIDSet) {
+            auto srcCRCPath = srcPath + CRC_SUFFIX;
+            if (mmapIDCRCSet.find(srcCRCPath) == mmapIDCRCSet.end()) {
+#ifdef MMKV_WIN32
+                MMKVWarning("crc not exist [%ws]", srcCRCPath.c_str());
+#else
+                MMKVWarning("crc not exist [%s]", srcCRCPath.c_str());
+#endif
+                continue;
+            }
+            auto basename = filename(srcPath);
+            const auto &strBasename = MMKVPath_t2String(basename);
+            auto mmapKey = isInSpecialDir ? strBasename : mmapedKVKey(strBasename, &dstDir);
+            auto dstPath = dstDir + MMKV_PATH_SLASH + basename;
+            if (restoreOneFromDirectory(mmapKey, srcPath, dstPath, compareFullPath)) {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+
+size_t MMKV::restoreAllFromDirectory(const MMKVPath_t &srcDir, const MMKVPath_t *dstDir) {
+    auto rootPath = dstDir ? dstDir : &g_rootDir;
+    if (*rootPath == srcDir) {
+        return true;
+    }
+    auto count = restoreAllFromDirectory(srcDir, *rootPath, true);
+
+    auto specialSrcDir = srcDir + MMKV_PATH_SLASH + SPECIAL_CHARACTER_DIRECTORY_NAME;
+    if (isFileExist(specialSrcDir)) {
+        auto specialDstDir = *rootPath + MMKV_PATH_SLASH + SPECIAL_CHARACTER_DIRECTORY_NAME;
+        count += restoreAllFromDirectory(specialSrcDir, specialDstDir, false);
+    }
+    return count;
+}
+
+// callbacks
+
 void MMKV::registerErrorHandler(ErrorHandler handler) {
     SCOPED_LOCK(g_instanceLock);
     g_errorHandler = handler;
@@ -934,7 +1261,7 @@ static string md5(const basic_string<T> &value) {
         snprintf(tmp, sizeof(tmp), "%2.2x", ch);
         strcat(buf, tmp);
     }
-    return string(buf);
+    return {buf};
 }
 
 static MMKVPath_t encodeFilePath(const string &mmapID) {
@@ -957,14 +1284,35 @@ static MMKVPath_t encodeFilePath(const string &mmapID) {
     }
 }
 
-string mmapedKVKey(const string &mmapID, MMKVPath_t *rootPath) {
+static MMKVPath_t encodeFilePath(const string &mmapID, const MMKVPath_t &rootDir) {
+    const char *specialCharacters = "\\/:*?\"<>|";
+    string encodedID;
+    bool hasSpecialCharacter = false;
+    for (auto ch : mmapID) {
+        if (strchr(specialCharacters, ch) != nullptr) {
+            encodedID = md5(mmapID);
+            hasSpecialCharacter = true;
+            break;
+        }
+    }
+    if (hasSpecialCharacter) {
+        MMKVPath_t path = rootDir + MMKV_PATH_SLASH + SPECIAL_CHARACTER_DIRECTORY_NAME;
+        mkPath(path);
+
+        return MMKVPath_t(SPECIAL_CHARACTER_DIRECTORY_NAME) + MMKV_PATH_SLASH + string2MMKVPath_t(encodedID);
+    } else {
+        return string2MMKVPath_t(mmapID);
+    }
+}
+
+string mmapedKVKey(const string &mmapID, const MMKVPath_t *rootPath) {
     if (rootPath && g_rootDir != (*rootPath)) {
         return md5(*rootPath + MMKV_PATH_SLASH + string2MMKVPath_t(mmapID));
     }
     return mmapID;
 }
 
-MMKVPath_t mappedKVPathWithID(const string &mmapID, MMKVMode mode, MMKVPath_t *rootPath) {
+MMKVPath_t mappedKVPathWithID(const string &mmapID, MMKVMode mode, const MMKVPath_t *rootPath) {
 #ifndef MMKV_ANDROID
     if (rootPath) {
 #else
@@ -977,13 +1325,7 @@ MMKVPath_t mappedKVPathWithID(const string &mmapID, MMKVMode mode, MMKVPath_t *r
     return g_rootDir + MMKV_PATH_SLASH + encodeFilePath(mmapID);
 }
 
-#ifndef MMKV_WIN32
-constexpr auto CRC_SUFFIX = ".crc";
-#else
-constexpr auto CRC_SUFFIX = L".crc";
-#endif
-
-MMKVPath_t crcPathWithID(const string &mmapID, MMKVMode mode, MMKVPath_t *rootPath) {
+MMKVPath_t crcPathWithID(const string &mmapID, MMKVMode mode, const MMKVPath_t *rootPath) {
 #ifndef MMKV_ANDROID
     if (rootPath) {
 #else

package/MMKV/Core/MMKV.h

@@ -38,11 +38,12 @@ class ThreadLock;
 MMKV_NAMESPACE_BEGIN
 
 enum MMKVMode : uint32_t {
-    MMKV_SINGLE_PROCESS = 0x1,
-    MMKV_MULTI_PROCESS = 0x2,
+    MMKV_SINGLE_PROCESS = 1 << 0,
+    MMKV_MULTI_PROCESS = 1 << 1,
 #ifdef MMKV_ANDROID
-    CONTEXT_MODE_MULTI_PROCESS = 0x4, // in case someone mistakenly pass Context.MODE_MULTI_PROCESS
-    MMKV_ASHMEM = 0x8,
+    CONTEXT_MODE_MULTI_PROCESS = 1 << 2, // in case someone mistakenly pass Context.MODE_MULTI_PROCESS
+    MMKV_ASHMEM = 1 << 3,
+    MMKV_BACKUP = 1 << 4,
 #endif
 };
 
@@ -146,6 +147,10 @@ class MMKV {
 #if defined(MMKV_ANDROID) && !defined(MMKV_DISABLE_CRYPT)
     void checkReSetCryptKey(int fd, int metaFD, std::string *cryptKey);
 #endif
+    static bool backupOneToDirectory(const std::string &mmapKey, const MMKVPath_t &dstPath, const MMKVPath_t &srcPath, bool compareFullPath);
+    static size_t backupAllToDirectory(const MMKVPath_t &dstDir, const MMKVPath_t &srcDir, bool isInSpecialDir);
+    static bool restoreOneFromDirectory(const std::string &mmapKey, const MMKVPath_t &srcPath, const MMKVPath_t &dstPath, bool compareFullPath);
+    static size_t restoreAllFromDirectory(const MMKVPath_t &srcDir, const MMKVPath_t &dstDir, bool isInSpecialDir);
 
 public:
     // call this before getting any MMKV instance
@@ -322,6 +327,26 @@ public:
     void unlock();
     bool try_lock();
 
+    static const MMKVPath_t &getRootDir();
+
+    // backup one MMKV instance from srcDir to dstDir
+    // if srcDir is null, then backup from the root dir of MMKV
+    static bool backupOneToDirectory(const std::string &mmapID, const MMKVPath_t &dstDir, const MMKVPath_t *srcDir = nullptr);
+
+    // restore one MMKV instance from srcDir to dstDir
+    // if dstDir is null, then restore to the root dir of MMKV
+    static bool restoreOneFromDirectory(const std::string &mmapID, const MMKVPath_t &srcDir, const MMKVPath_t *dstDir = nullptr);
+
+    // backup all MMKV instance from srcDir to dstDir
+    // if srcDir is null, then backup from the root dir of MMKV
+    // return count of MMKV successfully backuped
+    static size_t backupAllToDirectory(const MMKVPath_t &dstDir, const MMKVPath_t *srcDir = nullptr);
+
+    // restore all MMKV instance from srcDir to dstDir
+    // if dstDir is null, then restore to the root dir of MMKV
+    // return count of MMKV successfully restored
+    static size_t restoreAllFromDirectory(const MMKVPath_t &srcDir, const MMKVPath_t *dstDir = nullptr);
+
     // check if content been changed by other process
     void checkContentChanged();
 

package/MMKV/Core/MMKVLog.cpp

@@ -30,15 +30,7 @@ MMKVLogLevel g_currentLogLevel = MMKVLogInfo;
 
 mmkv::LogHandler g_logHandler;
 
-MMKV_NAMESPACE_END
-
-#ifdef ENABLE_MMKV_LOG
-#    include <cstdarg>
-#    include <string>
-
-using namespace mmkv;
-
-#    ifndef __FILE_NAME__
+#ifndef __FILE_NAME__
 const char *_getFileName(const char *path) {
     const char *ptr = strrchr(path, '/');
     if (!ptr) {
@@ -50,7 +42,16 @@ const char *_getFileName(const char *path) {
         return path;
     }
 }
-#    endif
+#endif
+
+MMKV_NAMESPACE_END
+
+
+#ifdef ENABLE_MMKV_LOG
+#    include <cstdarg>
+#    include <string>
+
+using namespace mmkv;
 
 #    ifndef MMKV_ANDROID
 

package/MMKV/Core/MMKVLog.h

@@ -45,7 +45,7 @@ extern mmkv::LogHandler g_logHandler;
 #        define __MMKV_FILE_NAME__ __FILE_NAME__
 #    else
 const char *_getFileName(const char *path);
-#        define __MMKV_FILE_NAME__ _getFileName(__FILE__)
+#        define __MMKV_FILE_NAME__ MMKV_NAMESPACE_PREFIX::_getFileName(__FILE__)
 #    endif
 
 #    define MMKVError(format, ...)                                                                                     \