diff --git a/Agora-RTM-Tutorial-Linux/include/IAgoraRtmCallManager.h b/Agora-RTM-Tutorial-Linux/include/IAgoraRtmCallManager.h index da07ee8..0d10ca0 100644 --- a/Agora-RTM-Tutorial-Linux/include/IAgoraRtmCallManager.h +++ b/Agora-RTM-Tutorial-Linux/include/IAgoraRtmCallManager.h @@ -10,177 +10,480 @@ namespace agora { namespace rtm { - + + /** + @brief RETURNED TO THE CALLER. States of an outgoing call invitation. + */ enum LOCAL_INVITATION_STATE { + + /** + 0: RETURNED TO THE CALLER. The initial state of a call invitation (idle). + */ LOCAL_INVITATION_STATE_IDLE = 0, + + /** + 1: RETURNED TO THE CALLER. The call invitation is sent to the callee. + */ LOCAL_INVITATION_STATE_SENT_TO_REMOTE = 1, + + /** + 2: RETURNED TO THE CALLER. The call invitation is received by the callee. + */ LOCAL_INVITATION_STATE_RECEIVED_BY_REMOTE = 2, + + /** + 3: RETURNED TO THE CALLER. The call invitation is accepted by the callee. + */ LOCAL_INVITATION_STATE_ACCEPTED_BY_REMOTE = 3, + + /** + 4: RETURNED TO THE CALLER. The call invitation is declined by the callee. + */ LOCAL_INVITATION_STATE_REFUSED_BY_REMOTE = 4, + + /** + 5: RETURNED TO THE CALLER. You have canceled the call invitation. + */ LOCAL_INVITATION_STATE_CANCELED = 5, + + /** + 6: RETURNED TO THE CALLER. The call invitation fails. + */ LOCAL_INVITATION_STATE_FAILURE = 6, }; + /** + @brief RETURNED TO THE CALLEE. States of an incoming call invitation. + */ enum REMOTE_INVITATION_STATE { + + /** + 0: RETURNED TO THE CALLEE. The initial state of a call invitation (idle). + */ REMOTE_INVITATION_STATE_IDLE = 0, + + /** + 1: RETURNED TO THE CALLEE. A call invitation from a remote caller is received. + */ REMOTE_INVITATION_STATE_INVITATION_RECEIVED = 1, + + /** + 2: RETURNED TO THE CALLEE. The message is sent to the caller that the call invitation is accepted. + */ REMOTE_INVITATION_STATE_ACCEPT_SENT_TO_LOCAL = 2, + + /** + 3: RETURNED TO THE CALLEE. You have declined the call invitation. + */ REMOTE_INVITATION_STATE_REFUSED = 3, + + /** + 4: RETURNED TO THE CALLEE. You have accepted the call invitation. + */ REMOTE_INVITATION_STATE_ACCEPTED = 4, + + /** + 5: RETURNED TO THE CALLEE. The call invitation is canceled by the remote caller. + */ REMOTE_INVITATION_STATE_CANCELED = 5, + + /** + 6: RETURNED TO THE CALLEE. The call invitation fails. + */ REMOTE_INVITATION_STATE_FAILURE = 6, }; + /** + @brief RETURNED TO THE CALLER. Error codes of an outgoing call invitation. + */ enum LOCAL_INVITATION_ERR_CODE { + + /** + 0: RETURNED TO THE CALLER. The outgoing invitation succeeds. + */ LOCAL_INVITATION_ERR_OK = 0, + + /** + 1: RETURNED TO THE CALLER. The callee is offline. + + The SDK performs the following: + - Keeps resending the call invitation to the callee, if the callee is offline. + - Returns this error code, if the callee is still offline 30 seconds since the call invitation is sent. + */ LOCAL_INVITATION_ERR_PEER_OFFLINE = 1, + + /** + 2: RETURNED TO THE CALLER. The callee is online but has not ACKed to the call invitation 30 seconds since it is sent. + */ LOCAL_INVITATION_ERR_PEER_NO_RESPONSE = 2, + + /** + 3: RETURNED TO THE CALLER. SAVED FOR FUTURE USE. The call invitation expires 60 seconds since it is sent, if the callee ACKs to the call invitation but neither the caller or callee takes any further action (cancel, accpet, or decline it). + */ LOCAL_INVITATION_ERR_INVITATION_EXPIRE = 3, + + /** + 4: RETURNED TO THE CALLER. The caller is not logged in. + */ LOCAL_INVITATION_ERR_NOT_LOGGEDIN = 4, }; - + + /** + @brief RETURNED TO THE CALLEE. Error codes of an incoming call invitation. + */ enum REMOTE_INVITATION_ERR_CODE { + + /** + 0: RETURNED TO THE CALLEE. The incoming calll invitation succeeds. + */ REMOTE_INVITATION_ERR_OK = 0, + + /** + 1: RETURNED TO THE CALLEE. The call invitation received by the callee fails: the callee is not online. + */ REMOTE_INVITATION_ERR_PEER_OFFLINE = 1, + + /** + 2: RETURNED TO THE CALLEE. The call invitation received by callee fails: The callee does not ACK within a set time after the callee accepts the call invitation. This is usually a result of a network interruption. + */ REMOTE_INVITATION_ERR_ACCEPT_FAILURE = 2, + + /** + 3: RETURNED TO THE CALLEE. The call invitation expires 60 seconds since it is sent, if the callee ACKs to the call invitation but neither the caller or callee takes any further action (cancel, accpet, or decline it). + */ REMOTE_INVITATION_ERR_INVITATION_EXPIRE = 3, }; + /** + @brief Error codes of the call invitation methods. + */ enum INVITATION_API_CALL_ERR_CODE { + + /** + 0: The method call succeeds. + */ INVITATION_API_CALL_ERR_OK = 0, + + /** + 1: The method call fails. The argument is invalid, for example, the value of the @p content parameter exceeds 8K bytes. + */ INVITATION_API_CALL_ERR_INVALID_ARGUMENT = 1, + + /** + 2: The method call fails. The call invitation has not started. + */ INVITATION_API_CALL_ERR_NOT_STARTED = 2, + + /** + 3: The method call fails. The call invitation has ended. + */ INVITATION_API_CALL_ERR_ALREADY_END = 3, // accepted, failure, canceled, refused + + /** + 4: The method call fails. The call invitation is already accepted. + */ INVITATION_API_CALL_ERR_ALREADY_ACCEPT = 4, // more details + + /** + 5: The method call fails. The call invitation is already sent. + */ INVITATION_API_CALL_ERR_ALREADY_SENT = 5, }; - /** RTM call request methods. - */ + /** + The class allowing the caller to retrieve the attributes of an outgoing call invitation. + */ class ILocalCallInvitation { protected: virtual ~ILocalCallInvitation() {} public: + + /** + Allows the caller to get the User ID of the callee. + */ virtual const char *getCalleeId() const = 0; - + + /** + Allows the caller to set the call invitation content. + + @param content The content of the call invitation. The @p content must not exceed 8 KB in length if encoded in UTF-8. + */ virtual void setContent(const char *content) = 0; + + /** + Allows the caller to get the call invitation content. + + @note The caller sets the call invitation content using the \ref agora::rtm::ILocalCallInvitation::setContent "setContent" method. + */ virtual const char *getContent() const = 0; - + + /** + Sets the channel ID. + + @note To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora RTM SDK does not join the channel of the specified channel ID. + + @param channelId The channel ID to be set. + */ virtual void setChannelId(const char *channelId) = 0; + + /** + Gets the channel ID. + */ virtual const char *getChannelId() const = 0; - + + /** + Allows the caller to get the callee's response to the call invitation. + + @note The callee sets his/her response using the \ref agora::rtm::IRemoteCallInvitation::setResponse "setResponse" method. + */ virtual const char *getResponse() const = 0; + + /** + Allows the caller to get the state of the outgoing call invitation. + @return State of the outgoing call invitation. See: #LOCAL_INVITATION_STATE. + */ virtual LOCAL_INVITATION_STATE getState() const = 0; - + + /** + Releases all resources used by the ILocalCallInvitation instance. + */ virtual void release() = 0; }; + /** + The class allowing the callee to retrieve the attributes of an incoming call invitation. + */ class IRemoteCallInvitation { protected: virtual ~IRemoteCallInvitation() {} public: + + /** + Allows the callee to get the User ID of the caller. + */ virtual const char *getCallerId() const = 0; - + + /** + Allows the callee to get the call invitation content set by the caller. + + @note The caller sets the call invitation content using the \ref agora::rtm::ILocalCallInvitation::setContent "setContent" method. + */ virtual const char *getContent() const = 0; + + /** + Allows the callee to set a response to the call invitation. + @param response The callee's response to the call invitation. The @p response must not exceed 8 KB in length if encoded in UTF-8. + */ virtual void setResponse(const char *response) = 0; + + /** + Allows the callee to get his/her response to the incoming call invitation. + + @note The callee sets a response to the incoming call invitation using the \ref agora::rtm::IRemoteCallInvitation::setResponse "setResponse" method. + */ virtual const char *getResponse() const = 0; - + + /** + Gets the channel ID. + */ virtual const char *getChannelId() const = 0; - + + /** + Allows the callee to get the state of the incoming call invitation. + + @return The state of the incoming call invitation See: #REMOTE_INVITATION_STATE. + */ virtual REMOTE_INVITATION_STATE getState() const = 0; + + /** + Releases all resources used by the IRemoteCallInvitation instance. + */ virtual void release() = 0; }; + /** + Callbacks for the call invitation methods. + */ class IRtmCallEventHandler { public: virtual ~IRtmCallEventHandler() { } - + + /** + Callback to the caller: occurs when the callee receives the call invitation. + + @param localInvitation An ILocalCallInvitation object. + */ virtual void onLocalInvitationReceivedByPeer(ILocalCallInvitation *localInvitation) { (ILocalCallInvitation *) localInvitation; } - + + /** + Callback to the caller: occurs when the caller cancels a call invitation. + + @param localInvitation An ILocalCallInvitation object. + */ virtual void onLocalInvitationCanceled(ILocalCallInvitation *localInvitation) { (ILocalCallInvitation *) localInvitation; } - + + /** + Callback to the caller: occurs when the life cycle of the outgoing call invitation ends in failure. + + @param localInvitation An ILocalCallInvitation object. + @param errorCode The error code. See #LOCAL_INVITATION_ERR_CODE. + */ virtual void onLocalInvitationFailure(ILocalCallInvitation *localInvitation, LOCAL_INVITATION_ERR_CODE errorCode) { (ILocalCallInvitation *) localInvitation; (LOCAL_INVITATION_ERR_CODE) errorCode; } - + + /** + Callback to the caller: occurs when the callee accepts the call invitation. + + @param localInvitation An ILocalCallInvitation object. + @param response The callee's response to the call invitation. + */ virtual void onLocalInvitationAccepted(ILocalCallInvitation *localInvitation, const char *response) { (ILocalCallInvitation *) localInvitation; (const char *) response; } + + /** + Callback to the caller: occurs when the callee refuses the call invitation. + @param localInvitation An ILocalCallInvitation object. + @param response The callee's response to the call invitation. + */ virtual void onLocalInvitationRefused(ILocalCallInvitation *localInvitation, const char *response) { (ILocalCallInvitation *) localInvitation; (const char *) response; } - + + /** + Callback for the callee: occurs when the callee refuses a call invitation. + + @param remoteInvitation An IRemoteCallInvitation object. + */ virtual void onRemoteInvitationRefused(IRemoteCallInvitation *remoteInvitation) { (IRemoteCallInvitation *) remoteInvitation; } - + + /** + Callback to the callee: occurs when the callee accepts a call invitation. + + @param remoteInvitation An IRemoteCallInvitation object. + */ virtual void onRemoteInvitationAccepted(IRemoteCallInvitation *remoteInvitation) { (IRemoteCallInvitation *) remoteInvitation; } - + + /** + Callback to the callee: occurs when the callee receives a call invitation. + + @param remoteInvitation An IRemoteCallInvitation object. + */ virtual void onRemoteInvitationReceived(IRemoteCallInvitation *remoteInvitation) { (IRemoteCallInvitation *) remoteInvitation; } - + + /** + Callback to the callee: occurs when the life cycle of the incoming call invitation ends in failure. + + @param remoteInvitation An IRemoteCallInvitation object. + @param errorCode The error code. See #REMOTE_INVITATION_ERR_CODE. + */ virtual void onRemoteInvitationFailure(IRemoteCallInvitation *remoteInvitation, REMOTE_INVITATION_ERR_CODE errorCode) { (IRemoteCallInvitation *) remoteInvitation; } - + + /** + Callback to the callee: occurs when the caller cancels the call invitation. + + @param remoteInvitation An IRemoteCallInvitation object. + */ virtual void onRemoteInvitationCanceled(IRemoteCallInvitation *remoteInvitation) { (IRemoteCallInvitation *) remoteInvitation; } }; - + + /** + RTM call manager methods. + */ class IRtmCallManager { protected: virtual ~IRtmCallManager() {} public: - /** Send Rtm call invite request. - - */ + + /** + Allows the caller to send a call invitation to the callee. + + @param invitation An \ref agora::rtm::ILocalCallInvitation "ILocalCallInvitation" object. + @return + - 0: Success. + - <0: Failure. See #INVITATION_API_CALL_ERR_CODE for the error code. + */ virtual int sendLocalInvitation(ILocalCallInvitation *invitation)= 0; - /** Send Rtm call invite request. - - */ + + /** + Allows the callee to accept an incoming call invitation. + + @param invitation An \ref agora::rtm::IRemoteCallInvitation "IRemoteCallInvitation" object. + @return + - 0: Success. + - <0: Failure. See #INVITATION_API_CALL_ERR_CODE for the error code. + */ virtual int acceptRemoteInvitation(IRemoteCallInvitation *invitation) = 0; - /** Send Rtm call refuse request - - */ + + /** + Allows the callee to decline an incoming call invitation. + + @param invitation An \ref agora::rtm::IRemoteCallInvitation "IRemoteCallInvitation" object. + @return + - 0: Success. + - <0: Failure. See #INVITATION_API_CALL_ERR_CODE for the error code. + */ virtual int refuseRemoteInvitation(IRemoteCallInvitation *invitation) = 0; - /** Send Rtm call end request - */ + + /** + Allows the caller to cancel an outgoing call invitation. + + @param invitation An \ref agora::rtm::ILocalCallInvitation "ILocalCallInvitation" object. + @return + - 0: Success. + - <0: Failure. See #INVITATION_API_CALL_ERR_CODE for the error code. + */ virtual int cancelLocalInvitation(ILocalCallInvitation *invitation) = 0; - + + /** + Creates an ILocalCallInvitation object. + + @param calleeId The Callee's user ID. + @return An \ref agora::rtm::ILocalCallInvitation "ILocalCallInvitation" object. + */ virtual ILocalCallInvitation *createLocalCallInvitation(const char *calleeId) = 0; + // sync_call - /** Releases all resources used by the IRtmCall instance. - */ + /** + Releases all resources used by the IRtmCallManager instance. + */ virtual void release() = 0; }; } diff --git a/Agora-RTM-Tutorial-Linux/include/IAgoraRtmService.h b/Agora-RTM-Tutorial-Linux/include/IAgoraRtmService.h index 6cf98c9..49b6359 100644 --- a/Agora-RTM-Tutorial-Linux/include/IAgoraRtmService.h +++ b/Agora-RTM-Tutorial-Linux/include/IAgoraRtmService.h @@ -1,11 +1,12 @@ // -// Agora's RTM SDK +// The Agora RTM SDK // // -// Copyright (c) 2019 Agora.io. All rights reserved. +// Copyright (c) 2020 Agora.io. All rights reserved. // #pragma once +#include #if defined(_WIN32) #define WIN32_LEAN_AND_MEAN #include @@ -38,303 +39,1481 @@ #define _AGORA_CPP_API #endif + +/** + The prefix for ending a call. You can use it with the \ref agora::rtm::IRtmService::sendMessageToPeer(const char *peerId, const IMessage *message, const SendMessageOptions &options) "sendMessageToPeer" method to be compatible with the endCall method of the legacy Agora Signaling SDK. + */ +#define AGORA_RTM_ENDCALL_PREFIX "AgoraRTMLegacyEndcallCompatibleMessagePrefix" + namespace agora { namespace rtm { - - /** Login states. - */ + + /** + @brief Error codes related to Initialization. + */ + enum INIT_ERR_CODE { + + /** + 0: Initialization succeeds. + */ + INIT_ERR_OK = 0, + + /** + 1: A common failure occurs during initialization. + */ + INIT_ERR_FAILURE = 1, + + /** + 2: The SDK is already initialized. + */ + INIT_ERR_ALREADY_INITIALIZED = 2, + + /** + 3: The App ID is invalid. + */ + INIT_ERR_INVALID_APP_ID = 3, + + /** + 4: The event handler is empty. + */ + INIT_ERR_INVALID_ARGUMENT = 4, + }; + + + /** + @brief Error codes related to login. + */ enum LOGIN_ERR_CODE { - /** Login succeeds. No error occurs. */ + + /** + 0: The method call succeeds, or login succeeds. + */ LOGIN_ERR_OK = 0, - /** Login fails. The reason is unknown.*/ + + /** + 1: Login fails. The reason is unknown. + */ LOGIN_ERR_UNKNOWN = 1, - /** Login is rejected. the SDK is not initialized or is rejected by the server. */ + + /** + 2: Login is rejected by the server. + */ LOGIN_ERR_REJECTED = 2, // Occurs when not initialized or server reject - /** Invalid login argument.*/ + + /** + 3: Invalid login argument. + */ LOGIN_ERR_INVALID_ARGUMENT = 3, - /** Invalid App ID. */ + + /** + 4: The App ID is invalid. + */ LOGIN_ERR_INVALID_APP_ID = 4, - /** Invalid token. */ + + /** + 5: The token is invalid. + */ LOGIN_ERR_INVALID_TOKEN = 5, - /** The token has expired and login is rejected.*/ + + /** + 6: The token has expired, and hence login is rejected. + */ LOGIN_ERR_TOKEN_EXPIRED = 6, - /** Unauthorized login. */ + + /** + 7: Unauthorized login. + */ LOGIN_ERR_NOT_AUTHORIZED = 7, - /** The user is already logged-in or logging-in. */ - LOGIN_ERR_ALREADY_LOGIN = 8, - /** A login timeout. */ + + /** + 8: The user has already logged in or is logging in the Agora RTM system, or the user has not called the \ref agora::rtm::IRtmService::logout "logout" method to leave the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" state. + */ + LOGIN_ERR_ALREADY_LOGGED_IN = 8, + + /** + 9: The login times out. The current timeout is set as six seconds. You need to log in again. + */ LOGIN_ERR_TIMEOUT = 9, + + /** + 10: The call frequency of the \ref agora::rtm::IRtmService::login "login" method exceeds the limit of two queries per second. + */ LOGIN_ERR_TOO_OFTEN = 10, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + LOGIN_ERR_NOT_INITIALIZED = 101, }; - /** Logout states. - */ + + /** + @brief Error codes related to logout. + */ enum LOGOUT_ERR_CODE { - /** Logout succeeds. No error occurs. */ + + /** + 0: The method call succeeds, or logout succeeds. + */ LOGOUT_ERR_OK = 0, - /** Logout fails. Maybe the SDK is not initialized or the user is not logged in. */ + + /** + 1: **RESERVED FOR FUTURE USE** + */ LOGOUT_ERR_REJECTED = 1, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + LOGOUT_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before the user logs out of the Agora RTM system. + */ + LOGOUT_ERR_USER_NOT_LOGGED_IN = 102, }; + /** + @brief Error codes related to renewing the RTM Token. + */ enum RENEW_TOKEN_ERR_CODE { + + /** + 0: The method call succeeds, or the renewing operation succeeds. + */ RENEW_TOKEN_ERR_OK = 0, + + /** + 1: Common failure. The user fails to renew the token. + */ RENEW_TOKEN_ERR_FAILURE = 1, + + /** + 2: The method call fails. The argument is invalid. + */ RENEW_TOKEN_ERR_INVALID_ARGUMENT = 2, + + /** + 3: **RESERVED FOR FUTURE USE** + */ RENEW_TOKEN_ERR_REJECTED = 3, + + /** + 4: The method call frequency exceeds the limit of two queries per second. + */ RENEW_TOKEN_ERR_TOO_OFTEN = 4, + + /** + 5: The token has expired. + */ RENEW_TOKEN_ERR_TOKEN_EXPIRED = 5, + + /** + 6: The token is invalid. + */ RENEW_TOKEN_ERR_INVALID_TOKEN = 6, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + RENEW_TOKEN_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before renewing the token. + */ + RENEW_TOKEN_ERR_USER_NOT_LOGGED_IN = 102, }; - /** Connection states. - */ + + /** + @brief Connection states between the SDK and the Agora RTM system. + */ enum CONNECTION_STATE { - /** The SDK is logged out of Agora's RTM service and is trying to log in. - - If the connection to Agora's RTM service is lost because, for example, if the network is down or switched, the SDK automatically tries to log in, triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback, and switches to the \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. -*/ + + /** + 1: The initial state. The SDK is disconnected from the Agora RTM system. + + When the user calls the \ref agora::rtm::IRtmService::login "login" method, the SDK starts to log in the Agora RTM system, triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback, and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTING "CONNECTION_STATE_CONNECTING" state. + */ CONNECTION_STATE_DISCONNECTED = 1, - /** The SDK is logging in Agora's RTM service. + + /** + 2: The SDK is logging in the Agora RTM system. - When the application calls the \ref agora::rtm::IRtmService::login "login" method, the SDK starts to log in Agora's RTM service, triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback, and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTING "CONNECTION_STATE_CONNECTING" state. - When the SDK successfully logs in Agora's RTM service, it triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTED "CONNECTION_STATE_CONNECTED" state. - - After the SDK logs in Agora's RTM service and when it finishes initializing the media engine, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onLoginSuccess "onLoginSuccess" callback. + - If the user successfully logs in the Agora RTM system and receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginSuccess "onLoginSuccess" callback, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTED "CONNECTION_STATE_CONNECTED" state. + - If the user fails to login the Agora RTM system and receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginFailure "onLoginFailure" callback, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_DISCONNECTED "CONNECTION_STATE_DISCONNECTED" state. */ CONNECTION_STATE_CONNECTING = 2, - /** The SDK is connected to Agora's RTM system. + + /** + 3: The SDK has logged in the Agora RTM system. - - When the app calls the \ref agora::rtm::IRtmService::login "login" method, the SDK starts to log in Agora's RTM service, triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback, and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTING "CONNECTION_STATE_CONNECTING" state. - - When the SDK successfully logs in Agora's RTM service, it triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTED "CONNECTION_STATE_CONNECTED" state. - - After the SDK logs in Agora's RTM service and when it finishes initializing the media engine, the SDK triggers the \ref agora::rtm::IChannelEventHandler::onMemberJoined "onMemberJoined" callback. + - If the connection state between the SDK and the Agora RTM system is interrupted because of network issues, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + - If the login is banned by the server because, for example, another instance logs in the Agora RTM system with the same user ID, the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback is triggered, and the SDK is switched to the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" state. + - If the user calls the \ref agora::rtm::IRtmService::logout "logout" method to log out of the Agora RTM system and receives the \ref agora::rtm::IRtmServiceEventHandler::onLogout "onLogout" callback (error code = `LOGOUT_ERR_OK`), the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_DISCONNECTED "CONNECTION_STATE_DISCONNECTED" state. */ CONNECTION_STATE_CONNECTED = 3, - /** The SDK keeps logging in Agora's RTM service after being logged out because of network issues. + + /** + 4: The connection state between the SDK and the Agora RTM system is interrupted due to network issues, and the SDK keeps re-logging in the Agora RTM system. - - If the SDK cannot log in Agora's RTM service within 10 seconds after being logged out, the SDK stays in the \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state and keeps logging in. - - If the SDK fails to log in Agora's RTM service 20 minutes after being logged out, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback, switches to the \ref agora::rtm::CONNECTION_STATE_FAILED "CONNECTION_STATE_FAILED" state, and stops logging in. + - If the SDK successfully re-logs in the Agora RTM system, the SDK triggers the \ref agora::rtm::IRtmServiceEventHandler::onConnectionStateChanged "onConnectionStateChanged" callback and switches to the \ref agora::rtm::CONNECTION_STATE_CONNECTED "CONNECTION_STATE_CONNECTED" state. The SDK automatically adds the user back to the channels he or she was in when the connection was interrupted, and synchronizes the local user's attributes with the server. + - If the SDK cannot re-log in the Agora RTM system, it stays in the \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state and keeps re-logging in the system. */ CONNECTION_STATE_RECONNECTING = 4, - /** The SDK has given up logging in Agora's RTM service, mainly because the SDK is banned by the service or because the SDK has logged in with the same user ID from a different instance or device. To log in again, call the \ref agora::rtm::IRtmService::logout "logout" method before calling the \ref agora::rtm::IRtmService::login "login" method again. - */ + + /** + 5: The SDK gives up logging in the Agora RTM system, mainly because another instance has logged in the Agora RTM system with the same user ID. + + You must call the \ref agora::rtm::IRtmService::logout "logout" method to leave this state before calling the \ref agora::rtm::IRtmService::login "login" method again. + */ CONNECTION_STATE_ABORTED = 5, }; - /** Reasons for a connection state change. - */ + /** + @brief Reasons for a connection state change. + */ enum CONNECTION_CHANGE_REASON { - /** The SDK is logging in Agora's RTM service. - */ + + /** + 1: The SDK is logging in the Agora RTM system. + */ CONNECTION_CHANGE_REASON_LOGIN = 1, - /** The SDK has logged in Agora's RTM service. - */ + + /** + 2: The SDK has logged in the Agora RTM system. + */ CONNECTION_CHANGE_REASON_LOGIN_SUCCESS = 2, - /** The SDK fails to log in Agora's RTM service. - */ + + /** + 3: The SDK fails to log in the Agora RTM system. + */ CONNECTION_CHANGE_REASON_LOGIN_FAILURE = 3, - /** The SDK fails to log in Agora's RTM service for more than 20 minutes and stops logging in. - */ + + /** + 4: The SDK fails to log in the Agora RTM system within six seconds and gives up. + */ CONNECTION_CHANGE_REASON_LOGIN_TIMEOUT = 4, - /** The SDK login to Agora's RTM service is interrupted. - */ + + /** + 5: The connection between the SDK and the Agora RTM system is interrupted. The system defines an interruption when the SDK loses connection with the Agora RTM system for network reasons and cannot recover in four seconds. + */ CONNECTION_CHANGE_REASON_INTERRUPTED = 5, - /** The SDK has logged out of Agora's RTM service. - */ + + /** + 6: The user has called the \ref agora::rtm::IRtmService::logout "logout" method to log out of the Agora RTM system. + */ CONNECTION_CHANGE_REASON_LOGOUT = 6, - /** The SDK login to Agora's RTM service is banned by Agora. - */ + + /** + 7: The SDK login to the Agora RTM system is banned by Agora. + */ CONNECTION_CHANGE_REASON_BANNED_BY_SERVER = 7, - + + /** + 8: Another user is logging in the Agora RTM system with the same User ID. + */ CONNECTION_CHANGE_REASON_REMOTE_LOGIN = 8, }; - /** States of sending a peer-to-peer message. - */ + /** + @brief Error codes related to sending a peer-to-peer message. + */ enum PEER_MESSAGE_ERR_CODE { - /** The receiver receives the peer-to-peer message. + + /** + 0: The method call succeeds, or the specified user receives the peer-to-peer message. */ PEER_MESSAGE_ERR_OK = 0, - /** The sender fails to send the peer-to-peer message. - */ + + /** + 1: The sender fails to send the peer-to-peer message. + */ PEER_MESSAGE_ERR_FAILURE = 1, - /** A timeout in sending the peer-to-peer message. The current timeout is set as 5 seconds. - */ + + /** + 2: A timeout occurs when sending the peer-to-peer message. The current timeout is set as 10 seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ PEER_MESSAGE_ERR_SENT_TIMEOUT = 2, - /** The receiver is offline and does not receive the peer-to-peer message. + + /** + 3: The specified user is offline and does not receive this peer-to-peer message. */ PEER_MESSAGE_ERR_PEER_UNREACHABLE = 3, + + /** + 4: The receiver is offline and does not receive this offline peer-to-peer message, but the server has cached it and will re-send it once he/she is back online. + */ + PEER_MESSAGE_ERR_CACHED_BY_SERVER = 4, + + /** + 5: The method call frequency exceeds the limit of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds, with channel and peer messages taken together.. + */ + PEER_MESSAGE_ERR_TOO_OFTEN = 5, + + /** + 6: The user ID is invalid. + */ + PEER_MESSAGE_ERR_INVALID_USERID = 6, + + /** + 7: The message is null or exceeds 32 KB in length. + */ + PEER_MESSAGE_ERR_INVALID_MESSAGE = 7, + + /** + 8: The message receiver‘s SDK is of an earlier version and hence cannot recognize this message. + */ + PEER_MESSAGE_ERR_IMCOMPATIBLE_MESSAGE = 8, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + PEER_MESSAGE_ERR_NOT_INITIALIZED = 101, + + /** + 102: The sender does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before sending the peer-to-peer message. + */ + PEER_MESSAGE_ERR_USER_NOT_LOGGED_IN = 102, }; - /** States of a user joining a channel. - */ + /** + @brief Error codes related to joining a channel. + */ enum JOIN_CHANNEL_ERR { - /** The user joins the channel successfully. - */ + + /** + 0: The method call succeeds, or the user joins the channel successfully. + */ JOIN_CHANNEL_ERR_OK = 0, - /** The user fails to join the channel. - */ + + /** + 1: Common failure. The user fails to join the channel. + */ JOIN_CHANNEL_ERR_FAILURE = 1, - /** The user cannot join the channel. The user may already be in the channel. - */ + + /** + 2: For v1.0.0 and earlier, the SDK returns this error when you try to join a channel that you have already joined. The SDK does not return this error code after v1.0.0. + */ JOIN_CHANNEL_ERR_REJECTED = 2, // Usually occurs when the user is already in the channel - /** The user fails to join the channel. Maybe the argument is invalid. - */ + + /** + 3: The user fails to join the channel because the argument is invalid. + */ JOIN_CHANNEL_ERR_INVALID_ARGUMENT = 3, - /** A timeout in joining the channel. - */ + + /** + 4: A timeout occurs when joining the channel. The current timeout is set as five seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ JOIN_CHANNEL_TIMEOUT = 4, + + /** + 5: The number of the RTM channels you are in exceeds the limit of 20. + */ + JOIN_CHANNEL_ERR_EXCEED_LIMIT = 5, + + /** + 6: The user is joining or has joined the channel. + */ + JOIN_CHANNEL_ERR_ALREADY_JOINED = 6, + + /** + 7: The method call frequency exceeds 50 queries every three seconds. + */ + JOIN_CHANNEL_ERR_TOO_OFTEN = 7, + + /** + 8: The frequency of joining the same channel exceeds two times every five seconds. + */ + JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN = 8, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + JOIN_CHANNEL_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before joining the channel. + */ + JOIN_CHANNEL_ERR_USER_NOT_LOGGED_IN = 102, }; - /** States of a user leaving a channel. - */ + /** + @brief Error codes related to leaving a channel. + */ enum LEAVE_CHANNEL_ERR { - /** The user leaves the channel successfully. - */ + + /** + 0: The method call succeeds, or the user leaves the channel successfully. + */ LEAVE_CHANNEL_ERR_OK = 0, - /** The user fails to leave the channel. - */ + + /** + 1: Common failure. The user fails to leave the channel. + */ LEAVE_CHANNEL_ERR_FAILURE = 1, - /** The user cannot leave the channel. The user may not be in the channel. - */ - LEAVE_CHANNEL_ERR_REJECTED = 2, // Usually occurs when the user is not in the channel + + /** + 2: **RESERVED FOR FUTURE USE** + */ + LEAVE_CHANNEL_ERR_REJECTED = 2, + + /** + 3: The user is not in the channel. + */ + LEAVE_CHANNEL_ERR_NOT_IN_CHANNEL = 3, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + LEAVE_CHANNEL_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before calling the \ref agora::rtm::IChannel::leave "leave" method. + */ + LEAVE_CHANNEL_ERR_USER_NOT_LOGGED_IN = 102, }; - - /** Reasons for a user leaving a channel. - */ + + /** + @brief Reasons why a user leaves the channel. + */ enum LEAVE_CHANNEL_REASON { - /** The user has quit the call. - */ + + /** + 1: The user has quit the call. + */ LEAVE_CHANNEL_REASON_QUIT = 1, - /** The user is banned by the server. - */ + + /** + 2: The user is banned by the server. + */ LEAVE_CHANNEL_REASON_KICKED = 2, }; - /** States of sending a channel message. - */ + /** + @brief Error codes related to sending a channel message. + */ enum CHANNEL_MESSAGE_ERR_CODE { - /** The sender sends the channel message successfully. - */ + + /** + 0: The method call succeeds, or the server receives the channel message. + */ CHANNEL_MESSAGE_ERR_OK = 0, - /** The sender fails to send the channel message. - */ + + /** + 1: Common failure. The user fails to send the channel message. + */ CHANNEL_MESSAGE_ERR_FAILURE = 1, - /** A timeout in sending the channel message. - */ + + /** + 2: The SDK does not receive a response from the server in 10 seconds. The current timeout is set as 10 seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ CHANNEL_MESSAGE_ERR_SENT_TIMEOUT = 2, + + /** + 3: The method call frequency exceeds the limit of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds, with channel and peer messages taken together.. + */ + CHANNEL_MESSAGE_ERR_TOO_OFTEN = 3, + + /** + 4: The message is null or exceeds 32 KB in length. + */ + CHANNEL_MESSAGE_ERR_INVALID_MESSAGE = 4, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + CHANNEL_MESSAGE_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before sending out a channel message. + */ + CHANNEL_MESSAGE_ERR_USER_NOT_LOGGED_IN = 102, }; - /** States of retrieving the user list of a channel. - */ + /** + @brief Error codes related to retrieving a channel member list. + */ enum GET_MEMBERS_ERR { - /** Retrieves the user list of a channel. - */ + + /** + 0: The method call succeeds, or the operation succeeds. + */ GET_MEMBERS_ERR_OK = 0, - /** Fails to retrieve the user list of a channel. - */ + + /** + 1: Common failure. The user fails to retrieve a member list of the channel. + */ GET_MEMBERS_ERR_FAILURE = 1, - /** Cannot retrieve the user list of a channel. - */ + + /** + 2: **RESERVED FOR FUTURE USE** + */ GET_MEMBERS_ERR_REJECTED = 2, - /** A timeout in retreiving the user list of a channel. - */ + + /** + 3: A timeout occurs when retrieving a member list of the channel. The current timeout is set as five seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ GET_MEMBERS_ERR_TIMEOUT = 3, + + /** + 4: The method call frequency exceeds the limit of five queries every two seconds. + */ + GET_MEMBERS_ERR_TOO_OFTEN = 4, + + /** + 5: The user is not in channel. + */ + GET_MEMBERS_ERR_NOT_IN_CHANNEL = 5, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + GET_MEMBERS_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before retrieving a member list. + */ + GET_MEMBERS_ERR_USER_NOT_LOGGED_IN = 102, }; + /** + @brief Error codes related to querying the online status of the specified peers. + */ enum QUERY_PEERS_ONLINE_STATUS_ERR { + + /** + 0: The method call succeeds, or the operation succeeds. + */ QUERY_PEERS_ONLINE_STATUS_ERR_OK = 0, + + /** + 1: Common failure. The user fails to query the online status of the specified peers. + */ QUERY_PEERS_ONLINE_STATUS_ERR_FAILURE = 1, + + /** + 2: The method call fails. The argument is invalid. + */ QUERY_PEERS_ONLINE_STATUS_ERR_INVALID_ARGUMENT = 2, + + /** + 3: **RESERVED FOR FUTURE USE** + */ QUERY_PEERS_ONLINE_STATUS_ERR_REJECTED = 3, + + /** + 4: The SDK fails to receive a response from the server in 10 seconds. The current timeout is set as 10 seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ QUERY_PEERS_ONLINE_STATUS_ERR_TIMEOUT = 4, + + /** + 5: The method call frequency exceeds the limit of (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + */ QUERY_PEERS_ONLINE_STATUS_ERR_TOO_OFTEN = 5, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + QUERY_PEERS_ONLINE_STATUS_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before querying the online status. + */ + QUERY_PEERS_ONLINE_STATUS_ERR_USER_NOT_LOGGED_IN = 102, + }; + + /** + @brief The online states of a peer. + */ + enum PEER_ONLINE_STATE { + + /** + 0: The peer is online (the SDK has logged in the Agora RTM system). + */ + PEER_ONLINE_STATE_ONLINE = 0, + + /** + 1: The peer is temporarily unreachable (the server has not received a packet from the SDK for more than six seconds). + */ + PEER_ONLINE_STATE_UNREACHABLE = 1, + + /** + 2: The peer is offline (the SDK has not logged in the Agora RTM system, or it has logged out of the system, or the server has not received a packet from the SDK for more than 30 seconds). + */ + PEER_ONLINE_STATE_OFFLINE = 2, + }; + + /** + @brief Subscription types. + */ + enum PEER_SUBSCRIPTION_OPTION { + /** + 0: Takes out a subscription to the online status of specified users. + */ + PEER_SUBSCRIPTION_OPTION_ONLINE_STATUS = 0, }; - /** Message types. - */ + /** + @brief Error codes related to subscribing to or unsubscribing from the status of specified peers. + */ + enum PEER_SUBSCRIPTION_STATUS_ERR { + + /** + 0: The method call succeeds, or the operation succeeds. + */ + PEER_SUBSCRIPTION_STATUS_ERR_OK = 0, + + /** + 1: Common failure. The user fails to subscribe to or unsubscribe from the status of the specified peers. + */ + PEER_SUBSCRIPTION_STATUS_ERR_FAILURE = 1, + + /** + 2: The method call fails. The argument is invalid. + */ + PEER_SUBSCRIPTION_STATUS_ERR_INVALID_ARGUMENT = 2, + + /** + 3: **RESERVED FOR FUTURE USE** + */ + PEER_SUBSCRIPTION_STATUS_ERR_REJECTED = 3, + + /** + 4: The SDK fails to receive a response from the server within 10 seconds. The current timeout is set as 10 seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ + PEER_SUBSCRIPTION_STATUS_ERR_TIMEOUT = 4, + + /** + 5: The method call frequency exceeds the limit of 10 queries every five seconds. + */ + PEER_SUBSCRIPTION_STATUS_ERR_TOO_OFTEN = 5, + + /** + 6: The number of peers, to whom you subscribe, exceeds the limit of 512. + */ + PEER_SUBSCRIPTION_STATUS_ERR_OVERFLOW = 6, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + PEER_SUBSCRIPTION_STATUS_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before this operation. + */ + PEER_SUBSCRIPTION_STATUS_ERR_USER_NOT_LOGGED_IN = 102, + }; + + /** + @brief Error codes related to getting a list of the peers by subscription option type. + */ + enum QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR { + + /** + 0: The method call succeeds, or the operation succeeds. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_OK = 0, + + /** + 1: Common failure. The user fails to query peers by subscription option type. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_FAILURE = 1, + + /** + 2: The SDK fails to receive a response from the server within 5 seconds. The current timeout is set as 5 seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_TIMEOUT = 2, + + /** + 3: The method call frequency exceeds the limit of 10 queries every five seconds. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_TOO_OFTEN = 3, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before the query. + */ + QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR_USER_NOT_LOGGED_IN = 102, + }; + + /** + @brief Error codes related to attrubute operations. + */ + enum ATTRIBUTE_OPERATION_ERR { + + /** + 0: The method call succeeds, or the attribute operation succeeds. + */ + ATTRIBUTE_OPERATION_ERR_OK = 0, + + /** + 1: @deprecated + */ + ATTRIBUTE_OPERATION_ERR_NOT_READY = 1, + + /** + 2: Common failure. The attribute operation fails. + */ + ATTRIBUTE_OPERATION_ERR_FAILURE = 2, + + /** + 3: The argument you put for this attribute operation is invalid. For example, you cannot set a user or channel attribute as "". + */ + ATTRIBUTE_OPERATION_ERR_INVALID_ARGUMENT = 3, + + /** + 4: The attribute size exceeds the limit. + + - For user attribute operations: The user's overall attribute size would exceed the limit of 16 KB, one of the user's attributes would exceeds 8 KB in size, or the number of this user's attributes would exceed 32 after this attribute operation. + - For channel attribute operations: The channel's overall attribute size would exceed the limit of 32 KB, one of the channel attributes would exceed 8 KB in size, or the number of this channel's attributes would exceed 32 after this attribute operation. + */ + ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW = 4, + + /** + 5: The method call frequency exceeds the limit. + + - For \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes", \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes", \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" and \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + - For \ref agora::rtm::IRtmService::getUserAttributes "getUserAttributes" and \ref agora::rtm::IRtmService::getUserAttributesByKeys "getUserAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 40 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + - For \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes", \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes", \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" and \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + - For \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" and \ref agora::rtm::IRtmService::getChannelAttributesByKeys "getChannelAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + */ + ATTRIBUTE_OPERATION_ERR_TOO_OFTEN = 5, + + /** + 6: The specified user is not found, either because the user is offline or because the user does not exist. + */ + ATTRIBUTE_OPERATION_ERR_USER_NOT_FOUND = 6, + + /** + 7: A timeout occurs during the attribute operation. The current timeout is set as five seconds. Possible reasons: The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" or \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + */ + ATTRIBUTE_OPERATION_ERR_TIMEOUT = 7, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + ATTRIBUTE_OPERATION_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before the attribute operation. + */ + ATTRIBUTE_OPERATION_ERR_USER_NOT_LOGGED_IN = 102, + }; + + /** + @brief Error codes related to retrieving the channel member count of specified channels. + */ + enum GET_CHANNEL_MEMBER_COUNT_ERR_CODE { + + /** + 0: The method call succeeds, or the operation succeeds. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_OK = 0, + + /** + 1: Unknown common failure. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_FAILURE = 1, + + /** + 2: One or several of your channel IDs is invalid, or @p channelCount < 0. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_INVALID_ARGUMENT = 2, + + /** + 3: The method call frequency exceeds the limit of one query per second. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_TOO_OFTEN = 3, + + /** + 4: A timeout occurs during this operation. The current timeout is set as five seconds. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_TIMEOUT = 4, + + /** + 5:@p channelCount is greater than 32. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_EXCEED_LIMIT = 5, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before this operation. + */ + GET_CHANNEL_MEMBER_COUNT_ERR_USER_NOT_LOGGED_IN = 102, + }; + + /** + @brief Error codes related to downloading a file or image. + */ + enum DOWNLOAD_MEDIA_ERR_CODE { + /** + 0: The method call succeeds, or the operation succeeds. + */ + DOWNLOAD_MEDIA_ERR_OK = 0, + + /** + 1: Unknown common failure. Check whether you have write access. + */ + DOWNLOAD_MEDIA_ERR_FAILURE = 1, + + /** + 2: An argument you put is invalid. For example, `mediaId` is in the wrong format or `filePath` is set as `null`. + */ + DOWNLOAD_MEDIA_ERR_INVALID_ARGUMENT = 2, + /** + 3: A timeout occurs. The current timeout is set as 120 seconds. The SDK assumes that a timeout occurs if it has not detected any file transmission between the SDK and the file server for 120 seconds. + */ + DOWNLOAD_MEDIA_ERR_TIMEOUT = 3, + + /** + 4: The file or image to download does not exist, either because the media ID you input is incorrect or because the validity of the media ID has expired. + */ + DOWNLOAD_MEDIA_ERR_NOT_EXIST = 4, + + /** + 5: You have exceeded the upper limit for file download. You can initiate a maximum of nine file download or upload tasks at the same time (download and upload tasks count together). + */ + DOWNLOAD_MEDIA_ERR_CONCURRENCY_LIMIT_EXCEEDED = 5, + + /** + 6: The file or image download task is aborted for either of the following reasons: + + - The user is in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" state. + - The user has cancelled the download task. + */ + DOWNLOAD_MEDIA_ERR_INTERRUPTED = 6, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + DOWNLOAD_MEDIA_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before this operation. + */ + DOWNLOAD_MEDIA_ERR_NOT_LOGGED_IN = 102, + }; + + + /** + @brief Error codes related to uploading a file or image. + */ + enum UPLOAD_MEDIA_ERR_CODE { + /** + 0: The method call succeeds, or the operation succeeds. + */ + UPLOAD_MEDIA_ERR_OK = 0, + + /** + 1: Unknown common failure. Please check whether the file exists and whether you can access the file. + */ + UPLOAD_MEDIA_ERR_FAILURE = 1, + + /** + 2: The argument you put is invalid. For example, `mediaId` is in the wrong format. + */ + UPLOAD_MEDIA_ERR_INVALID_ARGUMENT = 2, + + /** + 3: A timeout occurs. The current timeout is set as 120 seconds. The SDK assumes that a timeout occurs if it has not detected any file transmission between the SDK and the file server for 120 seconds. + */ + UPLOAD_MEDIA_ERR_TIMEOUT = 3, + + /** + 4: The size of the file or image to upload exceeds 30 MB. + */ + UPLOAD_MEDIA_ERR_SIZE_OVERFLOW = 4, + /** + 5: You have exceeded the upper limit for file upload. You can initiate a maximum of nine file upload or download tasks at the same time (upload and download tasks count together). + */ + UPLOAD_MEDIA_ERR_CONCURRENCY_LIMIT_EXCEEDED = 5, + /** + 6: The file or image upload task is aborted for either of the following reasons: + + - The user in the \ref agora::rtm::CONNECTION_STATE_ABORTED "CONNECTION_STATE_ABORTED" state. + - The user has cancelled the upload task. + */ + UPLOAD_MEDIA_ERR_INTERRUPTED = 6, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + UPLOAD_MEDIA_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before this operation. + */ + UPLOAD_MEDIA_ERR_NOT_LOGGED_IN = 102, + }; + + /** + @brief Error codes related to cancelling a download task or cancelling an upload task. + */ + enum CANCEL_MEDIA_ERR_CODE { + /** + 0: The method call succeeds, or the operation succeeds. + */ + CANCEL_MEDIA_ERR_OK = 0, + + /** + 1: Unknown common failure. + */ + CANCEL_MEDIA_ERR_FAILURE = 1, + + /** + 2: The task to cancel does not exist. You can only cancel an ongoing download or upload task. If the download or upload task completes, the corresponding @p requestId is no longer valid. + */ + CANCEL_MEDIA_ERR_NOT_EXIST = 2, + + /** + 101: \ref agora::rtm::IRtmService "IRtmService" is not initialized. + */ + CANCEL_MEDIA_ERR_NOT_INITIALIZED = 101, + + /** + 102: The user does not call the \ref agora::rtm::IRtmService::login "login" method, or the method call of \ref agora::rtm::IRtmService::login "login" does not succeed before this operation. + */ + CANCEL_MEDIA_ERR_NOT_LOGGED_IN = 102, + }; + + + + /** + @brief Message types. + */ enum MESSAGE_TYPE { - /** The message type is undefined. + + /** + 0: The message type is undefined. + */ + MESSAGE_TYPE_UNDEFINED = 0, + + /** + 1: A text message. + */ + MESSAGE_TYPE_TEXT = 1, + + /** + 2: A raw message. A raw message is a binary message whose size does not exceed 32 KB. + */ + MESSAGE_TYPE_RAW = 2, + + /** + 3: A file message. The size of a file message must be less than 32 KB. + */ + MESSAGE_TYPE_FILE = 3, + + /** + 4: An image message. The size of an image message must be less than 32 KB. + */ + MESSAGE_TYPE_IMAGE = 4, + }; + + /** + @brief Message sending options. */ - MESSAGE_TYPE_UNDEFINED = 0, - /** A text message. + struct SendMessageOptions{ + /** + Set the message as an offline message. + + - true: Set the message as an offline message. + - false: (default) Do not set the message as an offline message. + + @note This setting applies to the peer-to-peer message only, not to the channel message. */ - MESSAGE_TYPE_TEXT = 1, + bool enableOfflineMessaging; + /** + PRIVATE BETA Save the message to message history. + + - true: Save the message to message history. + - false: (default) Do not save the message to message history. + */ + bool enableHistoricalMessaging; + + SendMessageOptions() + : enableOfflineMessaging(false) + + , enableHistoricalMessaging(false) + + {} + }; + + /** + @brief A data structure holding a user attribute key and its value. + */ + struct RtmAttribute + { + + /** + User attribute name. Must be visible characters and not exceed 32 Bytes. + */ + const char* key; + + /** + Value of the user attribute. Must not exceed 8 KB. + */ + const char* value; }; - /** Channel and peer-to-peer message methods. - */ + /** + @brief A data structure representing the upload ratio or download ratio. + */ + struct MediaOperationProgress + { + /** + The total size of the file or image being loaded. + */ + long long totalSize; + /** + The size of the loaded part of the file or image. + */ + long long currentSize; + }; + + /** + @brief The class for setting or getting attributes of a channel. + */ + class IRtmChannelAttribute + { + protected: + virtual ~IRtmChannelAttribute() {} + public: + + /** + Sets the key of the channel attribute. + + @param key Key of channel attribute. Must be visible characters and not exceed 32 Bytes. + */ + virtual void setKey(const char *key) = 0; + + /** + Gets the key of the channel attribute. + + @return Key of the channel attribute. + */ + virtual const char *getKey() const = 0; + + /** + Sets the value of the channel attribute. + + @param value Value of the channel attribute. Must not exceed 8 KB in length. + */ + virtual void setValue(const char *value) = 0; + + /** + Gets the value of the channel attribute. + + @return Value of the channel attribute. + */ + virtual const char *getValue() const = 0; + + /** + Gets the User ID of the user who makes the latest update to the channel attribute. + + @return User ID of the user who makes the latest update to the channel attribute. + */ + virtual const char *getLastUpdateUserId() const = 0; + + /** + Gets the timestamp of when the channel attribute was last updated. + + @return Timestamp of when the channel attribute was last updated in milliseconds. + */ + virtual long long getLastUpdateTs() const = 0; + + /** + Release all resources used by the \ref agora::rtm::IRtmChannelAttribute "IRtmChannelAttribute" instance. + */ + virtual void release() = 0; + }; + + /** + @brief Data structure holding channel attribute-specific options. + */ + struct ChannelAttributeOptions{ + + /** + Indicates whether or not to notify all channel members of a channel attribute change. + + @note This flag is valid only within the current method call. + + - true: Notify all channel members of a channel attribute change. + - false: (Default) Do not notify all channel members of a channel attribute change. + */ + bool enableNotificationToChannelMembers; + ChannelAttributeOptions():enableNotificationToChannelMembers(false){} + }; + + /** + @brief The class for setting and retrieving attributes of a channel or peer-to-peer message. + */ class IMessage { protected: virtual ~IMessage() {} public: - /** Retrieves the channel or peer-to-peer message ID. - * - * @return The message ID, which is created within the message. - */ + + /** + Retrieves the unique ID of the message. + + @return The message ID. + */ virtual long long getMessageId() const = 0; - /** Retrieves the channel or peer-to-peer message type. + + /** + Retrieves the message type. - @return The message type. - */ + @return The message type. See #MESSAGE_TYPE. + */ virtual MESSAGE_TYPE getMessageType() const = 0; - /** Sets the channel or peer-to-peer text message. - * - * @param str The text message to be set. - */ + + /** + Sets the content of a text message, or the text description of a raw message. + + @param str The text message to be set. Must not exceed 32 KB in length. If the message is a raw message, ensure that the overall size of the text description and the raw message data does not exceed 32 KB. + */ virtual void setText(const char *str) = 0; - /** Retrieves the channel or peer-to-peer text message. - * - * @return The received text message. - */ + + /** + Retrieves the content of a text message, or the text description of a raw message. + + @return The content of the received text message, or the text description of the received raw message. + */ virtual const char *getText() const = 0; - /** Releases all resources used by the IMessage instance. - */ + + /** + Retrieves the starting address of the raw message in the memory. + + @return The starting address of the raw message in the memory. + */ + virtual const char *getRawMessageData() const = 0; + + /** + Retrieves the length of the raw message. + + @return The length of the raw message in Bytes. + */ + virtual int getRawMessageLength() const = 0; + /** + Allows the receiver to retrieve the timestamp of when the messaging server receives this message. + + @note + - You can infer from the returned timestamp the *approximate* time as to when this message was sent. + - The returned timestamp is on a millisecond time-scale. It is for demonstration purposes only, not for strict ordering of messages. + + + @return The timestamp (ms) of when the messaging server receives this message. + */ + virtual long long getServerReceivedTs() const = 0; + + /** + Allows the receiver to check whether this message has been cached on the server (Applies to peer-to-peer message only). + + @note + - This method returns false if a message is not cached by the server. Only if the sender sends the message as an offline message (sets \ref agora::rtm::SendMessageOptions::enableOfflineMessaging "enableOfflineMessaging" as true) when the specified user is offline, does the method return true when the user is back online. + - For now we only cache 200 offline messages for up to seven days for each message receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + @return + - true: This message has been cached on the server (the server caches this message and re-sends it to the receiver when he/she is back online). + - false: This message has not been cached on the server. + */ + virtual bool isOfflineMessage() const = 0; + + /** + Releases all resources used by the \ref agora::rtm::IMessage "IMessage" instance. + + @note For the message receiver: please access and save the content of the IMessage instance when receiving the \ref agora::rtm::IChannelEventHandler::onMessageReceived "onMessageReceived" or the \ref agora::rtm::IRtmServiceEventHandler::onMessageReceivedFromPeer "onMessageReceivedFromPeer" callback. The SDK will release the IMessage instance when the callback ends. + */ virtual void release() = 0; }; + + /** + @brief The class for setting and retrieving attributes of a file message. + */ + class IFileMessage : public IMessage + { + public: + + /** + Gets the size of the uploaded file. + + @return The size of the uploaded file in bytes. + */ + virtual long long getSize() const = 0; + + /** + Gets the media ID of the uploaded file. + + @note + - The media ID is automatically populated once the file is uploaded to the file server. + - The media ID is valid for 7 days because the file server keeps all uploaded files for 7 days only. + + @return The media ID of the uploaded file. + */ + virtual const char* getMediaId() const = 0; + + /** + Sets the thumbnail of the uploaded file. + + @param thumbnail The thumbnail of the uploaded file. Must be binary data. + @param length The length of the thumbnail. The size of @p thumbnail and @p fileName combined must not exceed 32 KB. + */ + virtual void setThumbnail(const uint8_t* thumbnail, int length) = 0; + + /** + Gets the thumbnail of the uploaded file. + + @return The thumbnail of the uploaded file. + */ + virtual const char* getThumbnailData() const = 0; + + /** + Gets the length of the thumbnail. + + @return The length of the thumbnail. + */ + virtual const long long getThumbnailLength() const = 0; + + /** + Sets the name of the uploaded file. + + @param fileName The name of the uploaded file. The size of @p thumbnail and @p fileName combined must not exceed 32 KB. + */ + virtual void setFileName(const char* fileName) = 0; + + /** + Gets the name of the uploaded file. + + @return The name of the uploaded file. + */ + virtual const char* getFileName() const = 0; + }; + + /** + @brief The class for setting and retrieving attributes of an image message. + */ + class IImageMessage : public IMessage + { + public: + /** + Gets the size of the uploaded image. + + @return The size of the uploaded image in bytes. + */ + virtual long long getSize() const = 0; + + /** + Gets the media ID of the uploaded image. + + @note + - The media ID is automatically populated once the image is uploaded to the file server. + - The media ID is valid for 7 days because the file server keeps all uploaded files for 7 days only. + + @return The media ID of the uploaded image. + */ + virtual const char* getMediaId() const = 0; + + /** + Sets the thumbnail of the uploaded image. + + @param thumbnail The thumbnail of the uploaded image. + @param length The length of the thumbnail in bytes. The size of @p thumbnail and @p fileName combined must not exceed 32 KB. + */ + virtual void setThumbnail(const uint8_t* thumbnail, long long length) = 0; + + /** + Gets the thumbnail data of the uploaded image. + + @return The thumbnail data of the uploaded image. + */ + virtual const char* getThumbnailData() const = 0; + + /** + Gets the length of the thumbnail data. + + @return The length of the thumbnail data. + */ + virtual const long long getThumbnailLength() const = 0; + + /** + Sets the file name of the uploaded image. + + @param fileName The file name of the uploaded image. The size of @p thumbnail and @p fileName combined must not exceed 32 KB. + */ + virtual void setFileName(const char* fileName) = 0; + + /** + Gets the file name of the uploaded image. + + @return The file name of the uploaded image. + */ + virtual const char* getFileName() const = 0; + + /** + Sets the width of the uploaded image. + + @note + - If the uploaded image is in JPG, JPEG, BMP, or PNG format, the SDK automatically calculates the width and height of the image. You can call \ref agora::rtm::IImageMessage::getWidth() "getWidth" directly to get the width of the image. + - Image width that is set by calling this method overrides the width calculated by the SDK. + + @param width The width of the uploaded image. + */ + virtual void setWidth(int width) = 0; + + /** + Gets the width of the uploaded image. + + @note + - If the uploaded image is in JPG, JPEG, BMP, or PNG format, the SDK automatically calculates the width and height of the image. You can call this method directly to get the width of the image. + - Image width that is set by calling \ref agora::rtm::IImageMessage::setWidth() "setWidth" overrides the width calculated by the SDK. + + @return The width of the uploaded image. Is 0 if the SDK does not support the format of the uploaded image. + */ + virtual int getWidth() const = 0; + + /** + Sets the height of the uploaded image. + + @note + - If the uploaded image is in JPG, JPEG, BMP, or PNG format, the SDK automatically calculates the width and height of the image. You can call \ref agora::rtm::IImageMessage::getHeight() "getHeight" directly to get the height of the image. + - Image height that is set by calling this method overrides the height calculated by the SDK. + + @param height The height of the uploaded image. Is 0 if the SDK does not support the format of the uploaded image. + */ + virtual void setHeight(int height) = 0; + + /** + Gets the height of the uploaded image. + + @note + - If the uploaded image is in JPG, JPEG, BMP, or PNG format, the SDK automatically calculates the width and height of the image. You can call this method directly to get the height of the image. + - Image height that is set by calling \ref agora::rtm::IImageMessage::setHeight() "setHeight" overrides the height calculated by the SDK. + + @return The height of the uploaded image. + */ + virtual int getHeight() const = 0; + + /** + Sets the width of the thumbnail. + + @note You need to work out the width of the thumbnail by yourself, because the SDK does not work out the value for you. + + @param width The width of the thumbnail. + */ + virtual void setThumbnailWidth(int width) = 0; + + /** + Gets the width of the thumbnail. + + @return The width of the thumbnail. + */ + virtual int getThumbnailWidth() const = 0; + + /** + Sets the height of the thumbnail. + + @note You need to work out the height of the thumbnail by yourself, because the SDK does not work out the value for you. + + @param height The height of the thumbnail. + */ + virtual void setThumbnailHeight(int height) = 0; + + /** + Gets the height of the thumbnail. + + @return The height of the thumbnail. + */ + virtual int getThumbnailHeight() const = 0; + }; - /** Agora RTM channel member methods. - */ + /** + @brief The class for retrieving the attributes of a channel member. + */ class IChannelMember { protected: virtual ~IChannelMember() {} public: - /** Gets the user ID of a user in the channel. - * - * @return User ID of a user in the channel. - */ + + /** + Retrieves the user ID of a user in the channel. + + @return User ID of a user in the channel. + */ virtual const char * getUserId() const = 0; - /** Gets the channel ID of the user. - * - * @return Channel ID of the user. - */ + + /** + Retrieves the channel ID of the user. + + @return Channel ID of the user. + */ virtual const char * getChannelId() const = 0; - /** Releases all resources used by the IChannelMember instance. - */ + + /** + Releases all resources used by the \ref agora::rtm::IChannelMember "IChannelMember" instance. + */ virtual void release() = 0; }; - + + /** + @brief The data structure holding an RTM user and the user's online status. + */ struct PeerOnlineStatus { + + /** + The user ID of the peer. + */ const char* peerId; + + /** + @deprecated Deprecated as of v1.2.0. Use \ref agora::rtm::PeerOnlineStatus::onlineState "onlineState" instead. + + The online status of the peer. + + - true: The user is online (the user has logged in the Agora RTM system). + - false: The user is offline (the user has logged out of the Agora RTM system, has not logged in, or has failed to logged in). + */ bool isOnline; + + /** + The online state of the peer. See #PEER_ONLINE_STATE. + + @note + - The server will never return the `unreachable` state, if you query the online status of specified peers (\ref agora::rtm::IRtmService::queryPeersOnlineStatus "queryPeersOnlineStatus"). See also: \ref agora::rtm::IRtmServiceEventHandler::onQueryPeersOnlineStatusResult "onQueryPeersOnlineStatusResult". + - The server may return the `unreachable` state, if you subscribe to the online status of specified peers (\ref agora::rtm::IRtmService::subscribePeersOnlineStatus "subscribePeersOnlineStatus"). See also: \ref agora::rtm::IRtmServiceEventHandler::onPeersOnlineStatusChanged "onPeersOnlineStatusChanged". + */ + PEER_ONLINE_STATE onlineState; }; -// class IChannelAttributes -// { -// public: -// static IChannelAttributes *createChannelAttributes(); -// -// virtual int addAttribute(const char *key, const char *value) = 0; -// virtual int removeAttribute(const char *key) = 0; -// virtual int getAttributesSize() const = 0; -// virtual void getAttributes(int size, char **key, char **value) const = 0; // todo: discussion, how to traveral -// virtual const char * getAttributeValue(const char *key) const = 0; -// -// virtual void release() = 0; -// }; -// - /** Callbacks for the Agora RTM channel methods. - */ + /** + @brief The data structure holding a channel ID and the current channel member count. + */ + struct ChannelMemberCount + { + /** + The ID of the channel. + */ + const char* channelId; + // count of channel, 0 if channel not found. + /** + The current member count of the channel. + + @note @p count is 0, if a channel with the specified @p channelId is not found. + */ + int count; + }; + + /** + @brief Callbacks for the Agora RTM channel methods. + */ class IChannelEventHandler { public: @@ -342,164 +1521,256 @@ namespace agora { virtual ~IChannelEventHandler() { } - /** Occurs when a user joins a channel. + + /** + Occurs when successfully joining a channel. - The local user receives this callback while all remote users receive the \ref agora::rtm::IChannelEventHandler::onMemberJoined "onMemberJoined" callback when the \ref agora::rtm::IChannel::join "join" method call succeeds. - */ + When the local user calls the \ref agora::rtm::IChannel::join "join" method and successfully joins the channel: + - The SDK triggers this callback; + - All remote users in the channel receive the \ref agora::rtm::IChannelEventHandler::onMemberJoined "onMemberJoined" callback. + */ virtual void onJoinSuccess() { } - /** Occurs when a user fails to join a channel. + + /** + Occurs when failing to join a channel. - The local user receives this callback when the \ref agora::rtm::IChannel::join "join" method call fails. See \ref agora::rtm::JOIN_CHANNEL_ERR "JOIN_CHANNEL_ERR" for the error codes. - */ + The local user receives this callback when the \ref agora::rtm::IChannel::join "join" method call fails. + + @param errorCode The error code. See #JOIN_CHANNEL_ERR. + */ virtual void onJoinFailure(JOIN_CHANNEL_ERR errorCode) { (JOIN_CHANNEL_ERR) errorCode; } - /** Occurs when a user leaves a channel. - The SDK triggers this callback when the \ref agora::rtm::IChannel::leave "leave" method call succeeds. See \ref agora::rtm::LEAVE_CHANNEL_ERR "LEAVE_CHANNEL_ERR" for the states. - */ + /** + Returns the result of the \ref agora::rtm::IChannel::leave "leave" method call. + + @param errorCode The error code. See #LEAVE_CHANNEL_ERR. + */ virtual void onLeave(LEAVE_CHANNEL_ERR errorCode) { (LEAVE_CHANNEL_ERR) errorCode; } - /** Occurs when all remote users receive a channel message from a sender. - - All remote users receive this callback while the sender receives the \ref agora::rtm::IChannelEventHandler::onSendMessageResult "onSendMessageResult" callback when the \ref agora::rtm::IChannel::sendMessage "sendMessage" method call succeeds. - - @param userId User ID of the sender. - @param message The received channel message. See IMessage. + /** + Occurs when receiving a channel message. - */ + @param userId The message sender. + @param message The received channel message. See \ref agora::rtm::IMessage "IMessage". + */ virtual void onMessageReceived(const char *userId, const IMessage *message) { (const char *) userId; (IMessage *) message; } - - /** Occurs when the sent channel message state changes. - - The sender receives this callback while all remote users receive the \ref agora::rtm::IChannelEventHandler::onMessageReceived "onMessageReceived" callback when the \ref agora::rtm::IChannel::sendMessage "sendMessage" method call succeeds. - - @param messageID The ID of the sent channel message. - @param state The new channel message state. See \ref agora::rtm::CHANNEL_MESSAGE_ERR_CODE "CHANNEL_MESSAGE_ERR_CODE". - - */ + /** + Occurs when receiving a channel image message. + + @param userId The message sender. + @param message The received channel image message. See \ref agora::rtm::IImageMessage "IImageMessage". + */ + virtual void onImageMessageReceived(const char *userId, const IImageMessage* message) + { + (IImageMessage *) message; + } + + /** + Occurs when receiving a channel file message. + + @param userId The message sender. + @param message The received channel file message. See \ref agora::rtm::IFileMessage "IFileMessage". + */ + virtual void onFileMessageReceived(const char *userId, const IFileMessage* message) + { + (IFileMessage *) message; + } + + /** + Returns the result of the \ref agora::rtm::IChannel::sendMessage "sendMessage" method call. + + @param messageId The ID of the sent channel message. + @param state The error codes. See #CHANNEL_MESSAGE_ERR_CODE. + */ virtual void onSendMessageResult(long long messageId, CHANNEL_MESSAGE_ERR_CODE state) { (long long) messageId; (CHANNEL_MESSAGE_ERR_CODE) state; } - /** Occurs when a user joins a channel. + + /** + Occurs when a remote user joins the channel. - All remote users receive this callback while the local user receives the \ref agora::rtm::IChannelEventHandler::onJoinSuccess "onJoinSuccess" callback when the \ref agora::rtm::IChannel::join "join" method call succeeds. + When a remote user calls the \ref agora::rtm::IChannel::join "join" method and receives the \ref agora::rtm::IChannelEventHandler::onJoinSuccess "onJoinSuccess" callback (successfully joins the channel), the local user receives this callback. + + @note This callback is disabled when the number of the channel members exceeds 512. - @param member The user joining the channel. See IChannelMember. - */ + @param member The user joining the channel. See IChannelMember. + */ virtual void onMemberJoined(IChannelMember *member) { (IChannelMember *) member; } - /** Occurs when a user leaves a channel. + + /** + Occurs when a remote member leaves the channel. - All remote users receive this callback while the local user receives the the \ref agora::rtm::IChannelEventHandler::onLeave "onLeave" callback when the \ref agora::rtm::IChannel::leave "leave" method call succeeds. + When a remote member in the channel calls the \ref agora::rtm::IChannel::leave "leave" method and receives the the \ref agora::rtm::IChannelEventHandler::onLeave "onLeave (LEAVE_CHANNEL_ERR_OK)" callback, the local user receives this callback. + + @note This callback is disabled when the number of the channel members exceeds 512. - @param member The user leaving the channel. See IChannelMember. - */ + @param member The channel member that leaves the channel. See IChannelMember. + */ virtual void onMemberLeft(IChannelMember *member) { (IChannelMember *) member; } - /** Occurs when the user list of a channel is retrieved. - - The SDK triggers this callback when the \ref agora::rtm::IChannel::getMembers "getMembers" method call succeeds. - - @param members The user list. See IChannelMember. - @param userCount The number of users. - @param errorCode Error code. See \ref agora::rtm::GET_MEMBERS_ERR "GET_MEMBERS_ERR". - - */ + + /** + Returns the result of the \ref agora::rtm::IChannel::getMembers "getMembers" method call. + + When the method call succeeds, the SDK returns the member list of the channel. + + @param members The member list. See IChannelMember. + @param userCount The number of members. + @param errorCode Error code. See #GET_MEMBERS_ERR. + */ virtual void onGetMembers(IChannelMember **members, int userCount, GET_MEMBERS_ERR errorCode) { (IChannelMember **) members; (int) userCount; } + + /** + Occurs when channel attributes are updated, and returns all attributes of the channel. + + @note This callback is enabled only when the user, who updates the attributes of the channel, sets \ref agora::rtm::ChannelAttributeOptions::enableNotificationToChannelMembers "enableNotificationToChannelMembers" as true. Also note that this flag is valid only within the current channel attribute method call. + + @param attributes All attribute of this channel. + @param numberOfAttributes The total number of the channel attributes. + */ + virtual void onAttributesUpdated(const IRtmChannelAttribute* attributes[], int numberOfAttributes) + { + (const IRtmChannelAttribute**) attributes; + (int) numberOfAttributes; + } + + /** + Occurs when the number of the channel members changes, and returns the new number. -// virtual void onAttributesUpdated(const IChannelAttributes *attributes) -// { -// (IChannelAttributes *) attributes; -// } -// -// virtual void onUpdateAttributesResponse(long long requestId, RESPONSE_CODE resCode) -// { -// (long long) requestId; -// (RESPONSE_CODE) resCode; -// } -// -// -// virtual void onAttributesDeleted(const IChannelAttributes *attributes) -// { -// (IChannelAttributes *) attributes; -// } -// -// virtual void onDeleteAttributesResponse(long long requestId, RESPONSE_CODE resCode) -// { -// (long long) requestId; -// (RESPONSE_CODE) resCode; -// } - }; - /** Agora RTM channel methods. - */ + @note + - When the number of channel members ≤ 512, the SDK returns this callback when the number changes at the frequency of once per second. + - When the number of channel members exceeds 512, the SDK returns this callback when the number changes at the frequency of once every three seconds. + - You will receive this callback when successfully joining an RTM channel, so Agora recommends implementing this callback to receive timely updates on the number of the channel members. + + @param memberCount Member count of this channel. + */ + virtual void onMemberCountUpdated(int memberCount) + { + (int) memberCount; + } + }; + + /** + @brief Agora RTM channel methods. + */ class IChannel { protected: virtual ~IChannel() {} public: // virtual void setEventHandler(IChannelEventHandler *eventHandler) = 0; - /** Allows a user to join a channel. - - If this method call succeeds: + /** + Joins a channel. + + @note You can join a maximum of 20 RTM channels at the same time. When the number of the channels you join exceeds the limit, you receive the \ref agora::rtm::JOIN_CHANNEL_ERR "JOIN_CHANNEL_ERR_FAILURE" error code. + + - If this method call succeeds: - The local user receives the \ref agora::rtm::IChannelEventHandler::onJoinSuccess "onJoinSuccess" callback. - All remote users receive the \ref agora::rtm::IChannelEventHandler::onMemberJoined "onMemberJoined" callback. - - If this method call fails, the local user receives the \ref agora::rtm::IChannelEventHandler::onJoinFailure "onJoinFailure" callback. See \ref agora::rtm::JOIN_CHANNEL_ERR "JOIN_CHANNEL_ERR" - for the error codes. + - If this method call fails, the local user receives the \ref agora::rtm::IChannelEventHandler::onJoinFailure "onJoinFailure" callback. See #JOIN_CHANNEL_ERR for the error codes. + @return + - 0: Success. + - ≠0: Failure. See #JOIN_CHANNEL_ERR for the error codes. */ virtual int join() = 0; - /** Allows a user to leave a channel. + + /** + Leaves a channel. - - If this method call succeeds: + - If this method call succeeds: - The local user receives the \ref agora::rtm::IChannelEventHandler::onLeave "onLeave" callback with the LEAVE_CHANNEL_ERR_OK state. - All remote users receive the \ref agora::rtm::IChannelEventHandler::onMemberLeft "onMemberLeft" callback. - - If this method call fails, the local user receives the \ref agora::rtm::IChannelEventHandler::onLeave "onLeave" callback with an error code. See \ref agora::rtm::LEAVE_CHANNEL_ERR "LEAVE_CHANNEL_ERR" for the error codes. - - */ + - If this method call fails, the local user receives the \ref agora::rtm::IChannelEventHandler::onLeave "onLeave" callback with an error code. See \ref agora::rtm::LEAVE_CHANNEL_ERR "LEAVE_CHANNEL_ERR" for the error codes. + @return + - 0: Success. + - ≠0: Failure. See #LEAVE_CHANNEL_ERR for the error codes. + */ virtual int leave() = 0; - /** Allows a local user to send a message in a channel. + + /** + @deprecated Allows a channel member to send a message to all members in the channel. + + Agora does not recommend using this method to send a channel message. Use \ref agora::rtm::IChannel::sendMessage(const IMessage *message, const SendMessageOptions &options) "sendMessage" instead. + + If this method call succeeds: + - The \ref agora::rtm::IChannelEventHandler::onSendMessageResult "onSendMessageResult" callback returns the result. + - All remote users in the channel receive the \ref agora::rtm::IChannelEventHandler::onMessageReceived "onMessageReceived" callback. + + @note You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds. + + @param message The message to be sent. See \ref agora::rtm::IMessage "IMessage". + @return + - 0: Success. + - ≠0: Failure. See #CHANNEL_MESSAGE_ERR_CODE for the error codes. + */ + virtual int sendMessage(const IMessage *message) = 0; - If this method call succeeds: - - The local user receives the \ref agora::rtm::IChannelEventHandler::onSendMessageResult "onSendMessageResult" callback. - - All remote users receive the \ref agora::rtm::IChannelEventHandler::onMessageReceived "onMessageReceived" callback. + /** + Allows a channel member to send a message to all members in the channel. + + If this method call succeeds: + - The \ref agora::rtm::IChannelEventHandler::onSendMessageResult "onSendMessageResult" callback returns the result. + - All remote users in the channel receive the \ref agora::rtm::IChannelEventHandler::onMessageReceived "onMessageReceived" callback. + + @note You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds. + + @param message The message to be sent. See \ref agora::rtm::IMessage "IMessage". + @param options Options when sending the channel message. See See \ref agora::rtm::SendMessageOptions "SendMessageOptions". + @return + - 0: Success. + - ≠0: Failure. See #CHANNEL_MESSAGE_ERR_CODE for the error codes. + */ + virtual int sendMessage(const IMessage *message, const SendMessageOptions &options) = 0; + + /** + Retrieves the channel ID. - @param message The message to be sent. See IMessage. - */ - virtual int sendMessage(const IMessage *message) = 0; -// virtual int updateAttributes(IChannelAttributes *attributes, long long &requestId) = 0; // move request id to attribute -// virtual int deleteAttributes(IChannelAttributes *attributes, long long &requestId) = 0; - /** Gets the channel ID. - */ + @return The channel ID of the channel. + */ virtual const char *getId() const = 0; - /** Retrieves the user list of a channel. + + /** + Retrieves a member list of the channel. - If this method call succeeds, the SDK triggers the \ref agora::rtm::IChannelEventHandler::onGetMembers "onGetMembers" callback. - */ + The \ref agora::rtm::IChannelEventHandler::onGetMembers "onGetMembers" callback returns the result of this method call. + + @note You can call this method at a maximum frequency of five calls every two seconds. This method returns a maximum of 512 members. If the number of channel members exceed 512, the method returns 512 members randomly. + + @return + - 0: Success. + - ≠0: Failure. See #GET_MEMBERS_ERR for the error codes. + */ virtual int getMembers() = 0; // sync_call - /** Releases all resources used by the IChannel instance. - */ + + /** + Releases all resources used by the \ref agora::rtm::IChannel "IChannel" instance. + */ virtual void release() = 0; }; @@ -510,180 +1781,1272 @@ namespace agora { { } - /** Occurs when a user logs in Agora's RTM service. + /** + Occurs when a user logs in the Agora RTM system. - The local user receives this callback when the \ref agora::rtm::IRtmService::login "login" method call succeeds. - */ + The local user receives this callback when the \ref agora::rtm::IRtmService::login "login" method call succeeds. + */ virtual void onLoginSuccess() {} - /** Occurs when a user fails to log in Agora's RTM service. + + /** + Occurs when a user fails to log in the Agora RTM system. - The local user receives this callback when the \ref agora::rtm::IRtmService::login "login" method call fails. See \ref agora::rtm::LOGIN_ERR_CODE "LOGIN_ERR_CODE" for the error codes. - */ + The local user receives this callback when the \ref agora::rtm::IRtmService::login "login" method call fails. See \ref agora::rtm::LOGIN_ERR_CODE "LOGIN_ERR_CODE" for the error codes. + */ virtual void onLoginFailure(LOGIN_ERR_CODE errorCode) { (LOGIN_ERR_CODE) errorCode; } + /** + Reports the result of the \ref agora::rtm::IRtmService::renewToken "renewToken" method call. + + @param token Your new token. + @param errorCode The error code. See #RENEW_TOKEN_ERR_CODE. + */ virtual void onRenewTokenResult(const char* token, RENEW_TOKEN_ERR_CODE errorCode) { (const char*) token; (RENEW_TOKEN_ERR_CODE) errorCode; } - + + /** + Occurs when the RTM server detects that the RTM token has exceeded the 24-hour validity period and when the SDK is in the \ref agora::rtm::CONNECTION_STATE_RECONNECTING "CONNECTION_STATE_RECONNECTING" state. + + - This callback occurs only when the SDK is reconnecting to the server. You will not receive this callback when the SDK is in the \ref agora::rtm::CONNECTION_STATE_CONNECTED "CONNECTION_STATE_CONNECTED" state. + - When receiving this callback, generate a new RTM Token on the server and call the \ref agora::rtm::IRtmService::renewToken "renewToken" method to pass the new Token on to the server. + */ virtual void onTokenExpired() { } - /** Occurs when a user logs out of Agora's RTM service. - - The local user receives this callback when the SDK calls the \ref agora::rtm::IRtmService::logout "logout" method. See \ref agora::rtm::LOGOUT_ERR_CODE "LOGOUT_ERR_CODE" for the states. + /** + Occurs when a user logs out of the Agora RTM system. - */ + The local user receives this callback when the SDK calls the \ref agora::rtm::IRtmService::logout "logout" method. See \ref agora::rtm::LOGOUT_ERR_CODE "LOGOUT_ERR_CODE" for the error codes. + */ virtual void onLogout(LOGOUT_ERR_CODE errorCode) { (LOGOUT_ERR_CODE) errorCode; } - /** Occurs when a connection state changes between the SDK and Agora's RTM service. + + /** + Occurs when the connection state changes between the SDK and the Agora RTM system. - @param state The new connection state. See \ref agora::rtm::CONNECTION_STATE "CONNECTION_STATE". - @param reason The reason for the connection state change. See \ref agora::rtm::CONNECTION_CHANGE_REASON "CONNECTION_CHANGE_REASON". + @param state The new connection state. See #CONNECTION_STATE. + @param reason The reason for the connection state change. See #CONNECTION_CHANGE_REASON. */ virtual void onConnectionStateChanged(CONNECTION_STATE state, CONNECTION_CHANGE_REASON reason) { } - /** Occurs when the sent peer-to-peer message state changes. - - The sender receives this callback while the receiver receives the \ref agora::rtm::IRtmServiceEventHandler::onMessageReceivedFromPeer "onMessageReceivedFromPeer" callback when the \ref agora::rtm::IRtmService::sendMessageToPeer "sendMessageToPeer" method call succeeds. + + /** + Reports the result of the \ref agora::rtm::IRtmService::sendMessageToPeer "sendMessageToPeer" method call. - @param messageID The ID of the sent message. - @param state The new peer-to-peer message state. See \ref agora::rtm::PEER_MESSAGE_ERR_CODE "PEER_MESSAGE_ERR_CODE". + @param messageId The ID of the sent message. + @param errorCode The peer-to-peer message state. See #PEER_MESSAGE_ERR_CODE. - */ + */ virtual void onSendMessageResult(long long messageId, PEER_MESSAGE_ERR_CODE errorCode) { (long long) messageId; (PEER_MESSAGE_ERR_CODE) errorCode; } - /** Occurs when the receiver receives the peer-to-peer message from the sender. + + /** + Occurs when receiving a peer-to-peer message. - The receiver receives this callback while the sender receives the \ref agora::rtm::IRtmServiceEventHandler::onSendMessageResult "onSendMessageResult" callback when the \ref agora::rtm::IRtmService::sendMessageToPeer "sendMessageToPeer" method call succeeds. - - @param peerID User ID of the sender. - @param message The message sent by the sender. See IMessage. - - */ + @param peerId The ID of the message sender. + @param message The received peer-to-peer message. See \ref agora::rtm::IMessage "IMessage". + */ virtual void onMessageReceivedFromPeer(const char *peerId, const IMessage *message) { (char *) peerId; (IMessage *) message; } + + /** + Occurs when receiving a peer-to-peer image message. + + @param peerId The ID of the message sender. + @param message The received peer-to-peer image message. See \ref agora::rtm::IImageMessage "IImageMessage". + */ + virtual void onImageMessageReceivedFromPeer(const char *peerId, const IImageMessage* message) + { + (char *) peerId; + (IImageMessage *) message; + } + + /** + Occurs when receiving a peer-to-peer file message. + + @param peerId The ID of the message sender. + @param message The received peer-to-peer file message. See \ref agora::rtm::IFileMessage "IFileMessage". + */ + virtual void onFileMessageReceivedFromPeer(const char *peerId, const IFileMessage* message) + { + (char *) peerId; + (IFileMessage *) message; + } + + /** + Reports the progress of an ongoing upload task. + + @note + - If the upload task is ongoing, the SDK returns this callback once every second. + - If the upload task comes to a halt, the SDK stops returning this callback until the task is going again. + + @param requestId The unique ID of the upload request. + @param progress The progress of the ongoing upload task. See \ref agora::rtm::MediaOperationProgress "MediaOperationProgress". + */ + virtual void onMediaUploadingProgress(long long requestId, const MediaOperationProgress &progress) + { + (long long) requestId; + (MediaOperationProgress) progress; + } + + /** + Reports the progress of an ongoing download task. + + @note + - If the download task is ongoing, the SDK returns this callback once every second. + - If the download task comes to a halt, the SDK stops returning this callback until the task is going again. + + @param requestId The unique ID of the download request. + @param progress The progress of the ongoing download task. See \ref agora::rtm::MediaOperationProgress "MediaOperationProgress". + */ + virtual void onMediaDownloadingProgress(long long requestId, const MediaOperationProgress &progress) + { + (long long) requestId; + (MediaOperationProgress) progress; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::createFileMessageByUploading "createFileMessageByUploading" method call. + + @param requestId The unique ID of the upload request. + @param fileMessage An \ref agora::rtm::IFileMessage "IFileMessage" instance. + @param code Error codes. See #UPLOAD_MEDIA_ERR_CODE. + */ + virtual void onFileMediaUploadResult(long long requestId, IFileMessage* fileMessage, UPLOAD_MEDIA_ERR_CODE code) + { + (long long) requestId; + (IFileMessage *) fileMessage; + (UPLOAD_MEDIA_ERR_CODE) code; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::createImageMessageByUploading "createImageMessageByUploading" method call. + + @param requestId The unique ID of the upload request. + @param imageMessage An \ref agora::rtm::IImageMessage "IImageMessage" instance. + @param code Error codes. See #UPLOAD_MEDIA_ERR_CODE. + */ + virtual void onImageMediaUploadResult(long long requestId, IImageMessage* imageMessage, UPLOAD_MEDIA_ERR_CODE code) + { + (long long) requestId; + (IImageMessage *) imageMessage; + (UPLOAD_MEDIA_ERR_CODE) code; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::downloadMediaToFile "downloadMediaToFile" method call. + + @param requestId The unique ID of the download request. + @param code Error codes. See #DOWNLOAD_MEDIA_ERR_CODE. + */ + virtual void onMediaDownloadToFileResult(long long requestId, DOWNLOAD_MEDIA_ERR_CODE code) + { + (long long)requestId; + (DOWNLOAD_MEDIA_ERR_CODE)code; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::downloadMediaToMemory "downloadMediaToMemory" method call. + + @note The SDK releases the downloaded file or image immediately after returning this callback. + + @param requestId The unique ID of the download request. + @param memory The memory address where the downloaded file or image is stored. + @param length The size of the downloaded file or image. + @param code Error codes. See #DOWNLOAD_MEDIA_ERR_CODE. + */ + virtual void onMediaDownloadToMemoryResult(long long requestId, const char* memory, long long length, DOWNLOAD_MEDIA_ERR_CODE code) + { + (long long) requestId; + (const char*) memory; + (long long) length; + (DOWNLOAD_MEDIA_ERR_CODE) code; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::cancelMediaDownload "cancelMediaDownload" or \ref agora::rtm::IRtmService::cancelMediaUpload "cancelMediaUpload" method call. + + @param requestId The unique ID of the cancel request. + @param code Error codes. See #CANCEL_MEDIA_ERR_CODE. + */ + virtual void onMediaCancelResult(long long requestId, CANCEL_MEDIA_ERR_CODE code) + { + (long long) requestId; + (CANCEL_MEDIA_ERR_CODE) code; + } - virtual void onQueryPeersOnlineStatusResult(long long requestId, const PeerOnlineStatus* peersStatus , int peerCount, QUERY_PEERS_ONLINE_STATUS_ERR errorCode) + /** + Reports the result of the \ref agora::rtm::IRtmService::queryPeersOnlineStatus "queryPeersOnlineStatus" method call. + + @param requestId The unique ID of this request. + @param peersStatus The online status of the peer. See PeerOnlineStatus. + @param peerCount The number of the queried peers. + @param errorCode Error Codes. See #QUERY_PEERS_ONLINE_STATUS_ERR. + */ + virtual void onQueryPeersOnlineStatusResult(long long requestId, const PeerOnlineStatus* peersStatus, int peerCount, QUERY_PEERS_ONLINE_STATUS_ERR errorCode) { (long long) requestId; (const PeerOnlineStatus*) peersStatus; (int) peerCount; (QUERY_PEERS_ONLINE_STATUS_ERR) errorCode; } - }; + /** + Returns the result of the \ref agora::rtm::IRtmService::subscribePeersOnlineStatus "subscribePeersOnlineStatus" or \ref agora::rtm::IRtmService::unsubscribePeersOnlineStatus "unsubscribePeersOnlineStatus" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #PEER_SUBSCRIPTION_STATUS_ERR. + */ + virtual void onSubscriptionRequestResult(long long requestId, PEER_SUBSCRIPTION_STATUS_ERR errorCode) + { + (long long)requestId; + (PEER_SUBSCRIPTION_STATUS_ERR)errorCode; + } + + /** + Returns the result of the \ref agora::rtm::IRtmService::queryPeersBySubscriptionOption "queryPeersBySubscriptionOption" method call. + + @param requestId The unique ID of this request. + @param peerIds A user ID array of the specified users, to whom you subscribe. + @param peerCount Count of the peers. + @param errorCode Error Codes. See #QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR. + */ + virtual void onQueryPeersBySubscriptionOptionResult(long long requestId, const char* peerIds[], int peerCount, QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR errorCode) + { + (const char**)peerIds; + (int)peerCount; + (QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR)errorCode; + } + + /** + Occurs when the online status of the peers, to whom you subscribe, changes. + + - When the subscription to the online status of specified peers succeeds, the SDK returns this callback to report the online status of peers, to whom you subscribe. + - When the online status of the peers, to whom you subscribe, changes, the SDK returns this callback to report whose online status has changed. + - If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns this callback to report whose online status has changed when successfully reconnecting to the server. + + @param peersStatus An array of peers' online states. See PeerOnlineStatus. + @param peerCount Count of the peers, whose online status changes. + */ + virtual void onPeersOnlineStatusChanged(const PeerOnlineStatus peersStatus[], int peerCount) + { + (const PeerOnlineStatus*)peersStatus; + (int)peerCount; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onSetLocalUserAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onAddOrUpdateLocalUserAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onDeleteLocalUserAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onClearLocalUserAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::getUserAttributes "getUserAttributes" or \ref agora::rtm::IRtmService::getUserAttributesByKeys "getUserAttributesByKeys" method call. + + @param requestId The unique ID of this request. + @param userId The user ID of the specified user. + @param attributes An array of the returned attributes. See RtmAttribute. + @param numberOfAttributes The total number of the user's attributes + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onGetUserAttributesResult(long long requestId, const char* userId, const RtmAttribute* attributes, int numberOfAttributes, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (const RtmAttribute*) attributes; + (int) numberOfAttributes; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onSetChannelAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onAddOrUpdateChannelAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onDeleteChannelAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" method call. + + @param requestId The unique ID of this request. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onClearChannelAttributesResult(long long requestId, ATTRIBUTE_OPERATION_ERR errorCode) + { + (long long) requestId; + (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" or \ref agora::rtm::IRtmService::getChannelAttributesByKeys "getChannelAttributesByKeys" method call. + + @param requestId The unique ID of this request. + @param attributes An array of the returned channel attributes. + @param numberOfAttributes The total number of the attributes. + @param errorCode Error Codes. See #ATTRIBUTE_OPERATION_ERR. + */ + virtual void onGetChannelAttributesResult(long long requestId, const IRtmChannelAttribute* attributes[], int numberOfAttributes, ATTRIBUTE_OPERATION_ERR errorCode) + { +// (long long) requestId; +// (const IRtmChannelAttribute**) attributes; +// (int) numberOfAttributes; +// (ATTRIBUTE_OPERATION_ERR) errorCode; + } + + /** + Reports the result of the \ref agora::rtm::IRtmService::getChannelMemberCount "getChannelMemberCount" method call. + + @param requestId The unique ID of this request. + @param channelMemberCounts An array of the channel member counts. + @param channelCount The total number of the channels. + @param errorCode Error Codes. See #GET_CHANNEL_MEMBER_COUNT_ERR_CODE. + */ + virtual void onGetChannelMemberCountResult(long long requestId, const ChannelMemberCount* channelMemberCounts , int channelCount, GET_CHANNEL_MEMBER_COUNT_ERR_CODE errorCode) + { + (long long) requestId; + (const ChannelMemberCount*) channelMemberCounts; + (int) channelCount; + (GET_CHANNEL_MEMBER_COUNT_ERR_CODE)errorCode; + } + }; class IRtmCallManager; class IRtmCallEventHandler; + + /** + @brief Output log filter level. + */ + enum LOG_FILTER_TYPE + { + + /** + 0: Do not output any log information. + */ + LOG_FILTER_OFF = 0, + + /** + 0x000f: Output CRITICAL, ERROR, WARNING, and INFO level log information. + */ + LOG_FILTER_INFO = 0x000f, + + /** + 0x000e: Output CRITICAL, ERROR, and WARNING level log information. + */ + LOG_FILTER_WARN = 0x000e, + + /** + 0x000c: Output CRITICAL and ERROR level log information. + */ + LOG_FILTER_ERROR = 0x000c, + + /** + 0x0008: Output CRITICAL level log information. + */ + LOG_FILTER_CRITICAL = 0x0008, + /** + Reserved for future use. + */ + LOG_FILTER_MASK = 0x80f, + }; class IRtmService { protected: virtual ~IRtmService() {} public: - /** Creates an IRtmService instance. + + /** + Initializes an IRtmService instance. - The Agora RTM SDK supports multiple {@link RtmClient} instances. + All methods in the IRtmService class are executed asynchronously. - All methods in the {@link RtmClient} class are executed asynchronously. - - @param appId The App ID issued by Agora to you. Apply for a new App ID from Agora if it is missing from your kit. - @param eventHandler An IRtmServiceEventHandler object that invokes callbacks to be passed to the application on Agora RTM SDK runtime events. - */ + @param appId The App ID issued by Agora to you. Apply for a new App ID from Agora if it is missing from your kit. + @param eventHandler An IRtmServiceEventHandler object that invokes callbacks to be passed to the application on Agora RTM SDK runtime events. + @return + - 0: Success. + - < 0: Failure. + */ virtual int initialize(const char *appId, IRtmServiceEventHandler *eventHandler) = 0; + + /** + Adds an IRtmServiceEventHandler object. + @param eventHandler An IRtmServiceEventHandler object. + */ virtual void addEventHandler(IRtmServiceEventHandler *eventHandler) = 0; + + /** + Removes an IRtmServiceEventHandler object. + + @param eventHandler An IRtmServiceEventHandler object. + */ virtual void removeEventHandler(IRtmServiceEventHandler *eventHandler) = 0; - /** Releases all resources used by the IRtmService instance. - */ + /** + Releases all resources used by the \ref agora::rtm::IRtmService "IRtmService" instance. + */ virtual void release(bool sync = false) = 0; - /** Allows a user to log in Agora's RTM system. - - - If this method call succeeds, the local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginSuccess "onLoginSuccess" callback. - - If this method call fails, the local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginFailure "onLoginFailure" callback. See \ref agora::rtm::LOGIN_ERR_CODE "LOGIN_ERR_CODE" for the error codes. - - @param token Token used to log in Agora's RTM system and used when dynamic authentication is enabled. Set @token as @p nil in the integration and test stages. - @param userId User ID of the user logging in Agora's RTM system. The string must not exceed 64 bytes in length or start with a space. - Supported characters: - - - The 26 lowercase English letters: a to z - - The 26 uppercase English letters: A to Z - - The 10 numbers: 0 to 9 - - Space - - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", "," - - @note Do not set @p userId as @p null. - */ + /** + Logs in the Agora RTM system. + + - If this method call succeeds, the local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginSuccess "onLoginSuccess" callback. + - If this method call fails, the local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginFailure "onLoginFailure" callback. See \ref agora::rtm::LOGIN_ERR_CODE "LOGIN_ERR_CODE" for the error codes. + + @note + - If you log in with the same user ID from a different instance, you will be kicked out of your previous login and removed from previously joined channels. + - The call frequency limit for this method is 2 queries per second. + - Only after you successfully call this method (when the local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLoginSuccess "onLoginSuccess" callback), can you call the key RTM methods except: + - \ref agora::rtm::IRtmService::createChannel "createChannel" + - \ref agora::rtm::IRtmService::createMessage "createMessage" + - \ref agora::rtm::IMessage::setText "setText" + - \ref agora::rtm::IRtmService::getRtmCallManager "getRtmCallManager" + - \ref agora::rtm::IRtmCallManager::createLocalCallInvitation "createLocalCallInvitation" + - \ref agora::rtm::IRtmService::createChannelAttribute "createChannelAttribute" + + @param token Token used to log in the Agora RTM system and used when dynamic authentication is enabled. Set @p token as @p nil in the integration and test stages. + @param userId The user ID of the user logging in Agora's RTM system. The string must not exceed 64 bytes in length. It cannot be empty, null or "null". + Supported characters: + - All lowercase English letters: a to z + - All uppercase English letters: A to Z + - All numeric characters: 0 to 9 + - The space character. + - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", "," + @return + - 0: Success. + - ≠0: Failure. See #LOGIN_ERR_CODE for the error codes. + */ virtual int login(const char *token, const char *userId) = 0; - /** Allows a user to log out of Agora's RTM system. + /** + Logs out of the Agora RTM system. - The local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLogout "onLogout" callback. See \ref agora::rtm::LOGOUT_ERR_CODE "LOGIN_ERR_CODE" for the states. - */ + The local user receives the \ref agora::rtm::IRtmServiceEventHandler::onLogout "onLogout" callback. See \ref agora::rtm::LOGOUT_ERR_CODE "LOGIN_ERR_CODE" for the error codes. + + @return + - 0: Success. + - ≠0: Failure. See #LOGOUT_ERR_CODE for the error codes. + */ virtual int logout() = 0; - + + /** + Renews the current RTM Token. + + You are required to renew your RTM Token when receiving the \ref agora::rtm::IRtmServiceEventHandler::onTokenExpired "onTokenExpired" callback, and the \ref agora::rtm::IRtmServiceEventHandler::onRenewTokenResult "onRenewTokenResult" callback returns the result of this method call. The call frequency limit for this method is 2 queries per second. + + @param token Your new RTM Token. + @return + - 0: Success. + - ≠0: Failure. See #RENEW_TOKEN_ERR_CODE for the error codes. + */ virtual int renewToken(const char* token) = 0; - /** Allows a local user (sender) to send a peer-to-peer message to a specific user (receiver). - - If this method call succeeds: - - The sender receives the \ref agora::rtm::IRtmServiceEventHandler::onSendMessageResult "onSendMessageResult" callback. - - The receiver receives the \ref agora::rtm::IRtmServiceEventHandler::onMessageReceivedFromPeer "onMessageReceivedFromPeer" callback. + /** + @deprecated Sends a peer-to-peer message to a specified user (receiver). + + @note + - We do not recommend using this method to send a peer-to-peer message. Use \ref agora::rtm::IRtmService::sendMessageToPeer(const char *peerId, const IMessage *message, const SendMessageOptions &options) "sendMessageToPeer" instead. + - You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds. @param peerId User ID of the receiver. - @param message The message to be sent. For information about creating a message, see IMessage. + @param message The message to be sent. For information about creating a message, see \ref agora::rtm::IMessage "IMessage". + @return + - 0: Success. + - ≠0: Failure. See #PEER_MESSAGE_ERR_CODE for the error codes. */ virtual int sendMessageToPeer(const char *peerId, const IMessage *message) = 0; + + /** + Downloads a file or image from the Agora server to the local memory by media ID. + + The SDK returns the result of this method call by the \ref agora::rtm::IRtmServiceEventHandler::onMediaDownloadToFileResult "onMediaDownloadToMemoryResult" callback. + + @note + - This method applies to scenarios requiring quick access to the downloaded file or image. + - The SDK releases the downloaded file or image immediately after returning the \ref agora::rtm::IRtmServiceEventHandler::onMediaDownloadToFileResult "onMediaDownloadToMemoryResult" callback. + + @param mediaId The media ID of the file or image on the Agora server. + @param requestId The unique ID of this download request. + @return + - 0: Success. + - ≠0: Failure. See #DOWNLOAD_MEDIA_ERR_CODE for the error codes. + */ + virtual int downloadMediaToMemory(const char* mediaId, long long &requestId) = 0; + + /** + Downloads a file or image from the Agora server to a specified local directory by media ID. + + The SDK returns the result of this method call by the \ref agora::rtm::IRtmServiceEventHandler::onMediaDownloadToFileResult "onMediaDownloadToFileResult" callback. + + @param mediaId The media ID of the file or image on the Agora server. + @param filePath The full path to the downloaded file or image. Must be in UTF-8. + @param requestId The unique ID of this download request. + @return + - 0: Success. + - ≠0: Failure. See #DOWNLOAD_MEDIA_ERR_CODE for the error codes. + */ + virtual int downloadMediaToFile(const char* mediaId, const char* filePath, long long &requestId) = 0; + + /** + Cancels an ongoing file or image download task by request ID. + + The SDK returns the result of this method call with the \ref agora::rtm::IRtmServiceEventHandler::onMediaCancelResult "onMediaCancelResult" callback. + + @note + You can only cancel an ongoing download task. After a download task completes, the corresponding request ID is no longer valid and hence you cannot cancel it. + + @param requestId The unique ID of the download request to cancel. + @return + - 0: Success. + - ≠0: Failure. See #CANCEL_MEDIA_ERR_CODE for the error codes. + */ + virtual int cancelMediaDownload(long long requestId) = 0; + + /** + Cancels an ongoing file or image upload task by request ID. + + The SDK returns the result of this method call with the \ref agora::rtm::IRtmServiceEventHandler::onMediaCancelResult "onMediaCancelResult" callback. + + @note + You can only cancel an ongoing upload task. After an upload task completes, you cannot cancel it and the corresponding request ID is no longer valid. + + @param requestId The unique ID of the upload request to cancel. + @return + - 0: Success. + - ≠0: Failure. See #CANCEL_MEDIA_ERR_CODE for the error codes. + */ + virtual int cancelMediaUpload(long long requestId) = 0; + + + /** + Sends an (offline) peer-to-peer message to a specified user (receiver). + + This method allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the RTM server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + If you use this method to send off a text message that starts off with AGORA_RTM_ENDCALL_PREFIX_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore" in your additional information but you can set \ as empty "". + + - The \ref agora::rtm::IRtmServiceEventHandler::onSendMessageResult "onSendMessageResult" callback returns the result of this method call. + - When the message arrives at the receiver, the receiver receives the \ref agora::rtm::IRtmServiceEventHandler::onMessageReceivedFromPeer "onMessageReceivedFromPeer" callback. + + If you use this method to send off a text message that starts off with AGORA_RTM_ENDCALL_PREFIX_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore" in your additional information but you can set \ as empty "". + + @note You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds. + + @param peerId User ID of the receiver. The string must not exceed 64 bytes in length. It cannot be empty, null, or "null". Supported characters: + - The 26 lowercase English letters: a to z + - The 26 uppercase English letters: A to Z + - The 10 numbers: 0 to 9 + - Space + - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", "," + @param message The message to be sent. For information about creating a message, See \ref agora::rtm::IMessage "IMessage". + @param options Options when sending the message to a peer. See \ref agora::rtm::SendMessageOptions "SendMessageOptions". + @return + - 0: Success. + - ≠0: Failure. See #PEER_MESSAGE_ERR_CODE for the error codes. + */ + virtual int sendMessageToPeer(const char *peerId, const IMessage *message, const SendMessageOptions &options) = 0; + + /** + Creates an Agora RTM channel. + + - If the method call succeeds, the SDK returns an IChannel instance. + - If this method call fails, the SDK returns @p null. + + @note You can create multiple channels in an IRtmService instance. But you can only join a maximum of 20 channels at the same time. As a good practice, Agora recommends calling the \ref agora::rtm::IChannel::release "release" method to release all resources of an RTM channel that you no longer use. + + @param channelId The unique channel name. A @p channelId cannot be empty, null, or "null". Must be less than 64 bytes in length. + Supported characters: + - All lowercase English letters: a to z + - All uppercase English letters: A to Z + - All numeric characters: 0 to 9 + - The space character. + - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", "," + @param eventHandler See IChannelEventHandler. + @return + - An \ref agora::rtm::IChannel "IChannel" object: Success. If a channel with the same @p channelId does not exist, the method returns the created channel instance. If a channel with the same @p channelId already exists, the method returns the existing channel instance. + - null: Failure. Possible reasons: The @p channelId is invalid or you have joined the maximum number of channels. + */ + virtual IChannel * createChannel(const char *channelId, IChannelEventHandler *eventHandler) = 0; + + /** + Gets an \ref agora::rtm::IRtmCallManager "IRtmCallManager" object. + + Each \ref agora::rtm::IRtmService "IRtmService" object corresponds to a unique \ref agora::rtm::IRtmCallManager "IRtmCallManager" object. That said, the \ref agora::rtm::IRtmCallManager "IRtmCallManager" object is \ref agora::rtm::IRtmService "IRtmService"-specific. + + @note When you do no use \ref agora::rtm::IRtmCallManager "IRtmCallManager", call the \ref agora::rtm::IRtmCallManager::release "release" method to release all of its resources. + + @param eventHandler An \ref agora::rtm::IRtmCallEventHandler "IRtmCallEventHandler" object. + @return An \ref agora::rtm::IRtmCallManager "IRtmCallManager" object. + */ + virtual IRtmCallManager* getRtmCallManager(IRtmCallEventHandler*eventHandler) = 0; + + /** + Creates an empty text \ref agora::rtm::IMessage "IMessage" instance. + + @note + - An \ref agora::rtm::IMessage "IMessage" instance can be used either for a channel message or for a peer-to-peer message. + - When you no longer need an \ref agora::rtm::IMessage "IMessage" instance, please call the \ref agora::rtm::IMessage::release "release" method to release all resources that it is using. + - You can set the content of the text message at a later point using the \ref agora::rtm::IMessage::setText "setText" method, but please ensure that the size of the text message does not exceed 32 KB. + + @return An empty text \ref agora::rtm::IMessage "IMessage" instance. + */ + virtual IMessage *createMessage() = 0; + + /** + Creates a text \ref agora::rtm::IMessage "IMessage" instance. + + @note + - An \ref agora::rtm::IMessage "IMessage" instance can be used either for a channel message or for a peer-to-peer message. + - When you no longer need an \ref agora::rtm::IMessage "IMessage" instance, please call the \ref agora::rtm::IMessage::release "release" method to release all resources that it is using. + + @param message The text content of the message. Must not exceed 32 KB in length. + + @return A text \ref agora::rtm::IMessage "IMessage" instance. + */ + virtual IMessage *createMessage(const char* message) = 0; + + /** + Creates a raw \ref agora::rtm::IMessage "IMessage" instance. + + @note + - An \ref agora::rtm::IMessage "IMessage" instance can be used either for a channel message or for a peer-to-peer message. + - When you no longer need an \ref agora::rtm::IMessage "IMessage" instance, please call the \ref agora::rtm::IMessage::release "release" method to release all resources that it is using. + - You can set a brief text description of the raw message at a later point using the \ref agora::rtm::IMessage::setText "setText" method, but please ensure that the size of the raw message and the description combined does not exceed 32 KB. + + @param rawData The starting address of the raw message. + @param length Length of the raw message. Must not exceed 32 KB in length. + + @return A raw \ref agora::rtm::IMessage "IMessage" instance. + */ + virtual IMessage *createMessage(const uint8_t* rawData, int length) = 0; + + /** + Creates a raw \ref agora::rtm::IMessage "IMessage" instance and sets its description. + + @note + - An \ref agora::rtm::IMessage "IMessage" instance can be used either for a channel message or for a peer-to-peer message. + - When you no longer need an \ref agora::rtm::IMessage "IMessage" instance, please call the \ref agora::rtm::IMessage::release "release" method to release all resources that it is using. + - You can set @p description as "" and add a brief text description of the raw message at a later point using the \ref agora::rtm::IMessage::setText "setText" method, but please ensure that the size of the raw message and the description combined does not exceed 32 KB. + + @param rawData The starting address of the raw message. + @param length The length of the raw message. Must not exceed 32 KB in length. + @param description A brief text description of the raw message. If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + + @return A raw \ref agora::rtm::IMessage "IMessage" instance with a brief text description. + */ + virtual IMessage *createMessage(const uint8_t* rawData, int length, const char* description) = 0; + + /** + Creates an \ref agora::rtm::IFileMessage "IFileMessage" instance by media ID. + + - If you have at hand the media ID of a file on the Agora server, you can call this method to create an \ref agora::rtm::IFileMessage "IFileMessage" instance. + - If you do not have a media ID, then you must call \ref agora::rtm::IRtmService::createFileMessageByUploading "createFileMessageByUploading" to get a corresponding \ref agora::rtm::IFileMessage "IFileMessage" instance by uploading a file to the Agora RTM server. + + @param mediaId The media ID of an uploaded file on the Agora server. + @return An \ref agora::rtm::IFileMessage "IFileMessage" instance. + */ + virtual IFileMessage *createFileMessageByMediaId(const char* mediaId) = 0; + + /** + Creates an \ref agora::rtm::IImageMessage "IImageMessage" instance by media ID. + + - If you have at hand the media ID of an image on the Agora server, you can call this method to create an \ref agora::rtm::IImageMessage "IImageMessage" instance. + - If you do not have a media ID, then you must call \ref agora::rtm::IRtmService::createImageMessageByUploading "createImageMessageByUploading" to get a corresponding \ref agora::rtm::IImageMessage "IImageMessage" instance by uploading an image to the Agora RTM server. + + @param mediaId The media ID of an uploaded image on the Agora server. + @return An \ref agora::rtm::IImageMessage "IImageMessage" instance. + */ + virtual IImageMessage *createImageMessageByMediaId(const char* mediaId) = 0; + + /** + Gets an \ref agora::rtm::IFileMessage "IFileMessage" instance by uploading a file to the Agora server. + + The SDK returns the result with the \ref agora::rtm::IRtmServiceEventHandler::onFileMediaUploadResult callback. If success, this callback returns a corresponding \ref agora::rtm::IFileMessage "IFileMessage" instance. + + @note + - If you have at hand the media ID of a file on the Agora server, you can call \ref agora::rtm::IRtmService::createFileMessageByMediaId "createFileMessageByMediaId" to create an \ref agora::rtm::IFileMessage "IFileMessage" instance. + - To cancel an ongoing file upload task, call \ref agora::rtm::IRtmService::cancelMediaUpload "cancelMediaUpload". + + + @param filePath The full path to the local file to upload. Must be in UTF-8. + @param requestId The unique ID of this upload request. + @return + - 0: Success. + - ≠0: Failure. See #UPLOAD_MEDIA_ERR_CODE for the error codes. + */ + virtual int createFileMessageByUploading(const char* filePath, long long &requestId) = 0; + + /** + Gets an \ref agora::rtm::IImageMessage "IImageMessage" instance by uploading an image to the Agora server. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onImageMediaUploadResult callback. If success, this callback returns a corresponding \ref agora::rtm::IImageMessage "ImageMessage" instance. + + - If the uploaded image is in JPEG, JPG, BMP, or PNG format, the SDK calculates the width and height of the image. You can call \ref agora::rtm::IImageMessage::getWidth "getWidth" and \ref agora::rtm::IImageMessage::getHeight "getHeight" to get the calculated width and height. + - Otherwise, you need to call \ref agora::rtm::IImageMessage::setWidth "setWidth" and \ref agora::rtm::IImageMessage::setHeight "setHeight" to set the width and height of the uploaded image by yourself. + + @note + - If you have at hand the media ID of an image on the Agora server, you can call \ref agora::rtm::IRtmService::createImageMessageByMediaId "createImageMessageByMediaId" to create an \ref agora::rtm::IImageMessage "IImageMessage" instance. + - To cancel an ongoing image upload task, call \ref agora::rtm::IRtmService::cancelMediaUpload "cancelMediaUpload". + + @param filePath The full path to the local image to upload. Must be in UTF-8. + @param requestId The unique ID of the upload request. + @return + - 0: Success. + - ≠0: Failure. See #UPLOAD_MEDIA_ERR_CODE for the error codes. + */ + virtual int createImageMessageByUploading(const char* filePath, long long &requestId) = 0; + + /** + Creates an \ref agora::rtm::IRtmChannelAttribute "IRtmChannelAttribute" instance. + + @return An \ref agora::rtm::IRtmChannelAttribute "IRtmChannelAttribute" instance. + */ + virtual IRtmChannelAttribute *createChannelAttribute() = 0; + + /** + Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options. + + @note The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact [support@agora.io](mailto:support@agora.io) for more information. + + @param parameters SDK options in the JSON format. + @return + - 0: Success. + - ≠0: Failure. + */ + virtual int setParameters(const char* parameters) = 0; +// virtual int getParameters(const char* key, any_document_t& result) = 0; + + /** + Queries the online status of the specified users. + + - Online: The user has logged in the Agora RTM system. + - Offline: The user has logged out of the Agora RTM system. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onQueryPeersOnlineStatusResult "onQueryPeersOnlineStatusResult" callback. + + @param peerIds[] An array of the specified user IDs. + @param peerCount Length of the list. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #QUERY_PEERS_ONLINE_STATUS_ERR for the error codes. + */ + virtual int queryPeersOnlineStatus(const char* peerIds[], int peerCount, long long &requestId) = 0; + + /** + Subscribes to the online status of the specified users. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onSubscriptionRequestResult "onSubscriptionRequestResult" callback. + + - When the method call succeeds, the SDK returns the \ref agora::rtm::IRtmServiceEventHandler::onPeersOnlineStatusChanged "onPeersOnlineStatusChanged" callback to report the online status of peers, to whom you subscribe. + - When the online status of the peers, to whom you subscribe, changes, the SDK returns the \ref agora::rtm::IRtmServiceEventHandler::onPeersOnlineStatusChanged "onPeersOnlineStatusChanged" callback to report whose online status has changed. + - If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the \ref agora::rtm::IRtmServiceEventHandler::onPeersOnlineStatusChanged "onPeersOnlineStatusChanged" callback to report whose online status has changed when successfully reconnecting to the server. + + @note + - When you log out of the Agora RTM system, all the status that you subscribe to will be cleared. To keep the original subscription after you re-log in the system, you need to redo the whole subscription process. + - When the SDK reconnects to the server from the state of being interupted, the SDK automatically subscribes to the peers and states before the interruption without human intervention. + + @param peerIds An array of the specified user IDs. + @param peerCount Length of the peer list. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #PEER_SUBSCRIPTION_STATUS_ERR for the error codes. + */ + virtual int subscribePeersOnlineStatus(const char* peerIds[], int peerCount, long long &requestId) = 0; - /** Creates an Agora RTM channel. + /** + Unsubscribes from the online status of the specified users. - - If the method call succeeds, the SDK returns an IChannel instance. - - If this method call fails, the SDK returns @p null. The @p channelId may be invalid, or an existing channel with the same @p channelId exists, or the number of channels is over the limit. + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onSubscriptionRequestResult "onSubscriptionRequestResult" callback. - @note You can create multiple channels in an IRtmService instance. + @param peerIds An array of the specified user IDs. + @param peerCount Length of the peer list. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #PEER_SUBSCRIPTION_STATUS_ERR for the error codes. + */ + virtual int unsubscribePeersOnlineStatus(const char* peerIds[], int peerCount, long long &requestId) = 0; - @param channelId The unique channel name for the Agora RTM session in the string format smaller than 64 bytes and cannot be empty or set as @p null. - Supported characters: - - The 26 lowercase English letters: a to z - - The 26 uppercase English letters: A to Z - - The 10 numbers: 0 to 9 - - Space - - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", "," + /** + Gets a list of the peers, to whose specific status you have subscribed. - @param eventHandler See IChannelEventHandler. - */ - virtual IChannel * createChannel(const char *channelId, IChannelEventHandler *eventHandler) = 0; + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onQueryPeersBySubscriptionOptionResult "onQueryPeersBySubscriptionOptionResult" callback. - virtual IRtmCallManager* getRtmCallManager(IRtmCallEventHandler*eventHandler) = 0; - /** Creates an IMessage instance. - * - * @note The IMessage instance can be either for a channel or peer-to-peer message. - * - * @return An IMessage instance. - */ - virtual IMessage *createMessage() = 0; - // todo: move to private - virtual int setParameters(const char* parameters) = 0; -// virtual int getParameters(const char* key, any_document_t& result) = 0; - virtual int queryPeersOnlineStatus(const char* peerIds[], int peerCount, long long& requestId) = 0; + @param option The status type, to which you have subscribed. See #PEER_SUBSCRIPTION_OPTION. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR for the error codes. + */ + virtual int queryPeersBySubscriptionOption(PEER_SUBSCRIPTION_OPTION option, long long &requestId) = 0; + + /** + Substitutes the local user's attributes with new ones. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onSetLocalUserAttributesResult "onSetLocalUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes", \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes", \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" and \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param attributes The new attributes. See RtmAttribute. + @param numberOfAttributes The number of the attributes. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int setLocalUserAttributes(const RtmAttribute* attributes, int numberOfAttributes, long long &requestId) = 0; + + /** + Adds or updates the local user's attribute(s). + + This method updates the local user's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) to the local user if it does not. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onAddOrUpdateLocalUserAttributesResult "onAddOrUpdateLocalUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes", \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes", \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" and \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param attributes The attrubutes to be added or updated. See RtmAttribute. + @param numberOfAttributes The number of the attributes. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int addOrUpdateLocalUserAttributes(const RtmAttribute* attributes, int numberOfAttributes, long long &requestId) = 0; + + /** + Deletes the local user's attributes by attribute keys. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onDeleteLocalUserAttributesResult "onDeleteLocalUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes", \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes", \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" and \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param attributeKeys An array of the attribute keys to be deleted. + @param numberOfKeys Number of the attribute keys. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int deleteLocalUserAttributesByKeys(const char* attributeKeys[], int numberOfKeys, long long &requestId) = 0; + + /** + Clears all attributes of the local user. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onClearLocalUserAttributesResult "onClearLocalUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::setLocalUserAttributes "setLocalUserAttributes", \ref agora::rtm::IRtmService::addOrUpdateLocalUserAttributes "addOrUpdateLocalUserAttributes", \ref agora::rtm::IRtmService::deleteLocalUserAttributesByKeys "deleteLocalUserAttributesByKeys" and \ref agora::rtm::IRtmService::clearLocalUserAttributes "clearLocalUserAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int clearLocalUserAttributes(long long &requestId) = 0; + + /** + Gets all attributes of a specified user. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onGetUserAttributesResult "onGetUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::getUserAttributes "getUserAttributes" and \ref agora::rtm::IRtmService::getUserAttributesByKeys "getUserAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 40 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + + @param userId The user ID of the specified user. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int getUserAttributes(const char* userId, long long &requestId) = 0; + + /** + Gets the attributes of a specified user by attribute keys. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onGetUserAttributesResult "onGetUserAttributesResult" callback. + + @note For \ref agora::rtm::IRtmService::getUserAttributes "getUserAttributes" and \ref agora::rtm::IRtmService::getUserAttributesByKeys "getUserAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 40 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + + @param userId The user ID of the specified user. + @param attributeKeys An array of the attribute keys. + @param numberOfKeys The number of the attribute keys. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int getUserAttributesByKeys(const char* userId, const char* attributeKeys[], int numberOfKeys, long long &requestId) = 0; + + /** + Resets the attributes of a specified channel. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onSetChannelAttributesResult "onSetChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to update its attributes. + - The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes. + - If more than one user can update the channel attributes, then Agora recommends calling \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" to update the cache before calling this method. + - For \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes", \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes", \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" and \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param channelId The channel ID of the specified channel. + @param attributes An array of channel attributes. See \ref agora::rtm::IRtmChannelAttribute "IRtmChannelAttribute". + @param numberOfAttributes The total number of the channel attributes. + @param options Options for this attribute operation. See ChannelAttributeOptions. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int setChannelAttributes(const char* channelId, const IRtmChannelAttribute* attributes[], int numberOfAttributes, const ChannelAttributeOptions &options, long long &requestId) = 0; + + /** + Adds or updates the attribute(s) of a specified channel. + + This method updates the specified channel's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) to the channel if it does not. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onAddOrUpdateChannelAttributesResult "onAddOrUpdateChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to update its attributes. + - The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes. + - If more than one user can update the channel attributes, then Agora recommends calling \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" to update the cache before calling this method. + - For \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes", \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes", \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" and \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param channelId The channel ID of the specified channel. + @param attributes An array of channel attributes. See \ref agora::rtm::IRtmChannelAttribute "IRtmChannelAttribute". + @param numberOfAttributes The total number of the channel attributes. + @param options Options for this attribute operation. See ChannelAttributeOptions. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int addOrUpdateChannelAttributes(const char* channelId, const IRtmChannelAttribute* attributes[], int numberOfAttributes, const ChannelAttributeOptions &options, long long &requestId) = 0; + + /** + Deletes the attributes of a specified channel by attribute keys. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onDeleteChannelAttributesResult "onDeleteChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to update its attributes. + - The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes. + - If more than one user can update the channel attributes, then Agora recommends calling \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" to update the cache before calling this method. + - For \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes", \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes", \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" and \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param channelId The channel ID of the specified channel. + @param attributeKeys An array of channel attribute keys. + @param numberOfKeys The total number of the channel attributes. + @param options Options for this attribute operation. See ChannelAttributeOptions. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int deleteChannelAttributesByKeys(const char* channelId, const char* attributeKeys[], int numberOfKeys, const ChannelAttributeOptions &options, long long &requestId) = 0; + + /** + Clears all attributes of a specified channel. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onClearChannelAttributesResult "onClearChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to clear its attributes. + - The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes. + - For \ref agora::rtm::IRtmService::setChannelAttributes "setChannelAttributes", \ref agora::rtm::IRtmService::addOrUpdateChannelAttributes "addOrUpdateChannelAttributes", \ref agora::rtm::IRtmService::deleteChannelAttributesByKeys "deleteChannelAttributesByKeys" and \ref agora::rtm::IRtmService::clearChannelAttributes "clearChannelAttributes" taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds. + + @param channelId The channel ID of the specified channel. + @param options Options for this attribute operation. See ChannelAttributeOptions. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int clearChannelAttributes(const char* channelId, const ChannelAttributeOptions &options, long long &requestId) = 0; + + /** + Gets all attributes of a specified channel. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onGetChannelAttributesResult "onGetChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to get its attributes. + - For \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" and \ref agora::rtm::IRtmService::getChannelAttributesByKeys "getChannelAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + + @param channelId The channel ID of the specified channel. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int getChannelAttributes(const char* channelId, long long &requestId) = 0; + + /** + Gets the attributes of a specified channel by attribute keys. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onGetChannelAttributesResult "onGetChannelAttributesResult" callback. + + @note + - You do not have to join the specified channel to get its attributes. + - For \ref agora::rtm::IRtmService::getChannelAttributes "getChannelAttributes" and \ref agora::rtm::IRtmService::getChannelAttributesByKeys "getChannelAttributesByKeys" taken together, the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds. + @param channelId The channel ID of the specified channel. + @param attributeKeys An array of attribute keys. + @param numberOfKeys The total number of the attribute keys. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #ATTRIBUTE_OPERATION_ERR for the error codes. + */ + virtual int getChannelAttributesByKeys(const char* channelId, const char* attributeKeys[], int numberOfKeys, long long &requestId) = 0; + + /** + Gets the member count of specified channels. + + The SDK returns the result by the \ref agora::rtm::IRtmServiceEventHandler::onGetChannelMemberCountResult "onGetChannelMemberCountResult" callback. + + @note + - The call frequency limit for this method is one query per second. + - We do not support getting the member counts of more than 32 channels in one method call. + - You do not have to join the specified channels to call this method. + + @param channelIds An array of the specified channel IDs. + @param channelCount The total number of the channels. + @param requestId The unique ID of this request. + @return + - 0: Success. + - ≠0: Failure. See #GET_CHANNEL_MEMBER_COUNT_ERR_CODE for the error codes. + */ + virtual int getChannelMemberCount(const char* channelIds[], int channelCount, long long &requestId) = 0; + + /** + Specifies the default path to the SDK log file. + + @note + - Ensure that the directory holding the log file exists and is writable. + - Ensure that you call this method immediately after calling the \ref agora::rtm::IRtmService::initialize "initialize" method to initialize an \ref agora::rtm::IRtmService "IRtmService" instance, otherwise the output log may be incomplete. + - For the Linux C++ platform, agorartm.log is in the current working directory. + + @param logfile The absolute file path to the log file. The string of @p logfile is in UTF-8. + @return + - 0: Success. + - ≠0: Failure. + */ + virtual int setLogFile(const char* logfile) = 0; + + /** + Sets the output log level of the SDK. + + You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. + + @param filter The log filter level. See #LOG_FILTER_TYPE. + @return + - 0: Success. + - ≠0: Failure. + */ + virtual int setLogFilter(LOG_FILTER_TYPE filter) = 0; + + /** + Sets the size of a single log file. The SDK has two log files with the same size. + + @param fileSizeInKBytes The size of a single log file (KB). The default is `10240` (KB). The value range is [512 KB, 1 GB]. + @return + - 0: Success. + - ≠0: Failure. + */ + virtual int setLogFileSize(int fileSizeInKBytes) = 0; }; +//////////////////////////////////////////////////////// +/** \addtogroup createRtmService +@{ +*/ +//////////////////////////////////////////////////////// + +/** +Creates an \ref agora::rtm::IRtmService "IRtmService" instance. + +@note When you no longer need an \ref agora::rtm::IRtmService "IRtmService" instance, ensure that you call the \ref agora::rtm::IRtmService::release "release" method to release all resources that it uses. +@return An \ref agora::rtm::IRtmService "IRtmService" instance. +*/ +AGORA_API IRtmService* AGORA_CALL createRtmService(); + +//////////////////////////////////////////////////////// +/** @} */ +//////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////// +/** \addtogroup getRtmSdkVersion +@{ +*/ +//////////////////////////////////////////////////////// + +/** +Gets the version of the Agora RTM SDK. + +@return The version of the Agora RTM SDK. +*/ +AGORA_API const char* AGORA_CALL getRtmSdkVersion(); + +/** + Region for the Agora RTM service. After setting a region, the RTM SDK can only connect to the Agora RTM service in the specified region. + */ +enum RTM_AREA_CODE { + /** + * Mainland China. + */ + AREA_CODE_CN = (1 << 0), + /** + * North America. + */ + AREA_CODE_NA = (1 << 1), + /** + * Europe. + */ + AREA_CODE_EU = (1 << 2), + /** + * Asia excluding Mainland China. + */ + AREA_CODE_AS = (1 << 3), + /** + * Japan. + */ + AREA_CODE_JP = (1 << 4), + /** + * India. + */ + AREA_CODE_IN = (1 << 5), + /** + * (Default) Global. + */ + AREA_CODE_GLOB = (0xFFFFFFFF) +}; + +/** + Context of the `%IRtmService` instance. + */ +struct RtmServiceContext +{ + /** + * Region for the Agora RTM service. The default is #AREA_CODE_GLOB. + */ + int areaCode = AREA_CODE_GLOB; +}; + +/** + Error codes returned by \ref agora::rtm::setRtmServiceContext "setRtmServiceContext". See #RTM_AREA_CODE. + */ +enum SET_RTM_SERVICE_CONTEXT_ERR_CODE +{ + /** + 0: Successfully configured the context for the Agora RTM service. + */ + SET_RTM_SERVICE_CONTEXT_ERR_OK = 0, + /** + 1: Failed to configure the context for the Agora RTM service because at least one \ref agora::rtm::IRtmService "IRtmService" instance already exists. Call \ref agora::rtm::IRtmService::release "release" to destroy any existing `%IRtmService` instance before configuring the context for the Agora RTM service. + */ + SET_RTM_SERVICE_CONTEXT_ERR_FAILURE = 1, +}; + +/** + Sets the context of all `IRtmService` instances. All `%IRtmservice` instances you create after calling this method match the context. + + @note You must call this method before calling #createRtmService to create an `%IRtmservice` instance or after destroying any existing `%IRtmservice` instance. Otherwise, this method returns the #SET_RTM_SERVICE_CONTEXT_ERR_FAILURE error code. + + @param context Context of the `%IRtmservice` instance, including geofencing. See \ref agora::rtm::RtmServiceContext "RtmServiceContext". + + @return #SET_RTM_SERVICE_CONTEXT_ERR_CODE. + */ +AGORA_API SET_RTM_SERVICE_CONTEXT_ERR_CODE AGORA_CALL setRtmServiceContext(const RtmServiceContext& context); + +//////////////////////////////////////////////////////// +/** @} */ +//////////////////////////////////////////////////////// } } diff --git a/Agora-RTM-Tutorial-Linux/lib/libagora_rtm_sdk.so b/Agora-RTM-Tutorial-Linux/lib/libagora_rtm_sdk.so index b6e0409..0f1368b 100644 Binary files a/Agora-RTM-Tutorial-Linux/lib/libagora_rtm_sdk.so and b/Agora-RTM-Tutorial-Linux/lib/libagora_rtm_sdk.so differ diff --git a/Agora-RTM-Tutorial-Linux/rtm_demo.cpp b/Agora-RTM-Tutorial-Linux/rtm_demo.cpp index 3d17b68..0689d3c 100644 --- a/Agora-RTM-Tutorial-Linux/rtm_demo.cpp +++ b/Agora-RTM-Tutorial-Linux/rtm_demo.cpp @@ -2,6 +2,7 @@ #include #include #include +#include //#include #include "IAgoraRtmService.h" @@ -164,7 +165,7 @@ class DemoMessaging { std::cout << RED <<"error creating rtm service!" << std::endl; exit(0); } - ret = rtmService_->initialize(APP_ID.c_str(), eventHandler_.get()); + int ret = rtmService_->initialize(APP_ID.c_str(), eventHandler_.get()); if (ret) { std::cout << RED << "error initializing rtm service: " << ret << std::endl; exit(0);