Objective-C Client APIs
- initWarp
- setRecoveryAllowance
- recoverConnection
- connectWithUserName
- initUDP
- disconnect
- joinLobby
- leaveLobby
- subscribeLobby
- unsubscribeLobby
- joinRoom
- joinRoomWithNUser
- joinRoomInRange
- joinRoomWithProperties
- leaveRoom
- createRoom
- createTurnRoom
- sendMove
- deleteRoom
- subscribeRoom
- unsubscribeRoom
- sendChat
- sendPrivateChat
- sendUpdatePeers
- getLiveRoomInfo
- getLiveUserInfo
- getLiveLobbyInfo
- setCustomUserData
- setCustomRoomData
- getOnlineUsers
- getAllRooms
- getRoomWithNUser
- getRoomWithProperties
- getRoomInRange
- updateRoom
- lockRoomProperties
- unlockRoomProperties
- startGame
- stopGame
- getMoveHistory
- addConnectionRequestListener
- addZoneRequestListener
- addRoomRequestListener
- addLobbyRequestListener
- addNotificationListener
- addUpdateRequestListener
- addChatRequestListener
- addTurnBasedRoomListener
- removeConnectionRequestListener
- removeZoneRequestListener
- removeLobbyRequestListener
- removeChatRequestListener
- removeUpdateRequestListener
- removeRoomRequestListener
- removeNotificationListener
- removeTurnBasedRoomListener
- setGeo
- getUserStatus
- getOnlineUsersCount
- getAllRoomsCount
- joinAndSubscribeRoom
- leaveAndUnsubscribeRoom
- getRoomInRangeWithProperties
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.
+(void)initWarp:(NSString *)apiKey secretKey:(NSString *)secretKey
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
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.
-(void)setRecoveryAllowance:(int) maxRecoveryTime
Parameters
maxRecoveryTime - time - the time (in seconds) allowed to the client to recover from intermittent connection loss
Returns
void
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).
-(void)recoverConnection
Parameters
Returns
void
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 first one will win and the second one will get an error. The username string parameter length must be more than 0 and less than 25. Also it shouldn’t contain the following characters “, ; / \”. The result of the operation is provided in the onConnectDone callback of the ConnectionRequestListener.
- ( void ) connectWithUserName : ( NSString * ) userName
Parameters
username - name of the player
Returns
void
This API checks if device has a full duplex UDP connection or not with the AppWarp server. Incoming UDP Traffic may be blocked if the client is behind certain types of NATs(Network address translation). It determines the connectivity by performing a 3-way handshake with the server over UDP and provides the result in onInitUDPDone callbacks of the ConnectionRequestListener. In case of lack of connectivity, the server will fall back to sending updates over TCP for the client. Sending can continue over UDP irrespective.
ResultCode:
1. SUCCESS : If the client has full duplex UDP connectivity.
2. BAD_REQUEST : If the client is unable to receive UDP traffic from the server.
-(void)initUDP
Parameters
Returns
void
Disconnects the connection with the WARP server. The result for this request will be provided in the onDisconnectDone callback of the ConnectionRequestListener.
- ( void ) disconnect
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.
- ( void ) joinLobby
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.
- ( void ) leaveLobby
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.
- ( void ) subscribeLobby
Parameters
Returns
void
Sends a unsubscribe lobby request to the server. Result of the request is provided in the onUnsubscribeLobbyDone callback of the registered LobbyRequestListener objects.
- ( void ) unsubscribeLobby
Parameters
Returns
void
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.
- ( void ) joinRoom : ( NSString * ) roomId
Parameters
roomId - Id of the room to be joined
Returns
void
- ( void ) joinRoomWithNUser : ( int ) userCount
Parameters
userCount- number of users in room to be joined
Returns
void
- ( void ) joinRoomInRangeBetweenMinUsers : ( int ) minUsers andMaxUsers : ( int ) maxUsers maxPrefered : ( BOOL ) maxPrefered
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
Returns
void
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.
- ( void ) joinRoomWithProperties : ( NSDictionary * ) properties
Parameters
properties- properties of the room to be joined
Returns
void
Sends a leave room request to the server. Result of the request is provided in the onLeaveRoomDone callback of the registered RoomRequestListener.
- ( void ) leaveRoom : ( NSString * ) roomId
Parameters
roomId - Id of the room to be left
Returns
void
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.
- ( void ) createRoomWithRoomName : ( NSString * ) roomName roomOwner : ( NSString * ) roomOwner properties : ( NSDictionary * ) properties maxUsers : ( int ) maxUsers
Parameters
roomName - name of the room roomOwner - owner of the room ( behavior and usage of this meta property is up to the developer ) properties - properties of room ( can be null ) maxUsers - number of maximum users allowed in the room
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.
-(void)createTurnRoomWithRoomName:(NSString*)roomName roomOwner:(NSString*)roomOwner properties:(NSDictionary*)properties maxUsers:(int)maxUsers turnExpiresIn:(int)time
Parameters
roomName - name of the room roomOwner - owner of the room ( behavior and usage of this meta property is up to the developer ) properties - properties of room ( can be null ) maxUsers - number of maximum users allowed in the room turnTime - the time ( in seconds ) allowed for a user to complete its turn and send a move .
Returns
void
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.
- ( void ) deleteRoom : ( NSString * ) roomId
Parameters
roomId - Id of the room to be deleted
Returns
void
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.
- ( void ) subscribeRoom : ( NSString * ) roomId
Parameters
roomId - Id of the room to be subscribed
Returns
Sends a unsubscribe room request to the server. Result of the request is provided in the onUnSubscribeRoomDone callback of the registered RoomRequestListener objects.
- ( void ) unsubscribeRoom : ( NSString * ) roomId
Parameters
roomId - Id of the room to be subscribed
Returns
void
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. The size of each chat message is limited to 500 bytes. All users who are subscribed to the location in which the message is sent will get a onChatReceived event on their registered NotifyListener objects.
- ( void ) sendChat : ( NSString * ) message
Parameters
message - message to be send
Returns
void
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.
- ( void ) sendPrivateChat : ( NSString * ) message toUser : ( NSString * ) userName
Parameters
username - recipient of the message
message - message to be send
Returns
void
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. The size of the byte array per API call is limited to 1000 bytes. 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. 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. The corresponding UDP flavor of this API is sendUdpUpdatePeers, 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.
- ( void ) sendUpdatePeers : ( NSData * ) update
Parameters
update - data of type NSData to be sent
Returns
void
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.
- ( void ) getLiveRoomInfo : ( NSString * ) roomId
Parameters
roomId - Id of the room
Returns
void
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.
- ( void ) getLiveUserInfo : ( NSString * ) username
Parameters
username - user who's information is requested
Returns
void
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.
- ( void ) getLiveLobbyInfo
Parameters
Returns
void
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.
- ( void ) setCustomUserData : ( NSString * ) username customData : ( NSString * ) customData
Parameters
userName - user for whom custom data has to be updated 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 : ( NSString * ) roomId customData : ( NSString * ) customData
Parameters
roomId - Id of the room customRoomData - custom data that will be set for the room
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.
- ( void ) getOnlineUsers
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.
- ( void ) getAllRooms
Parameters
Returns
void
- ( void ) getRoomWithNUser : ( int ) userCount
Parameters
userCount - number of users in room to be joined .
void
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.
- ( void ) getRoomWithProperties : ( NSDictionary * ) properties
Parameters
properties - properties of the room to be joined .
void
- ( void ) getRoomInRangeBetweenMinUser : ( int ) minUsers andMaxUser : ( int ) maxUsers
Parameters
minUsers- number of minimun users in room to be joined
maxUsers- number of maximum users in room to be joined
Returns
void
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.
- ( void ) updateRoom : ( NSString * ) roomID addProperties : ( NSDictionary * ) properties removeProperties : ( NSArray * ) propertiesKeyArray
Parameters
roomId - Id of the room properties - properties that will be set for the room propertiesKeyArray - properties that will be removed for the room
void
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 Connect and Disconnect APIs. The object must implement the ConnectionRequestListener interface.
- ( void ) addConnectionRequestListener : ( id ) connectionListener
Parameters
connectionListener - instance of ConnectionRequestListener for listening to the request
Returns
void
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 zone level requests such as create/delete room or live user info requests. The object must implement the ZoneRequestListener interface.
- ( void ) addZoneRequestListener : ( id ) zoneListener
Parameters
zoneListener - instance of ZoneListener for listening to the request
Returns
void
- ( void ) lockRoomProperties : ( NSDictionary * ) lockProperties
Parameters
lockProperties - properties to be lock for the room
Returns
void
- ( void ) unlockRoomProperties : ( NSArray * ) unlockProperties
Parameters
unlockProperties - properties to be unlock for the room
Returns
void
-(void)startGame
Parameters
Returns
void
-(void)stopGame
Parameters
Returns
void
-(void)getMoveHistory
Parameters
Returns
void
-(void) sendMove:(NSString*) moveData
Parameters
moveData - any meta data associated with the move.
Returns
void
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 requests pertaining to a room. The object must implement the RoomRequestListener interface.
- ( void ) addRoomRequestListener : ( id ) roomListener
Parameters
roomListener - instance of RoomListener for listening to the request
Returns
void
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 lobby level request. The object must implement the LobbyRequestListener interface.
- ( void ) addLobbyRequestListener : ( id ) lobbyListener
Parameters
lobbyListener - instance of LobbyListener for listening to the request
Returns
void
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). The object must implement the NotifyListener interface.
- ( void ) addNotificationListener : ( id ) notifyListener
Parameters
notifyListener - instance of NotificationListener for listening to the request
Returns
void
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 a SendUpdatePeers request. The object must implement the UpdateRequestListener interface.
- ( void ) addUpdateRequestListener : ( id ) updateListener
Parameters
updateListener - listener object
Returns
void
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 a SendChat request. The object must implement the ChatRequestListener interface.
- ( void ) addChatRequestListener : ( id ) chatListener
Parameters
chatListener - listener object
Returns
void
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 a sendMove request. The object must implement the TurnBasedRoomListener interface.
-(void)addTurnBasedRoomListener:(id)turnBasedRoomListener
Parameters
turnBasedRoomListener - listener object
Returns
void
Removes your listener for connection requests
-(void)removeConnectionRequestListener:(id)conListener
Parameters
conListener - listener object
Returns
void
Removes your listener for zone requests
-(void)removeZoneRequestListener:(id)zoneListener
Parameters
zoneListener - listener object
Returns
void
Removes your listener for lobby requests
-(void)removeLobbyRequestListener:(id)lobbyListener
Parameters
lobbyListener - listener object
Returns
void
Removes your listener for chat requests
-(void)removeChatRequestListener:(id)chatListener
Parameters
chatListener - listener object
Returns
void
Removes your listener for update requests
-(void)removeUpdateRequestListener:(id)updateListener
Parameters
updateListener - listener object
Returns
void
Removes your listener for room requests
-(void)removeRoomRequestListener:(id)roomListener
Parameters
roomListener - listener object
Returns
void
Removes your listener for notifications
-(void)removeNotificationListener:(id)notificationListener
Parameters
notificationListener - listener object
Returns
void
Removes your listener for turn-based room requests
-(void)removeTurnBasedRoomListener:(id)roomListener
Parameters
roomListener - listener object
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.
-(void)setGeo:(NSString*)_geo
Parameters
geo - server location. For e.g. US, EU, JAPAN
Returns
void
Retrieves status of user via user name on the server. Result is provided in the onGetUserStatusDone callback of the registered ZoneRequestListener objects. This is useful to find either user is connected or not.
-(void)getUserStatus:(NSString*)userName;
Parameters
userName - Username of the player
Returns
void
Retrieves total number of users connected (online) to the server. Result is provided in the onGetOnlineUsersCountDone callback of the registered ZoneRequestListener objects.
-(void)getOnlineUsersCount;
Parameters
void
Returns
void
Retrieves total number of rooms on the server. Result is provided in the onGetAllRoomsCountDone callback of the registered ZoneRequestListener objects.
-(void)getAllRoomsCount;
Parameters
void
Returns
void
Sends a join and subscribe room request to the server. Result of the request is provided in the onJoinAndSubscribeRoomDone 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. 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.
-(void)joinAndSubscribeRoom:(NSString*)roomId;
Parameters
roomId - Id of the room to be subscribed
Returns
void
Sends a leave and unsubscribe room request to the server. Result of the request is provided in the onLeaveAndUnsubscribeRoomDone callback of the registered RoomRequestListener objects.
-(void)leaveAndUnsubscribeRoom:(NSString*)roomId;
Parameters
roomId - Id of the room to be subscribed
Returns
void
Retrieves information of the rooms that contain at least minUsers , at most maxUsers and set of property value pairs in them. Result is provided in the onGetMatchedRoomsDone callback of the registered ZoneRequestListener objects. This is useful in building a filtered list of rooms.
-(void)getRoomInRangeWithProperties:(NSDictionary*)properties minUser:(int)minUser maxUser:(int)maxUser maxPrefered:(BOOL)maxPrefered;
Parameters
properties- properties of the room to be joined
minUsers- number of minimun users in room to be joined
maxUsers- number of maximum users in room to be joined
maxPrefered- If true, joins the room having max users
Returns
void