0
# Utility Types and Interfaces
1

2
Supporting interfaces, exceptions, and utility classes used by MMKV for advanced functionality and error handling.
3

4
## Capabilities
5

6
### Content Change Notifications
7

8
Interface for receiving inter-process content change notifications.
9

10
```java { .api }
11
/**
12
 * Inter-process content change notification.
13
 * Triggered by any method call, such as getXXX() or setXXX() or checkContentChangedByOuterProcess().
14
 */
15
interface MMKVContentChangeNotification {
16
    /**
17
     * Inter-process content change notification callback
18
     * @param mmapID The unique ID of the changed MMKV instance
19
     */
20
    void onContentChangedByOuterProcess(String mmapID);
21
}
22
```
23

24
**Usage Example:**
25

26
```java
27
// Register for content change notifications
28
MMKV.registerContentChangeNotify(new MMKVContentChangeNotification() {
29
    @Override
30
    public void onContentChangedByOuterProcess(String mmapID) {
31
        Log.i("MMKV", "Content changed in: " + mmapID);
32
        // Handle the change
33
    }
34
});
35

36
// Unregister when no longer needed
37
MMKV.unregisterContentChangeNotify();
38
```
39

40
### Native Memory Buffer
41

42
High-performance native memory wrapper for direct JNI access.
43

44
```java { .api }
45
/**
46
 * A native memory wrapper, whose underlying memory can be passed to another JNI method directly.
47
 * Avoiding unnecessary JNI boxing and unboxing.
48
 * Must be destroy manually using MMKV.destroyNativeBuffer().
49
 */
50
class NativeBuffer {
51
    /** Pointer to native memory */
52
    long pointer;
53
    
54
    /** Size of the buffer in bytes */
55
    int size;
56
    
57
    /** Constructor for native buffer */
58
    NativeBuffer(long ptr, int length);
59
}
60
```
61

62
**Usage Example:**
63

64
```java
65
// Create native buffer for efficient data transfer
66
NativeBuffer buffer = MMKV.createNativeBuffer(1024);
67
if (buffer != null) {
68
    try {
69
        // Write value to native buffer
70
        MMKV kv = MMKV.defaultMMKV();
71
        int written = kv.writeValueToNativeBuffer("key", buffer);
72
        
73
        if (written > 0) {
74
            // Use the buffer data in native code
75
            Log.d("MMKV", "Written " + written + " bytes to buffer");
76
        }
77
    } finally {
78
        // Always destroy the buffer to avoid memory leaks
79
        MMKV.destroyNativeBuffer(buffer);
80
    }
81
}
82
```
83

84
### MMKV Handler Interface
85

86
Callback handler for MMKV error recovery and log redirection.
87

88
```java { .api }
89
/**
90
 * Callback handler for MMKV.
91
 * Callback is called on the operating thread of the MMKV instance.
92
 */
93
interface MMKVHandler {
94
    /**
95
     * Called on CRC32-check failure
96
     * By default MMKV will discard all data on crc32-check failure
97
     * @param mmapID The unique ID of the MMKV instance
98
     * @return Return OnErrorRecover to recover any data on the file
99
     */
100
    MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
101
    
102
    /**
103
     * Called on file length mismatch
104
     * By default MMKV will discard all data on file length mismatch
105
     * @param mmapID The unique ID of the MMKV instance
106
     * @return Return OnErrorRecover to recover any data on the file
107
     */
108
    MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
109
    
110
    /**
111
     * Whether to redirect MMKV logs to this handler
112
     * @return Return false if you don't want log redirecting
113
     */
114
    boolean wantLogRedirecting();
115
    
116
    /**
117
     * Log redirecting callback
118
     * @param level The level of this log
119
     * @param file The file name of this log
120
     * @param line The line of code of this log
121
     * @param function The function name of this log
122
     * @param message The content of this log
123
     */
124
    void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
125
}
126
```
127

128
### Exception Types
129

130
```java { .api }
131
/**
132
 * Exception thrown when trying to use MMKV on unsupported architecture
133
 */
134
class UnsupportedArchitectureException extends RuntimeException {
135
    UnsupportedArchitectureException(String message);
136
}
137
```
138

139
### Static Utility Methods
140

141
Global MMKV utility methods for configuration and information.
142

143
```java { .api }
144
/**
145
 * Get the device's memory page size
146
 * @return The memory page size in bytes
147
 */
148
static int pageSize();
149

150
/**
151
 * Get the version of MMKV
152
 * @return The version string
153
 */
154
static String version();
155

156
/**
157
 * Notify MMKV that App is about to exit
158
 * It's totally fine not calling it at all
159
 */
160
static void onExit();
161

162
/**
163
 * Set the log level of MMKV
164
 * @param level The log level, defaults to LevelInfo
165
 */
166
static void setLogLevel(MMKVLogLevel level);
167

168
/**
169
 * Get the root folder of MMKV
170
 * @return The root folder path, defaults to $(FilesDir)/mmkv
171
 */
172
static String getRootDir();
173
```
174

175
### Native Buffer Management
176

177
Static methods for creating and managing native buffers.
178

179
```java { .api }
180
/**
181
 * Create a native buffer for direct memory access
182
 * An NativeBuffer must be manually destroyed to avoid memory leak
183
 * @param size The size of the underlying memory
184
 * @return NativeBuffer instance or null on failure
185
 */
186
static NativeBuffer createNativeBuffer(int size);
187

188
/**
189
 * Destroy the native buffer to avoid memory leak
190
 * @param buffer The buffer to destroy
191
 */
192
static void destroyNativeBuffer(NativeBuffer buffer);
193
```
194

195
### Process Mode Checker Control
196

197
Methods to control process mode validation.
198

199
```java { .api }
200
/**
201
 * Manually enable the process mode checker
202
 * By default, it's automatically enabled in DEBUG build, and disabled in RELEASE build
203
 * If enabled, MMKV will throw exceptions when an MMKV instance is created with mismatch process mode
204
 */
205
static void enableProcessModeChecker();
206

207
/**
208
 * Manually disable the process mode checker
209
 * By default, it's automatically enabled in DEBUG build, and disabled in RELEASE build
210
 */
211
static void disableProcessModeChecker();
212
```
213

214
### Content Change Notification Registration
215

216
Methods to register and unregister for inter-process content change notifications.
217

218
```java { .api }
219
/**
220
 * Register for MMKV inter-process content change notification.
221
 * The notification will trigger only when any method is manually called on the MMKV instance.
222
 * For example checkContentChangedByOuterProcess().
223
 * @param notify The notification handler
224
 */
225
static void registerContentChangeNotify(MMKVContentChangeNotification notify);
226

227
/**
228
 * Unregister for MMKV inter-process content change notification.
229
 */
230
static void unregisterContentChangeNotify();
231
```