corona-api-reference

Dev Center
Corona Client APIs Corona Client Notification Listeners Corona Client Event Result Codes
AppWarp S2 Corona API Guide

Corona Client APIs

initialize
Top
initialize ( appKey ,s2Address )
Initializes the singleton instance of WarpClient with the appKey of the zone and the IP address of the AppWarp S2 server.

Parameters

appKey - The  Application  key  of the zone its created from the admin dashboard. 
s2Address - The IP address of the server where the AppWarp S2 zone is hosted.
connectWithUserName
Top
 connectWithUserName ( username, s2Address )
Sets up an authenticated session with the Application zone on the server specified when the singleton was initialized. The username passed in this method must be unique across all other concurrently connected users. If two users with the same name try to connect at the same time, then the first one will win and the seconds one will get an auth error.

Parameters

username - Username of the player

authData - custom data for validation by the zone adaptor on the server

The result of the operation is provided in the registered “onConnectDone” request listener defined as 

onConnectDone (resultCode )
disconnect
Top
 disconnect ()
Disconnects the connection with the AppWarp server.

Parameters

The result of the operation is provided in the registered “onDisconnectDone” request listener defined as 

onDisconnectDone (resultCode )
joinLobby
Top
 joinLobby ()
Sends a join lobby request to the server.

Parameters

Result of the request is provided in the “onJoinLobbyDone” callback of the registered RequestListener defined as 

onJoinLobbyDone (resultCode )
leaveLobby
Top
 leaveLobby ()
Sends a leave lobby request to the server.

Parameters

Result of the request is provided in the “onLeaveLobbyDone” callback of the registered RequestListener defined as 

onLeaveLobbyDone (resultCode )
subscribeLobby
Top
 subscribeLobby ()
Sends a subscribe lobby request to the server. Users which have subscribed to the lobby receive chat events from other users in the lobby as well as join/leave notifications about all players to and fro the lobby and all the rooms. In addition, lobby subscribers get notifications when a new room is created or deleted. All these notification events are given in the registered notificationlisteners.

Parameters

Result of the request is provided in the “onSubscribeLobbyDone” callback of the registered RequestListener defined as 

onSubscribeLobbyDone (resultCode )
unsubscribeLobby
Top
 unsubscribeLobby ()
Sends a unsubscribe lobby request to the server.

Parameters

Result of the request is provided in the “onUnsubscribeLobbyDone” callback of the registered RequestListener defined as 

onUnsubscribeLobbyDone (resultCode )
joinRoom
Top
 joinRoom ( roomId )
Sends a join room request to the server. A user can only be joined in one location (room or lobby) at a time. If a user joins a room, it will automatically be removed from its current location.

Parameters

roomId - Id of the room to be joined

Result of the request is provided in the “onJoinRoomDone” callback of the registered RequestListener defined as 

onJoinRoomDone (resultCode , roomid )
joinRoomInRange
Top
 joinRoomInRange ( minUesrs ,maxUesrs ,maxPreferred )
Sends a join room request to the server with the condition that the room must have at least minUsers and at Most maxUsers. This is useful is supporting quick play modes.

Parameters

minUsers- number of minimum users in room to be joined

maxUsers- number of maximum users in room to be joined

maxPreferred- flag to specify search priority for room to be joined

Result of the request is provided in the “onJoinRoomDone” callback of the registered RequestListener defined as 

onJoinRoomDone (resultCode , roomid )
joinRoomWithProperties
Top
 joinRoomWithProperties ( tableProperties )
Sends a join room request to the server with the condition that the room must have a matching set of property value pairs associated with it. This is useful in match making.

Parameters

tableProperties- properties of the room to be joined

Result of the request is provided in the “onJoinRoomDone” callback of the registered RequestListener defined as 

onJoinRoomDone (resultCode , roomid )
sendMove
Top
 sendMove( moveData )
Sends a move message to the turn based room in which the user is currently joined. All users who are subscribed to the room will get a “onMoveCompleted” event on their registered notificationlisteners objects.

