miiselector.h

Go to the documentation of this file.

/**
 * @file miiselector.h
 * @brief Mii Selector Applet (appletEd).
 */
 
#pragma once
#include <3ds/types.h>
#include <3ds/mii.h>
 
/// Magic value needed to launch the applet.
#define MIISELECTOR_MAGIC 0x13DE28CF
 
/// Maximum length of title to be displayed at the top of the Mii selector applet
#define MIISELECTOR_TITLE_LEN 64
 
/// Number of Guest Miis available for selection
#define MIISELECTOR_GUESTMII_SLOTS 6
 
/// Maximum number of user Miis available for selection
#define MIISELECTOR_USERMII_SLOTS 100
 
/// Parameter structure passed to AppletEd
typedef struct
{
    u8 enable_cancel_button;          ///< Enables canceling of selection if nonzero.
    u8 enable_selecting_guests;       ///< Makes Guets Miis selectable if nonzero.
    u8 show_on_top_screen;            ///< Shows applet on top screen if nonzero,
                                      ///< otherwise show it on the bottom screen.
    u8 _unk0x3[5];                    ///< @private
    u16 title[MIISELECTOR_TITLE_LEN]; ///< UTF16-LE string displayed at the top of the applet. If
                                      ///< set to the empty string, a default title is displayed.
    u8 _unk0x88[4];                   ///< @private
    u8 show_guest_page;               ///< If nonzero, the applet shows a page with Guest
                                      ///< Miis on launch.
    u8 _unk0x8D[3];                   ///< @private
    u32 initial_index;                ///< Index of the initially selected Mii. If
                                      ///< @ref MiiSelectorConf.show_guest_page is
                                      ///< set, this is the index of a Guest Mii,
                                      ///< otherwise that of a user Mii.
    u8 mii_guest_whitelist[MIISELECTOR_GUESTMII_SLOTS];   ///< Each byte set to a nonzero value
                                                          ///< enables its corresponding Guest
                                                          ///< Mii to be enabled for selection.
    u8 mii_whitelist[MIISELECTOR_USERMII_SLOTS];   ///< Each byte set to a nonzero value enables
                                                   ///< its corresponding user Mii to be enabled
                                                   ///< for selection.
    u16 _unk0xFE;                                  ///< @private
    u32 magic; ///< Will be set to @ref MIISELECTOR_MAGIC before launching the
               ///< applet.
} MiiSelectorConf;
 
/// Maximum length of the localized name of a Guest Mii
#define MIISELECTOR_GUESTMII_NAME_LEN 12
 
/// Structure written by AppletEd
typedef struct
{
    u32 no_mii_selected;                ///< 0 if a Mii was selected, 1 if the selection was
                                        ///< canceled.
    u32 guest_mii_was_selected;         ///< 1 if a Guest Mii was selected, 0 otherwise.
    u32 guest_mii_index;                ///< Index of the selected Guest Mii,
                                        ///< 0xFFFFFFFF if no guest was selected.
    MiiData mii;                        ///< Data of selected Mii.
    u16 _pad0x68;                       ///< @private
    u16 checksum;                       ///< Checksum of the returned Mii data.
                                        ///< Stored as a big-endian value; use
                                        ///< @ref miiSelectorChecksumIsValid to
                                        ///< verify.
    u16 guest_mii_name[MIISELECTOR_GUESTMII_NAME_LEN]; ///< Localized name of a Guest Mii,
                                                       ///< if one was selected (UTF16-LE
                                                       ///< string). Zeroed otherwise.
} MiiSelectorReturn;
 
/// AppletEd options
enum
{
    MIISELECTOR_CANCEL     = BIT(0), ///< Show the cancel button
    MIISELECTOR_GUESTS     = BIT(1), ///< Make Guets Miis selectable
    MIISELECTOR_TOP        = BIT(2), ///< Show AppletEd on top screen
    MIISELECTOR_GUESTSTART = BIT(3), ///< Start on guest page
};
 
/**
 * @brief Initialize Mii selector config
 * @param conf Pointer to Miiselector config.
 */
