C API Reference

• WarpClient APIs
• WarpClient Events
• WarpClient Listeners
• WarpClient Event Result Codes

WarpClient APIs

• initialize
• connect
• disconnect
• joinLobby
• leaveLobby
• subscribeLobby
• unsubscribeLobby
• joinRoom
• joinRoomWithNUser
• joinRoomWithProperties
• leaveRoom
• createRoom
• deleteRoom
• subscribeRoom
• unsubscribeRoom
• sendChat
• sendUpdatePeers
• getLiveRoomInfo
• getLiveUserInfo
• getLiveLobbyInfo
• setCustomUserData
• updateRoomProperties
• getOnlineUsers
• getAllRooms
• getRoomWithNUser
• getRoomWithProperties
• addZoneRequestListener
• addRoomRequestListener
• addLobbyRequestListener
• addNotificationListener
• addConnectionRequestListener

###initialize

   static void initialize(std::string apiKey, std::string secretKey);

Initializes the singleton instance of WarpClient with the developer credentials

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

###connect

  void connect(std::string username);

Initiates your connection with the WARP server. The result of the operation is provided in the onConnectDone callback of the ConnectionListener.

Parameters

username - Username of the player

Returns

void

###disconnect

    void disconnect();

Disconnects the connection with the WARP server. The result for this request will be provided in the onDisconnectDone callback of the ConnectionListener

Parameters

Returns

void

###joinLobby

   void joinLobby();

Sends a join lobby request to the server. Result of the request is provided in the onJoinLobbyDone callback of the LobbyListener

Parameters

Returns

void

###leaveLobby

    void leaveLobby();

Sends a leave lobby request to the server. Result of the request is provided in the onLeaveLobbyDone callback of the LobbyListener

Parameters

Returns

void

###subscribeLobby

    void subscribeLobby();

Sends a subscribe lobby request to the server. Result of the request is provided in the onSubscribeLobbyDone callback of the LobbyListener

Parameters

Returns

void

###unsubscribeLobby

    void unsubscribeLobby();

Sends a unsubscribe lobby request to the server. Result of the request is provided in the onUnsubscribeLobbyDone callback of the LobbyListener

Parameters

Returns

void

###joinRoom

    void joinRoom(std::string roomId);

Sends a join room request to the server. Result of the request is provided in the onJoinRoomDone callback of the RoomListener

Parameters

roomId - Id of the room to be joined

Returns

void

###joinRoomWithNUser

    void joinRoomWithNUser(int userCount);

Sends a join room match making request to the server. Result of the request is provided in the onJoinRoomDone callback of the RoomListener

Parameters

userCount- number of users in room to be joined

Returns

void

###joinRoomWithProperties

    void joinRoomWithProperties(std::map<std::string,std::string> tableProperties);

Sends a join room match making request to the server. Result of the request is provided in the onJoinRoomDone callback of the RoomListener

Parameters

tableProperties- properties of the room to be joined

Returns

void

###leaveRoom

    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 RoomListener

Parameters

roomId - Id of the room to be left

Returns

void

###createRoom

    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 parameters. Result of the request is provided in the onCreateRoomDone callback of the ZoneListener.

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

###deleteRoom

    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 ZoneListener.

Parameters

roomId - Id of the room to be deleted

Returns

void

###subscribeRoom

    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 RoomListener.

Parameters

roomId - Id of the room to be subscribed

Returns

'void'

###unsubscribeRoom

    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 RoomListener.

Parameters

roomId - Id of the room to be subscribed

Returns

void

###sendChat

    void sendChat(std::string message);

Sends a chat message to room in which the user is currently joined. Result of the request is provided in the onSendChatDone callback of the ChatListener

Parameters

message - message to be send

Returns

void

###sendupdatePeers

    void sendUpdatePeers(byte* update, int updateLength);

Sends a custom update message to room in which the user is currently joined. Result of the request is provided in the onSendUpdateDone callback of the UpdateListener. 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

Returns

void

###getLiveRoomInfo

    void getLiveRoomInfo(std::string roomId);

Retrieves live information of the room from the server. Result is provided in the onGetLiveRoomInfo callback of the RoomListener.

Parameters

roomId - Id of the room

Returns

void

###getLiveUserInfo

    void getLiveUserInfo(std::string username);

Retrieves live information of the user from the server. Result is provided in the onGetLiveUserInfo callback of the ZoneListener.

Parameters

username - user who's information is requested

Returns

