Functional APIs

API List

HMR

Static Public Function	Method Signature
void	init(Context appContext, long appId, String appVersion, HummerEventListener listener)
RequestId	login(long uid, String region, String token, HMR.Completion completion)
Service	getService(Class serviceClass)
RequestId	logout()
State	getState()
String	getVersion()
RequestId	refreshToken(String token, HMR.Completion completion)
boolean	setLoggerFilePath(String loggerPath)
boolean	setLogLevel(HMRLogLevel level)
boolean	setLogCallback(HummerLogCallback callback)
boolean	uploadLogsManually(String remark)

PeerService

Note

The APIs of adding or deleting room/member attributes can be specified whether to issue broadcast notifications to other members in the room via the instance Options.

Public Member Function	Method Signature
RequestId	sendMessage(long toUserId, Message message, MessagingOptions options, HMR.Completion completion)
RequestId	queryUserOnlineStatus(Set userIds, HMR.CompletionArg<Map<Long, Boolean>> completion)
RequestId	addEventListener(EventListener listener)
RequestId	removeEventListener(EventListener listener)

RoomService

Public Member Function	Method Signature
RequestId	join(RoomId roomId, Map<String, String> appExtras, RoomJoiningOptions options, HMR.Completion completion)
RequestId	leave(RoomId roomId, HMR.Completion completion)
RequestId	queryMemberCounts(RoomId roomId, String roomRegion, HMR.CompletionArg<Map<RoomId, Integer>> completion)
RequestId	queryMembers(RoomId roomId, HMR.CompletionArg<Map<RoomId, Integer>> completion)
RequestId	setRoomAttributes(RoomId roomId, Map<String, String> attributes, RoomAttributeOptions options, HMR.Completion completion)
RequestId	addOrUpdateRoomAttributes(RoomId roomId, Map<String, String> attributes, RoomAttributeOptions options, HMR.Completion completion)
RequestId	deleteRoomAttributes(RoomId roomId, Set keys, RoomAttributeOptions options, HMR.Completion completion)
RequestId	clearRoomAttributes(RoomId roomId, RoomAttributeOptions options, HMR.Completion completion)
RequestId	queryRoomAttributesByKeys(RoomId roomId, Set keys, HMR.CompletionArg<Map<String, String>> completion)
RequestId	queryRoomAttributes(RoomId roomId, HMR.CompletionArg<Map<String, String>> completion)
RequestId	setMemberAttributes(RoomId roomId, Map<String, String> attributes, MemberAttributeOptions options, HMR.Completion completion)
RequestId	addOrUpdateMemberAttributes(RoomId roomId, long userId, Map<String, String> attributes, MemberAttributeOptions options, HMR.Completion completion)
RequestId	deleteMemberAttributes(RoomId roomId, long userId, Set keys, MemberAttributeOptions options, HMR.Completion completion)
RequestId	clearMemberAttributes(RoomId roomId, long userId, MemberAttributeOptions options, HMR.Completion completion)
RequestId	queryMemberAttributes(RoomId roomId, long userId, HMR.CompletionArg<Map<String, String>> completion)
RequestId	queryMemberAttributesByKeys(RoomId roomId, long userId, Set keys, HMR.CompletionArg<Map<String, String>> completion)
RequestId	sendMessage(RoomId roomId, Message message, MessagingOptions options, HMR.Completion completion)
RequestId	addRoomEventListener(RoomEventListener listener)
RequestId	removeRoomEventListener(RoomEventListener listener)
RequestId	addMemberEventListener(MemberEventListener listener)
RequestId	removeMemberEventListener(MemberEventListener listener)

API Details

HMR

HMR.init

public static void init(@NonNull final Context appContext,
                        final long appId,
                        final String appVersion,
                        @NonNull final HummerEventListener listener)

Initialize a Hummer SDK.

Notes:

Unless otherwise specified, all Hummer interface functions are called asynchronously, and the API is called in the same thread.

Parameters

Parameter	Description
appContext	Context
appId	appId used for identifying specific services, and manually applied for from Hummer service providers. See details in APPID apply for details.
appVresion	Current application version for data statistics and fault locating.
listener	Event listener HummerEventListener

HMR.login

public static RequestId login(final long uid,
                              @NonNull final String region,
                              @NonNull final String token,
                              @Nullable final HMR.Completion completion)

Switch to the context of a specific user. This method is executed after a user logs in for upper-layer services.

