Signaling API - Windows Beta

Methods

Account Information System

Login(login)

public virtual void login (char const * appId, size_t appId_size,char const * account, size_t account_size,char const * token, size_t token_size,uint32_t uid,char const * deviceID, size_t deviceID_size)=0;

This method allows the users to log into the Agora signaling system. The users must log in before they can perform any action.

It triggers the onLoginSuccess callback upon a successful execution, otherwise it returns onLoginFailed. If the application lost the connection with the server, it returns the onLogout callback.

Parameter Description
appId App ID provided by Agora at https://dashboard.agora.io.
account

User ID defined by the client. It can be up to 128 visible characters (space is not permitted currently).

It can be the uid, nickname, guid and other content as long as it is unique.

The account parameter mentioned across this document follow the same rule.

token Signaling Key generated by App ID and App Certificate. See Agora Keys User Guide for details.
uid Expired, set it as 0.
deviceID Set it as NULL.

Login(login2)

public virtual void login2(std::string vendorID, std::string account, std::string token, uint32_t uid, std::string deviceID, int retry_time_in_s, int retry_count) = 0;

This method allows the users to log into the Agora signaling system.

Parameter Description
appId App ID provided by Agora at https://dashboard.agora.io.
account

User ID defined by the client. It can be up to 128 visible characters (space is not permitted currently).

It can be the uid, nickname, guid and other content as long as it is unique.

The account parameter mentioned across this document follow the same rule.

token Signaling Key generated by App ID and App Certificate. See Agora Keys User Guide for details.
uid Expired, set it as 0.
deviceID Set it as NULL.
retry_time_in_s The length of the time it retries to login, 30 seconds by default.
retry_count The number it retries to login, 3 times by default.

Log out(logout)

It triggers the onLogout callback upon a successful execution.

public virtual void logout () = 0;

Send Point-to-Point Message(messageInstantSend)

public void messageInstantSend(String account,int uid,String msg,String msgID);

This method send point-to-point message to a specific account.

Upon a successful execution, the user receives onMessageSendSuccess event, and the other user receives onMessageInstantReceive.

If the execution fails, the user receives onMessageSendError event.

Parameter Description
account User ID defined by the client.
uid

Obsolete.

Set it as 0.

msg

Message body.

Each message must be no greater than 8K visible characters.

Set User Attributes(set_attr)

public virtual void set_attr (char const * name, size_t name_size,char const * value, size_t value_size) = 0;

This method sets the user attributes.

Parameter Description
name

Attribute name.

It can be up to 256 visible characters

value

Attribute value.

It can be up to 128 visible characters

Get Your Own User Attributes(get_attr)

This method gets your own user attributes. You will receive the onUserAttrResult event.

public virtual void get_attr (char const * name, size_t name_size) = 0;
Parameter Description
name

Attribute name.

It can be up to 256 visible characters

Get All of Your Own Attributes(get_attr_all)

public virtual void get_attr_all () = 0;

This method gets all of your attributes. You will receive the onUserAttrResult upon a successful execution.

Get Attributes of Specific User(get_user_attr)

public virtual void get_user_attr (char const * account, size_t account_size,char const * name, size_t name_size) = 0;

This method allows the user to get the attributes of a specific user. The user will receive onUserAttrResult event.

Parameter Description
account User ID defined by the client.
name

Attribute name.

It can be up to 256 visible characters

Get All attributes of Specific User(get_user_attr_all)

public virtual void get_user_attr_all (char const * account, size_t account_size) = 0;

This method allows the user to get all the attributes of a specific user. The user will receive the onUserAttrAllResult callback upon a successful execution.

Parameter Description
account User ID defined by the client.

Check Login Status(isOnline)

public virtual bool isOnline () = 0;

This method checks whether the user is logged in the Agora signaling system or not, online or offline.

Parameter Description
Return Value

1: Online

0: Offline

Channel System

Join Channel(channelJoin)

public virtual void channelJoin (char const * channelID, size_t channelID_size) = 0;

This method allows the users to join a specified channel. Whenever he/she joins a specified channel, he/she will be disconnected automatically from the previously joined channel, if any.

Once the user joins a channel, he/she receives the onChannelJoined callback, and other users in the same channel receive the onChannelUserJoined callback. If the user fails to join a specified channel, he/she receives the onChannelJoinFailed callback.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Leave Channel(channelLeave)