Parameters

moveData - data associated with the move

Result of the request is provided in the “onSendMoveDone” callback of the registered RequestListener defined as 

onSendMovedone (resultCode )
leaveRoom
Top
 leaveRoom ( roomId )
Sends a leave room request to the server.

Parameters

roomId - Id of the room to be left

Result of the request is provided in the “onLeaveRoomDone” callback of the registered RequestListener defined as 

onLeaveRoomDone (resultCode , roomid )
createRoom
Top
 createRoom ( name ,owner ,maxUsers ,tableProperties )
Sends a create room request to the server with the given meta data. If successful, this will create a dynamic room at the server. These rooms lifetime is limited till the time users are inside it. Read more about Rooms here.

Parameters

name - name of the room

owner - administrator of the room

maxUsers - number of maximum users allowed in the room

tableProperties - properties of room for matchmaking (pass null if not required )

Result of the request is provided in the “onCreateRoomDone” callback of the registered RequestListener defined as 

onCreateRoomDone (resultCode , roomid , name )
createTurnRoom
Top
 createTurnRoom ( name ,owner ,maxUsers ,tableProperties, turnTime)
Sends a create turn room request to the server with the given meta data and turn time. If successful, this will create a dynamic turn based room at the server. These rooms lifetime is limited till the time users are inside it. Read more about Rooms here.

Parameters

name - name of the room

owner - administrator of the room

maxUsers - number of maximum users allowed in the room

tableProperties - properties of room for matchmaking (pass null if not required )

turnTime - the time given for each turn

Result of the request is provided in the “onCreateRoomDone” callback of the registered RequestListener defined as 

onCreateRoomDone (resultCode , roomid , name )
deleteRoom
Top
 deleteRoom ( roomId )
Sends a delete room request to the server. Only dynamic rooms can be deleted through this API. Static rooms (created from AppHQ) can not be deleted through this. Read more about Rooms here.

Parameters

roomId - Id of the room to be deleted

Result of the request is provided in the “onDeleteRoomDone” callback of the registered RequestListener defined as 

onDeleteRoomDone (resultCode , roomid , name )
subscribeRoom
Top
 subscribeRoom ( roomId )
Sends a subscribe room request to the server. Once subscribed, the client will receive all notifications from the room such as chat, update and property change events. In addition the client will also receive notifications when a user joins or leaves the subscribed room. These notifications are given in the registered notificationlisteners objects.

Parameters

roomId - Id of the room to be subscribed

Result of the request is provided in the “onSubscribeRoomDone” callback of the registered RequestListener defined as 

onSubscribeRoomDone (resultCode , roomid )
unsubscribeRoom
Top
 unsubscribeRoom ( roomId )
Sends a unsubscribe room request to the server.

Parameters

roomId - Id of the room to be un-subscribed

Result of the request is provided in the “onUnsubscribeRoomDone” callback of the registered RequestListener defined as 

onUnsubscribeRoomDone (resultCode , roomid )
sendChat
Top
 sendChat ( message )
Sends a chat message to the room (or lobby) in which the user is currently joined. All users who are subscribed to the location in which the message is sent will get a “onChatReceived” event on their registered notificationlisteners objects.

Parameters

message - message to be send

Result of the request is provided in the “onSendChatDone” callback of the registered RequestListener defined as 

onSendChatDone (resultCode )
SendPrivateChat
Top

Sends a private message to the given user if its online. The sender and receiver don’t need to be in the same room or lobby for the private message to be delivered. This is useful in building invite/challenge friend like scenarios. If successful, the receiver will get a “onPrivateChatReceived” event on its registered notificationlisteners objects.

  public void sendPrivateChat (username , message )

Parameters

username - recipient of the message

message - message to be send

Result of the request is provided in the “onSendPrivateChatDone” callback of the registered RequestListener defined as 

