function WarpClient .initialize(api, secret, host)
Initializes the instance of WarpClient with the developer credentials. This has to be called only once during the lifetime of the application. It is required before you can call any other API.
Parameters
api - The Application key given when the application was created .
secret - The secret key corresponding to the application key given when the application was created .
host - AppWarp Server IP Or Name.
function WarpClient .getSessionID()
It gives sessionId of the current established connection,otherwise returns zero.
Parameters None
function WarpClient .recoverConnection()
Attempts to recover from an intermittent connection error. If successful, the client will be placed in the same room as before the loss and all its subscriptions will be maintained. The other subscribed users of the room, will receive onUserResumed notification. This can only be called if an established session was lost due to a connectivity error and the client got onConnectDone with a recoverable connection error code. The connection must be restored within the recovery allowance period, after which the server considers the session to be over (non-recoverable).
Parameters None
recoverConnectionWithSessionID
function WarpClient .recoverConnectionWithSessionID(sessionID, username)
Attempts to recover from an intermittent connection error.Since this API requires sessionId so it has to be saved by the game on the last successful connection.The other subscribed users of the room, will receive onUserResumed notification.The connection must be restored within the recovery allowance period, after which the server considers the session to be over (non-recoverable).
Parameters
sessionID - sessionId of the last successful session
username- name of the player
function WarpClient .setRecoveryAllowance(time)
Sets the time allowed for the client to recover from an intermittent connection loss. This must be set before the initial connect API is called as that associates the value on the server for the given connection.
Parameters
time - the time (in seconds) allowed to the client to recover from intermittent connection loss
Sends a byte array update message to the recipient user. This is useful if developers want to send private data between the users. It is unreliable and may not work over cellular data connections – hence no result callback should be expected from it. The corresponding flavor of this API is sendPrivateUpdate which shows a similar behavior.
function WarpClient .sendUDPPrivateUpdate(username,message)
Parameters
username - recipient of the message
message - message to be sent
Sends a byte array update message to the recipient user. Remote user will get an onPrivateUpdateReceived event on their registered NotifyListener objects. This is useful if developers want to send private data between the users. The corresponding UDP flavor of this API is sendUDPPrivateUpdate, which is unreliable and may not work over cellular data connections – hence no result callback should be expected from it. The behavior is otherwise similar.
function WarpClient .sendPrivateUpdate(username,message)
Parameters
username - recipient of the message
message - message to be sent
Result of the request is provided in the registered “onSendPrivateUpdateDone ” request listener defined as
onSendPrivateUpdateDone ( resultCode )
function WarpClient .sendUDPUpdatePeers(message)
Sends a byte array update message to the room to which the user is currently joined. 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 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. The size of the byte array must not exceed 1000. It is unreliable and may not work over cellular data connections – hence no result callback should be expected from it.The corresponding UDP flavor of this API is sendUpdatePeers which shows a similar behavior.
Parameters
message- binary data to be send
Result of the request is provided in the “onSendUDPUpdatePeersDone” callback of the registered RequestListener defined as
onSendUDPUpdatePeersDone (resultCode )
function WarpClient .initUDP()
If the user is connected, it sends an associated UDP Port message to the room (or lobby) to which the user is currently joined. It is unreliable and may not work over cellular data connections – hence no result callback should be expected from it.
Parameters None
The result of the operation is provided in the registered “onInitUDPDone” request listener defined as
onInitUDPDone ( resultCode )
When the onNextTurnRequest is sent by the server, it sends the next turn to the server for the joined turn based room.If the joined user is not in turn based room or if it’s not the user’s turn, this request will fail. If successful, this will result in onMoveCompleted notification for all the subscribed users on the registered
notificationlisteners objects.
Parameters
moveData - data associated with the next turn.
Result of the request is provided in the “onSetNextTurnDone” callback of the registered RequestListener defined as
onSetNextTurnDone ( resultCode )
function WarpClient .addRequestListener(request, listener)
Adds (registers) the given listener object to the list of objects on which callbacks will be invoked when a response from the server is received for the given request.
Parameters
request- the request on which the callback will be invoked.
listener- listener for the given request
function WarpClient .addNotificationListener(notification, listener)
Adds (registers) the given listener object to the list of objects on which callbacks will be invoked when a notification is received from the server from any subscribed location (room or lobby).
Parameters
notification - the notification on which the callback will be invoked.
listener- listener for the given notification
function WarpClient .resetRequestListener(request)
Sets the Request Listener for the corresponding request as nil.
Parameters
request- the request for which the Request Listener is to be reset.
resetNotificationListener
function WarpClient .resetNotificationListener(notification)
Sets the Notification Listener for the corresponding notification as nil.
Parameters
notification- the notification for which the Notification Listener is to be reset.
function WarpClient .connectWithUserName(username)
Sets up your connection with the AppWarp cloud server. 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 last one will win and the older one will get disconnected.
Parameters
username - Username of the player
The result of the operation is provided in the registered “onConnectDone” request listener defined as
onConnectDone ( resultCode )
function WarpClient .disconnect()
Disconnects the connection with the AppWarp server.
Parameters None
The result of the operation is provided in the registered “onDisconnectDone” request listener defined as
onDisconnectDone ( resultCode )
function WarpClient .joinLobby()
Sends a join lobby request to the server.
Parameters None
Result of the request is provided in the “onJoinLobbyDone” callback of the registered RequestListener defined as
onJoinLobbyDone (resultCode )
function WarpClient .leaveLobby()
Sends a leave lobby request to the server.
Parameters None
Result of the request is provided in the “onLeaveLobbyDone” callback of the registered RequestListener defined as
onLeaveLobbyDone (resultCode )
function WarpClient .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 None
Result of the request is provided in the “onSubscribeLobbyDone” callback of the registered RequestListener defined as
onSubscribeLobbyDone (resultCode )
function WarpClient .unsubscribeLobby()
Sends a unsubscribe lobby request to the server.
Parameters None
Result of the request is provided in the “onUnsubscribeLobbyDone” callback of the registered RequestListener defined as
onUnsubscribeLobbyDone (resultCode )
function WarpClient .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 )
function WarpClient .joinRoomInRange(minUsers, maxUsers, 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 )
function WarpClient .joinRoomWithProperties(matchProperties)
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
matchProperties- 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 )
function WarpClient .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 )
function WarpClient .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 )
function WarpClient .createRoom(name, owner, maxUsers, properties, cleanupTime)
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
properties - properties of room for matchmaking (pass null if not required )
cleanupTime - seconds after which the room is deleted if it remains empty (between 0 and 3600)
Result of the request is provided in the “onCreateRoomDone” callback of the registered RequestListener defined as
onCreateRoomDone (resultCode , roomid , name )
function WarpClient .createTurnRoom(name, owner, maxUsers, properties, turnTime, cleanupTime)
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
cleanupTime - seconds after which the room is deleted if it remains empty (between 0 and 3600)
Result of the request is provided in the “onCreateRoomDone” callback of the registered RequestListener defined as
onCreateRoomDone (resultCode , roomid , name )
function WarpClient .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 )
function WarpClient .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 )
function WarpClient .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 )
function WarpClient .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 )
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.
function WarpClient .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 )
function WarpClient .sendUpdatePeers(message)
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
message - binary data to be send
Result of the request is provided in the “onSendUpdatePeersDone” callback of the registered RequestListener defined as
onSendUpdatePeersDone (resultCode )
function WarpClient .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.
function WarpClient .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 )
function WarpClient .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 None
Result of the request is provided in the “onGetMoveHistoryDone” callback of the registered RequestListener defined as
onGetMoveHistoryDone ( resultCode , historyTable )
function WarpClient .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 None
Result of the request is provided in the “onGetLiveLobbyInfoDone” callback of the registered RequestListener defined as
onGetLiveLobbyInfoDone (resultCode , lobbyTable )
function WarpClient .setCustomUserData(username, data)
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
data- 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 )
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.
function WarpClient .setCustomRoomData(roomid, data)
Parameters
roomId - Id of the room
data- 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 )
function WarpClient .updateRoomProperties ( roomid, newProperties, removeProperties)
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
newProperties- properties that will be set for the room
removeProperties- properties that will be removed from the room
Result of the request is provided in the “onUpdateRoomProperties” callback of the registered RequestListener defined as
onUpdateRoomProperties ( resultCode , roomTable )
function WarpClient .lockProperties(lockPropertiesTable)
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
lockPropertiesTable - properties to be locked for the room
Result of the request is provided in the “onLockPropertiesDone” callback of the registered RequestListener defined as
onLockPropertiesDone (resultCode )
function WarpClient .unlockProperties(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
unlockPropertiesArray - list of keys to be unlocked for the user.
Result of the request is provided in the “onUnlockPropertiesDone” callback of the registered RequestListener defined as
onUnlockPropertiesDone ( resultCode )
function WarpClient .getOnlineUsers()
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 )
function WarpClient .getAllRooms()
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 )
function WarpClient .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 )
function WarpClient .startGame(isDefaultLogic,nextTurn)
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
isDefaultLogic - a true boolean value
nextTurn- an empty string for next turn
Result of the request is provided in the “onStartGameDone” callback of the registered RequestListener defined as
onStartGameDone ( resultCode )
function WarpClient .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 None
Result of the request is provided in the “onStopGameDone” callback of the registered RequestListener defined as
onStopGameDone ( resultCode )
function WarpClient .getRoomsWithProperties(matchProperties)
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
matchProperties- 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 )
setGeo allows you to connect to our cloud servers in locations other than the default location. This offers developers the choice to connect to the closest server depending on the client’s device location.
function WarpClient .setGeo(geo)
Parameters
geo - server location. For e.g. US, EU, JAPAN
Returns
void
function WarpClient .getOnlineUsersCount()
Retrieves total number of users connected (online) to the server.
Parameters None
Result of the request is provided in the “onGetOnlineUsersCountDone” callback of the registered RequestListener defined as
onGetOnlineUsersCountDone ( resultCode ,count)
function WarpClient .getAllRoomsCount()
Retrieves total number of rooms on the server.
Parameters None
Result of the request is provided in the “onGetAllRoomsCountDone” callback of the registered RequestListener defined as
onGetAllRoomsCountDone ( resultCode ,count)
function WarpClient .joinAndSubscribeRoom(roomid)
Sends a join and subscribe 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. 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 join and subscribed
Result of the request is provided in the “onJoinAndSubscribeRoomDone” callback of the registered RequestListener defined as
onJoinAndSubscribeRoomDone (resultCode , roomid )
Leave And Unsubscribe Room
function WarpClient .leaveAndUnsubscribeRoom(roomid)
Sends a leave and unsubscribe room request to the server.
Parameters
roomid - Id of the room to be subscribed
Result of the request is provided in the “onLeaveAndUnsubscribeRoomDone” callback of the registered RequestListener defined as
onLeaveAndUnsubscribeRoomDone (resultCode , roomid )
Get Room In Range With Properties
function WarpClient .getRoomInRangeWithProperties(minUsers,maxUser,matchProperties)
Retrieves information of the rooms that contain at least minUsers , at most maxUsers and set of property value pairs 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
matchProperties- 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 )
function WarpClient .getUserStatus(username)
Retrieves status of user via username on the server. This is useful to find either user is connected or not.
Parameters
username - Username of the player
The result of the operation is provided in the registered “onUserStatusDone” request listener defined as
onUserStatusDone ( resultCode , status , username)
