frd.h
Go to the documentation of this file.
/**
* @file frd.h
* @brief Friend Services
*/
#pragma once
#include <3ds/mii.h>
#define FRIEND_SCREEN_NAME_SIZE 0xB ///< 11-byte UTF-16 screen name
#define FRIEND_COMMENT_SIZE 0x21 ///< 33-byte UTF-16 comment
#define FRIEND_LIST_SIZE 0x64 ///< 100 (Max number of friends)
#pragma pack(push, 1)
/// Friend key data
typedef struct
{
u32 principalId;
u32 padding;
u64 localFriendCode;
} FriendKey;
/// Friend Title data
typedef struct
{
u64 tid;
u32 version;
u32 unk;
} TitleData;
/// Friend profile data
typedef struct
{
u8 region; ///< The region code for the hardware.
u8 country; ///< Country code.
u8 area; ///< Area code.
u8 language; ///< Language code.
u8 platform; ///< Platform code.
u32 padding;
} FriendProfile;
/// Game Description structure
typedef struct
{
TitleData data;
u16 desc[128];
} GameDescription;
/// Friend Notification Event structure
typedef struct
{
u8 type;
u8 padding3[3];
u32 padding;
FriendKey key;
} NotificationEvent;
#pragma pack(pop)
/// Enum to use with FRD_GetNotificationEvent
typedef enum
{
USER_WENT_ONLINE = 1, ///< Self went online
USER_WENT_OFFLINE, ///< Self went offline
FRIEND_WENT_ONLINE, ///< Friend Went Online
FRIEND_UPDATED_PRESENCE, ///< Friend Presence changed
FRIEND_UPDATED_MII, ///< Friend Mii changed
FRIEND_UPDATED_PROFILE, ///< Friend Profile changed
FRIEND_WENT_OFFLINE, ///< Friend went offline
FRIEND_REGISTERED_USER, ///< Friend registered self as friend
FRIEND_SENT_INVITATION ///< Friend Sent invitation
} NotificationTypes;
/// Initializes FRD service.
Result frdInit(void);
/// Exists FRD.
void frdExit(void);
/// Get FRD handle.
Handle *frdGetSessionHandle(void);
/**
* @brief Gets the login status of the current user.
* @param state Pointer to write the current user's login status to.
*/
Result FRDU_HasLoggedIn(bool *state);
/**
* @brief Gets the online status of the current user.
* @param state Pointer to write the current user's online status to.
*/
Result FRDU_IsOnline(bool *state);
/// Logs out of Nintendo's friend server.
Result FRD_Logout(void);
/**
* @brief Log in to Nintendo's friend server.
* @param event Event to signal when Login is done.
*/
Result FRD_Login(Handle event);
/**
* @brief Gets the current user's friend key.
* @param key Pointer to write the current user's friend key to.
*/
Result FRD_GetMyFriendKey(FriendKey *key);
/**
* @brief Gets the current user's privacy information.
* @param isPublicMode Determines whether friends are notified of the current user's online status.
* @param isShowGameName Determines whether friends are notified of the application that the current user is running.
* @param isShowPlayedGame Determiens whether to display the current user's game history.
*/
Result FRD_GetMyPreference(bool *isPublicMode, bool *isShowGameName, bool *isShowPlayedGame);
/**
* @brief Gets the current user's profile information.
* @param profile Pointer to write the current user's profile information to.
*/
Result FRD_GetMyProfile(FriendProfile *profile);
/**
* @brief Gets the current user's screen name.
* @param name Pointer to write the current user's screen name to.
* @param max_size Max size of the screen name.
*/
Result FRD_GetMyScreenName(char *name, size_t max_size);
/**
* @brief Gets the current user's Mii data.
* @param mii Pointer to write the current user's mii data to.
*/
Result FRD_GetMyMii(MiiData *mii);
/**
* @brief Gets the current user's playing game.
* @param titleId Pointer to write the current user's playing game to.
*/
Result FRD_GetMyPlayingGame(u64 *titleId);
/**
* @brief Gets the current user's favourite game.
* @param titleId Pointer to write the title ID of current user's favourite game to.
*/
Result FRD_GetMyFavoriteGame(u64 *titleId);
/**
* @brief Gets the current user's comment on their friend profile.
* @param comment Pointer to write the current user's comment to.
* @param max_size Max size of the comment.
*/
Result FRD_GetMyComment(char *comment, size_t max_size);
/**
* @brief Gets the current user's friend key list.
* @param friendKeyList Pointer to write the friend key list to.
* @param num Stores the number of friend keys obtained.
* @param offset The index of the friend key to start with.
* @param size Size of the friend key list. (FRIEND_LIST_SIZE)
*/
Result FRD_GetFriendKeyList(FriendKey *friendKeyList, u32 *num, u32 offset, u32 size);
/**
* @brief Gets the current user's friends' Mii data.
* @param miiDataList Pointer to write Mii data to.
* @param friendKeyList Pointer to FriendKeys.
* @param size Number of Friendkeys.
*/
Result FRD_GetFriendMii(MiiData *miiDataList, const FriendKey *friendKeyList, size_t size);
/**
* @brief Get the current user's friends' profile data.
* @param profile Pointer to write profile data to.
* @param friendKeyList Pointer to FriendKeys.
* @param size Number of FriendKeys.
*/
Result FRD_GetFriendProfile(FriendProfile *profile, const FriendKey *friendKeyList, size_t size);
/**
* @brief Get the current user's friends' playing game.
* @param desc Pointer to write Game Description data to.
* @param friendKeyList Pointer to FriendKeys,
* @param size Number Of FriendKeys.
*/
Result FRD_GetFriendPlayingGame(GameDescription *desc, const FriendKey *friendKeyList, size_t size);
/**
* @brief Get the current user's friends' favourite game.
* @param desc Pointer to write Game Description data to.
* @param friendKeyList Pointer to FriendKeys,
* @param count Number Of FriendKeys.
*/
Result FRD_GetFriendFavouriteGame(GameDescription *desc, const FriendKey *friendKeyList, u32 count);
/**
* @brief Gets whether a friend key is included in the current user's friend list.
* @param friendKeyList Pointer to a list of friend keys.
* @param isFromList Pointer to a write the friendship status to.
*/
Result FRD_IsInFriendList(FriendKey *friendKeyList, bool *isFromList);
/**
* @brief Updates the game mode description string.
* @param desc Pointer to write the game mode description to.
*/
Result FRD_UpdateGameModeDescription(const char *desc);
/**
* @brief Event which is signaled when friend login states change.
* @param event event which will be signaled.
*/
Result FRD_AttachToEventNotification(Handle event);
/**
* @brief Get Latest Event Notification
* @param event Pointer to write recieved notification event struct to.
* @param count Number of events
* @param recievedNotifCount Number of notification reccieved.
*/
Result FRD_GetEventNotification(NotificationEvent *event, u32 count, u32 *recievedNotifCount);
/**
* @brief Returns the friend code using the given principal ID.
* @param principalId The principal ID being used.
* @param friendCode Pointer to write the friend code to.
*/
Result FRD_PrincipalIdToFriendCode(u32 principalId, u64 *friendCode);
/**
* @brief Returns the principal ID using the given friend code.
* @param friendCode The friend code being used.
* @param principalId Pointer to write the principal ID to.
*/
Result FRD_FriendCodeToPrincipalId(u64 friendCode, u32 *principalId);
/**
* @brief Checks if the friend code is valid.
* @param friendCode The friend code being used.
* @param isValid Pointer to write the validity of the friend code to.
*/
Result FRD_IsValidFriendCode(u64 friendCode, bool *isValid);
/**
* @brief Sets the Friend API to use a specific SDK version.
* @param sdkVer The SDK version needed to be used.
*/
Result FRD_SetClientSdkVersion(u32 sdkVer);
/**
* @brief Add a Friend online.
* @param event Event signaled when friend is registered.
* @param principalId PrincipalId of the friend to add.
*/
Result FRD_AddFriendOnline(Handle event, u32 principalId);
/**
* @brief Remove a Friend.
* @param principalId PrinipalId of the friend code to remove.
* @param localFriendCode LocalFriendCode of the friend code to remove.
*/
Result FRD_RemoveFriend(u32 principalId, u64 localFriendCode);
FRD_GetMyComment
Result FRD_GetMyComment(char *comment, size_t max_size)
Gets the current user's comment on their friend profile.
FRD_GetMyFavoriteGame
Result FRD_GetMyFavoriteGame(u64 *titleId)
Gets the current user's favourite game.
FRD_GetMyPreference
Result FRD_GetMyPreference(bool *isPublicMode, bool *isShowGameName, bool *isShowPlayedGame)
Gets the current user's privacy information.
FRD_GetMyMii
Result FRD_GetMyMii(MiiData *mii)
Gets the current user's Mii data.
FRD_GetFriendMii
Result FRD_GetFriendMii(MiiData *miiDataList, const FriendKey *friendKeyList, size_t size)
Gets the current user's friends' Mii data.
FRD_GetMyPlayingGame
Result FRD_GetMyPlayingGame(u64 *titleId)
Gets the current user's playing game.
FRD_IsInFriendList
Result FRD_IsInFriendList(FriendKey *friendKeyList, bool *isFromList)
Gets whether a friend key is included in the current user's friend list.
FRD_AddFriendOnline
Result FRD_AddFriendOnline(Handle event, u32 principalId)
Add a Friend online.
FRD_GetMyScreenName
Result FRD_GetMyScreenName(char *name, size_t max_size)
Gets the current user's screen name.
frdExit
void frdExit(void)
Exists FRD.
FRD_AttachToEventNotification
Result FRD_AttachToEventNotification(Handle event)
Event which is signaled when friend login states change.
FRD_RemoveFriend
Result FRD_RemoveFriend(u32 principalId, u64 localFriendCode)
Remove a Friend.
FRD_GetFriendFavouriteGame
Result FRD_GetFriendFavouriteGame(GameDescription *desc, const FriendKey *friendKeyList, u32 count)
Get the current user's friends' favourite game.
FRD_GetFriendPlayingGame
Result FRD_GetFriendPlayingGame(GameDescription *desc, const FriendKey *friendKeyList, size_t size)
Get the current user's friends' playing game.
FRD_IsValidFriendCode
Result FRD_IsValidFriendCode(u64 friendCode, bool *isValid)
Checks if the friend code is valid.
frdInit
Result frdInit(void)
Initializes FRD service.
FRD_SetClientSdkVersion
Result FRD_SetClientSdkVersion(u32 sdkVer)
Sets the Friend API to use a specific SDK version.
NotificationTypes
NotificationTypes
Enum to use with FRD_GetNotificationEvent.
Definition: frd.h:61
FRIEND_SENT_INVITATION
@ FRIEND_SENT_INVITATION
Friend Sent invitation.
Definition: frd.h:70
FRIEND_REGISTERED_USER
@ FRIEND_REGISTERED_USER
Friend registered self as friend.
Definition: frd.h:69
FRIEND_UPDATED_PROFILE
@ FRIEND_UPDATED_PROFILE
Friend Profile changed.
Definition: frd.h:67
FRIEND_WENT_OFFLINE
@ FRIEND_WENT_OFFLINE
Friend went offline.
Definition: frd.h:68
USER_WENT_ONLINE
@ USER_WENT_ONLINE
Self went online.
Definition: frd.h:62
USER_WENT_OFFLINE
@ USER_WENT_OFFLINE
Self went offline.
Definition: frd.h:63
FRIEND_WENT_ONLINE
@ FRIEND_WENT_ONLINE
Friend Went Online.
Definition: frd.h:64
FRIEND_UPDATED_MII
@ FRIEND_UPDATED_MII
Friend Mii changed.
Definition: frd.h:66
FRIEND_UPDATED_PRESENCE
@ FRIEND_UPDATED_PRESENCE
Friend Presence changed.
Definition: frd.h:65
FRD_UpdateGameModeDescription
Result FRD_UpdateGameModeDescription(const char *desc)
Updates the game mode description string.
FRDU_HasLoggedIn
Result FRDU_HasLoggedIn(bool *state)
Gets the login status of the current user.
FRD_PrincipalIdToFriendCode
Result FRD_PrincipalIdToFriendCode(u32 principalId, u64 *friendCode)
Returns the friend code using the given principal ID.
FRD_GetEventNotification
Result FRD_GetEventNotification(NotificationEvent *event, u32 count, u32 *recievedNotifCount)
Get Latest Event Notification.
frdGetSessionHandle
Handle * frdGetSessionHandle(void)
Get FRD handle.
FRD_GetMyFriendKey
Result FRD_GetMyFriendKey(FriendKey *key)
Gets the current user's friend key.
FRDU_IsOnline
Result FRDU_IsOnline(bool *state)
Gets the online status of the current user.
FRD_Login
Result FRD_Login(Handle event)
Log in to Nintendo's friend server.
FRD_GetFriendKeyList
Result FRD_GetFriendKeyList(FriendKey *friendKeyList, u32 *num, u32 offset, u32 size)
Gets the current user's friend key list.
FRD_Logout
Result FRD_Logout(void)
Logs out of Nintendo's friend server.
FRD_GetFriendProfile
Result FRD_GetFriendProfile(FriendProfile *profile, const FriendKey *friendKeyList, size_t size)
Get the current user's friends' profile data.
FRD_GetMyProfile
Result FRD_GetMyProfile(FriendProfile *profile)
Gets the current user's profile information.
FRD_FriendCodeToPrincipalId
Result FRD_FriendCodeToPrincipalId(u64 friendCode, u32 *principalId)
Returns the principal ID using the given friend code.
mii.h
Shared Mii struct.
FriendKey
Friend key data.
Definition: frd.h:16
FriendProfile
Friend profile data.
Definition: frd.h:32
FriendProfile::platform
u8 platform
Platform code.
Definition: frd.h:37
FriendProfile::region
u8 region
The region code for the hardware.
Definition: frd.h:33
FriendProfile::country
u8 country
Country code.
Definition: frd.h:34
FriendProfile::area
u8 area
Area code.
Definition: frd.h:35
FriendProfile::language
u8 language
Language code.
Definition: frd.h:36
GameDescription
Game Description structure.
Definition: frd.h:43
MiiData
Shared Mii struct.
Definition: mii.h:13
NotificationEvent
Friend Notification Event structure.
Definition: frd.h:50
TitleData
Friend Title data.
Definition: frd.h:24
u64
uint64_t u64
64-bit unsigned integer
Definition: types.h:24
u8
uint8_t u8
would be nice if newlib had this already
Definition: types.h:21
Handle
u32 Handle
Resource handle.
Definition: types.h:41
Result
s32 Result
Function result.
Definition: types.h:42
u16
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
u32
uint32_t u32
32-bit unsigned integer
Definition: types.h:23