GOG GALAXY SDK Documentation
IFriends Class Referenceabstract

The interface for managing social info and activities. More...

#include <IFriends.h>

Public Member Functions

virtual AvatarCriteria GetDefaultAvatarCriteria ()=0
 Returns the default avatar criteria. More...
 
virtual void SetDefaultAvatarCriteria (AvatarCriteria defaultAvatarCriteria)=0
 Sets the default avatar criteria. More...
 
virtual void RequestUserInformation (GalaxyID userID, AvatarCriteria avatarCriteria=AVATAR_TYPE_NONE, IUserInformationRetrieveListener *const listener=NULL)=0
 Performs a request for information about specified user. More...
 
virtual bool IsUserInformationAvailable (GalaxyID userID)=0
 Checks if the information of specified user is available. More...
 
virtual const char * GetPersonaName ()=0
 Returns the user's nickname. More...
 
virtual void GetPersonaNameCopy (char *buffer, uint32_t bufferLength)=0
 Copies the user's nickname to a buffer. More...
 
virtual PersonaState GetPersonaState ()=0
 Returns the user's state. More...
 
virtual const char * GetFriendPersonaName (GalaxyID userID)=0
 Returns the nickname of a specified user. More...
 
virtual void GetFriendPersonaNameCopy (GalaxyID userID, char *buffer, uint32_t bufferLength)=0
 Copies the nickname of a specified user. More...
 
virtual PersonaState GetFriendPersonaState (GalaxyID userID)=0
 Returns the state of a specified user. More...
 
virtual const char * GetFriendAvatarUrl (GalaxyID userID, AvatarType avatarType)=0
 Returns the URL of the avatar of a specified user. More...
 
virtual void GetFriendAvatarUrlCopy (GalaxyID userID, AvatarType avatarType, char *buffer, uint32_t bufferLength)=0
 Copies URL of the avatar of a specified user. More...
 
virtual uint32_t GetFriendAvatarImageID (GalaxyID userID, AvatarType avatarType)=0
 Returns the ID of the avatar of a specified user. More...
 
virtual void GetFriendAvatarImageRGBA (GalaxyID userID, AvatarType avatarType, void *buffer, uint32_t bufferLength)=0
 Copies the avatar of a specified user. More...
 
virtual bool IsFriendAvatarImageRGBAAvailable (GalaxyID userID, AvatarType avatarType)=0
 Checks if a specified avatar image is available. More...
 
virtual void RequestFriendList (IFriendListListener *const listener=NULL)=0
 Performs a request for the user's list of friends. More...
 
virtual bool IsFriend (GalaxyID userID)=0
 Checks if a specified user is a friend. More...
 
virtual uint32_t GetFriendCount ()=0
 Returns the number of retrieved friends in the user's list of friends. More...
 
virtual GalaxyID GetFriendByIndex (uint32_t index)=0
 Returns the GalaxyID for a friend. More...
 
virtual void SendFriendInvitation (GalaxyID userID, IFriendInvitationSendListener *const listener=NULL)=0
 Sends a friend invitation. More...
 
virtual void RequestFriendInvitationList (IFriendInvitationListRetrieveListener *const listener=NULL)=0
 Performs a request for the user's list of incoming friend invitations. More...
 
virtual void RequestSentFriendInvitationList (ISentFriendInvitationListRetrieveListener *const listener=NULL)=0
 Performs a request for the user's list of outgoing friend invitations. More...
 
virtual uint32_t GetFriendInvitationCount ()=0
 Returns the number of retrieved friend invitations. More...
 
virtual void GetFriendInvitationByIndex (uint32_t index, GalaxyID &userID, uint32_t &sendTime)=0
 Reads the details of the friend invitation. More...
 
virtual void RespondToFriendInvitation (GalaxyID userID, bool accept, IFriendInvitationRespondToListener *const listener=NULL)=0
 Responds to the friend invitation. More...
 
