Client Friend API Reference

The Friends service allows developers to manage the player's friend list. The player can invite friends to join a party for matchmaking or to chat.

API List

API	Description
GetFriendList	Get my friend list.
AddFriend	Add the player to my friend list. If the peer player is online, he will receive an OnAddFriendRequest event. If the peer player is not online, he can call GetReceivedFriendRequests API when he goes online later to know that someone wants to add him as a friend. Only after the peer player accepts your friend request can the two of you become friends with each other.
RemoveFriend	Remove the player from my friend list. If the peer player is online, he will receive an OnFriendRemoved event. If the peer player is not online, he will not receive an OnFriendRemoved event even when he is online, but the friend list will be updated. Note: Only the peer player can receive the OnFriendRemoved event, the API caller(you) can check the callback result for the operation succeeded or not.
GetReceivedFriendRequests	Get the list of received friend requests. These friend requests are from the players who want to add me as a friend.
GetSentFriendRequests	Get the list of sent friend requests. These friend requests are from me because I want to add some players as a friend.
AcceptFriendRequest	Accept the player's request, after that, the two of us become friends with each other. If the peer player is online, he will receive an OnAddFriendResponse event. If the peer player is not online, he will not receive the OnAddFriendResponse event even if he goes online later, but the friend list will be updated. Note: Only the peer player can receive the OnAddFriendResponse event, the API caller(you) can check the callback result for the operation succeeded or not.
RejectFriendRequest	Reject the player's request.
DelSentFriendRequest	Delete the friend request I sent to other player. Affects the result returned when calling the GetSentFriendRequests API in the future.
BatchAddFriend	Add players to my friend list. (max 50 players)
SearchPlayers	Search for players.
SearchPlayersWithFilter	Search for players with filter.
GetRecentPlayers	Get recent players. Players on the blocklist will be filtered out. Return up to 20 recent players who have interacted with the current player.
GetRecommendedPlayers	Get recommended players. Friends and blocklisted players will be filtered out.
GetPotentialFriends	Get a list of players who may be your friends. Friends and blocklisted players will be filtered out. And the result will be ordered by the mutual friend count descending.
SetFriendRemark	Set remark to your friend, for example, "Tommy, a humorous man, met in the battle.", Max remark length: 32 characters.
SubscribeFriendPresence	Subscribe to the presence of all friends. You will be notified of presence changes from your friends.
UnsubscribeFriendPresence	Unsubscribe friend presence.
GetMyFriendsLimit	Query the maximum limit of friends you can have.
GetMutualFriendsCount	Get mutual friends count between this player and target players.

Event List

Event	Description
SetOnAddFriendRequest	The event will be triggered when receive a request to add friend.
SetOnAddFriendResponse	The event will be triggered when your add-friend request was accepted by player.
SetOnFriendRemoved	The event will be triggered when someone has remove you from his/her friend list.
SetOnBadgeNumOfFriendReq	The event will be triggered when the player login PGOS or the list of friend requests received changes.
SetOnFriendPresenceChanged	The event will be triggered when the presence of a friend changed. The premise is that you must first subscribe to the friend presence.

API Details

GetFriendList

Get my friend list.

