Functional APIs

API List

• hmr

Public Static Function	Method Signature
void	init(uint32_t appId, const String& appVer, HummerEventHandler* handler)
char*	getSDKVersion()
RequestId	login(UserId userId, const String& region, const String& token)
RequestId	logout()
State	getState()
UserId	getUserId()
RequestId	refreshToken(const String& token)
bool	setLoggerFilePath(const String& path)
bool	setLogLevel(HMRLogLevel level
bool	setLogCallback(HummerLogCallback* callback)
bool	uploadLogsManually(const String& remark)

• PeerService

Public Member Function	Method Signature
RequestId	addEventHandler(PeerEventHandler* handler)
RequestId	removeEventHandler(PeerEventHandler* handler)
RequestId	sendMessage(UserId userId, const Message& message, const MessagingOptions& options = MessagingOptions())
RequestId	queryUserOnlineStatus(UserId userIds[], int count)

• RoomService

Public Member Function	Method Signature
RequestId	sendMessage(const RoomId& roomId, const Message& message, const MessagingOptions& options = MessagingOptions())
RequestId	addMemberEventHandler(MemberEventHandler* handler)
RequestId	removeMemberEventHandler(MemberEventHandler* handler)
RequestId	addRoomEventHandler(RoomEventHandler* handler)
RequestId	removeRoomEventHandler(RoomEventHandler* handler)
RequestId	joinRoom(const RoomId& roomId, const Dictionary& extras, const RoomJoinningOptions& options = RoomJoinningOptions())
RequestId	leaveRoom(const RoomId& roomId)
RequestId	setMemberAttributes(const RoomId& roomId, UserId userId, const Dictionary& attributes, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	addOrUpdateMemberAttributes(const RoomId& roomId, UserId userId, const Dictionary& attributes, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	deleteMemberAttributes(const RoomId& roomId, UserId userId, const String keys[], int numberOfKeys, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	clearMemberAttributes(const RoomId& roomId, UserId userId, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	queryMemberAttributes(const RoomId& roomId, UserId userId)
RequestId	queryMemberAttributesByKeys(const RoomId& roomId, UserId userId, const String keys[], int numberOfKeys)
RequestId	setRoomAttributes(const RoomId& roomId, const Dictionary& attributes, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	addOrUpdateRoomAttributes(const RoomId& roomId, const Dictionary& attributes, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	clearRoomAttributes(const RoomId& roomId, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	deleteRoomAttributes(const RoomId& roomId, const String keys[], int numberOfKeys, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	queryRoomAttributes(const RoomId& roomId)
RequestId	queryRoomAttributesByKeys(const RoomId& roomId, const String keys[], int numberOfKeys)
RequestId	queryMemberCounts(const String& roomRegion, const String roomIds[], int numberOfIds)
RequestId	queryMembers(const RoomId& roomId)

API Details

hmr

hmr::init

void init(uint32_t appId, 
          const String& appVer, 
          HummerEventHandler* handler)

Initialize a Hummer SDK

Notes:

• Unless otherwise specified, all Hummer API functions are called asynchronously, and the API is called in the same thread.
• The initial API must be called in the main thread.

Parameters

Parameter	Description
appId	appid for distinguishing services
appVer	Application version for data statistics and fault locating
handler	Event listener

---

hmr::getSDKVersion

const char* getSDKVersion()

Get SDK version information.

Return

• SDK version information

---

hmr::login

RequestId login(UserId userId, 
                const String& region, 
                const String& token)

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

Parameters

Parameter	Description
userId	User ID
region	Region configuration parameters for enabling user context
token	A token for initializing services

Return

• RequestId: unique request identifier

---

hmr::logout

RequestId logout()

Log out an SDK.

Notes:

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

Return

• RequestId: unique request identifier

---

hmr::getState

State getState()

Get the SDK current status. See details in hmr::State.

Return

SDK current status

---

hmr::refreshToken

RequestId refreshToken(const String& token)

Refresh a user token.

Parameters

Parameter	Description
token	A user token to be refreshed

Return

• RequestId: incrementing request ID for fault locating

---

hmr::setLoggerFilePath

bool setLoggerFilePath(const String& path)

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

Parameters

Parameter	Description
path	Set the global default directory of the log root path

Return

• [bool:]: return true for success.

---

hmr::setLogLevel

bool setLogLevel(hmr::HMRLogLevel level)

Set log output level

Parameters

Parameter	Description
level	Log level，See details in HMRLogLevel

Return

• [bool]：Return "true" for success.

---

hmr::setLogCallback

bool setLogCallback(HummerLogCallback* callback)

Set log output callback

Parameters

Parameter	Description
callback	Log output callback,see details in HummerLogCallback

Return

• [bool]：Return "true" for success.

---

hmr::uploadLogsManually

bool uploadLogsManually(const String& remark)

Report logs manually.

Parameters

Parameter	Description
remark	Remarks

Return

• [bool]：Return "true" for success.

---

PeerService

hmr::rts::PeerService::addEventHandler

RequestId addEventHandler(PeerEventHandler* handler)

Add listeners for signaling messages.

Notes:

• A listener mode for adding listeners for member events
• Based on the principle that listener applicants release the listeners, properly manage listener release after applying for one.
• When releasing listeners, call removeEventHandler to remove the SDK listener reference.

Parameters

Parameter	Description
handler	Listener to be added

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::PeerService::removeEventHandler

RequestId removeEventHandler(PeerEventHandler* handler)

Remove listeners for signaling messages.

Parameters

Parameter	Description
handler	Listener to be removed

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::PeerService::sendMessage

RequestId sendMessage(UserId userId,
                      const Message& message, 
                      const MessagingOptions& options = MessagingOptions())

Send P2P signaling messages.

Parameters

Parameter	Description
userId	ID of a signaling message receiver
message	Signaling messages to be sent
options	Configuration for sending the message

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::PeerService::queryUserOnlineStatus

RequestId queryUserOnlineStatus(UserId userIds[], int count)

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
count	Number of user lists

Return

• RequestId: incrementing request ID for fault locating

---

RoomService

hmr::rts::RoomService::sendMessage

RequestId sendMessage(const RoomId& roomId, 
                        const Message& message, 
                        const MessagingOptions& options = MessagingOptions()) 

Send room messages.

Parameters

Parameter	Description
roomId	Room ID for target operations
message	Message
options	Configuration for sending the message

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::addMemberEventHandler

RequestId addMemberEventHandler(MemberEventHandler* handler)

Add listeners for Member.

Notes:

• A listener mode for adding listeners for member events.
• Based on the principle that listener applicants release the listeners, properly manage listener release after applying for one.
• When releasing listeners, call removeMemberEventHandler to remove the SDK listener reference.

Parameters

Parameter	Description
handler	Listener to be added

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::removeMemberEventHandler

RequestId removeMemberEventHandler(MemberEventHandler* handler)

Remove listeners for Member.

Parameters

Parameter	Description
handler	Listener to be removed

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::addRoomEventHandler

RequestId addRoomEventHandler(RoomEventHandler* handler)

Add listeners for room events.

Notes:

• A listener mode for adding listeners for member events.
• Based on the principle that listener applicants release the listeners, properly manage listener release after applying for one.
• When releasing listeners, call removeRoomEventHandler to remove the SDK listener reference.

Parameters

Parameter	Description
handler	Listener to be added

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::removeRoomEventHandler

RequestId removeRoomEventHandler(RoomEventHandler* handler)

Remove listeners for room events.

Parameters

Parameter	Description
handler	Listener to be removed

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::joinRoom

RequestId joinRoom(const RoomId& roomId, 
                    const Dictionary& extras, 
                    const RoomJoinningOptions& options = RoomJoinningOptions())

APIs for joining a room.

Parameters

Parameter	Description
RoomId	Room: the room ID can contain only letters and digits selected from '[A,Z],[a,z],[0,9],-,_', with 64 bytes at maximum.[][][]
extras	Extension information for joining a room
options	Optional parameters for joining a room. See details in RoomJoiningOptions.

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::leaveRoom

RequestId leaveRoom(const RoomId& roomId)

APIs for exiting a room.

Parameters

Parameter	Description
roomId	Room ID for target operations. See details in RoomId.

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::setMemberAttributes

RequestId setMemberAttributes(const RoomId& roomId, 
                                UserId userId, const Dictionary& attributes, 
                                const MemberAttributeOptions& options = MemberAttributeOptions())

Set user profiles in the current room.

Notes:

• Set user information in the current room.
• 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.

Parameters

Parameter	Description
roomId	Room ID for target operations
userId	Room member
attributes	Information
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::addOrUpdateMemberAttributes

RequestId addOrUpdateMemberAttributes(const RoomId& roomId, 
                                        UserId userId, 
                                        const Dictionary& attributes, 
                                        const MemberAttributeOptions& options = MemberAttributeOptions())

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.

Parameters

Parameter	Description
roomId	Room ID for target operations
userId	Room member
attributes	Information
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::deleteMemberAttributes

RequestId deleteMemberAttributes(const RoomId& roomId, 
                                    UserId userId, const String keys[], 
                                    int numberOfKeys, 
                                    const MemberAttributeOptions& options = MemberAttributeOptions()) 

Delete specific user profiles in the current room.

Notes:

• Return success if some user profiles are deleted while some user profiles do not exist.
• You can only set your own profiles at present.

Parameters

Parameter	Description
roomId	Room ID
userId	Room member
keys	Set of attribute keys
numberOfKeys	Size of profile key set
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::clearMemberAttributes

RequestId clearMemberAttributes(const RoomId& roomId, 
                                UserId userId, 
                                const MemberAttributeOptions& options = MemberAttributeOptions())

Clear all user profiles in the room.

Notes:

• Return success if no profiles are set for the specific user.
• You can only set your own profiles at present.

Parameters

Parameter	Description
roomId	Room ID
userId	Room member
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryMemberAttributes

RequestId queryMemberAttributes(const RoomId& roomId, UserId userId)

Search all user profiles in the current room.

Notes:

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

Parameters

Parameter	Description
roomId	Room ID for target operations
userId	User ID

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryMemberAttributesByKeys

RequestId queryMemberAttributesByKeys(const RoomId& roomId, 
                                        UserId userId, 
                                        const String keys[], 
                                        int numberOfKeys)

Search specific user profiles in the current room.

Notes:

• Return success if the searched profiles 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 for target operations
userId	User ID
keys	Profile keys
numberOfKeys	Size of profile key set

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::setRoomAttributes

RequestId setRoomAttributes(const RoomId& roomId, 
                            const Dictionary& attributes, 
                            const RoomAttributeOptions& options = RoomAttributeOptions()) 

Set room profiles (full configuration of room profiles is supported for joining and exiting a room).

Notes:

• 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.

Parameters

Parameter	Description
roomId	Room ID for target operations
attributes	Profiles
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::addOrUpdateRoomAttributes

RequestId addOrUpdateRoomAttributes(const RoomId& roomId, 
                                        const Dictionary& attributes,
                                        const RoomAttributeOptions& options = RoomAttributeOptions())

Update profiles of specific rooms.

Notes:

• Update while profiles exist.
• Add while no profiles exist.

Parameters

Parameter	Description
roomId	Room ID
attributes	Profiles
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::deleteRoomAttributes

RequestId deleteRoomAttributes(const RoomId& roomId, 
                                const String keys[], 
                                int numberOfKeys, 
                                const RoomAttributeOptions& options = RoomAttributeOptions())

Delete specific attributes of specific rooms

Parameters

Parameter	Description
roomId	Room ID
keys	Profile keys
keys	Size of profile key set
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::clearRoomAttributes

RequestId clearRoomAttributes(const RoomId& roomId, const RoomAttributeOptions& options = RoomAttributeOptions())

Clear profiles of specific rooms.

Notes:

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

Parameters

Parameter	Description
roomId	Room ID
options	Options, see details in MemberAttributeOptions

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryRoomAttributes

RequestId queryRoomAttributes(const RoomId& roomId) 

Search all profiles of specific rooms.

Parameters

Parameter	Description
roomId	Room ID

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryRoomAttributesByKeys

RequestId queryRoomAttributesByKeys(const RoomId& roomId, const String keys[], int numberOfKeys)

Search specific profiles of specific rooms.

Parameters

Parameter	Description
roomId	Room ID
keys	Profile keys
numberOfKeys	Number of profiles

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryMemberCounts

RequestId queryMemberCounts(const String& roomRegion, 
                                const String roomIds[], 
                                int numberOfIds)

Batch search of the number of room members.

Notes:

• Support concurrent search of 20 rooms at maximum.

Parameters

Parameter	Description
roomRegion	Room region
roomIds	Room list
numberOfIds	Number of rooms

Return

• RequestId: incrementing request ID for fault locating

---

hmr::rts::RoomService::queryMembers

RequestId queryMembers(const RoomId& roomId)

Search a list of room members.

Notes:

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

Parameters

Parameter	Description
roomId	Room ID

Return

• RequestId: incrementing request ID for fault locating

---

Reference Class

hmr::State

/**
* SDK current status
*/
enum State {
	/** Disconnected */
	HMR_DISCONNECTED = 0,
	/** Connecting */
	HMR_CONNECTING = 1,
	/** Re-connecting */
	HMR_RECONNECTING = 2,
	/** Connected */
	HMR_CONNECTED = 3,
};

hmr::RequestId

typedef uint64_t RequestId

hmr::String

	/**
	* String data structure
	*
	* Corresponding to the std::string data structure of c++. To avoid the STL version
	* conflict, dedicated encapsulation is provided.
	*/
	struct StringImpl;
	struct HMR_API String {
	public: 
		String();
		String(const char* ansiString);
		String(const char* rawBytes, int size);
		String(const String& cpy);
		~String();
		String& operator=(const String& rhs);

		const char* c_str() const;
		const char* operator()() const;
		bool operator==(const String& _Right) const;
		bool operator<(const String& _Right) const;
		int size() const;

	private:
		StringImpl* impl;
	};

hmr::KVItem

	/**
	* Binary data item for Key-Value string
	*
	* Corresponding to the std::pair<std::string, std::string> data structure of c++. To avoid the STL version
	* conflict, dedicated encapsulation is provided.
	*/
	struct KVItem {
		const char* key;
		const char* value;
	};

hmr::Dictionary

	/**
	* Data structure of string dictionary
	*
	* Data structure corresponding to the std::map<std::string, std::string> of c++. To avoid the STL version
	* conflict, dedicated encapsulation is provided.
	*/
	class DictionaryImpl;
	struct HMR_API Dictionary {
	public: 
		Dictionary();
		Dictionary(const Dictionary& cpy);
		Dictionary& operator = (const Dictionary& rhs);
		~Dictionary();

		/**
		* Add KV data items
		*
		* @param key Index name of header data
		* @param value Header data value
		*/
		void add(const char* key, const char* value);

		/**
		* Remove KV data items based on the value of key.
		*
		* @param Index name of header data
		*/
		void remove(const char* key);

		/**
		* Get the total quantity of data items
		*/
		int count() const;

		/**
		* Position data item, which is used for enumerating data when the value of key is unknown.
		*/
		const KVItem* itemAt(int position) const;

		/**
		* Query the header value based on the header data key
		*
		* @param key Index name of header data
		*/
		const char* valueFor(const char* key) const;

		bool operator == (const Dictionary& rhs) const;

	private: 
		DictionaryImpl* impl;
	};

hmr::Code

// Return code encapsulation.
	struct Code {
		HMRCode code;
		String   desc;
	};

hmr::HMRLogLevel

enum HMRLogLevel
{
  HMR_LOG_LEVEL_TRACE = 0,
  HMR_LOG_LEVEL_DEBUG = 1,
  HMR_LOG_LEVEL_INFO = 2,
  HMR_LOG_LEVEL_WARNING = 3,
  HMR_LOG_LEVEL_ERROR = 4
};

hmr::HummerLogCallback

class HummerLogCallback
{
 public:
  /**
   * @brief Log output callback日
   * @param [IN] level Level of the log to be output
   * @param [IN] msg Log to be output
   */
  virtual void onHummerLogWithLevel(HMRLogLevel level, const String& msg) = 0;

 public:
  virtual ~HummerLogCallback() {}
};

hmr::rts::Message

/**
* Message body
*/
struct Message {
	String type;
	String content;
	Dictionary extras;
};

hmr::rts::MessagingOptions

/**
* Message configuration information
*/
struct MessagingOptions {
};

hmr::rts::RoomId

/**
* Room body
* Uniquely identify a room with the room ID and room region.
*/
struct RoomId {
public: 
	RoomId();
	RoomId(const String& id);
	RoomId(const String& id, const String& region);

	String getId() const;
	void setId(const String& id);

	String getRegion() const;
	void setRegion(const String& region);

	bool operator<(const RoomId& lhs) const;

	String toString() const;

private:
	String id;
	String region;
};

hmr::rts::RoomAttributeOptions

struct RoomAttributeOptions
{
  bool enableNotification = false; //Broadcasting is disabled by default

};

hmr::rts::MemberAttributeOptions

struct MemberAttributeOptions
{
  bool enableNotification = false; //Broadcasting is disabled by default
};