512 lines
18 KiB
C
512 lines
18 KiB
C
/**
|
|
* @file UplayFriends.h
|
|
* @brief The Uplay PC Friends API
|
|
*/
|
|
#ifndef UPLAY_FRIENDS_H
|
|
#define UPLAY_FRIENDS_H
|
|
|
|
#include "Uplay/UplayEvent.h"
|
|
#include "Uplay/UplayUser.h"
|
|
#include "Uplay/UplayOverlapped.h"
|
|
#include "Uplay/UplayPresence.h"
|
|
#include "Uplay/UplayTypes.h"
|
|
|
|
#if _MSC_VER > 1000
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifndef UPLAY_API
|
|
#ifdef _WIN32
|
|
#if defined EXPORTING_DLL
|
|
#define UPLAY_API __declspec(dllexport)
|
|
#elif defined IMPORTING_DLL
|
|
#define UPLAY_API __declspec(dllimport)
|
|
#else
|
|
#define UPLAY_API
|
|
#endif
|
|
#endif // _Win32
|
|
|
|
#ifdef __APPLE__
|
|
#define UPLAY_API __attribute__((visibility("default")))
|
|
#define __cdecl
|
|
#endif // __APPLE__
|
|
#endif // UPLAY_API
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif // __cplusplus
|
|
|
|
/**
|
|
* @defgroup friends Friends
|
|
* @brief Functions for the friends subsystem
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_FRIENDS_Relationship
|
|
* @brief Relationship between a user and the current one
|
|
*/
|
|
enum UPLAY_FRIENDS_Relationship
|
|
{
|
|
/** There is no relation */
|
|
UPLAY_FRIENDS_Relationship_None,
|
|
/** The user is a friend */
|
|
UPLAY_FRIENDS_Relationship_Friends,
|
|
/** A friendship request has been sent to the user */
|
|
UPLAY_FRIENDS_Relationship_FriendRequestSent,
|
|
/** A friendship request has been received from the user */
|
|
UPLAY_FRIENDS_Relationship_FriendRequestReceived
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_FRIENDS_InitFlags
|
|
* @brief Flags for the ::UPLAY_FRIENDS_Init() call
|
|
*/
|
|
enum UPLAY_FRIENDS_InitFlags
|
|
{
|
|
/** Place holder value */
|
|
UPLAY_FRIENDS_InitFlags_None = 0
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_FRIENDS_FriendListFilter
|
|
* @brief Filter flags for the ::UPLAY_FRIENDS_GetFriendList() call
|
|
*/
|
|
enum UPLAY_FRIENDS_FriendListFilter
|
|
{
|
|
/** Include sent friend requests in the list */
|
|
UPLAY_FRIENDS_FriendListFilter_FriendRequestSent = 0x1,
|
|
/** Include received friend requests in the list */
|
|
UPLAY_FRIENDS_FriendListFilter_FriendRequestReceived = 0x2,
|
|
/** Include friends in the list */
|
|
UPLAY_FRIENDS_FriendListFilter_Friends = 0x4,
|
|
/** Include blacklisted users in the list */
|
|
UPLAY_FRIENDS_FriendListFilter_BlackListed = 0x8,
|
|
|
|
/** Include everything */
|
|
UPLAY_FRIENDS_FriendListFilter_All = 0xff
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_FRIENDS_FriendSelectionUIResultStatus
|
|
* @brief Friend selection UI result statuses
|
|
*/
|
|
enum UPLAY_FRIENDS_FriendSelectionUIResultStatus
|
|
{
|
|
/** Friend selection was canceled. */
|
|
UPLAY_FRIENDS_FriendSelectionUIResultStatus_Canceled = 0,
|
|
/** A friend was selected. */
|
|
UPLAY_FRIENDS_FriendSelectionUIResultStatus_Ok,
|
|
/** No friend was selected. */
|
|
UPLAY_FRIENDS_FriendSelectionUIResultStatus_EmptyList
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_FRIENDS_MenuItemMode
|
|
* @brief Menu item mode flags for the ::UPLAY_FRIENDS_EnableFriendMenuItem call.
|
|
*/
|
|
enum UPLAY_FRIENDS_MenuItemMode
|
|
{
|
|
/** Show the menu item for all friends in the same party */
|
|
UPLAY_FRIENDS_MenuItemMode_EnableForFriendsInParty = 1,
|
|
/** Show the menu item for all friends playing the same game */
|
|
UPLAY_FRIENDS_MenuItemMode_EnableForFriendsInSameGame = 2,
|
|
/** Show the menu item for all friends playing in the same game session (server) as you */
|
|
UPLAY_FRIENDS_MenuItemMode_EnableForFriendsInSameGameSession = 4,
|
|
/** Show the menu item for the specified friends (can not be combined with any other flag) */
|
|
UPLAY_FRIENDS_MenuItemMode_Manual = 8
|
|
};
|
|
|
|
#pragma pack(push, 8)
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_Friend
|
|
* @brief Contains information about a user
|
|
*/
|
|
typedef struct UPLAY_FRIENDS_Friend_t
|
|
{
|
|
/** Null terminated UTF-8 string representing the account ID of the user. */
|
|
const char* accountIdUtf8;
|
|
/** Null terminated UTF-8 string representing the nick of the user. */
|
|
const char* nickUtf8;
|
|
/** The relationship with the current user. See enum ::UPLAY_FRIENDS_Relationship for valid values. */
|
|
UPLAY_uint32 relationship;
|
|
/** DEPRECATED! The Uplay avatar ID of the user. */
|
|
UPLAY_uint32 avatarId;
|
|
/** The online status of the user. */
|
|
struct UPLAY_PRESENCE_Presence* presence;
|
|
/** The blacklist status of the user. Valid values are UPLAY_true or UPLAY_false. */
|
|
UPLAY_uint8 blackListed;
|
|
} UPLAY_FRIENDS_Friend;
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_FriendList
|
|
* @brief Structure containing a list of friends
|
|
*/
|
|
typedef struct UPLAY_FRIENDS_FriendList_t
|
|
{
|
|
/** The number of entries in the \c list member */
|
|
UPLAY_uint32 count;
|
|
/** A list of users in the friend list */
|
|
const UPLAY_FRIENDS_Friend** list;
|
|
} UPLAY_FRIENDS_FriendList;
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_FriendSelectionUIResult
|
|
* @brief Result structure for the ::UPLAY_FRIENDS_ShowFriendSelectionUI() call
|
|
*
|
|
* If the \c status member is \c UPLAY_FRIENDS_FriendSelectionUIResultStatus_Ok, then
|
|
* \c accountIdUtf8 will contain the account ID of the selected user, otherwise it will
|
|
* be left uninitialized.
|
|
*/
|
|
typedef struct UPLAY_FRIENDS_FriendSelectionUIResult_t
|
|
{
|
|
/** Status value. See enum ::UPLAY_FRIENDS_FriendSelectionUIResultStatus for valid values. */
|
|
UPLAY_uint32 status;
|
|
/** Null terminated UTF-8 string containing the account ID of the selected user */
|
|
char accountIdUft8[128];
|
|
} UPLAY_FRIENDS_FriendSelectionUIResult;
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_MenuItemFilter
|
|
* @brief Filter struct for the ::UPLAY_FRIENDS_EnableFriendMenuItem call.
|
|
*/
|
|
typedef struct UPLAY_FRIENDS_MenuItemFilter_t
|
|
{
|
|
/** List of account IDs to filter */
|
|
const char** enabledAccountIdsUtf8;
|
|
/** Number of elements in the list */
|
|
UPLAY_uint32 count;
|
|
} UPLAY_FRIENDS_MenuItemFilter;
|
|
|
|
/*======================
|
|
* Event structs
|
|
*/
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_FriendListUpdated
|
|
* @brief Event struct for friend list updates
|
|
*/
|
|
struct UPLAY_FRIENDS_FriendListUpdated
|
|
{
|
|
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_FriendUpdated
|
|
* @brief Event struct for friend updates
|
|
*/
|
|
struct UPLAY_FRIENDS_FriendUpdated
|
|
{
|
|
/** The previous state of the updated friend */
|
|
const UPLAY_FRIENDS_Friend* previousState;
|
|
/** The state of the updated friend */
|
|
const UPLAY_FRIENDS_Friend* updated;
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_GameInviteAccepted
|
|
* @brief Event struct for accepted game invites
|
|
*/
|
|
struct UPLAY_FRIENDS_GameInviteAccepted
|
|
{
|
|
/** The game session for the invite */
|
|
UPLAY_USER_GameSession* gameSession;
|
|
/** Null terminated UTF-8 string containing the account ID of the user who sent the invite */
|
|
const char* accountIdUtf8;
|
|
};
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_FRIENDS_FriendMenuItemSelected
|
|
* @brief Event struct for selected friend list menu items
|
|
*/
|
|
struct UPLAY_FRIENDS_FriendMenuItemSelected
|
|
{
|
|
/** The selected custom menu item */
|
|
UPLAY_uint32 menuItemId;
|
|
/** The friend for which the menu item was selected */
|
|
const UPLAY_FRIENDS_Friend* selectedFriend;
|
|
};
|
|
|
|
#pragma pack(pop)
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_Init(UPLAY_uint32)
|
|
* @brief Initialize the friends subsystem.
|
|
*
|
|
* This function has to be called before the any other friends function.
|
|
*
|
|
* @param aFlags
|
|
* Bitmask with flags from ::UPLAY_FRIENDS_InitFlags
|
|
*
|
|
* @returns Non-zero on success
|
|
*
|
|
* @note For details on the error check ::UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_Init(
|
|
UPLAY_uint32 aFlags);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_GetFriendList(UPLAY_uint32, UPLAY_FRIENDS_FriendList*)
|
|
* @brief Gets list of friends
|
|
*
|
|
* The list of friends will contain all users with a relationship to the current user,
|
|
* filtered according to the \c aFriendListFilter parameter.
|
|
*
|
|
* @param aFriendListFilter
|
|
* Bitmask with filter flags from ::UPLAY_FRIENDS_FriendListFilter
|
|
* @param aOutFriendList
|
|
* The resulting friend list will be stored here
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_GetFriendList(
|
|
UPLAY_uint32 aFriendListFilter,
|
|
UPLAY_FRIENDS_FriendList* aOutFriendList);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_RequestFriendship(const char*, UPLAY_Overlapped*)
|
|
* @brief Sends friendship request to user
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_ConnectionError | Unknown error
|
|
* UPLAY_OverlappedResult_NotFound | The user could not be found
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aSearchStringUtf8
|
|
* Null terminated UTF-8 string containing either the account ID, email or the Uplay profile name of the user
|
|
* @param aOverlapped
|
|
* Overlapped structure
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_RequestFriendship(
|
|
const char* aSearchStringUtf8,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn UPLAY_uint8 UPLAY_FRIENDS_IsFriend(const char*)
|
|
* @brief Checks if a user is a friend.
|
|
*
|
|
* @param aAccountIdUtf8
|
|
* Null terminated UTF-8 string containing the account ID of the user
|
|
*
|
|
* @returns One if the user is a friend, zero otherwise.
|
|
*/
|
|
UPLAY_uint8
|
|
UPLAY_API UPLAY_FRIENDS_IsFriend(
|
|
const char* aAccountIdUtf8);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_AddToBlackList(const char*, UPLAY_Overlapped*)
|
|
* @brief Blacklist a user
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_ConnectionError | Unknown error
|
|
* UPLAY_OverlappedResult_NotFound | The user could not be found
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aAccountIdUtf8
|
|
* Null terminated UTF-8 string containing the account ID of the user
|
|
* @param aOverlapped
|
|
* Overlapped structure
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_AddToBlackList(
|
|
const char* aAccountIdUtf8,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn UPLAY_uint8 UPLAY_FRIENDS_IsBlackListed(const char*)
|
|
* @brief Checks if a user is blacklisted
|
|
*
|
|
* @param aAccountIdUtf8
|
|
* Null terminated UTF-8 string containing the account ID of the user
|
|
*
|
|
* @returns One if the user is blacklisted, zero otherwise.
|
|
*/
|
|
UPLAY_uint8
|
|
UPLAY_API UPLAY_FRIENDS_IsBlackListed(
|
|
const char* aAccountIdUtf8);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_ShowFriendSelectionUI(const char**,
|
|
* UPLAY_uint32,
|
|
* UPLAY_Overlapped*,
|
|
* UPLAY_FRIENDS_FriendSelectionUIResult*)
|
|
* @brief Show friend selection UI
|
|
*
|
|
* This function will open the overlay and let the user select a friend from his
|
|
* friend list.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_ConnectionError | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aAccountIdFilterListUtf8
|
|
* Array of null terminated UTF-8 strings containing the account IDs of
|
|
* the friends to show. \c NULL for no filter.
|
|
* @param aAccountIdFilterListLength
|
|
* Number of entries in \c aAccountIdFilterListUtf8.
|
|
* @param aOverlapped
|
|
* Overlapped structure
|
|
* @param aOutResult
|
|
* The selected friend and status. Populated when the operation completes.
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_ShowFriendSelectionUI(
|
|
const char** aAccountIdFilterListUtf8,
|
|
UPLAY_uint32 aAccountIdFilterListLength,
|
|
UPLAY_Overlapped* aOverlapped,
|
|
UPLAY_FRIENDS_FriendSelectionUIResult* aOutResult);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_EnableFriendMenuItem(UPLAY_uint32, UPLAY_uint32, UPLAY_FRIENDS_MenuItemFilter*)
|
|
* @brief Enable a custom friend list menu item
|
|
*
|
|
* When the menu item is clicked a UPLAY_FRIENDS_FriendMenuItemSelected will be received.
|
|
*
|
|
* @param aId
|
|
* Menu item ID to enable.
|
|
* @param aMenuItemMode
|
|
* Bitmask with flags from ::UPLAY_FRIENDS_MenuItemMode
|
|
* @param aFilter
|
|
* Filter users that the menu item should be enabled for. Only used if \c aMenuItemMode is \c UPLAY_FRIENDS_MenuItemMode_Manual.
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_EnableFriendMenuItem(
|
|
UPLAY_uint32 aId,
|
|
UPLAY_uint32 aMenuItemMode,
|
|
UPLAY_FRIENDS_MenuItemFilter* aFilter);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_DisableFriendMenuItem(UPLAY_uint32)
|
|
* @brief Disables a custom friend list menu item
|
|
*
|
|
* @param aId
|
|
* Menu item ID to disable.
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_DisableFriendMenuItem(
|
|
UPLAY_uint32 aId);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_InviteToGame(const char*, UPLAY_Overlapped*)
|
|
* @brief Invite a user to the current game session
|
|
*
|
|
* @note A game session needs to be set up with ::UPLAY_USER_SetGameSession() before
|
|
* this function can be called.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_ConnectionError | Unknown error
|
|
* UPLAY_OverlappedResult_NotFound | Invalid account ID
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aAccountIdUtf8
|
|
* Null terminated UTF-8 string containing the account ID of the user to invite
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error check ::UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_InviteToGame(
|
|
const char* aAccountIdUtf8,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_ShowInviteFriendsToGameUI(const char**, UPLAY_uint32)
|
|
* @brief Show invite friends to game UI
|
|
*
|
|
* This function will open the overlay and let the user invite friends to game from his
|
|
* friend list.
|
|
*
|
|
* @param aAccountIdFilterListUtf8
|
|
* Array of null terminated UTF-8 strings containing the account IDs of
|
|
* the friends to show. \c NULL for showing all online friends.
|
|
* @param aAccountIdFilterListLength
|
|
* Number of entries in \c aAccountIdFilterListUtf8.
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_ShowInviteFriendsToGameUI(
|
|
const char** aAccountIdFilterListUtf8,
|
|
UPLAY_uint32 aAccountIdFilterListLength);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_FRIENDS_AddPlayedWith(const char*, const char**, UPLAY_uint32)
|
|
* @brief For the game to inform about player interaction.
|
|
* This information will be used for friend suggestions in the platform.
|
|
*
|
|
* @note This call can be made with any account id. Not only with the player's friends.
|
|
*
|
|
* @param aDescriptionUtf8
|
|
* A null terminated UTF8-string with a detailed description of the context of the
|
|
* game that was played with other users. Max length: 256 bytes.
|
|
* Suggestion: name of a stage or course. *This text is not localized*.
|
|
* Game name or id should not be included.
|
|
* @param aAccountIdListUtf8
|
|
* List of account ids. Array of null terminated UTF-8 strings
|
|
* containing the account IDs of the players. Doesn't have to be a friend.
|
|
* @param aAccountIdListLength
|
|
* Number of entries in \c aAccountIdListUtf8.
|
|
*
|
|
* @returns Non-zero on success
|
|
* @note For details on the error call UPLAY_GetLastError()
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_FRIENDS_AddPlayedWith(
|
|
const char* aDescriptionUtf8,
|
|
const char** aAccountIdListUtf8,
|
|
UPLAY_uint32 aAccountIdListLength);
|
|
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif // __cplusplus
|
|
|
|
#endif // UPLAY_FRIENDS_H
|