public virtual void channelLeave (char const * channelID, size_t channelID_size) = 0;

This method allows the users to leave the current channel. Once the user left the channel, all rest users in the channel receive the onChannelUserLeaved callback.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Query Channel User Number(channelQueryUserNum)

public virtual void channelQueryUserNum (char const * channelID, size_t channelID_size) = 0;

This method allows the users to query the number of users in a specified channel. Upon a successful execution, the users will receive the onChannelQueryUserNumResult callback.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Set Channel Attributes(channelSetAttr)

public  virtual void channelSetAttr (char const * channelID, size_t channelID_size,char const * name, size_t name_size,char const * value, size_t value_size) = 0;

This method sets the channel attributes. Whenever a change is made on the attributes, all users in the channel receive the onChannelAttrUpdated event.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

name

Attribute name.

It can be up to 128 visible characters .

value

Attribute value.

It can be up to 1024 visible characters .

Delete Channel Attributes(channelDelAttr)

public virtual void channelDelAttr (char const * channelID, size_t channelID_size,char const * name, size_t name_size,char const * value, size_t value_size) = 0;
Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

name

Attribute name.

It can be up to 128 visible characters .

value

Attribute value.

It can be up to 128 visible characters .

Delete All Channel Attributes(channelClearAttr)

public virtual void channelClearAttr (char const * channelID, size_t channelID_size) = 0;

This method deletes all the attributes of a specified channel.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Send Channel Message(messageChannelSend)