virtual void DeleteFriend (GalaxyID userID, IFriendDeleteListener *const listener=NULL)=0
 Removes a user from the friend list. More...
 
virtual void SetRichPresence (const char *key, const char *value, IRichPresenceChangeListener *const listener=NULL)=0
 Sets the variable value under a specified name. More...
 
virtual void DeleteRichPresence (const char *key, IRichPresenceChangeListener *const listener=NULL)=0
 Removes the variable value under a specified name. More...
 
virtual void ClearRichPresence (IRichPresenceChangeListener *const listener=NULL)=0
 Removes all rich presence data for the user. More...
 
virtual void RequestRichPresence (GalaxyID userID=GalaxyID(), IRichPresenceRetrieveListener *const listener=NULL)=0
 Performs a request for the user's rich presence. More...
 
virtual const char * GetRichPresence (const char *key, GalaxyID userID=GalaxyID())=0
 Returns the rich presence of a specified user. More...
 
virtual void GetRichPresenceCopy (const char *key, char *buffer, uint32_t bufferLength, GalaxyID userID=GalaxyID())=0
 Copies the rich presence of a specified user to a buffer. More...
 
virtual uint32_t GetRichPresenceCount (GalaxyID userID=GalaxyID())=0
 Returns the number of retrieved properties in user's rich presence. More...
 
virtual void GetRichPresenceByIndex (uint32_t index, char *key, uint32_t keyLength, char *value, uint32_t valueLength, GalaxyID userID=GalaxyID())=0
 Returns a property from the rich presence storage by index. More...
 
virtual const char * GetRichPresenceKeyByIndex (uint32_t index, GalaxyID userID=GalaxyID())=0
 Returns a key from the rich presence storage by index. More...
 
virtual void GetRichPresenceKeyByIndexCopy (uint32_t index, char *buffer, uint32_t bufferLength, GalaxyID userID=GalaxyID())=0
 Copies a key from the rich presence storage by index to a buffer. More...
 
virtual void ShowOverlayInviteDialog (const char *connectionString)=0
 Shows game invitation dialog that allows to invite users to game. More...
 
virtual void SendInvitation (GalaxyID userID, const char *connectionString, ISendInvitationListener *const listener=NULL)=0
 Sends a game invitation without using the overlay. More...
 
virtual void FindUser (const char *userSpecifier, IUserFindListener *const listener=NULL)=0
 Finds a specified user. More...
 
virtual bool IsUserInTheSameGame (GalaxyID userID) const =0
 Checks if a specified user is playing the same game. More...
 

Detailed Description

The interface for managing social info and activities.

Member Function Documentation

◆ ClearRichPresence()

virtual void ClearRichPresence ( IRichPresenceChangeListener *const  listener = NULL)
pure virtual

Removes all rich presence data for the user.

This call in asynchronous. Responses come to the IRichPresenceChangeListener.

Parameters
[in]listenerThe listener for specific operation.

◆ DeleteFriend()

virtual void DeleteFriend ( GalaxyID  userID,
IFriendDeleteListener *const  listener = NULL 
)
pure virtual

Removes a user from the friend list.

This call in asynchronous. Responses come to the IFriendDeleteListener.

Parameters
[in]userIDThe ID of the user to be removed from the friend list.
[in]listenerThe listener for specific operation.

◆ DeleteRichPresence()

virtual void DeleteRichPresence ( const char *  key,
IRichPresenceChangeListener *const  listener = NULL 
)
pure virtual

Removes the variable value under a specified name.

If the variable doesn't exist method call has no effect.

This call in asynchronous. Responses come to the IRichPresenceChangeListener.

Parameters
[in]keyThe name of the variable to be removed.
[in]listenerThe listener for specific operation.

◆ FindUser()

virtual void FindUser ( const char *  userSpecifier,
IUserFindListener *const  listener = NULL 
)
pure virtual

Finds a specified user.

