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] listener The 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]	userID	The ID of the user to be removed from the friend list.
[in]	listener	The 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]	key	The name of the variable to be removed.
[in]	listener	The 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]	userSpecifier	The specifier of the user.
[in]	listener	The 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]	userID	The ID of the user.
[in]	avatarType	The 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]	userID	The ID of the user.
[in]	avatarType	The type of avatar.
[in,out]	buffer	The output buffer.
[in]	bufferLength	The 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]	userID	The ID of the user.
[in]	avatarType	The 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]	userID	The ID of the user.
[in]	avatarType	The type of avatar.
[in,out]	buffer	The output buffer.
[in]	bufferLength	The 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] index Index 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]	index	Index as an integer in the range of [0, number of friend invitations).
[out]	userID	The ID of the user who sent the invitation.
[out]	sendTime	The 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] userID The 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]	userID	The ID of the user.
[in,out]	buffer	The output buffer.
[in]	bufferLength	The 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] userID The 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]	buffer	The output buffer.
[in]	bufferLength	The 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]	userID	The ID of the user.
[in]	key	The 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]	index	Index as an integer in the range of [0, number of entries).
[in,out]	key	The name of the property of the rich presence storage.
[in]	keyLength	The length of the name of the property of the rich presence storage.
[in,out]	value	The value of the property of the rich presence storage.
[in]	valueLength	The length of the value of the property of the rich presence storage.
[in]	userID	The 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]	key	The name of the property of the user's rich presence.
[in,out]	buffer	The output buffer.
[in]	bufferLength	The size of the output buffer.
[in]	userID	The 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] userID The 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]	index	Index as an integer in the range of [0, number of entries).
[in]	userID	The 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]	index	Index as an integer in the range of [0, number of entries).
[in,out]	buffer	The output buffer.
[in]	bufferLength	The size of the output buffer.
[in]	userID	The 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] userID The 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]	userID	The ID of the user.
[in]	avatarType	The 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] userID The 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] userID The 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] listener The 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] listener The 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]	userID	The ID of the user.
[in]	listener	The 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] listener The 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]	userID	The ID of the user.
[in]	avatarCriteria	The bit sum of the AvatarType.
[in]	listener	The 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]	userID	The ID of the user who sent the friend invitation.
[in]	accept	True when accepting the invitation, false when declining.
[in]	listener	The 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]	userID	The ID of the user.
[in]	listener	The 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]	userID	The ID of the user.
[in]	connectionString	The string which contains connection info with the limit of 4095 bytes.
[in]	listener	The 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] defaultAvatarCriteria The 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]	key	The name of the property of the user's rich presence.
[in]	value	The value of the property to set.
[in]	listener	The 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] connectionString The string which contains connection info with the limit of 4095 bytes.

Public Member Functions

Detailed Description

Member Function Documentation

◆ ClearRichPresence()

◆ DeleteFriend()

◆ DeleteRichPresence()

◆ FindUser()

◆ GetDefaultAvatarCriteria()

◆ GetFriendAvatarImageID()

◆ GetFriendAvatarImageRGBA()

◆ GetFriendAvatarUrl()

◆ GetFriendAvatarUrlCopy()

◆ GetFriendByIndex()

◆ GetFriendCount()

◆ GetFriendInvitationByIndex()

◆ GetFriendInvitationCount()

◆ GetFriendPersonaName()

◆ GetFriendPersonaNameCopy()

◆ GetFriendPersonaState()

◆ GetPersonaName()

◆ GetPersonaNameCopy()

◆ GetPersonaState()

◆ GetRichPresence()

◆ GetRichPresenceByIndex()

◆ GetRichPresenceCopy()

◆ GetRichPresenceCount()

◆ GetRichPresenceKeyByIndex()

◆ GetRichPresenceKeyByIndexCopy()

◆ IsFriend()

◆ IsFriendAvatarImageRGBAAvailable()

◆ IsUserInformationAvailable()

◆ IsUserInTheSameGame()

◆ RequestFriendInvitationList()

◆ RequestFriendList()

◆ RequestRichPresence()

◆ RequestSentFriendInvitationList()

◆ RequestUserInformation()

◆ RespondToFriendInvitation()

◆ SendFriendInvitation()

◆ SendInvitation()

◆ SetDefaultAvatarCriteria()

◆ SetRichPresence()

◆ ShowOverlayInviteDialog()