Client P2PBattle API Reference
Unlike online battle sessions, PGOS manages P2P battle sessions through game clients instead of dedicated servers or local dedicated servers.
API List
| API | Description |
|---|---|
| ActivateP2PBattleSession | NOTE: This interface can only called by HOST client. Activate a P2P battle session. Signal PGOS that the host is ready for clients to connect. |
| TerminateP2PBattleSession | NOTE: This interface can only called by HOST client. Terminate a P2P battle session. This method should be called when a P2P game is(or will) end. |
| AcceptP2PPlayerBattleSession | NOTE: This interface can only called by HOST client. Validates a player session, and signal PGOS to update player session's status to Active. This method should be called when a client requests a connection to the server. |
| DisconnectP2PPlayerBattleSession | NOTE: This interface can only called by HOST client. Turn a player session status to Disconnected.You can call this interface when the player disconnects from DS non-permanently. The player session can be resumed to Active at any time by calling the AcceptPlayerBattleSession interface again. |
| RemoveP2PPlayerBattleSession | NOTE: This interface can only called by HOST client. Turn a player session status to Completed.You should call this interface when a player. This interface will set the player session to a final state and cannot be restored. |
| DescribeP2PPlayerBattleSessions | NOTE: This interface can only called by HOST client. Query players session for a battle session. |
| DescribeP2PBattleSessions | Get a list of the P2P battle sessions that the player is participating in. |
| TerminateP2PPlayerBattleSession | Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called. This interface should be called when the player wants to leave the battle session. |
| ReportHostHealth | P2P clients can use this interface to report the health status of a host to PGOS. Note that calls originating from the host itself will be ignored. |
| RejectHostMigrating | The client elected as the new host calls this interface to reject the host identity. The current battle session will terminate after this call. |
Event List
| Event | Description |
|---|---|
| SetOnStartP2PBattleSession | NOTE: This event is for HOST client only. The event will be triggered when a new P2P battle session is assigned to this client. |
| SetOnP2PBattleSessionTerminate | NOTE: This event is for HOST client only. The event will be triggered once the P2P battle session being terminated from admin portal. Game server should call TerminateP2PBattleSession. Otherwise, the session will be reclaimed by PGOS after 5 minutes. |
| SetOnP2PPlayerBattleSessionsTerminated | This event will be triggered in the following two situations: 1. The game client calls the TerminateP2PPlayerBattleSession interface, and the event is triggered in the host. 2. The host calls the TerminateP2PBattleSession interface, and the event is triggered in the game client. |
| SetOnP2PBattleSessionUpdated | The event will be triggered when battle session status or player battle session of current player status updated. |
API Details
ActivateP2PBattleSession
NOTE: This interface can only called by HOST client. Activate a P2P battle session. Signal PGOS that the host is ready for clients to connect.
/**
* NOTE: This interface can only called by HOST client.
* Activate a P2P battle session. Signal PGOS that the host is ready for clients to connect.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void ActivateP2PBattleSession(
const ActivateP2PBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const ActivateP2PBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
TerminateP2PBattleSession
NOTE: This interface can only called by HOST client. Terminate a P2P battle session. This method should be called when a P2P game is(or will) end.
/**
* NOTE: This interface can only called by HOST client.
* Terminate a P2P battle session.
* This method should be called when a P2P game is(or will) end.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void TerminateP2PBattleSession(
const TerminateP2PBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const TerminateP2PBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
AcceptP2PPlayerBattleSession
NOTE: This interface can only called by HOST client. Validates a player session, and signal PGOS to update player session's status to Active. This method should be called when a client requests a connection to the server.
/**
* NOTE: This interface can only called by HOST client.
* Validates a player session, and signal PGOS to update player session's status to Active.
* This method should be called when a client requests a connection to the server.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void AcceptP2PPlayerBattleSession(
const AcceptP2PPlayerBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const AcceptP2PPlayerBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
DisconnectP2PPlayerBattleSession
NOTE: This interface can only called by HOST client. Turn a player session status to Disconnected.You can call this interface when the player disconnects from DS non-permanently. The player session can be resumed to Active at any time by calling the AcceptPlayerBattleSession interface again.
/**
* NOTE: This interface can only called by HOST client.
* Turn a player session status to Disconnected.You can call this interface when the player disconnects from DS non-permanently.
* The player session can be resumed to Active at any time by calling the AcceptPlayerBattleSession interface again.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void DisconnectP2PPlayerBattleSession(
const DisconnectP2PPlayerBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const DisconnectP2PPlayerBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
RemoveP2PPlayerBattleSession
NOTE: This interface can only called by HOST client. Turn a player session status to Completed.You should call this interface when a player. This interface will set the player session to a final state and cannot be restored.
/**
* NOTE: This interface can only called by HOST client.
* Turn a player session status to Completed.You should call this interface when a player.
* This interface will set the player session to a final state and cannot be restored.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void RemoveP2PPlayerBattleSession(
const RemoveP2PPlayerBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const RemoveP2PPlayerBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
DescribeP2PPlayerBattleSessions
NOTE: This interface can only called by HOST client. Query players session for a battle session.
/**
* NOTE: This interface can only called by HOST client.
* Query players session for a battle session.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void DescribeP2PPlayerBattleSessions(
const DescribeP2PPlayerBattleSessionsParams& params,
PgosDataCallback<DescribeP2PPlayerBattleSessionsResult> result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const DescribeP2PPlayerBattleSessionsParams& | |
| result_callback | PgosDataCallback<DescribeP2PPlayerBattleSessionsResult> | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
DescribeP2PBattleSessions
Get a list of the P2P battle sessions that the player is participating in.
/**
* Get a list of the P2P battle sessions 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 DescribeP2PBattleSessions(
PgosDataCallback<DescribeP2PBattleSessionsResult> result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| result_callback | PgosDataCallback<DescribeP2PBattleSessionsResult> | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
TerminateP2PPlayerBattleSession
Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called. This interface should be called when the player wants to leave the battle session.
/**
* Try to terminate the player session in a P2P battle. The player session status will turn to Completed after interface is called.
* This interface should be called when the player wants to leave the battle session.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void TerminateP2PPlayerBattleSession(
const TerminateP2PPlayerBattleSessionParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const TerminateP2PPlayerBattleSessionParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
ReportHostHealth
P2P clients can use this interface to report the health status of a host to PGOS. Note that calls originating from the host itself will be ignored.
/**
* P2P clients can use this interface to report the health status of a host to PGOS. Note that calls originating from the host itself will be ignored.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void ReportHostHealth(
const ReportHostHealthParams& params,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| params | const ReportHostHealthParams& | |
| result_callback | PgosCallback | The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD. |
Return: void
RejectHostMigrating
The client elected as the new host calls this interface to reject the host identity. The current battle session will terminate after this call.
/**
* The client elected as the new host calls this interface to reject the host identity. The current battle session will terminate after this call.
*
* @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
*/
void RejectHostMigrating(
const pgos::pstring& battle_session_id,
PgosCallback result_callback);
Parameters:
| Param | Type | Description |
|---|---|---|
| battle_session_id | const std::string& | |
| 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
SetOnStartP2PBattleSession
NOTE: This event is for HOST client only. The event will be triggered when a new P2P battle session is assigned to this client.
/**
* OnSetOnStartP2PBattleSession:
* NOTE: This event is for HOST client only.
* The event will be triggered when a new P2P battle session is assigned to this client.
*
* @param event Event result.
*/
void SetOnStartP2PBattleSession(
const StartP2PBattleSessionEvt& event);
Parameters:
| Param | Type | Description |
|---|---|---|
| event | const StartP2PBattleSessionEvt& | Event result. |
SetOnP2PBattleSessionTerminate
NOTE: This event is for HOST client only. The event will be triggered once the P2P battle session being terminated from admin portal. Game server should call TerminateP2PBattleSession. Otherwise, the session will be reclaimed by PGOS after 5 minutes.
/**
* OnSetOnP2PBattleSessionTerminate:
* NOTE: This event is for HOST client only.
* The event will be triggered once the P2P battle session being terminated from admin portal.
* Game server should call TerminateP2PBattleSession. Otherwise, the session will be reclaimed by PGOS after 5 minutes.
*
* @param event Event result.
*/
void SetOnP2PBattleSessionTerminate(
const P2PBattleSessionTerminateEvt& event);
Parameters:
| Param | Type | Description |
|---|---|---|
| event | const P2PBattleSessionTerminateEvt& | Event result. |
SetOnP2PPlayerBattleSessionsTerminated
This event will be triggered in the following two situations: 1. The game client calls the TerminateP2PPlayerBattleSession interface, and the event is triggered in the host. 2. The host calls the TerminateP2PBattleSession interface, and the event is triggered in the game client.
/**
* OnSetOnP2PPlayerBattleSessionsTerminated:
* This event will be triggered in the following two situations:
* 1. The game client calls the TerminateP2PPlayerBattleSession interface, and the event is triggered in the host.
* 2. The host calls the TerminateP2PBattleSession interface, and the event is triggered in the game client.
*
* @param event Event result.
*/
void SetOnP2PPlayerBattleSessionsTerminated(
const P2PPlayerBattleSessionsTerminatedEvt& event);
Parameters:
| Param | Type | Description |
|---|---|---|
| event | const P2PPlayerBattleSessionsTerminatedEvt& | Event result. |
SetOnP2PBattleSessionUpdated
The event will be triggered when battle session status or player battle session of current player status updated.
/**
* OnSetOnP2PBattleSessionUpdated:
* The event will be triggered when battle session status or player battle session of current player status updated.
*
* @param event Event result.
*/
void SetOnP2PBattleSessionUpdated(
const P2PBattleSessionUpdatedEvt& event);
Parameters:
| Param | Type | Description |
|---|---|---|
| event | const P2PBattleSessionUpdatedEvt& | Event result. |