This call is asynchronous. Responses come to the IUserFindListener.

Searches for the user given either a username or an email address. Only exact match will be returned.

Parameters
[in]userSpecifierThe specifier of the user.
[in]listenerThe listener for specific operation.

◆ GetDefaultAvatarCriteria()

virtual AvatarCriteria GetDefaultAvatarCriteria ( )
pure virtual

Returns the default avatar criteria.

Returns
The bit sum of default AvatarType.

◆ GetFriendAvatarImageID()

virtual uint32_t GetFriendAvatarImageID ( GalaxyID  userID,
AvatarType  avatarType 
)
pure virtual

Returns the ID of the avatar of a specified user.

Precondition
Retrieve the avatar image first by calling RequestUserInformation() with appropriate avatar criteria.
Parameters
[in]userIDThe ID of the user.
[in]avatarTypeThe type of avatar.
Returns
The ID of the avatar image.

◆ GetFriendAvatarImageRGBA()

virtual void GetFriendAvatarImageRGBA ( GalaxyID  userID,
AvatarType  avatarType,
void *  buffer,
uint32_t  bufferLength 
)
pure virtual

Copies the avatar of a specified user.

Precondition
Retrieve the avatar image first by calling RequestUserInformation() with appropriate avatar criteria.
The size of the output buffer should be 4 * height * width * sizeof(char).
Parameters
[in]userIDThe ID of the user.
[in]avatarTypeThe type of avatar.
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.

◆ GetFriendAvatarUrl()

virtual const char* GetFriendAvatarUrl ( GalaxyID  userID,
AvatarType  avatarType 
)
pure virtual

Returns the URL of the avatar of a specified user.

Remarks
This call is not thread-safe as opposed to GetFriendAvatarUrlCopy().
Precondition
You might need to retrieve the data first by calling RequestUserInformation().
Parameters
[in]userIDThe ID of the user.
[in]avatarTypeThe type of avatar.
Returns
The URL of the avatar.

◆ GetFriendAvatarUrlCopy()

virtual void GetFriendAvatarUrlCopy ( GalaxyID  userID,
AvatarType  avatarType,
char *  buffer,
uint32_t  bufferLength 
)
pure virtual

Copies URL of the avatar of a specified user.

Precondition
You might need to retrieve the data first by calling RequestUserInformation().
Parameters
[in]userIDThe ID of the user.
[in]avatarTypeThe type of avatar.
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.

◆ GetFriendByIndex()

virtual GalaxyID GetFriendByIndex ( uint32_t  index)
pure virtual

Returns the GalaxyID for a friend.

Precondition
Retrieve the list of friends first by calling RequestFriendList().
Parameters
[in]indexIndex as an integer in the range of [0, number of friends).
Returns
The GalaxyID of the friend.

◆ GetFriendCount()

virtual uint32_t GetFriendCount ( )
pure virtual

Returns the number of retrieved friends in the user's list of friends.

Precondition
Retrieve the list of friends first by calling RequestFriendList().
Returns
The number of retrieved friends, or 0 if failed.

◆ GetFriendInvitationByIndex()

virtual void GetFriendInvitationByIndex ( uint32_t  index,
GalaxyID userID,
uint32_t &  sendTime 
)
pure virtual

Reads the details of the friend invitation.

Remarks
This function can be used only in IFriendInvitationListRetrieveListener callback.
Parameters
[in]indexIndex as an integer in the range of [0, number of friend invitations).
[out]userIDThe ID of the user who sent the invitation.
[out]sendTimeThe time at which the friend invitation was sent.

◆ GetFriendInvitationCount()

virtual uint32_t GetFriendInvitationCount ( )
pure virtual

Returns the number of retrieved friend invitations.

Remarks
This function can be used only in IFriendInvitationListRetrieveListener callback.
Returns
The number of retrieved friend invitations, or 0 if failed.

◆ GetFriendPersonaName()

