static void initialize ( std :: string apiKey , std :: string secretKey );
Initializes the singleton 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
apiKey - The Application key given when the application was created.
secretKey - The secret key corresponding to the application key given when the application was created.
Returns
void
Marmalade Only Call this function at least once in your game loop if you have set
polling mode to true. By, default polling mode is set to true. This
function will check if there’s any update from the AppWarp server.
Parameters
Returns
void
void connect ( std :: string 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. The result of the operation is provided in the
onConnectDone callback of the
ConnectionRequestListener.
Parameters
username - Username of the player
Returns
void
Disconnects the connection with the AppWarp server. The result for this
request will be provided in the onDisConnectDone callback of the
ConnectionRequestListener.
Parameters
Returns
void
Initializes the UDP handshake with the AppWarp server. The result for this
request will be provided in the onInitUDPDone callback of the
ConnectionRequestListener.
Parameters
Returns
void
Sends a join lobby request to the server. Result of the request is provided in the onJoinLobbyDone callback of the registered
LobbyRequestListener objects.
Parameters
Returns
void
Sends a leave lobby request to the server. Result of the request is provided in the onLeaveLobbyDone callback of the registered
LobbyRequestListener objects.
Parameters
Returns
void
Sends a subscribe lobby request to the server. Result of the request is
provided in the onSubscribeLobbyDone callback of the registered
LobbyRequestListener objects. 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
NotifyListener objects.
Parameters
Returns
void
void unsubscribe Lobby ();
Sends a unsubscribe lobby request to the server. Result of the request
is provided in the onUnsubscribeLobbyDone callback of the
LobbyRequestListener.
Parameters
Returns
void
void join Room ( std :: string roomId );
Sends a join room request to the server. Result of the request is provided in the onJoinRoomDone callback of the registered
RoomRequestListener objects. 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
Returns
void
void join Room With NUser ( int userCount );
Deprecated Sends a join room request to the server with the condition that the room
must have at least the given number of users. Result of the request is
provided in the onJoinRoomDone callback of the registered
RoomRequestListener. This is useful is supporting quick play modes.
Parameters
userCount- number of users in room to be joined
Returns
void
void joinRoomInUserRange ( int minJoinedUsers , int maxJoinedUsers , bool maxPreferred );
sends a join room request to the server for any room that currently has
joined users in the range given. maxPreferred indicates the preference
in the case that multiple rooms with the desired params are found. The
result of the request is provided in the onJoinRoomDone callback of the
registered
RoomRequestListener. This is useful is supporting quick play modes.
Parameters
userCount- number of users in room to be joined
Returns
void
Join Room With Properties
void joinRoomWithProperties( std :: map < std :: string , std :: string > 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. Result of the request is provided in the
onJoinRoomDone callback of the registered
RoomRequestListener.
Parameters
tableProperties- properties of the room to be joined
Returns
void
void leaveRoom ( std :: string roomId );
Sends a leave room request to the server. Result of the request is provided in the onLeaveRoomDone callback of the registered
RoomRequestListener.
Parameters
roomId - Id of the room to be left
Returns
void
void createRoom ( std :: string name , std :: string owner , int maxUsers , std :: map < std :: string , std :: string > tableProperties );
Sends a create room request to the server with the given meta data.
Result of the request is provided in the onCreateRoomDone callback of
the registered
ZoneRequestListener objects. 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 )
Returns
void
void deleteRoom ( std :: tring roomId );
Sends a delete room request to the server. Result of the request is provided in the onDeleteRoomDone callback of the registered
ZoneRequestListener objects. 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
Returns
void
void subscribeRoom ( std :: string roomId );
Sends a subscribe room request to the server. Result of the request is
provided in the onSubscribeRoomDone callback of the registered
RoomRequestListener objects. 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
NotifyListener objects.
Parameters
roomId - Id of the room to be subscribed
Returns
‘void’
void unsubscribeRoom ( std :: string roomId );
Sends a unsubscribe room request to the server. Result of the request is
provided in the onUnSubscribeRoomDone callback of the registered
RoomRequestListener objects.
Parameters
roomId - Id of the room to be subscribed
Returns
void
void sendChat ( std :: string message );
Sends a chat message to the room (or lobby) in which the user is
currently joined. Result of the request is provided in the
onSendChatDone callback of the registered
ChatRequestListener objects. All users who are subscribed to the location in which the
message is sent will get a onChatReceived event on their registered
NotifyListener objects.
Parameters
message - message to be send
Returns
void
void sendPrivateChat ( std :: string toUser , std :: string message )
Sends a private message to the given user if its online. Result of
the request is provided in the onSendPrivateChatDone callback of the
registered ChatRequestListener objects. 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
NotifyListener objects.
Parameters
toUser - the recipient of the private chat
message - message to be send
Returns
void
void sendUpdate ( byte * update , int updateLength );
Sends a byte array update message to room in which the user is currently
joined. Result of the request is provided in the onSendUpdateDone
callback of the registered
UpdateRequestListener objects. All users who are subscribed to the room in which the update
is sent will get a onUpdatePeersReceived event on their registered
NotifyListener 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. This API also has a
UDP option as well which is called sendUDPUpdate (onSendUpdateDone result is not provided in this case). It can only be used if the application has completed the
initUDP handshake successfully with the 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 and location with respect to the cloud server.
Parameters
update - binary data to be send
Returns
void
void getLiveRoomInfo ( std :: string roomId );
Retrieves the live information of the given room from the server. Result
is provided in the onGetLiveRoomInfoDone callback of the registered
RoomRequestListener objects. 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
Returns
void
void getLiveUserInfo ( std :: string username );
Retrieves the live information of the user from the server. Result is
provided in the onGetLiveUserInfo callback of the registered
ZoneRequestListener objects. 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
Returns
void
void getLiveLobbyInfo ();
Retrieves live information of the lobby from the server. Result is
provided in the onGetLiveLobbyInfo callback of the registered
LobbyRequestListener objects. The information returned includes the names of the users who are currently joined in the lobby.
Parameters
Returns
void
void setCustomUserData ( std :: string userName , std :: string customData );
Updates the custom data associated with the given user on the server (if
the given user is online). Result is provided in the
onSetCustomUserDataDone callback of the registered
ZoneRequestListener objects. 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
Returns
void
Updates the custom data associated with the given room on the server.
The result is provided in the onSetCustomRoomDataDone callback of the
registered RoomRequestListener objects. 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.
void SetCustomRoomData ( std :: string roomId , std :: string customRoomData )
Parameters
roomId - Id of the room
customRoomData - custom data that will be set for the room
Returns
void
void updateRoomProperties ( std :: string roomID , std :: map < std :: string , std :: string > tableProperties , std :: vector < std :: string > removeArray );
Updates the properties associated with the given room on the server.
Result is provided in the onUpdatePropertyDone callback of the
registered
RoomRequestListener objects. 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. This request (if successful) will also
result in an onUserChangeRoomProperty notification on the registered
NotifyListener 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
Returns
void
void lockProperties ( std :: map < std :: string , std :: string > properties );
Lock the properties associated with the joined room on the server for
requested user. Result is provided in the onLockPropertyDone callback
of the registered RoomRequestListener objects. 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
onUserChangeRoomProperty notification on the registered NotifyListener objects to be triggered for all subscribed users of the room.
Parameters
properties - properties and their values to be locked
Returns
void
void unlockProperties ( std :: vector < std :: string > properties );
Unlock the properties associated with the joined room on the server
for requested user. Result is provided in the onUnlockPropertyDone
callback of the registered RoomRequestListener objects. 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 onUserChangeRoomProperty
notification on the registered NotifyListener objects to be triggered for all subscribed users of the room.
Parameters
properties - vector of properties to be unlocked
Returns
void
Retrieves usernames of all the users connected (online) to the server.
Result is provided in the onGetOnlineUsers callback of the registered
ZoneRequestListener objects.
Parameters
Returns
void
Retrieves the room ids of all the rooms on the server. Result is provided in the onGetAllRoomsDone callback of the registered
ZoneRequestListener objects. To get a filtered list of rooms, use the
GetRoomWithNUser or
GetRoomWithProperties APIs.
Parameters
Returns
void
void getRoomWithNUser ( int userCount );
Deprecated Retrieves information of the rooms that contain at least
n users in them. Result is provided in the onGetMatchedRoomsDone callback of the registered
ZoneRequestListener objects. This is useful in building a filtered list of rooms.
Parameters
userCount- number of users in room to be joined
Returns
void
void getRoomsInUserRange ( int minJoinedUsers , int maxJoinedUsers );
Retrieves information of the rooms that contain currently have joined
users in the range given. Result is provided in the
onGetMatchedRoomsDone callback of the registered
ZoneRequestListener objects. This is useful in building a filtered list of rooms.
Parameters
minJoinedUsers- minimum number of users in room to be joined
maxJoinedUsers- maximum number of users in room to be joined
Returns
void
void getRoomWithProperties ( std :: map < std :: string , std :: string > properties );
Retrieves information of the room that contain properties which match
with the given properties. Result is provided in the
onGetMatchedRoomsDone callback of the registered
ZoneRequestListener objects. This is useful in building a filtered list of rooms.
Parameters
properties- properties of the room to be joined
Returns
void
Set Zone Request Listener
void setZoneRequestListener ( ZoneRequestListener * listener );
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 zone level requests such as create/delete room or live user info
requests. The object must implement the
ZoneRequestListener interface.
Parameters
listener - method for listening to the request
Returns
void
Set Room Request Listener
void setRoomRequestListener ( RoomRequestListener * listener );
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 requests pertaining to a room. The object must implement the
RoomRequestListener interface.
Parameters
listener - method for listening to the request
Returns
void
Set Lobby Request Listener
void setLobbyRequestListener ( LobbyRequestListener * listener );
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 lobby level request. The object must implement the
LobbyRequestListener interface.
Parameters
listener - method for listening to the request
Returns
void
Set Notification Listener
public void setNotificationListener ( NotifyListener * listener );
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). The object must
implement the
NotifyListener interface.
Parameters
listener - method for listening to the request
Returns
void
Set Connection Request Listener
void addConnectionRequestListener ( ConnectionRequestListener * listener )
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 Connect and Disconnect APIs. The object must implement the
ConnectionRequestListener interface.
Parameters
listener - method for listening to the request
Returns
void
Set Update Request Listener
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 a SendUpdatePeers request. The object must implement the UpdateRequestListener interface.
void AddUpdateRequestListener ( UpdateRequestListener * listener )
Parameters
listener - listener object
Returns
void
Set Chat Request Listener
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 a SendChat request. The object must implement the ChatRequestListener interface.
public void AddChatRequestListener ( ChatRequestListener * listener )
Parameters
listener - listener object
Returns
void
Sends a start game request to the server. Result of the request is provided in the onGameStarted callback of the TurnBasedRoomListener.
Returns
void
Sends a stop game request to the server. Result of the request is provided in the onGameStopped callback of the TurnBasedRoomListener.
Returns
void
Sends a get move history request to the server. Result of the request is provided in the onGetMoveHistoryDone callback of the TurnBasedRoomListener.
Returns
void
Sends a create turn based room request to the server with the given meta data. Result of the request is provided in the onCreateRoomDone callback of the registered ZoneRequestListener objects. 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.
public void createTurnRoom ( String name , String owner , int maxUsers , std::map < std::string , std::string > tableProperties , int turnTime )
Parameters
name - name of the room
owner - owner of the room ( behavior and usage of this meta property is up to the developer )
maxUsers - number of maximum users allowed in the room
tableProperties - properties of room ( can be null )
turnTime - the time ( in seconds ) allowed for a user to complete its turn and send a move .
Returns
void
Sends a move to the server for the joined turn based room.Result of the request is provided in the onSendMoveDone callback of the registered TurnBasedRoomListener objects. If the joined user is not a turn based room or if its not the users turn, this request will fail. If successful, this will result in onMoveCompleted notification for all the subscribed users on the registered NotifyListener objects.
public void sendMove ( std::string moveData )
Parameters
moveData - any meta data associated with the move
Returns
void
public void setRecoveryAllowance ( int maxRecoveryTime )
Sets the time allowed to 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
maxRecoveryTime - time - the time (in seconds) allowed to the client to recover from intermittent connection loss
Returns
void
public void 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
Returns
void
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.
public void setGeo(std::string _geo)
Parameters
_geo - server location. For e.g. US, EU, JAPAN
Returns
void