Parameters

Parameter	Description
uid	User ID, which cannot be 0
region	Parameters of regions for connecting a server. Consult relevant SDK developers for details.
token	User token for service authentication.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

HMR.getService

public static <Service> Service getService(@NonNull Class<Service> serviceClass)

Get a service instance.

Parameters

Parameter	Description
serviceClass	Service instance class

Return

Service instance

HMR.logout

public static RequestId logout()

Log out an SDK.

Notes:

This operation must be executed before a user deregisters (logs out of) with a service.

Return

RequestId: incrementing request ID for fault locating

HMR.getState

public static State getState()

Get the SDK current status. See details in HMR.State for details..

Return

SDK current status

HMR.getVersion

public static String getVersion()

Get SDK version information.

Return

SDK version information

HMR.refreshToken

public static RequestId refreshToken(@NonNull final String token,
                                     @Nullable final HMR.Completion completion);

Refresh a user token.

Parameters

Parameter	Description
token	A user token to be refreshed
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

HMR.setLoggerFilePath

public static boolean setLoggerFilePath(@NonNull String loggerPath)

Set a log saving path. The caller should ensure that the path is valid.

Notes:

Do not set it to the system root directory!

Parameters

Parameter	Description
loggerPath	Log saving path required

Return

Operation result

HMR.setLogLevel

public static boolean setLogLevel(HMRLogLevel level)

Set log level

Parameters

Parameter	Description
HMRLogLevel	Log level, see details in HMRLogLevel

Return

Operation result

HMR.setLogCallback

public static boolean setLogCallback(HummerLogCallback callback)

Set log output callback

Parameters

Parameter	Description
HummerLogCallback	Log output callback, see details in HummerLogCallback

Return

Operation result

HMR.uploadLogsManually

public static boolean uploadLogsManually(String remark)

Report logs manually

Parameters

Parameter	Description
remark	Remarks

Return

Operation result

PeerService

PeerService.queryUserOnlineStatus

RequestId queryUserOnlineStatus(@NonNull Set<Long> userIds,
                                @Nullable HMR.CompletionArg<Map<Long, Boolean>> completion);

Batch search of online users can search the status of a specific user.

Parameters

Parameter	Description
userIds	Search of a list of online users' IDs
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

PeerService.sendMessage

RequestId sendMessage(final long toUserId,
                      @NonNull final Message message,
                      @NonNull final MessagingOptions options,
                      @Nullable HMR.Completion completion);

Send P2P signaling messages.

Parameters

Parameter	Description
toUsedId	ID of a signaling message receiver
message	Signaling message to be sent. See details in Message.
options	Configuration information for sending the message (a reserved field). See details in MessagingOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

PeerService.addEventListener

RequestId addEventListener(EventListener listener);

Add listeners for signaling messages.

Parameters

Parameter	Description
listener	Listener to be added. See details in EventListener.

Return

RequestId: incrementing request ID for fault locating

PeerService.removeEventListener

RequestId removeEventListener(EventListener listener);

Remove listeners for signaling messages.

Parameters

Parameter	Description
listener	Listener to be removed. See details in EventListener.

Return

RequestId: Incrementing request ID for fault locating

RoomService

RoomService.join

RequestId join(@NonNull RoomId roomId,
               @Nullable Map<String, String> appExtras,
               @Nullable RoomJoiningOptions options,
               @Nullable HMR.Completion completion);

APIs for joining a room.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
appExtras	Extension information for joining a room
options	Optional parameters for joining a room. See details in RoomJoiningOptions..
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.leave

RequestId leave(@NonNull RoomId roomId, @Nullable HMR.Completion completion);

APIs for exiting a room.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: Incrementing request ID for fault locating

RoomService.queryMemberCounts

RequestId queryMemberCounts(@NonNull final Set<String> roomIds,
                            @NonNull String roomRegion,
                            @Nullable HMR.CompletionArg<Map<RoomId, Integer>> completion);

Batch search for number of room members.

Notes:

Support concurrent search of 20 rooms at maximum.

Do not support cross-region room search.

Parameters

Parameter	Description
roomIds	Room ID specified by operations. See details in RoomId.ID..
roomRegion	Room region. See details in RoomId.region
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.queryMembers

RequestId queryMembers(@NonNull RoomId roomId,
                        @Nullable HMR.CompletionArg<List<Long>> completion);