/**
 * Get my friend list.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetFriendList(
    PgosDataCallback<FriendListInfo> result_callback);

Parameters:

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

Return: void

AddFriend

Add the player to my friend list. If the peer player is online, he will receive an OnAddFriendRequest event. If the peer player is not online, he can call GetReceivedFriendRequests API when he goes online later to know that someone wants to add him as a friend. Only after the peer player accepts your friend request can the two of you become friends with each other.

/**
 * Add the player to my friend list.
 * If the peer player is online, he will receive an OnAddFriendRequest event.
 * If the peer player is not online, he can call GetReceivedFriendRequests API when he goes online later to know that someone wants to add him as a friend.
 * Only after the peer player accepts your friend request can the two of you become friends with each other.
 * 
 * @param params Request struct for add friend
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void AddFriend(
    const AddFriendParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const AddFriendParams&	Request struct for add friend
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RemoveFriend

Remove the player from my friend list. If the peer player is online, he will receive an OnFriendRemoved event. If the peer player is not online, he will not receive an OnFriendRemoved event even when he is online, but the friend list will be updated. Note: Only the peer player can receive the OnFriendRemoved event, the API caller(you) can check the callback result for the operation succeeded or not.

/**
 * Remove the player from my friend list.
 * If the peer player is online, he will receive an OnFriendRemoved event.
 * If the peer player is not online, he will not receive an OnFriendRemoved event even when he is online, but the friend list will be updated.
 * Note: Only the peer player can receive the OnFriendRemoved event, the API caller(you) can check the callback result for the operation succeeded or not.
 * 
 * @param player_id The player id to remove
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RemoveFriend(
    const pgos::pstring& player_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The player id to remove
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetReceivedFriendRequests

Get the list of received friend requests. These friend requests are from the players who want to add me as a friend.

/**
 * Get the list of received friend requests.
 * These friend requests are from the players who want to add me as a friend.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetReceivedFriendRequests(
    PgosDataCallback<FriendReqListInfo> result_callback);

Parameters:

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

Return: void

GetSentFriendRequests

Get the list of sent friend requests. These friend requests are from me because I want to add some players as a friend.

/**
 * Get the list of sent friend requests.
 * These friend requests are from me because I want to add some players as a friend.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetSentFriendRequests(
    PgosDataCallback<FriendReqListInfo> result_callback);

Parameters:

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

Return: void

AcceptFriendRequest

Accept the player's request, after that, the two of us become friends with each other. If the peer player is online, he will receive an OnAddFriendResponse event. If the peer player is not online, he will not receive the OnAddFriendResponse event even if he goes online later, but the friend list will be updated. Note: Only the peer player can receive the OnAddFriendResponse event, the API caller(you) can check the callback result for the operation succeeded or not.

/**
 * Accept the player's request, after that, the two of us become friends with each other.
 * If the peer player is online, he will receive an OnAddFriendResponse event. 
 * If the peer player is not online, he will not receive the OnAddFriendResponse event even if he goes online later, but the friend list will be updated.
 * Note: Only the peer player can receive the OnAddFriendResponse event, the API caller(you) can check the callback result for the operation succeeded or not.
 * 
 * @param player_id The player id who sent the add-friend request
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void AcceptFriendRequest(
    const pgos::pstring& player_id,
    PgosDataCallback<AcceptFriendRequestResult> result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The player id who sent the add-friend request
result_callback	PgosDataCallback<AcceptFriendRequestResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RejectFriendRequest

Reject the player's request.

/**
 * Reject the player's request.
 * 
 * @param player_id The player id who sent the add-friend request
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RejectFriendRequest(
    const pgos::pstring& player_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The player id who sent the add-friend request
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

DelSentFriendRequest

Delete the friend request I sent to other player. Affects the result returned when calling the GetSentFriendRequests API in the future.

/**
 * Delete the friend request I sent to other player.
 * Affects the result returned when calling the GetSentFriendRequests API in the future.
 * 
 * @param player_id The id of other player
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void DelSentFriendRequest(
    const pgos::pstring& player_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The id of other player
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

BatchAddFriend

Add players to my friend list. (max 50 players)

/**
 * Add players to my friend list. (max 50 players)
 * 
 * @param params Request struct for batch add friend
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchAddFriend(
    const BatchAddFriendParams& params,
    PgosDataCallback<BatchAddFriendRsp> result_callback);

Parameters:

Param	Type	Description
params	const BatchAddFriendParams&	Request struct for batch add friend
result_callback	PgosDataCallback<BatchAddFriendRsp>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

SearchPlayers

Search for players.

/**
 * Search for players.
 * 
 * @param params Request struct for search players.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SearchPlayers(
    const SearchPlayersParams& params,
    PgosDataCallback<PlayerSearchInfoList> result_callback);

Parameters:

Param	Type	Description
params	const SearchPlayersParams&	Request struct for search players.
result_callback	PgosDataCallback<PlayerSearchInfoList>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

SearchPlayersWithFilter

Search for players with filter.

/**
 * Search for players with filter.
 * 
 * @param params Request struct for search players with filter
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SearchPlayersWithFilter(
    const SearchPlayersWithFilterParams& params,
    PgosDataCallback<PlayerSearchInfoList> result_callback);

Parameters:

Param	Type	Description
params	const SearchPlayersWithFilterParams&	Request struct for search players with filter
result_callback	PgosDataCallback<PlayerSearchInfoList>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetRecentPlayers

Get recent players. Players on the blocklist will be filtered out. Return up to 20 recent players who have interacted with the current player.

/**
 * Get recent players. Players on the blocklist will be filtered out. Return up to 20 recent players who have interacted with the current player.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetRecentPlayers(
    PgosDataCallback<PlayerSearchInfoList> result_callback);

Parameters:

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

Return: void

GetRecommendedPlayers

Get recommended players. Friends and blocklisted players will be filtered out.

/**
 * Get recommended players. Friends and blocklisted players will be filtered out.
 * 
 * @param params Request struct for get recommended players
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetRecommendedPlayers(
    const GetRecommendedPlayersParams& params,
    PgosDataCallback<PlayerSearchInfoList> result_callback);

Parameters:

Param	Type	Description
params	const GetRecommendedPlayersParams&	Request struct for get recommended players
result_callback	PgosDataCallback<PlayerSearchInfoList>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetPotentialFriends

Get a list of players who may be your friends. Friends and blocklisted players will be filtered out. And the result will be ordered by the mutual friend count descending.

/**
 * Get a list of players who may be your friends. Friends and blocklisted players will be filtered out.
 * And the result will be ordered by the mutual friend count descending.
 * 
 * @param params Request struct for get potential friends
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetPotentialFriends(
    const GetPotentialFriendsParams& params,
    PgosDataCallback<GetPotentialFriendsResult> result_callback);

Parameters:

Param	Type	Description
params	const GetPotentialFriendsParams&	Request struct for get potential friends
result_callback	PgosDataCallback<GetPotentialFriendsResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

SetFriendRemark

Set remark to your friend, for example, "Tommy, a humorous man, met in the battle.", Max remark length: 32 characters.

/**
 * Set remark to your friend, for example, "Tommy, a humorous man, met in the battle.",  Max remark length: 32 characters.
 * 
 * @param params Request struct for set friend remark
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SetFriendRemark(
    const SetFriendRemarkParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const SetFriendRemarkParams&	Request struct for set friend remark
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

SubscribeFriendPresence

Subscribe to the presence of all friends. You will be notified of presence changes from your friends.

/**
 * Subscribe to the presence of all friends. You will be notified of presence changes from your friends.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SubscribeFriendPresence(
    PgosCallback result_callback);

Parameters:

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

Return: void

UnsubscribeFriendPresence

Unsubscribe friend presence.

/**
 * Unsubscribe friend presence.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void UnsubscribeFriendPresence(
    PgosCallback result_callback);

Parameters:

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

Return: void

GetMyFriendsLimit

Query the maximum limit of friends you can have.

/**
 * Query the maximum limit of friends you can have.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetMyFriendsLimit(
    PgosDataCallback<GetMyFriendsLimitResult> result_callback);

Parameters:

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

Return: void

GetMutualFriendsCount

Get mutual friends count between this player and target players.

/**
 * Get mutual friends count between this player and target players.
 * 
 * @param params Request struct for get mutual friends
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetMutualFriendsCount(
    const GetMutualFriendsCountParams& params,
    PgosDataCallback<GetMutualFriendsCountResult> result_callback);

Parameters:

Param	Type	Description
params	const GetMutualFriendsCountParams&	Request struct for get mutual friends
result_callback	PgosDataCallback<GetMutualFriendsCountResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

Event Details

SetOnAddFriendRequest

The event will be triggered when receive a request to add friend.

/**
 * OnSetOnAddFriendRequest:
 * The event will be triggered when receive a request to add friend.
 * 
 * @param event Event result of friend request.
 */