onSendPrivateChatDone (resultCode )
sendUpdatePeers
Top
 sendUpdatePeers ( update )
Sends a byte array update message to room in which the user is currently joined. All users who are subscribed to the room in which the update is sent will get a “onUpdatePeersReceived” event on their registered notificationlisteners objects. This is useful if developers want to send their own binary encoded data across and is useful in minimizing the payload exchanged between the clients and AppWarp cloud server. The size of each message should be limited to 1000 bytes. The frequency at which these messages can be processed is not restricted by the server. However, the latency involved is largely determined by the client’s bandwidth.

Parameters

update - binary data to be send

Result of the request is provided in the “onSendUpdatePeersDone” callback of the registered RequestListener defined as 

onSendUpdatePeersDone (resultCode )
getLiveRoomInfo
Top
 getLiveRoomInfo ( roomId )
Retrieves the live information of the given room from the server. The information includes the names of the currently joined users, the rooms properties and any associated customData. This is useful in getting a snapshot of a rooms state.

Parameters

roomId - Id of the room

Result of the request is provided in the “onGetLiveRoomInfoDone” callback of the registered RequestListener defined as 

onGetLiveRoomInfoDone (resultCode , roomTable )

The roomTable contains the following information fields

  • id : id of the room whose information this table contains
  • name: name of the room specified while creating
  • maxUsers: maximum number of users allowed in the room
  • owner: owner of the room specified while creating
  • customData: customData associated with the room
  • propertyTable: properties of the room set while creating or through the updateRoomProperties Api
  • lockTable: table containing the keys that have been locked and the corresponding lock owners.
getLiveUserInfo
Top
 getLiveUserInfo ( username )

Retrieves the live information of the user from the server. The information (if user is online) includes the current location of the user and any associated custom data. It is useful in building scenarios where you want to find if a users friends are online or not and then join their room if found online.

Parameters

username - user who's information is requested

Result of the request is provided in the “onGetLiveUserInfoDone” callback of the registered RequestListener defined as 

onGetLiveUserInfoDone (resultCode , name , customData , locid , isLobby )
getMoveHistory
Top
 getMoveHistory ()

Sends a move history fetch request to the turn based room in which the user is currently joined. If successful, the event will also contain an array (historyTable) of the last (upto 5) moves in the room.

Parameters

Result of the request is provided in the “onGetMoveHistoryDone” callback of the registered RequestListener defined as 

onGetMoveHistoryDone(resultCode , historyTable )
getLiveLobbyInfo
Top
 getLiveLobbyInfo ()

Retrieves live information of the lobby from the server. The information returned includes the names of the users who are currently joined in the lobby.

Parameters

Result of the request is provided in the “onGetLiveLobbyInfoDone” callback of the registered RequestListener defined as 

onGetLiveLobbyInfoDone (resultCode , lobbyTable )
setCustomUserData
Top
 setCustomUserData ( userName ,customData )

Updates the custom data associated with the given user on the server (if the given user is online). It can be useful in setting status messages or avatar url’s etc for online users.

Parameters

userName - user for whom custom data has to be update
customData - custom data that will be set for the user

Result of the request is provided in the “onSetCustomUserDataDone” callback of the registered RequestListener defined as 

onSetCustomUserDataDone (resultCode , name , custom , locid , isLobby )
setCustomRoomData
Top

Updates the custom data associated with the given room on the server. It is recommended you use the room’s properties where ever possible. Use this when you need to associate data with a room which can not be represented as key value pairs.

SetCustomRoomData (roomId , customRoomData )

Parameters

roomId - Id of the room
customRoomData - custom data that will be set for the room

Result of the request is provided in the “onSetCustomRoomDataDone” callback of the registered RequestListener defined as 

 onSetCustomRoomDataDone (resultCode , roomTable )
updateRoomProperties
Top
 updateRoomProperties ( roomID ,tableProperties ,removeArray )