Get a list of members in the specific room.

Notes:

When over 500 members have joined a room, 500 randomly selected members are returned.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.setRoomAttributes

RequestId setRoomAttributes(@NonNull RoomId roomId,
                            @NonNull final Map<String, String> attributes,
                            @Nullable final RoomAttributeOptions options,
                            @Nullable HMR.Completion completion);

Set room profiles.

Notes:

Support full configuration of room profiles for joining and exiting a room.

Clear room profiles when this room keeps empty for 10 minutes.

Size of each profile can be up to 8 KB. Each room contains 32 profiles at maximum.

You are not advised to set the maximum number of profiles and maximum capacity of each profile. Otherwise, you may fail to get profile value when all of them reach peak value.

When configuring room profiles, you should fill in parameter Key (otherwise, an error is returned), whereas parameter Value can be null.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
attributes	Profiles
options	Reserved field. See details in RoomAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.addOrUpdateRoomAttributes

RequestId addOrUpdateRoomAttributes(@NonNull RoomId roomId,
                                    @NonNull final Map<String, String> attributes,
                                    @Nullable final RoomAttributeOptions options,
                                    @Nullable HMR.Completion completion);

Add or update profiles of specific rooms.

Notes:

Update while there are profiles; otherwise, add profiles.

Clear room profiles when this room keeps empty for 10 minutes.

Size of each profile can be up to 8 KB. Each room contains 32 profiles at maximum.

You are not advised to set the maximum number of profiles and maximum capacity of each profile. Otherwise, you may fail to get profile value when all of them reach peak value.

When configuring room profiles, you should fill in parameter Key (otherwise, an error is returned), whereas parameter Value can be null.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
attributes	Profiles
options	Reserved fields. See details in RoomAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID fault locating

RoomService.deleteRoomAttributes

RequestId deleteRoomAttributes(@NonNull RoomId roomId,
                               @NonNull final Set<String> keys,
                               @Nullable final RoomAttributeOptions options,
                               @Nullable HMR.Completion completion);

Delete specific profiles of specific rooms.

Notes:

Return success if specific room profiles exist and are deleted.

Return success if specific room profiles do not exist.

Return success if some specific room profiles exist.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
keys	Profile keys
options	Reserved fields. See details in RoomAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.clearRoomAttributes

RequestId clearRoomAttributes(@NonNull RoomId roomId,
                              @Nullable final RoomAttributeOptions options,
                              @Nullable HMR.Completion completion);

Clear profiles of specific rooms.

Notes:

Clear room profiles when this room keeps empty for 10 minutes.

Return success if profiles are not configured for a specific room or do not exist.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
options	Reserved fields. See details in RoomAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: Incrementing request ID for fault locating

RoomService.queryRoomAttributesByKeys

RequestId queryRoomAttributesByKeys(@NonNull RoomId roomId,
                                    @NonNull final Set<String> keys,
                                    @Nullable HMR.CompletionArg<Map<String, String>> completion);

Search specific profiles of specific rooms.

Notes:

Profile keys; A single key cannot be empty.

Return success if the searched profile does not exist, but the returned result is empty.

Only return existing profiles if some room profiles exist.

Return success if specific room profiles have never been configured, or have been cleared due to timeout but are not configured again. The returned result is empty.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
keys	Profile keys
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.queryRoomAttributes

RequestId queryRoomAttributes(@NonNull RoomId roomId,
                              @Nullable HMR.CompletionArg<Map<String, String>> completion);

Search all profiles of specific rooms.

Notes:

Return success if specific room profiles have never been configured, or have been cleared due to timeout but are not configured again. The returned result is empty.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: Incrementing request ID for fault locating

RoomService.setMemberAttributes

RequestId setMemberAttributes(@NonNull final RoomId roomId,
                              final long userId,
                              @NonNull final Map<String, String> attributes,
                              @Nullable final MemberAttributeOptions options,
                              @Nullable HMR.Completion completion);

Set user profiles in the current room.

Notes:

You can only set your own profiles at present.

Size of a user's profile can be up to 8 KB. 32 profiles are supported at maximum.

You are not advised to set the maximum number of profiles and maximum capacity of each profile. Otherwise, you may fail to get profile value when all the profiles reach peak value.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	Member ID specified by operations
attributes	Profiles
options	Profile options, reserved fields. See details in MemberAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.addOrUpdateMemberAttributes