virtual const char* GetFriendPersonaName ( GalaxyID  userID)
pure virtual

Returns the nickname of a specified user.

Remarks
This call is not thread-safe as opposed to GetFriendPersonaNameCopy().
Precondition
You might need to retrieve the data first by calling RequestUserInformation().
Parameters
[in]userIDThe ID of the user.
Returns
The nickname of the user.

◆ GetFriendPersonaNameCopy()

virtual void GetFriendPersonaNameCopy ( GalaxyID  userID,
char *  buffer,
uint32_t  bufferLength 
)
pure virtual

Copies the nickname of a specified user.

Precondition
You might need to retrieve the data first by calling RequestUserInformation().
Parameters
[in]userIDThe ID of the user.
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.

◆ GetFriendPersonaState()

virtual PersonaState GetFriendPersonaState ( GalaxyID  userID)
pure virtual

Returns the state of a specified user.

Precondition
You might need to retrieve the data first by calling RequestUserInformation().
Parameters
[in]userIDThe ID of the user.
Returns
The state of the user.

◆ GetPersonaName()

virtual const char* GetPersonaName ( )
pure virtual

Returns the user's nickname.

Remarks
This call is not thread-safe as opposed to GetPersonaNameCopy().
Returns
The nickname of the user.

◆ GetPersonaNameCopy()

virtual void GetPersonaNameCopy ( char *  buffer,
uint32_t  bufferLength 
)
pure virtual

Copies the user's nickname to a buffer.

Parameters
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.

◆ GetPersonaState()

virtual PersonaState GetPersonaState ( )
pure virtual

Returns the user's state.

Returns
The state of the user.

◆ GetRichPresence()

virtual const char* GetRichPresence ( const char *  key,
GalaxyID  userID = GalaxyID() 
)
pure virtual

Returns the rich presence of a specified user.

Remarks
This call is not thread-safe as opposed to GetRichPresenceCopy().
Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]userIDThe ID of the user.
[in]keyThe name of the property of the user's rich presence.
Returns
The rich presence of the user.

◆ GetRichPresenceByIndex()

virtual void GetRichPresenceByIndex ( uint32_t  index,
char *  key,
uint32_t  keyLength,
char *  value,
uint32_t  valueLength,
GalaxyID  userID = GalaxyID() 
)
pure virtual

Returns a property from the rich presence storage by index.

Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]indexIndex as an integer in the range of [0, number of entries).
[in,out]keyThe name of the property of the rich presence storage.
[in]keyLengthThe length of the name of the property of the rich presence storage.
[in,out]valueThe value of the property of the rich presence storage.
[in]valueLengthThe length of the value of the property of the rich presence storage.
[in]userIDThe ID of the user.

◆ GetRichPresenceCopy()

virtual void GetRichPresenceCopy ( const char *  key,
char *  buffer,
uint32_t  bufferLength,
GalaxyID  userID = GalaxyID() 
)
pure virtual

Copies the rich presence of a specified user to a buffer.

Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]keyThe name of the property of the user's rich presence.
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.
[in]userIDThe ID of the user.

◆ GetRichPresenceCount()

virtual uint32_t GetRichPresenceCount ( GalaxyID  userID = GalaxyID())
pure virtual

Returns the number of retrieved properties in user's rich presence.

Parameters
[in]userIDThe ID of the user.
Returns
The number of retrieved keys, or 0 if failed.

◆ GetRichPresenceKeyByIndex()

virtual const char* GetRichPresenceKeyByIndex ( uint32_t  index,
GalaxyID  userID = GalaxyID() 
)
pure virtual

Returns a key from the rich presence storage by index.

Remarks
This call is not thread-safe as opposed to GetRichPresenceKeyByIndexCopy().
Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]indexIndex as an integer in the range of [0, number of entries).
[in]userIDThe ID of the user.
Returns
The rich presence key under the index of the user.

◆ GetRichPresenceKeyByIndexCopy()

