nim.h

Go to the documentation of this file.

/**
 * @file nim.h
 * @brief NIM (network installation management) service.
 *
 * This service is used to download and install titles from Nintendo's CDN.
 *
 * We differentiate between two different kinds of downloads:
 *
 * - "active" downloads, which are downloads started with @ref NIMS_StartDownload or @ref NIMS_StartDownloadSimple. The process must keep polling the current status using @ref NIMS_GetProgress.
 * - "tasks", which are downloads started with @ref NIMS_RegisterTask. These are only processed in sleep mode.
 */
#pragma once
 
// FS_MediaType
#include <3ds/services/fs.h>
 
/// Mode that NIM downloads/installs a title with.
typedef enum
{
    IM_DEFAULT = 0, ///< Initial installation
    IM_UNKNOWN1,    ///< Unknown
    IM_UNKNOWN2,    ///< Unknown
    IM_REINSTALL,   ///< Reinstall currently installed title; use this if the title is already installed (including updates)
} NIM_InstallationMode;
 
/// Current state of a NIM download/installation.
typedef enum
{
    DS_NOT_INITIALIZED = 0, ///< Download not yet initialized
    DS_INITIALIZED,         ///< Download initialized
    DS_DOWNLOAD_TMD,        ///< Downloading and installing TMD
    DS_PREPARE_SAVE_DATA,   ///< Initializing save data
    DS_DOWNLOAD_CONTENTS,   ///< Downloading and installing contents
    DS_WAIT_COMMIT,         ///< Waiting before calling AM_CommitImportTitles
    DS_COMMITTING,          ///< Running AM_CommitImportTitles
    DS_FINISHED,            ///< Title installation finished
    DS_VERSION_ERROR,       ///< (unknown error regarding title version)
    DS_CREATE_CONTEXT,      ///< Creating the .ctx file?
    DS_CANNOT_RECOVER,      ///< Irrecoverable error encountered (e.g. out of space)
    DS_INVALID,             ///< Invalid state
} NIM_DownloadState;
 
/// Input configuration for NIM download/installation tasks.
typedef struct
{
    u64 titleId;   ///< Title ID
    u32 version;   ///< Title version
    u32 unknown_0; ///< Always 0
    u8 ratingAge;  ///< Age for the HOME Menu parental controls
    u8 mediaType;  ///< Media type, see @ref FS_MediaType enum
    u8 padding[2]; ///< Padding
    u32 unknown_1; ///< Unknown input, seems to be always 0
} NIM_TitleConfig;
 
/// Output struct for NIM downloads/installations in progress.
typedef struct
{
    u32 state;          ///< State, see NIM_DownloadState enum
    Result lastResult;  ///< Last result code in NIM
    u64 downloadedSize; ///< Amount of bytes that have been downloaded
    u64 totalSize;      ///< Amount of bytes that need to be downloaded in total
} NIM_TitleProgress;
 
/**
 * @brief Initializes nim:s. This uses networking and is blocking.
 * @param buffer A buffer for internal use. It must be at least 0x20000 bytes long.
 * @param buffer_len Length of the passed buffer.
 */
Result nimsInit(void *buffer, size_t buffer_len);
 
/**
 * @brief Initializes nim:s with the given TIN. This uses networking and is blocking.
 * @param buffer A buffer for internal use. It must be at least 0x20000 bytes long.
 * @param buffer_len Length of the passed buffer.
 * @param TIN The TIN to initialize nim:s with. If you do not know what a TIN is or why you would want to change it, use @ref nimsInit instead.
 */
Result nimsInitWithTIN(void *buffer, size_t buffer_len, const char *TIN);
 
/// Exits nim:s.
void nimsExit(void);
 
/// Gets the current nim:s session handle.
Handle *nimsGetSessionHandle(void);
 
/**
 * @brief Sets an attribute.
 * @param attr Name of the attribute.
 * @param val Value of the attribute.
 */
Result NIMS_SetAttribute(const char *attr, const char *val);
 
/**
 * @brief Checks if nim wants a system update.
 * @param want_update Set to true if a system update is required. Can be NULL.
 */
Result NIMS_WantUpdate(bool *want_update);
 
/**
 * @brief Makes a TitleConfig struct for use with @ref NIMS_RegisterTask, @ref NIMS_StartDownload or @ref NIMS_StartDownloadSimple.
 * @param cfg Struct to initialize.
 * @param titleId Title ID to download and install.
 * @param version Version of the title to download and install.
 * @param ratingAge Age for which the title is aged; used by parental controls in HOME Menu.
 * @param mediaType Media type of the title to download and install.
 */
void NIMS_MakeTitleConfig(NIM_TitleConfig *cfg, u64 titleId, u32 version, u8 ratingAge, FS_MediaType mediaType);
 
/**
 * @brief Registers a background download task with NIM. These are processed in sleep mode only.
 * @param cfg Title config to use. See @ref NIMS_MakeTitleConfig.
 * @param name Name of the title in UTF-8. Will be displayed on the HOME Menu. Maximum 73 characters.
 * @param maker Name of the maker/publisher in UTF-8. Will be displayed on the HOME Menu. Maximum 37 characters.
 */
Result NIMS_RegisterTask(const NIM_TitleConfig *cfg, const char *name, const char *maker);
 
/**
 * @brief Checks whether a background download task for the given title is registered with NIM.
 * @param titleId Title ID to check for.
 * @param registered Whether there is a background download task registered.
 */
Result NIMS_IsTaskRegistered(u64 titleId, bool *registered);
 
/**
 * @brief Unregisters a background download task.
 * @param titleId Title ID whose background download task to cancel.
 */
Result NIMS_UnregisterTask(u64 titleId);
 
/**
 * @brief Starts an active download with NIM. Progress can be checked with @ref NIMS_GetProcess. Do not exit the process while a download is in progress without calling @ref NIMS_CancelDownload.
 * @param cfg Title config to use. See @ref NIMS_MakeTitleConfig.
 * @param mode The installation mode to use. See @ref NIM_InstallationMode.
 */
Result NIMS_StartDownload(const NIM_TitleConfig *cfg, NIM_InstallationMode mode);
 
/**
 * @brief Starts an active download with NIM with default installation mode; cannot reinstall titles. Progress can be checked with @ref NIMS_GetProcess. Do not exit the process while a download is in progress without calling @ref NIMS_CancelDownload.
 * @param cfg Title config to use. See @ref NIMS_MakeTitleConfig.
 */
Result NIMS_StartDownloadSimple(const NIM_TitleConfig *cfg);
 
/**
 * @brief Checks the status of the current active download.
 * @param tp Title progress struct to write to. See @ref NIM_TitleProgress.
 */
Result NIMS_GetProgress(NIM_TitleProgress *tp);
 
/**
 * @brief Cancels the current active download with NIM.
 */
Result NIMS_CancelDownload(void);