Playing games with your friends and meeting new players online is an important part of many online services. The Friends Interface contains features to manage a user's list of social contacts, including adding, removing, and blocking other users.
Managing Friends
Friends lists are stored on the online service's servers, and can change during a session as friends are added or removed, join and leave games and sessions, or log in and out of the service. As a result, managing these lists involves querying the server for the latest information, then caching that information and using it in your game.
Retrieving Friends Lists
The first step in dealing with a user's friends lists is generally to call ReadFriendsList, which retrieves the most up-to-date version of a named friends list belonging to a specified local user.
Valid list names can be found in the EFriendsList enumerated type, and can be converted into strings by the provided ToStringfunction.
Because it queries a remote machine, the ReadFriendsList is asynchronous and will call a delegate of type FOnReadFriendsListComplete when complete.
On success, this call caches the list so that it can be examined later without repeatedly querying the remote machine, or requiring developers to write their own caching code.
It also updates presence status data for the users on the list.
The data returned by FOnReadFriendsListComplete only contains information regarding the success or failure of the ReadFriendsList operation.
Examining Friends Lists
After a successful call to ReadFriendsList retrieves and caches a list, developers can use GetFriendsList to get a copy of the list itself, or GetFriend to retrieve an individual friend from the list.
In addition, a known user's FUniqueNetId can be passed to the IsFriend function to check a specified list for that user.
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.
Calling ReadFriendsList to keep the cached lists up-to-date should be considered.
Inviting a Friend
The SendInvite function will send an invitation to another user, identified by that user's FUniqueNetId.
Upon acceptance, the user will be added to the specified list by the online service.
A delegate of type FOnSendInviteComplete will be called when this operation finishes, but this only means that the invitation has been sent (or has failed to send), not that the intended recipient has received or responded to it.
Some online services may have custom user interfaces for sending invitations, and these may open automatically when SendInvite is called.
All SendInvite calls will eventually trigger the FOnSendInviteComplete delegate.
This includes cases where an external UI is opened and the user cancels it.
Accepting or Rejecting an Invitation
When an invitation from another user has arrived, a delegate of type FOnInviteReceivedDelegate will be called, containing the FUniqueNetId of the sender and the recipient.
The invited user can then call AcceptInvite or RejectInvite to respond, specifying the name of the list where the new friend should appear.
AcceptInvite uses a delegate of type FOnAcceptInviteComplete to communicate the results of the operation, while RejectInvite uses an FOnRejectInviteComplete delegate.
Deleting a Friends List
The online service can be instructed to delete a friends list through the asynchronous DeleteFriendsList function.
When complete, a delegate of type FOnDeleteFriendsListComplete will be called.
Deleting a Friend
To remove a friend from a list belonging to a local user, call the DeleteFriend function.
When the operation is complete, a delegate of type FOnDeleteFriendComplete will be called.
It may be possible for a friend to exist in multiple lists on some online services; if this is the case, this function will only remove the friend from the specified list.
Dealing with Players Met Online
Online services often keep a separate list of players that a user has encountered recently, such as in a public gaming session, but has not added to the friends list or blocked. Like friends lists, the list of recently-met players is handled by querying the online service and then caching the list.
Retrieving the List of Recently-Met Players
The QueryRecentPlayers makes an asynchronous call to the online service, calling a delegate of type FOnQueryRecentPlayersComplete upon completion.
If successful, the Friends Interface will cache the list locally.
Examining Recently-Met Players
Once a successful call to QueryRecentPlayers has retrieved the list of recently-met players, the GetRecentPlayers function will return the cached array.
The individual elements of the array contain the user's data as well as a function to tell when the player was last seen online.
Managing the Block List
Many online services provide the ability for a user to prevent specific other users from contacting or playing with them through the service. The Friends Interface can retrieve and cache a list of blocked users, as well as utilize the online service's block and unblock features.
Listing Currently-Blocked Users
To retrieve the list of blocked users, call the QueryBlockedPlayers function.
This function is asynchronous, and will call a delegate of type FOnQueryBlockedPlayersComplete when it completes.
In addition, any changes made to the list of blocked users will result in notification through an FOnBlockListChange delegate.
Blocking and Unblocking Users
The BlockPlayer and UnblockPlayer functions will make asynchronous calls to the online service, requesting that a specific player, identified by an FUniqueNetId, be blocked or unblocked by a local player.
When these operations complete, they will return success or failure information through delegates of type FOnBlockedPlayerComplete and FOnUnblockedPlayerComplete, respectively.