void SetOnAddFriendRequest(
    const AddFriendRequestEvt& event);

Parameters:

Param	Type	Description
event	const AddFriendRequestEvt&	Event result of friend request.

SetOnAddFriendResponse

The event will be triggered when your add-friend request was accepted by player.

/**
 * OnSetOnAddFriendResponse:
 * The event will be triggered when your add-friend request was accepted by player.
 * 
 * @param event Event result of friend response.
 */
void SetOnAddFriendResponse(
    const AddFriendResponseEvt& event);

Parameters:

Param	Type	Description
event	const AddFriendResponseEvt&	Event result of friend response.

SetOnFriendRemoved

The event will be triggered when someone has remove you from his/her friend list.

/**
 * OnSetOnFriendRemoved:
 * The event will be triggered when someone has remove you from his/her friend list.
 * 
 * @param event Event result contains information about the player info who remove.
 */
void SetOnFriendRemoved(
    const FriendRemovedEvt& event);

Parameters:

Param	Type	Description
event	const FriendRemovedEvt&	Event result contains information about the player info who remove.

SetOnBadgeNumOfFriendReq

The event will be triggered when the player login PGOS or the list of friend requests received changes.

/**
 * OnSetOnBadgeNumOfFriendReq:
 * The event will be triggered when the player login PGOS or the list of friend requests received changes.
 * 
 * @param event Event result contains the badge num.
 */
void SetOnBadgeNumOfFriendReq(
    const BadgeNumOfFriendReqEvt& event);

Parameters:

Param	Type	Description
event	const BadgeNumOfFriendReqEvt&	Event result contains the badge num.

SetOnFriendPresenceChanged

The event will be triggered when the presence of a friend changed. The premise is that you must first subscribe to the friend presence.

/**
 * OnSetOnFriendPresenceChanged:
 * The event will be triggered when the presence of a friend changed. The premise is that you must first subscribe to the friend presence.
 * 
 * @param event Event result contains the friend's new presence.
 */
void SetOnFriendPresenceChanged(
    const FriendPresenceChangedEvt& event);

Parameters:

Param	Type	Description
event	const FriendPresenceChangedEvt&	Event result contains the friend's new presence.