void

###getLiveLobbyInfo

    void getLiveLobbyInfo();

Retrieves live information of the lobby from the server. Result is provided in the onGetLiveLobbyInfo callback of the LobbyListener.

Parameters

Returns

void

###setCustomUserData

    void setCustomUserData(std::string userName, std::string customData);

Updates the custom data associated with the given user on the server. Result is provided in the onSetCustomUserDataDone callback of the ZoneListener.

Parameters

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

Returns

void

###updateRoomProperties

   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 RoomListener.

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

###getOnlineUsers

    void getOnlineUsers();

Retrieves usernames of all the users connected to the server. Result is provided in the onGetOnlineUsers callback of the ZoneListener.

Parameters

Returns

void

###getAllRooms

    void getAllRooms();

Retrieves room ids of all the live rooms on the server. Result is provided in the onGetAllRoomsDone callback of the ZoneListener.

Parameters

Returns

void

###getRoomWithNUser

    void getRoomWithNUser(int userCount);

Retrieves information of the room that contain n user in it from the server. Result is provided in the onGetMatchedRoomsDone callback of the ZoneListener.

Parameters

userCount- number of users in room to be joined

Returns

void

###getRoomWithProperties

    void getRoomWithProperties(std::map<std::string,std::string> properties);

Retrieves information of the room that contain specific properties from the server. Result is provided in the onGetMatchedRoomsDone callback of the ZoneListener.

Parameters

properties- properties of the room to be joined

Returns

void

###setZoneRequestListener

  void setZoneRequestListener(ZoneRequestListener *listener);

Set your listener object on which callbacks will be invoked when a response from the server is received for Zone level requests like create/deleteRoom, User requests etc.

Parameters

listener - method for listening to the request

Returns

void

###setRoomRequestListener

   void setRoomRequestListener(RoomRequestListener *listener);

Set your listener object on which callbacks will be invoked when a response from the server is received for Room requests like join/leaveRoom, subscribe/unsubscribeRoom and getLiveRoomInfo

Parameters

listener - method for listening to the request

Returns

void

###setLobbyRequestListener

void setLobbyRequestListener(LobbyRequestListener *listener);

Set your listener object on which callbacks will be invoked when a response from the server is received for Lobby requests like join/leaveLobby, subscribe/unsubscribeLobby and getLiveLobbyInfo

Parameters

listener - method for listening to the request

Returns

void

###setNotificationListener

  public void setNotificationListener(NotifyListener *listener);

add your listener object on which callbacks will be invoked when a notification is received from the server for any resource that has been subscribed to.

Parameters

listener - method for listening to the request

Returns

void

###setConnectionRequestListener

   void addConnectionRequestListener(ConnectionRequestListener *listener)

Set your listener object on which callbacks will be invoked when a response from the server is received for connect, joinZone and disconnect APIs.

Parameters

listener - method for listening to the request

Returns

void

WarpClient Events

• AllRoomsEvent
• AllUsersEvent
• ChatEvent
• ConnectEvent
• LiveRoomInfoEvent
• LiveUserInfoEvent
• LobbyEvent
• RoomEvent
• UpdateEvent
• MatchedRoomEvent

###AllRoomsEvent

This event is raised in response to the getAllRooms request. It is passed in the registered ZoneRequestListener's onGetAllRoomsDone request. It exposes the following properties

	struct liveresult_struct
	{
		int result;
		std::vector<std::string> list;
	};
	typedef liveresult_struct liveresult;

###AllUsersEvent

This event is raised in response to the getOnlineUsers request. It is passed in the registered ZoneRequestListener's onGetOnlineUsersDone method. It exposes the following properties

	struct liveresult_struct
	{
		int result;
		std::vector<std::string> list;
	};
	typedef liveresult_struct liveresult;

Represents an array of usernames for all the online users if the request is successful.

###ChatEvent

This event is raised when a chat notification is received from a subscribed location such as room or lobby. It is passed in registered NotifyListener's onChatReceived method. It exposes the following properties

	struct chat_struct
	{
		std::string chat;
		std::string sender;
		int locid;
		bool isLocationLobby;
		int result;
	};
	typedef chat_struct chat;

###ConnectEvent

This event is raised in response to a connect request. It is passed in the registered ConnectionRequestListener's onConnectDone method. It exposes the following properties

	int result

###LiveRoomInfoEvent

