Interface Overview
Update time: 2022/11/28 07:39:01
Interface overview
IM SDK for Android offers two types of interfaces:
-
Interfaces ends with
Service
, such asAuthService
. This type of interfaces initiate requests actively. -
Interfaces ends with
ServiceObserver
, such asAuthServiceObserver
. This type of interfaces serve as observers for events and changes. Some classes ends withObserver
, such asSystemMessageObserver
.
You must call methods included in the SDK in the main process. Call methods in the SDK XXXService
and register observers included in XXXServiceObserver
in the main process. If an event occurs, the corresponding callback must be executed in the main thread of the main process. If you want a module runs in a non-main process, you must implement the communication between the main process and the non-main process (IPC channels such as AIDL/Messenger/ContentProvider/BroadcastReceiver) and forward the data returned by the callback or observer in the main process to the non-main process.
The SDK provides three types of return values: basic data types (synchronous), InvocationFuture (asynchronous), and AbortableFuture (asynchronous). Most asynchronous interfaces initiate the call from the main process, then executes in the background process, and finally returns the result to the main process.
If it takes a long time or transmits a large amount of data when you call the AbortableFuture asynchronous interface, you can use the abort() method to interrupt the request. For example, upload, download, and login.
Asynchronous interfaces can set callbacks using RequestCallback or RequestCallbackWrapper.
Callback | Description |
---|---|
RequestCallback | includes three callbacks: onSuccess, onFailed, and onException |
RequestCallbackWrapper | returns onResult and contains three methods for success, failure, and exception. |
SDK v4.4.0 API call framework enhancements:
-
Supports asynchronous API calls initiated by non-UI threads with Looper, and returns data to the caller thread. Earlier versions will return data to the UI thread by default.
-
Provides an interface for force asynchronous call conversion to synchronous call: NIMClient#syncRequest, which allows you to set the maximum waiting time for synchronization, and supports the scenarios where CommsEase APIs are called synchronously in non-UI threads.
-
Automatically add generated NIMSDK classes. You can directly use the NIMSDK#getXXXService method to get the service interface. You do not have to pass the XXXService.class. This simplifies the API call. For example, replace
NIMClient.getService(AuthService.class).login()
withNIMSDK.getAuthService().login()
. The classes automatically generated by other plug-ins are NIMChatRoomSDK and NIMLuceneSDK.
Data cache directory
When a multimedia message is received, the SDK will download related files by default, and the SDK will also record some key log files. Therefore, the SDK must have a data cache directory.
This directory can be created using SDKOptions#sdkStorageRootPath
during SDK initialization.
From SDK v4.4.0, if you configure the directory in the extension storage cache directory of your app, such as Context#getExternalCacheDir and Context.getExternalFilesDir, the SDK will not check the write permissions.
Files in this directory will be deleted when the app is uninstalled. You can also manually delete the files in the directory in the settings interface.
If this directory is not configured, the default directory is /{external card root directory}/{app package name}/nim/
, where the external card root directory can be obtained using Environment.getExternalStorageDirectory().getPath()
.
To clear the cache, your app scans the files in this directory and clean them based on the rules. After the SDK initialization is complete, you can get the SDK data cache directory calling NimClient#getSdkStorageDirPath
.
The SDK data cache directory contains the following folders:
Subdirectories | File |
---|---|
log | SDK log file: such as nim_sdk.log, up to 8MB in size. |
image | Original images of image messages. |
audio | Audios of audio messages. |
video | Original videos of video messages. |
thumb | Thumbnails of image or video messages. |
file | Files of file messages. |