Client Battle API Reference

Battle session is the foundation of battle service. Battle session instances can be created through services such as Lobby / Matchmaking / World or via the PGOS HTTP API, and placed in online or local DS via the DS Hosting service. The battle session also manages data such as the players in the game and the DS access information.

API List

API	Description
GetBattleRecordList	Get a list of battle records
GetBattleBriefList	Get a list of battle brief
GetBattleData	Get all battle data
GetBattleDetail	Get the detail of the battle
DescribePlayerBattleSession	Get the player's battle session info.
DescribeBattleSessions	Get a list of the battle sesions that the player is participating in.
TerminatePlayerBattleSession	Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called.
GetDSHostingLatencies	Obtain the latencies from the client to the DS hosting data centers. In general, the first round of latency testing will be completed in approximately 2~3 seconds after logging into PGOS. If the API is called before the testing is completed, or an exception occurs, the latency data returned by the API will be empty.
SetCustomDSHostingLatencies	Set custom latencies for the DS hosting data centers. This API is used to set custom latency values for different DS hosting data centers, which can be useful for testing purposes. After setting custom latencies, the client will use these values instead of the actual measured latencies when selecting a DS hosting data center.

Event List

Event	Description
SetOnLatencyTestRoundCompleted	The event will be triggered when a round of latency testing is completed.

API Details

GetBattleRecordList

Get a list of battle records

/**
 * Get a list of battle records
 * 
 * @param player_id The player id to query
 * @param tags  Get the list for specific tags, if the tags is empty, the tag will not be filtered
 * @param keys Get the list for specific keys, if the keys is empty, the key will not be filtered
 * @param offset The starting position of the list
 * @param count The count of the list
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetBattleRecordList(
    const pgos::pstring& player_id,
    const pgos::pvector<pgos::pstring>& tags,
    const pgos::pvector<pgos::pstring>& keys,
    int32_t offset,
    int32_t count,
    PgosDataCallback<BattleListInfo> result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The player id to query
tags	const std::vector<std::string>&	Get the list for specific tags, if the tags is empty, the tag will not be filtered
keys	const std::vector<std::string>&	Get the list for specific keys, if the keys is empty, the key will not be filtered
offset	int32_t	The starting position of the list
count	int32_t	The count of the list
result_callback	PgosDataCallback<BattleListInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetBattleBriefList

Get a list of battle brief

/**
 * Get a list of battle brief
 * 
 * @param player_id The player id to query
 * @param tags  Get the list for specific tags, if the tags is empty, the tag will not be filtered
 * @param offset The starting position of the list
 * @param count The count of the list
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetBattleBriefList(
    const pgos::pstring& player_id,
    const pgos::pvector<pgos::pstring>& tags,
    int32_t offset,
    int32_t count,
    PgosDataCallback<BattleBriefListInfo> result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The player id to query
tags	const std::vector<std::string>&	Get the list for specific tags, if the tags is empty, the tag will not be filtered
offset	int32_t	The starting position of the list
count	int32_t	The count of the list
result_callback	PgosDataCallback<BattleBriefListInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetBattleData

Get all battle data

/**
 * Get all battle data
 * 
 * @param battle_session_id The battle session id to query
 * @param keys Get the list for specific keys, if the keys is empty, the key will not be filtered
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetBattleData(
    const pgos::pstring& battle_session_id,
    const pgos::pvector<pgos::pstring>& keys,
    PgosDataCallback<BattleDataInfo> result_callback);

Parameters:

Param	Type	Description
battle_session_id	const std::string&	The battle session id to query
keys	const std::vector<std::string>&	Get the list for specific keys, if the keys is empty, the key will not be filtered
result_callback	PgosDataCallback<BattleDataInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetBattleDetail

Get the detail of the battle

/**
 * Get the detail of the battle
 * 
 * @param battle_session_id The battle session id to query
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetBattleDetail(
    const pgos::pstring& battle_session_id,
    PgosDataCallback<BattleDetailInfo> result_callback);

Parameters:

Param	Type	Description
battle_session_id	const std::string&	The battle session id to query
result_callback	PgosDataCallback<BattleDetailInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

DescribePlayerBattleSession

Get the player's battle session info.

Deprecated, use DescribeBattleSessions instead.

/**
 * Get the player's battle session info.
 * [DEPRECATED!!!] DescribePlayerBattleSession was declared deprecated, consider using DescribeBattleSessions instead.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void DescribePlayerBattleSession(
    PgosDataCallback<PlayerBattleSessionInfo> result_callback);

Parameters:

Param	Type	Description
result_callback	PgosDataCallback<PlayerBattleSessionInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

DescribeBattleSessions

Get a list of the battle sesions that the player is participating in.

/**
 * Get a list of the battle sesions that the player is participating in.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void DescribeBattleSessions(
    PgosDataCallback<DescribeBattleSessionsResult> result_callback);

Parameters:

Param	Type	Description
result_callback	PgosDataCallback<DescribeBattleSessionsResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

TerminatePlayerBattleSession

Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called.

/**
 * Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called.
 * 
 * @param battle_session_id The battle session id
 * @param player_battle_session_id The player battle session id, !!! NOT BATTLE SESSION ID !!!
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void TerminatePlayerBattleSession(
    const pgos::pstring& battle_session_id,
    const pgos::pstring& player_battle_session_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
battle_session_id	const std::string&	The battle session id
player_battle_session_id	const std::string&	The player battle session id, !!! NOT BATTLE SESSION ID !!!
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetDSHostingLatencies

Obtain the latencies from the client to the DS hosting data centers. In general, the first round of latency testing will be completed in approximately 2~3 seconds after logging into PGOS. If the API is called before the testing is completed, or an exception occurs, the latency data returned by the API will be empty.

/**
 * Obtain the latencies from the client to the DS hosting data centers.
 * In general, the first round of latency testing will be completed in approximately 2~3 seconds after logging into PGOS.
 * If the API is called before the testing is completed, or an exception occurs, the latency data returned by the API will be empty.
 * 
 * @return The latencies from the client to the DS hosting data centers.
 */
DSHostingLatencies GetDSHostingLatencies();

Parameters:

(No parameters)

Return: DSHostingLatencies

The latencies from the client to the DS hosting data centers.

SetCustomDSHostingLatencies

Set custom latencies for the DS hosting data centers. This API is used to set custom latency values for different DS hosting data centers, which can be useful for testing purposes. After setting custom latencies, the client will use these values instead of the actual measured latencies when selecting a DS hosting data center.

/**
 * Set custom latencies for the DS hosting data centers.
 * This API is used to set custom latency values for different DS hosting data centers, which can be useful for testing purposes.
 * After setting custom latencies, the client will use these values instead of the actual measured latencies when selecting a DS hosting data center.
 * 
 * @param latencies The custom latencies to set for DS hosting data centers.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SetCustomDSHostingLatencies(
    const DSHostingLatencies& latencies,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
latencies	const DSHostingLatencies&	The custom latencies to set for DS hosting data centers.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

Event Details

SetOnLatencyTestRoundCompleted

The event will be triggered when a round of latency testing is completed.

/**
 * OnSetOnLatencyTestRoundCompleted:
 * The event will be triggered when a round of latency testing is completed.
 * 
 * @param event Event details when a latency test round is completed.
 */
void SetOnLatencyTestRoundCompleted(
    const LatencyTestRoundCompletedEvt& event);

Parameters:

Param	Type	Description
event	const LatencyTestRoundCompletedEvt&	Event details when a latency test round is completed.