Updates the properties associated with the given room on the server. Properties which are not found on the server, will be added while properties which are already present will simply be updated with the new values. You can also specify the list of properties that you want to remove from the remove. Update property will fail if any other user has lock on same property that you are going to update or remove. This request (if successful) will also result in an “onUserChangedRoomProperty” notification on the registered notificationlisteners objects to be triggered for all subscribed users of the room.

Parameters

roomId - Id of the room
tableProperties - properties that will be set for the room
removeArray - properties that will be removed for the room

Result of the request is provided in the “onUpdateRoomProperties” callback of the registered RequestListener defined as 

 onUpdateRoomProperties (resultCode , roomTable )
lockProperties
Top
 lockProperties ( tableProperties )
Lock the properties associated with the joined room on the server for requested user. Lock properties will fail if any other user has lock on same property, otherwise property will be added in lockTable with owner name. This request (if successful) will also result in an “onUserChangedRoomProperty” notification on the registered notificationlisteners objects to be triggered for all subscribed users of the room.

Parameters

lockProperties - properties to be lock for the room

Result of the request is provided in the “onLockPropertiesDone” callback of the registered RequestListener defined as 

 onLockPropertiesDone (resultCode )
unlockProperties
Top
 lockProperties ( unlockPropertiesArray )
Unlock the properties associated with the joined room on the server for requested user. Unlock properties will fail if any other user has lock on same property, otherwise property will be removed from lock table. This request (if successful) will also result in an “onUserChangedRoomProperty” notification on the registered notificationlisteners objects to be triggered for all subscribed users of the room.

Parameters

unlockProperties - properties to be unlock for the room

Result of the request is provided in the “onUnlockPropertiesDone” callback of the registered RequestListener defined as 

 onUnlockPropertiesDone (resultCode )
getOnlineUsers
Top
  public voidgetOnlineUsers ()

Retrieves usernames of all the users connected (online) to the server.

Parameters

Result of the request is provided in the “onGetOnlineUsersDone” callback of the registered RequestListener defined as 

onGetOnlineUsersDone (resultCode , usersTable )
getAllRooms
Top
  public voidgetAllRooms ()

Retrieves the room ids of all the rooms on the server. To get a filtered list of rooms, use the getRoomsInRange or getRoomsWithProperties APIs.

Parameters

Result of the request is provided in the “onGetAllRoomsDone” callback of the registered RequestListener defined as 

onGetAllRoomsDone (resultCode , roomsTable )
getRoomsInRange
Top
 getRoomsInRange ( minUsers ,maxUsers )

Retrieves information of the rooms that contain at least minUsers and at most maxUsers in them. This is useful in building a filtered list of rooms.

Parameters

minUsers- number of minimun users in room to be joined

maxUsers- number of maximum users in room to be joined

Result of the request is provided in the “onGetMatchedRoomsDone” callback of the registered RequestListener defined as 

onGetMatchedRoomsDone (resultCode , roomsTable )
startGame
Top
 startGame()

Sends a start game request to the turn based room in which the user is currently joined. If successful, all users who are subscribed to the room will get a “onGameStarted” event on their registered notificationlisteners objects.

Parameters

Result of the request is provided in the “onStartGameDone” callback of the registered RequestListener defined as 

onStartGameDone(resultCode )
stopGame
Top
 stopGame()

Sends a stop game request to the turn based room in which the user is currently joined. If successful, all users who are subscribed to the room will get a “onGameStopped” event on their registered notificationlisteners objects.

Parameters

Result of the request is provided in the “onStopGameDone” callback of the registered RequestListener defined as 

onStopGameDone(resultCode )
getRoomsWithProperties
Top
 getRoomsWithProperties ( properties )

Retrieves information of the room that contain properties which match with the given properties. This is useful in building a filtered list of rooms.

Parameters

properties- properties of the room to be joined

Result of the request is provided in the “onGetMatchedRoomsDone” callback of the registered RequestListener defined as 

onGetMatchedRoomsDone (resultCode , roomsTable )