Friends Interface

Interface to retrieve friends lists, or to add or remove other users.

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 lists for a logged-in user.

Friends 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 use the Friends Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Friends List data. You can activate EAS on the Developer Portal , or learn more in Epic's documentation . Without EAS and user consent, you will still be able to initialize the EOS SDK and the Friends Interface, but all Friends Interface function calls to the back-end service will fail.

Retrieving and Caching the Friends List

To retrieve a user'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 logged-in user's friends list.

The first step in dealing with a user's friends lists is to call EOS_Friends_QueryFriends with an EOS_Friends_QueryFriendsOptions data structure. This will download the most up-to-date version of a user'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:

Property

Value

ApiVersion

EOS_FRIENDS_QUERYFRIENDS_API_LATEST

LocalUserId

The EOS_EpicAccountId of the logged-in user whose friends list you want to retrieve.

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.

Examining the Friends List

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.

    The EOS_EpicAccountId returned by this function can be passed to the User Info Interface to retrieve additional information about the user.

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

    Value

    Description

    EOS_FS_NotFriends

    The users are not friends.

    EOS_FS_InviteSent

    The local user has sent a friend invite to the other user.

    EOS_FS_InviteReceived

    The other user has sent a friend invite to the local user.

    EOS_FS_Friends

    The users are friends.

Friends lists can change at any time, both from in-game events like meeting new players, and from out-of-game events like the user 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.

Subscribing to Friend Status Updates

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

Parameter

Description

Options

An EOS_Friends_AddNotifyFriendsUpdateOptions structure, with ApiVersion as its only parameter.

Callback

A valid callback function consistent with EOS_Friends_OnFriendsUpdateCallback.

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

Parameter

Description

LocalUserId

The EOS_EpicAccountId of the local user receiving the update about their friends.

TargetUserId

The EOS_EpicAccountId of the user whose status is being updated.

PreviousStatus

The previous value of the target user's status.

CurrentStatus

The updated value of the target user's status.

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.

Managing the Friends List

All of the APIs for managing the friends list have been deprecated. Calling any of the following functions will return a result of EOS_NotImplemented:

  • EOS_Friends_AcceptInvite

  • EOS_Friends_RejectInvite

  • EOS_Friends_SendInvite

  • EOS_Friends_DeleteFriend

We are considering our options for how to bring this functionality back into the SDK. When these APIs become available again, this documentation will be updated to reflect their usage and expected behaviors.