RequestId addOrUpdateMemberAttributes(@NonNull final RoomId roomId,
                                      final long userId,
                                      @NonNull final Map<String, String> attributes,
                                      @Nullable final MemberAttributeOptions options,
                                      @Nullable HMR.Completion completion);

Add or update user profiles in the current room.

Notes:

Update while there are profiles; otherwise, add profiles.

You can only set your own profiles at present.

Size of a user's profile can be up to 8 KB. 32 profiles are supported at maximum.

You are not advised to set the maximum number of profiles and maximum capacity of each profile. Otherwise, you may fail to get profile value when all the profiles reach peak value.

Add or update local user profiles in batches.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	User ID
attributes	Profiles
options	Profile options, reserved fields. See details in MemberAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.deleteMemberAttributes

RequestId deleteMemberAttributes(@NonNull final RoomId roomId,
                                 final long userId,
                                 @NonNull final Set<String> keys,
                                 @Nullable final MemberAttributeOptions options,
                                 @Nullable HMR.Completion completion);

Delete specific user profiles in the current room.

Notes:

You can only set your own profiles at present.

Return success if some user profiles are deleted while some user profiles do not exist.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	User ID
keys	Profile keys
options	Profile options, reserved fields. See details in MemberAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.clearMemberAttributes

RequestId clearMemberAttributes(@NonNull final RoomId roomId,
                                final long userId,
                                @Nullable final MemberAttributeOptions options,
                                @Nullable HMR.Completion completion);

Clear all user profiles in the current room.

Notes:

You can only set your own profiles at present.

Return success if no profiles are configured for the specific user.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	User ID
options	Profile options, reserved fields. See details in MemberAttributeOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: Incrementing request ID for fault locating

RoomService.queryMemberAttributesByKeys

RequestId queryMemberAttributesByKeys(@NonNull final RoomId roomId,
                                      final long userId,
                                      @NonNull final Set<String> keys,
                                      @Nullable HMR.CompletionArg<Map<String, String>> completion);

Search specific user profiles in the current room.

Notes:

Return success if the searched profile does not exist, but the returned result is empty.

If some profiles exist, return success only for existing profiles with these profiles being the result.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	User ID
keys	Profile keys
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.queryMemberAttributes

RequestId queryMemberAttributes(@NonNull final RoomId roomId,
                                final long userId,
                                @Nullable HMR.CompletionArg<Map<String, String>> completion);

Search all user profiles in the current room.

Notes:

Return success if no profiles are configured for a user. The result is empty.

Parameters

Parameter	Description
roomId	Room ID specified by operations. See details in RoomId..
userId	User ID
completion	Asynchronous callback of this operation. See details in HMR.CompletionArg..

Return

RequestId: incrementing request ID for fault locating

RoomService.sendMessage

RequestId sendMessage(@NonNull RoomId roomId,
                      @NonNull Message message,
                      @NonNull MessagingOptions options,
                      @Nullable HMR.Completion completion);

Send room messages

Parameters

Parameter	Description
roomId	Room ID. See details in RoomId.
message	Signaling message to be sent. See details in Message..
options	Configuration for sending the message. See details in MessagingOptions.
completion	Asynchronous callback of this operation. See details in HMR.Completion..

Return

RequestId: incrementing request ID for fault locating

RoomService.addMemberEventListener

RequestId addMemberEventListener(MemberEventListener listener);

Add listeners for members.

Parameters

Parameter	Description
listener	Listener object to be added. See details in MemberEventListener.

Return

RequestId: incrementing request ID for fault locating

RoomService.removeMemberEventListener

RequestId removeMemberEventListener(MemberEventListener listener);

Remove listeners for members.

Parameters

Parameter	Description
listener	Listener objects to be removed. See details in MemberEventListener.

Return

RequestId: incrementing request ID for fault locating

RoomService.addRoomEventListener

RequestId addRoomEventListener(RoomEventListener listener);

Add room listeners

Parameters

Parameter	Description
listener	Listener object to be added. See details in RoomEventListener.

Return

RequestId: an incrementing request ID for fault locating.

RoomService.removeRoomEventListener

RequestId removeRoomEventListener(RoomEventListener listener);

Remove room listeners.

Parameters

Parameter	Description
listener	Listener objects to be removed. See details in RoomEventListener.

Return

RequestId: incrementing request ID for fault locating