public virtual void messageChannelSend (char const * channelID, size_t channelID_size,char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0;

This method sends channel message, and all users in the same channel receive onMessageChannelReceive event.

The user who sent the message receives onMessageSendSuccess event upon a successful execution, otherwise, receives onMessageSendError.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

msg

Message body.

In a large group call, each message must be no greater than 1K visible characters.

Each user cannot send more than 60 message per second, the entire channel can not send more than 600 messages per second.

In an one-on-one call, each message must be no greater than 8K visible characters.

msgID

Visible characters, can be set as NULL.

It is used to mark the callback message.

Call System

Initiate a Call(channelInviteUser)

public virtual void channelInviteUser (char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid=0) = 0;

This method initiates a call, that is, inviting other user to join a specific channel. If the call fails, the user will receive onInviteFailed event. Possible reasons are listed as follows:

  • The other user is offline;
  • Network issue in the local;
  • Server error;

If the user(calling) gets confirmation from the other user(called), the user will receive onInviteReceivedByPeer event, and the other will receive onInviteReceived.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid Obsolete. Set it as 0.

Initiate a Call (channelInviteUser2)

virtual void channelInviteUser2 (char const * channelID, size_t channelID_size,char const * account, size_t account_size,char const * extra, size_t extra_size) = 0;

Same as above with different parameters.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Send DTMF Message to Other User(channelInviteDTMF)

public virtual void channelInviteDTMF (char const * channelID, size_t channelID_size,char const * phoneNum, size_t phoneNum_size,char const * dtmf, size_t dtmf_size) = 0;

This method sends DTMF message to the other user for calling via SIP gateway.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

phoneNum The phone number of the other user.
dtmf The subsequent analog phone number(DTMF) to be entered after the call gets through.

Accept Call(channelInviteAccept)

public virtual void channelInviteAccept (char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid) = 0;

This method accepts the received call request/invitation. Once this API is called, the other user will receive onInviteAcceptedByPeer event.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

Reject Call(channelInviteRefuse)

virtual void channelInviteRefuse (char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * extra, size_t extra_size) = 0;

This method rejects the received call invitation/request. Once this API is called, the other user will receive the onInviteRefusedByPeer event.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

End Call(channelInviteEnd)

public virtual void channelInviteEnd (char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid) = 0;

This method closed the call after the call has been connected. The user receives the onInviteEndByMyself event, and the other user receives onInviteEndByPeer.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

Internal-test or Obsolete Interface

Interface Prototype Description
messageAppSend public virtual void messageAppSend (char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0; Agora internal test only
messageChannelSendFast public virtual void messageChannelSendFast (char const * channelID, size_t channelID_size,char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0; Agora internal test only
messagePushSend public virtual void messagePushSend (char const * account, size_t account_size,uint32_t uid,char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0; Agora internal test only
messageChatSend public virtual void messageChatSend (char const * account, size_t account_size,uint32_t uid,char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0; Agora internal test only
messageDTMFSend public virtual void messageDTMFSend (uint32_t uid,char const * msg, size_t msg_size,char const * msgID, size_t msgID_size) = 0; Obsolete
setBackground public virtual void setBackground (uint32_t bOut) = 0; Agora internal test only
setNetworkStatus public virtual void setNetworkStatus (uint32_t bOut) = 0; Agora internal test only
Ping virtual void ping () = 0; Agora internal test only
channelInvitePhone public virtual void channelInvitePhone (char const * channelID, size_t channelID_size,char const * phoneNum, size_t phoneNum_size,uint32_t uid=0) = 0; Obsolete
channelInvitePhone2 public virtual void channelInvitePhone2 (char const * channelID, size_t channelID_size,char const * phoneNum, size_t phoneNum_size,char const * sourcesNum, size_t sourcesNum_size) = 0; Obsolete
channelInvitePhone3 public virtual void channelInvitePhone3 (char const * channelID, size_t channelID_size,char const * phoneNum, size_t phoneNum_size,char const * sourcesNum, size_t sourcesNum_size,char const * extra, size_t extra_size) = 0; Obsolete

Events

Connection Lost Event(onReconnecting)

public virtual void onReconnecting(uint32_t nretry) {}

This event is triggered when the connection with the Agora signaling system is lost after login.

Parameter Description
nretry The current reconnection number.

Connection Recovered Event(onReconnected)

public virtual void onReconnected(int fd) {}

This event is triggered when the application is reconnected to the Agora signaling system. When the reconnection fails, the event onLogout will be triggered instead.

Parameter Description
fd For Agora internal use.

User Online Event(onLoginSuccess)

public virtual void onLoginSuccess(uint32_t uid,int fd) {}

This event is triggered when the user is logged into the Agora signaling system.

Parameter Description
fd For Agora internal use.

User Offline Event(onLogout)

public virtual void onLogout(int ecode) {}

This event is triggered when the user logged out the Agora signaling system.

Parameter Description
ecode error code

User Login Failed Event(onLoginFailed)

public virtual void onLoginFailed(int ecode) {}

This callback is triggered when the user fails to log into the Agora signaling system.

Parameter Description
ecode error code

User Joined Channel Event(onChannelJoined)

public virtual void onChannelJoined(char const * channelID, size_t channelID_size) {}

This event is triggered when the user has joined a channel.

Parameter Description
channelID Channel name

User Failed to Join Channel Event(onChannelJoinFailed)

public virtual void onChannelJoinFailed(char const * channelID, size_t channelID_size,int ecode) {}

This event is triggered when the user fails to join a channel.

Parameter Description
channelID Channel name
ecode error code

User Left Channel Event(onChannelLeaved)

public virtual void onChannelLeaved(char const * channelID, size_t channelID_size,int ecode) {}

This event is triggered when the user left a channel.

Parameter Description
channelID Channel name
ecode error code

Other User Joined Channel Event(onChannelUserJoined)

public virtual void onChannelUserJoined(char const * account, size_t account_size,uint32_t uid) {}

This event is triggered when other user joined the channel.

Parameter Description
account User ID defined by the client.
uid obsolete

Other User Left Channel Event(onChannelUserLeaved)

public virtual void onChannelUserLeaved(char const * account, size_t account_size,uint32_t uid) {}

This event is triggered when other user left the channel.

Parameter Description
account User ID defined by the client.
uid obsolete

User List Received Event(onChannelUserList)

public virtual void onChannelUserList(int n,char** accounts,uint32_t* uids) {}

This event is triggered when the user has joined a non-large channel(less than 200 people).

Parameter Description
accounts List of User IDs defined by the client.
uids obsolete

User Number Received Event(onChannelQueryUserNumResult)

public virtual void onChannelQueryUserNumResult(char const * channelID, size_t channelID_size,int ecode,int num) {}

This event is triggered when the user has queried the user number of the channel.

Parameter Description
channelID Channel name
ecode Error code
num The query result

Channel Attribute Changed Event(onChannelAttrUpdated)

public virtual void onChannelAttrUpdated(char const * channelID, size_t channelID_size,char const * name, size_t name_size,char const * value, size_t value_size,char const * type, size_t type_size) {}

This event is triggered when the channel attribute is changed.

Parameter Description
channelID Channel name
name Attribute name
value Attribute value
type

Change types:

  • “update”: Update
  • “del”: Delete
  • “clear”: Delete all

Call Invitation Received Event(onInviteReceived)

virtual void onInviteReceived(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * extra, size_t extra_size) {}

This event is triggered when the user received a call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Other User Received Call Event(onInviteReceivedByPeer)

public virtual void onInviteReceivedByPeer(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid) {}

This event is received the caller when the other user has received the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete

Other User Accepted Call Event(onInviteAcceptedByPeer)

virtual void onInviteAcceptedByPeer(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * extra, size_t extra_size) {}

This event is received by the caller when the other user has accepted the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other issue defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Other User Rejected Call Event(onInviteRefusedByPeer)

virtual void onInviteRefusedByPeer(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * extra, size_t extra_size) {}

This event is received by the caller when the other user rejected the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Call Failed Event (onInviteFailed)

virtual void onInviteFailed(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,int ecode,char const * extra, size_t extra_size) {}

This event is triggered when a call fails.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Other User Ended Call Event(onInviteEndByPeer)

virtual void onInviteEndByPeer(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * extra, size_t extra_size) {}

This event is triggered when the other user ended the call.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client
msg Message body
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Call Ended Event(onInviteEndByMyself)

public virtual void onInviteEndByMyself(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid) {}

This event is received by the user when the user ended the call.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client
uid obsolete
msg Message body

Message Received Event(onInviteMsg)

public virtual onInviteMsg(char const * channelID, size_t channelID_size, char const * account, size_t account_size, int uid, String msgType, String msgData, String extra)

This event is triggered when you have received the DTMF message sent from the other user.

Parameter Description
channelID Channel name. It can be up to 128 visible characters
account User ID of the other user defined by the client
uid Obsolete.
msgType The message Type. Currently it means DTMF
msgData The detailed DTMF message. The supported string scope: 0-9, * , #
extra The extra information of the call, which can be a string, a JSON string, or NULL.

Message Failed Event(onMessageSendError)

public virtual void onMessageSendError(char const * messageID, size_t messageID_size,int ecode) {}

This event is triggered when the user fails to send a message.

Parameter Description
messageID Message ID
ecode Error code

Message Sent Event(onMessageSendSuccess)

public virtual void onMessageSendSuccess(char const * messageID, size_t messageID_size) {}

This event is triggered when the user sent a message successfully.

Parameter Description
messageID Message ID

Other User Received Message Event(onMessageInstantReceive)

public virtual void onMessageInstantReceive(char const * account, size_t account_size,uint32_t uid,char const * msg, size_t msg_size) {}

This event is triggered when the other user has received the message.

Parameter Description
account User ID defined by the client
uid Obsolete
msg Message body

Channel Message Received Event(onMessageChannelReceive)

public virtual void onMessageChannelReceive(char const * channelID, size_t channelID_size,char const * account, size_t account_size,uint32_t uid,char const * msg, size_t msg_size) {}

This event is trigged upon receiving the channel message.

Parameter Description
channelID Channel name
account User ID defined by the client
uid obsolete
msg Message body

Log Printed Event(onLog)

public virtual void onLog(char const * txt, size_t txt_size) {}

This event is trigged upon a line of log is printed out.

Parameter Description
txt Content of a log line

Attribute Received Event(onUserAttrResult)

public virtual void onUserAttrResult(char const * account, size_t account_size,char const * name, size_t name_size,char const * value, size_t value_size) {}

This event is triggered when the user has queried the attribute of a specific user.

Parameter Description
account User ID defined by the client
name Attribute name
value The json value of all attributes

All Attribute Received Event(onUserAttrAllResult)

public virtual void onUserAttrAllResult(char const * account, size_t account_size,char const * value, size_t value_size) {}

This event is triggered when the user has queried all the attributes of a specific user.

Parameter Description
account User ID defined by the client
value The json value of all attributes

Internal-test or Obsolete Interface

Interface Prototype Description
onMessageAppReceived public virtual void onMessageAppReceived(char const * msg, size_t msg_size) {} Agora internal test only