Interface Overview

Update time: 2022/11/28 15:39:01

Interface overview

IM SDK for Android offers two types of interfaces:

  • Interfaces ends with Service, such as AuthService. This type of interfaces initiate requests actively.

  • Interfaces ends with ServiceObserver, such as AuthServiceObserver. This type of interfaces serve as observers for events and changes. Some classes ends with Observer, such as SystemMessageObserver.

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() with NIMSDK.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.
Was this page helpful?
  • Interface overview
  • Data cache directory