Friends Interface

Playing games with your friends and meeting new players online are important parts of many online services. The Epic Online Services (EOS) SDK uses the Friends Interface to retrieve the friends list for a logged-in player.

Friend lists are stored by the online service's servers, and can change during a session as friends are added or removed or if friends grant or revoke consent for the game to use their information.

Upon successful completion of a friends list query, the Friends Interface creates a local cache that is used by all other Friends Interface functions. Additionally the SDK receives notifications from the backend about events that lead to mutations of the friends list, such as a friend being removed, an invite being accepted or a friend revoking their consent to have their information used by the game.

To retrieve a player's friends list, you will need an EOS_HFriends handle. You can acquire this handle through the Platform Interface function, EOS_Platform_GetFriendsInterface. Friends Interface functions require this handle to access your signed-in user's friends list. It is important to note that EOS_Friends_QueryFriends will only return friends who have played the game at least once and have given their consent. Consent is either give upon game purchase or when a player signs in to an application using Epic Account Services (EAS) and allows EAS access to their account data.

The first step in dealing with a player's friends list is to call EOS_Friends_QueryFriends with an EOS_Friends_QueryFriendsOptions data structure. This will download the most up-to-date version of a player's friends list into the local cache, then invoke your EOS_Friends_QueryFriends callback function upon completion.

To perform the EOS_Friends_QueryFriends call, create and initialize an EOS_Friends_QueryFriendsOptions structure as follows:

Pass the Friends Interface handle, the EOS_Friends_QueryFriendsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.

When your callback executes, you can check the ResultCode field of the EOS_Friends_QueryFriendsCallbackInfo structure to determine whether the operation succeeded or failed. A success code indicates that the SDK has cached the latest data from the server, which you can examine at any time.

After a successful call to EOS_Friends_QueryFriends, developers can perform the following useful functions using the local cache:

• Determine the number of friends on the list by calling EOS_Friends_GetFriendsCount.
• Retrieve the EOS_EpicAccountId of each friend by calling EOS_Friends_GetFriendAtIndex.

• Determine the current status of the social relationship by calling EOS_Friends_GetStatus. This function returns one of four values:

Note: The EOS_AS_FriendsManagement scope controls whether the signed-in player can make changes or view pending changes to their social graph (for example, their friend status). By default, this scope isn't enabled. The EOS SDK returns only the Friends (EOS_FS_Friends) and Not Friends (EOS_FS_NotFriends) statuses to your game. The Social Overlay handles pending invites for you, which includes the remaining Invite Sent (EOS_FS_InviteSent) and Invite Received (EOS_FS_InviteReceived) statuses. While these statuses are available in the header, you do not need to handle these statuses in your game.

Friends lists can change at any time, both from in-game events like meeting new players, and from out-of-game events like the player modifying the account from a separate system. Games do not need and should not call EOS_Friends_QueryFriends more than once per login of a player. However, after a player logs out, their friends list must be queried again if they log in again. To keep a game's local copy of the friends list up to date, subscribe to friend status update notifications.

To receive a notification when friend's status changes call EOS_Friends_AddNotifyFriendsUpdate with following parameters:

The callback function will be called when a friend gets an update. The callback receives an EOS_Friends_OnFriendsUpdateInfo structure with the following parameters:

EOS_Friends_AddNotifyFriendsUpdate will return an EOS_NotificationId, which is a special handle that must be used to unsubscribe from notifications when they are no longer needed. In the event of a failure, it will return a result code of EOS_INVALID_NOTIFICATIONID.

To unsubscribe from friend status updates, use the function EOS_Friends_RemoveNotifyFriendsUpdate, which that accepts notification ID received during subscription.

You can allow the local user to send friend requests to other users in the game, by calling the EOS_Friends_SendInvite SDK API. To implement game UI functionality for accepting or rejecting any received friend invites, you can use the EOS_Friends_AcceptInvite and EOS_Friends_RejectInvite SDK APIs respectively.

These APIs will return EOS_NotImplemented on platforms without yet the availability.