void miiSelectorInit(MiiSelectorConf *conf);
 
/**
 * @brief Launch the Mii selector library applet
 *
 * @param conf Configuration determining how the applet should behave
 */
void miiSelectorLaunch(const MiiSelectorConf *conf, MiiSelectorReturn* returnbuf);
 
/**
 * @brief Sets title of the Mii selector library applet
 *
 * @param conf Pointer to miiSelector configuration
 * @param text Title text of Mii selector
 */
void miiSelectorSetTitle(MiiSelectorConf *conf, const char* text);
 
/**
 * @brief Specifies which special options are enabled in the Mii selector
 *
 * @param conf Pointer to miiSelector configuration
 * @param options Options bitmask
 */
void miiSelectorSetOptions(MiiSelectorConf *conf, u32 options);
 
/**
 * @brief Specifies which guest Miis will be selectable
 *
 * @param conf Pointer to miiSelector configuration
 * @param index Index of the guest Miis that will be whitelisted.
 * @ref MIISELECTOR_GUESTMII_SLOTS can be used to whitelist all the guest Miis.
 */
void miiSelectorWhitelistGuestMii(MiiSelectorConf *conf, u32 index);
 
/**
 * @brief Specifies which guest Miis will be unselectable
 *
 * @param conf Pointer to miiSelector configuration
 * @param index Index of the guest Miis that will be blacklisted.
 * @ref MIISELECTOR_GUESTMII_SLOTS can be used to blacklist all the guest Miis.
 */
void miiSelectorBlacklistGuestMii(MiiSelectorConf *conf, u32 index);
 
/**
 * @brief Specifies which user Miis will be selectable
 *
 * @param conf Pointer to miiSelector configuration
 * @param index Index of the user Miis that will be whitelisted.
 * @ref MIISELECTOR_USERMII_SLOTS can be used to whitlist all the user Miis
 */
void miiSelectorWhitelistUserMii(MiiSelectorConf *conf, u32 index);
 
/**
 * @brief Specifies which user Miis will be selectable
 *
 * @param conf Pointer to miiSelector configuration
 * @param index Index of the user Miis that will be blacklisted.
 * @ref MIISELECTOR_USERMII_SLOTS can be used to blacklist all the user Miis
 */
void miiSelectorBlacklistUserMii(MiiSelectorConf *conf, u32 index);
 
/**
 * @brief Specifies which Mii the cursor should start from
 *
 * @param conf Pointer to miiSelector configuration
 * @param index Indexed number of the Mii that the cursor will start on.
 * If there is no mii with that index, the the cursor will start at the Mii
 * with the index 0 (the personal Mii).
 */
static inline void miiSelectorSetInitialIndex(MiiSelectorConf *conf, u32 index)
{
    conf->initial_index = index;
}
 
/**
 * @brief Get Mii name
 *
 * @param returnbuf Pointer to miiSelector return
 * @param out String containing a Mii's name
 * @param max_size Size of string. Since UTF8 characters range in size from 1-3 bytes
 * (assuming that no non-BMP characters are used), this value should be 36 (or 30 if you are not
 * dealing with guest miis).
 */
void miiSelectorReturnGetName(const MiiSelectorReturn *returnbuf, char* out, size_t max_size);
 
/**
 * @brief Get Mii Author
 *
 * @param returnbuf Pointer to miiSelector return
 * @param out String containing a Mii's author
 * @param max_size Size of string. Since UTF8 characters range in size from 1-3 bytes
 * (assuming that no non-BMP characters are used), this value should be 30.
 */
void miiSelectorReturnGetAuthor(const MiiSelectorReturn *returnbuf, char* out, size_t max_size);
 
/**
 * @brief Verifies that the Mii data returned from the applet matches its
 * checksum
 *
 * @param returnbuf Buffer filled by Mii selector applet
 * @return `true` if `returnbuf->checksum` is the same as the one computed from `returnbuf`
 */
bool miiSelectorChecksumIsValid(const MiiSelectorReturn *returnbuf);