This event is raised in response to the getLiveRoomInfo or getLiveLobbyInfo request. It is passed in the registered RoomRequestListener's onGetLiveRoomInfoDone method and in the LobbyRequestListener's onGetLiveLobbyInfoDone method. It exposes the following properties

	struct liveroom_struct
	{
		room rm;
		std::string customData;
		std::vector<std::string> users;
		std::map<std::string, std::string> properties;
		int result;
	};
	typedef liveroom_struct liveroom;

###LiveUserInfoEvent

This event is raised in response to the getLiveUserInfo request. It is passed in the registered ZoneRequestListener's onGetLiverUserInfo request method. It exposes the following properties

	struct liveuser_struct
	{
		std::string name;
		std::string locationId;
		std::string customData;
		int result;
	};
	typedef liveuser_struct liveuser;

###LobbyEvent

This event is raised in response to requests for join/leave/subscribe/unsubscribe lobby. It is passed in the corresponding methods of the registered LobbyRequestListener. It exposes the following properties.

	struct lobby_struct
	{
		std::string lobbyid;
		std::string owner;
		int maxUsers;
		std::string name;
		bool isPrimary;
		int result;
	};
	typedef lobby_struct lobby; 

###RoomEvent

This event is raised in response to requests for join/leave/subscribe/unsubscribe room. It is passed in the corresponding methods of the registered RoomRequestListener. It exposes the following properties.

	struct room_struct
	{
		std::string roomId;
		std::string owner;
		int maxUsers;
		std::string name;
		int result;
	};
	typedef room_struct room; 

###UpdateEvent

This event is raised when a updatePeers notification is received from a subscribed location such as room or lobby. It is passed in registered NotifyListener's onUpdatePeersReceived method. It exposes the following properties

	AppWarp::byte update[]
	int len

###MatchedRoomEvent

This event is raised in response to requests for matchmaking request(getRoomwithNUsers/getRoomWithProperties). It is passed in the corresponding methods of the registered ZoneRequestListener. It exposes the following properties.

	struct matchedroom_struct
	{
		int result;
		std::vector<room> roomData;
	};
	typedef matchedroom_struct matchedroom;

WarpClient Listeners

• ConnectionRequestListener
• RoomRequestListener
• ZoneRequestListener
• LobbyRequestListener
• UpdateRequestListener
• ChatRequestListener
• NotifyListener

###ConnectionRequestListener

    /**
     * Invoked in response to a connect request.
     * @param event
     */
    public void onConnectDone(int event);

    /**
     * Invoked in response to a disconnect request.
     * @param event
     */
    public void onDisconnectDone(int event);

###RoomRequestListener

    /**
     * Invoked in response to a subscribeRoom request.
     * @param event
     */
    public void onSubscribeRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a UnSubscribeRoom request.
     * @param event
     */
    public void onUnSubscribeRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a joinRoom request.
     * @param event
     */
    public void onJoinRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a leaveRoom request.
     * @param event
     */
    public void onLeaveRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a getLiveRoomInfo request.
     * @param event
     */
    public void onGetLiveRoomInfoDone(AppWarp::liveroom event);
    /**
     * Invoked in response to a setCustomRoomData request.
     * @param event
     */
    public void onSetCustomRoomDataDone(AppWarp::liveroom event);
    /* TODO Added by saurav for match making
     * Invoked in response to add property to any room
     */
    public void onUpdatePropertyDone(AppWarp::liveroom event);

###ZoneRequestListener

    /**
     * Invoked in response to a deleteRoom request.
     * @param event
     */
    public void onDeleteRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a getAllRooms request.
     * @param event
     */
    public void onGetAllRoomsDone(AppWarp::liveresult event);
    /**
     * Invoked in response to a createRoom request.
     * @param event
     */
    public void onCreateRoomDone(AppWarp::room event);
    /**
     * Invoked in response to a getOnlineUsers request.
     * @param event
     */
    public void onGetOnlineUsersDone(AppWarp::liveresult event);
    /**
     * Invoked in response to a getLiveUserInfo request.
     * @param event
     */
    public void onGetLiveUserInfoDone(AppWarp::liveuser event);
    /**
     * Invoked in response to a setCustomRoomData request.
     * @param event
     */
    public void onSetCustomUserDataDone(AppWarp::liveuser event);
    
     /**
     * Invoked in response to a getMatchMaking Rooms request.
     * @param event
     */
    public void onGetMatchedRoomsDone(AppWarp::matchedroom event);