virtual void GetRichPresenceKeyByIndexCopy ( uint32_t  index,
char *  buffer,
uint32_t  bufferLength,
GalaxyID  userID = GalaxyID() 
)
pure virtual

Copies a key from the rich presence storage by index to a buffer.

Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]indexIndex as an integer in the range of [0, number of entries).
[in,out]bufferThe output buffer.
[in]bufferLengthThe size of the output buffer.
[in]userIDThe ID of the user.

◆ IsFriend()

virtual bool IsFriend ( GalaxyID  userID)
pure virtual

Checks if a specified user is a friend.

Precondition
Retrieve the list of friends first by calling RequestFriendList().
Parameters
[in]userIDThe ID of the user.
Returns
true if the specified user is a friend, false otherwise.

◆ IsFriendAvatarImageRGBAAvailable()

virtual bool IsFriendAvatarImageRGBAAvailable ( GalaxyID  userID,
AvatarType  avatarType 
)
pure virtual

Checks if a specified avatar image is available.

Parameters
[in]userIDThe ID of the user.
[in]avatarTypeThe type of avatar.
Returns
true if the specified avatar image is available, false otherwise.

◆ IsUserInformationAvailable()

virtual bool IsUserInformationAvailable ( GalaxyID  userID)
pure virtual

Checks if the information of specified user is available.

The information can be retrieved by calling RequestUserInformation().

Parameters
[in]userIDThe ID of the user.
Returns
true if the information of the user is available, false otherwise.

◆ IsUserInTheSameGame()

virtual bool IsUserInTheSameGame ( GalaxyID  userID) const
pure virtual

Checks if a specified user is playing the same game.

Precondition
Retrieve the rich presence first by calling RequestRichPresence().
Parameters
[in]userIDThe ID of the user.
Returns
true if the specified user is playing the same game, false otherwise.

◆ RequestFriendInvitationList()

virtual void RequestFriendInvitationList ( IFriendInvitationListRetrieveListener *const  listener = NULL)
pure virtual

Performs a request for the user's list of incoming friend invitations.

This call is asynchronous. Responses come to the IFriendInvitationListRetrieveListener.

Parameters
[in]listenerThe listener for specific operation.

◆ RequestFriendList()

virtual void RequestFriendList ( IFriendListListener *const  listener = NULL)
pure virtual

Performs a request for the user's list of friends.

This call is asynchronous. Responses come to the IFriendListListener.

Parameters
[in]listenerThe listener for specific operation.

◆ RequestRichPresence()

virtual void RequestRichPresence ( GalaxyID  userID = GalaxyID(),
IRichPresenceRetrieveListener *const  listener = NULL 
)
pure virtual

Performs a request for the user's rich presence.

This call is asynchronous. Responses come both to the IRichPresenceListener and IRichPresenceRetrieveListener.

Parameters
[in]userIDThe ID of the user.
[in]listenerThe listener for specific operation.

◆ RequestSentFriendInvitationList()

virtual void RequestSentFriendInvitationList ( ISentFriendInvitationListRetrieveListener *const  listener = NULL)
pure virtual

Performs a request for the user's list of outgoing friend invitations.

This call is asynchronous. Responses come to the ISentFriendInvitationListRetrieveListener.

Parameters
[in]listenerThe listener for specific operation.

◆ RequestUserInformation()

virtual void RequestUserInformation ( GalaxyID  userID,
AvatarCriteria  avatarCriteria = AVATAR_TYPE_NONE,
IUserInformationRetrieveListener *const  listener = NULL 
)
pure virtual

Performs a request for information about specified user.

This call is asynchronous. Responses come both to the IPersonaDataChangedListener and to the IUserInformationRetrieveListener.