Enumeration & Reference

HMR

HMR.State

public enum State { }

SDK current status

Enumeration Value	Meaning
Disconnected	Disconnected
Connecting	Connecting
Reconnecting	Reconnecting
Connectedsed	Connected

HMR.HMRLogLevel

public enum HMRLogLevel {
    /**
    * Output logs of TRACE level
    */
    HMR_LOG_LEVEL_TRACE(0),

    /**
    * Output logs of DEBUG level
    */
    HMR_LOG_LEVEL_DEBUG(1),

    /**
    * Output key information and logs of DEBUG level
    */
    HMR_LOG_LEVEL_INFO(2),

    /**
    * Output logs of WARNING level
    */
    HMR_LOG_LEVEL_WARNING(3),

    /**
    * Output logs of ERROR level
    */
    HMR_LOG_LEVEL_ERROR(4);
}

HMR.Completion

/**
 * API callback after operation completion
 */
public API Completion {
    void onSuccess(RequestId requestId);
    void onFailed(RequestId requestId, Error err);
}

HMR.CompletionArg

/**
 * API callback after operation completion. Callback parameters varying with scenarios are included.
 */
public interface CompletionArg<Argument> {
    void onSuccess(RequestId requestId, Argument arg);
    void onFailed(RequestId requestId, Error err);
}

HMR.HummerLogCallback

public interface HummerLogCallback {
    /**
    * Log output callback
    *
    * @param level The level of logs to be output
    * @param msg   Logs to be output
    */
    void onHmrLogWithLevel(HMRLogLevel level, String msg);
}

RequestId

/**
 * RequestId body
 */
public class RequestId {
    private String id;

    public RequestId(Long val) {
        id = String.valueOf(val);
    }

    public String getId() {
        return id;
    }

    @Override
    public String toString() {
        return getId();
    }
}

PeerService

Message

/**
 * Message body
 */
public class Message {

    /**
     * Message type
     */
    private String type;

    /**
     * Message data
     */
    private byte[] content;

    /**
     * Extended information
     */
    private Map<String, String> extras;

    public Message(final String type, final byte[] content) {
        this.type = type;
        this.content = content;
    }

    public Message(final String type, final byte[] content, final Map<String, String> extras) {
        this.type = type;
        this.content = content;
        this.extras = extras;
    }

    public String getType() {
        return type;
    }

    public byte[] getContent() {
        return content;
    }

    public Map<String, String> getExtras() {
        return extras;
    }
}

MessagingOptions

/**
 * Message option body, reserved parameter
 */
public class MessagingOptions {

}

RoomService

RoomId

/**
 * Room ID body
 */
public class RoomId {
 	  /**
     *The ID can only contain letters and digits selected from [a-zA-Z0-9_-], with 64 bytes at maximum.
     */
    private String id;

    private String region;

    public RoomId(@NonNull String id) {
        this.id = id;
    }

    public RoomId(@NonNull String id, @NonNull String region) {
        this.id = id;
        this.region = region;
    }

    public String getId() {
        return id;
    }

    public String getRegion() {
        if (region != null) {
            return region;
        }

        //If there is no default region, you can use a user login region filled in Hummer.login. 
        // Region set to display > Region specified during login > default region
        if (HMRContext.region != null) {
            return HMRContext.region.area;
        }

        return HMRContext.Region.AREA_CN;
    }
}

RoomJoiningOptions

/**
 * Optional item body for joining a room, reserved parameter
 */
public class RoomJoiningOptions {}

RoomAttributeOptions

/**
 * Optional item body for room profiles, reserved parameter
 */
public class RoomAttributeOptions {
     /**
      * Whether to inform, no (default)
      */
    private boolean enableNotification = false;

    public boolean getEnableNotification() {
        return enableNotification;
    }

    public RoomAttributeOptions setEnableNotification(boolean enableNotification) {
        this.enableNotification = enableNotification;
        return this;
    }
}

MemberAttributeOptions

/**
 * Optional item body for room member profiles, reserved parameter
 */
public class MemberAttributeOptions {}
public class MemberAttributeOptions {
  /**
   * Whether to inform, no (default)
   */
    private boolean enableNotification = false;

    public boolean getEnableNotification() {
        return enableNotification;
    }

    public MemberAttributeOptions setEnableNotification(boolean enableNotification) {
        this.enableNotification = enableNotification;
        return this;
    }
}