###LobbyRequestListener

    /**
     * Invoked in response to a joinLobby request.
     * @param event
     */
    public void onJoinLobbyDone(AppWarp::lobby event);
    /**
     * Invoked in response to a leaveLobby request.
     * @param event
     */
    public void onLeaveLobbyDone(AppWarp::lobby event);
    /**
     * Invoked in response to a subscribeLobby request.
     * @param event
     */
    public void onSubscribeLobbyDone(AppWarp::lobby event);
    /**
     * Invoked in response to a UnSubscribeLobby request.
     * @param event
     */
    public void onUnSubscribeLobbyDone(AppWarp::lobby event);
    /**
     * Invoked in response to a getLiveLobbyInfo request.
     * @param event
     */
    public void onGetLiveLobbyInfoDone(AppWarp::livelobby event);

###UpdateRequestListener

    /**
     * Result of SendUpdatePeers request. The result value maps to a WarpResponseResultCode
     * @param result
     */
    public void onSendUpdateDone(int result);

###ChatRequestListener

    /**
     * Result of SendChat request. The result value maps to a WarpResponseResultCode
     * @param result
     */
    public void onSendChatDone(int result);

###NotifyListener

    /**
     * Invoked when a room is created. Lobby subscribers will receive this.
     * @param event
     */
    public void onRoomCreated(AppWarp::room event);
    /**
     * Invoked when a room is deleted. Lobby subscribers will receive this.
     * @param event
     */
    public void onRoomDestroyed(AppWarp::room event);
    /**
     * Invoked when a user leaves a room. Lobby and the concerned room subscribers 
     * will receive this.
     * @param event
     * @param username
     */
    public void onUserLeftRoom(AppWarp::room event, std::string username);
    /**
     * Invoked when a user joins a room. Lobby and the concerned room subscribers 
     * will receive this.
     * @param event
     * @param username
     */
    public void onUserJoinedRoom(AppWarp::room event, std::string username);

    /**
     * Invoked when a user leaves a lobby. Lobby subscribers will receive this.
     * @param event
     * @param username
     */
    public void onUserLeftLobby(AppWarp::lobby event, std::string username);
    /**
     * Invoked when a user joins a lobby. Lobby subscribers will receive this.
     * @param event
     * @param username
     */
    public void onUserJoinedLobby(AppWarp::lobby event, std::string username);    
    
    /**
     * Invoked when a joined user sends a chat. Rooms subscribers will receive this.
     * @param event
     */
    public void onChatReceived(AppWarp::chat event);
    /**
     * Invoked when a joined user sends a updatePeers request. Rooms subscribers 
     * will receive this.
     * @param update
	 * @param len
     */
    public void onUpdatePeersReceived(AppWarp::byte update[], int len);
    /**
     * Invoked when a user change room property. Lobby and the concerned room subscribers 
     * will receive this.
     * @param event
     * @param username
	 * @param properties
     */
    public void onUserChangeRoomProperty(AppWarp::room event, std::string username,std::map<std::string, std::string> properties);

WarpClient Event Result Codes

    AppWarp::ResultCode::success = 0;
    AppWarp::ResultCode::auth_error = 1;
    AppWarp::ResultCode::resource_not_found = 2;
    AppWarp::ResultCode::resource_moved = 3;
    AppWarp::ResultCode::bad_request = 4;
    AppWarp::ResultCode::connection_error = 5;
    AppWarp::ResultCode::unknown_error = 6;
    AppWarp::ResultCode::size_error = 7;
    AppWarp::ResultCode::api_not_found = 8;	

SUCCESS

The request was successfully received and processed by the server.

AUTH_ERROR

The session id sent in the request was incorrect. This can happen if the client connects without initializing with the correct keys.

RESOURCE_NOT_FOUND

The resource for which the request was intended is not known to the server. For example a bad room id is given to a joinRoom request.

RESOURCE_MOVED

The resource for which the request was intended to has moved to a state where it can't process the request. For example, if a client sends a chat or updatePeers message and the connected user is not present in any room.

UNKNOWN_ERROR

This is an unexpected error. Retrying the request is recommended if this happens.

BAD_REQUEST

This occurs if the parameters passed to the request are invalid. For example if null or empty string is passed in the roomId parameter of a joinRoom request.

CONNECTION_ERR

This occurs if the underlying TCP connection with AppWarp cloud service got broken. The client will need to reconnect to the service and retry the operation.

API NOT FOUND

This occurs if inavlid API Key was used initialization