Remarks
This call is performed automatically for friends (after requesting the list of friends) and fellow lobby members (after entering a lobby or getting a notification about some other user joining it), therefore in many cases there is no need for you to call it manually and all you should do is wait for the appropriate callback to come to the IPersonaDataChangedListener.
User avatar will be downloaded according to bit sum of avatarCriteria and defaultAvatarCriteria set by calling SetDefaultAvatarCriteria().
Parameters
[in]userIDThe ID of the user.
[in]avatarCriteriaThe bit sum of the AvatarType.
[in]listenerThe listener for specific operation.

◆ RespondToFriendInvitation()

virtual void RespondToFriendInvitation ( GalaxyID  userID,
bool  accept,
IFriendInvitationRespondToListener *const  listener = NULL 
)
pure virtual

Responds to the friend invitation.

This call is asynchronous. Responses come to the IFriendInvitationRespondToListener.

Parameters
[in]userIDThe ID of the user who sent the friend invitation.
[in]acceptTrue when accepting the invitation, false when declining.
[in]listenerThe listener for specific operation.

◆ SendFriendInvitation()

virtual void SendFriendInvitation ( GalaxyID  userID,
IFriendInvitationSendListener *const  listener = NULL 
)
pure virtual

Sends a friend invitation.

This call is asynchronous. Responses come to the IFriendInvitationSendListener.

Parameters
[in]userIDThe ID of the user.
[in]listenerThe listener for specific operation.

◆ SendInvitation()

virtual void SendInvitation ( GalaxyID  userID,
const char *  connectionString,
ISendInvitationListener *const  listener = NULL 
)
pure virtual

Sends a game invitation without using the overlay.

This call is asynchronous. Responses come to the ISendInvitationListener.

If invited user accepts the invitation, the connection string gets added to the command-line parameters for launching the game. If the game is already running, the connection string comes to the IGameInvitationReceivedListener, or to the IGameJoinRequestedListener if accepted by the user on the overlay.

Parameters
[in]userIDThe ID of the user.
[in]connectionStringThe string which contains connection info with the limit of 4095 bytes.
[in]listenerThe listener for specific operation.

◆ SetDefaultAvatarCriteria()

virtual void SetDefaultAvatarCriteria ( AvatarCriteria  defaultAvatarCriteria)
pure virtual

Sets the default avatar criteria.

Remarks
The avatar criteria will be used for automated downloads of user information, as well as additional criteria in case of calling RequestUserInformation().
Parameters
[in]defaultAvatarCriteriaThe bit sum of default AvatarType.

◆ SetRichPresence()

virtual void SetRichPresence ( const char *  key,
const char *  value,
IRichPresenceChangeListener *const  listener = NULL 
)
pure virtual

Sets the variable value under a specified name.

There are three keys that can be used:

  • "status" - The description visible in Galaxy Client with the limit of 3000 bytes.
  • "metadata" - The metadata that describes the status to other instances of the game with the limit of 2048 bytes.
  • "connect" - The string which contains connection info with the limit of 4095 bytes. It can be regarded as a passive version of IFriends::SendInvitation() because it allows friends that notice the rich presence to join a multiplayer game.

User must be signed in through Galaxy.

Passing NULL value removes the entry.

This call in asynchronous. Responses come to the IRichPresenceChangeListener.

Parameters
[in]keyThe name of the property of the user's rich presence.
[in]valueThe value of the property to set.
[in]listenerThe listener for specific operation.

◆ ShowOverlayInviteDialog()

virtual void ShowOverlayInviteDialog ( const char *  connectionString)
pure virtual

Shows game invitation dialog that allows to invite users to game.

If invited user accepts the invitation, the connection string gets added to the command-line parameters for launching the game. If the game is already running, the connection string comes to the IGameInvitationReceivedListener, or to the IGameJoinRequestedListener if accepted by the user on the overlay.

Precondition
For this call to work, the overlay needs to be initialized first. To check whether the overlay is initialized, call IUtils::GetOverlayState().
Parameters
[in]connectionStringThe string which contains connection info with the limit of 4095 bytes.