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);
fs.h
Filesystem Services.
FS_MediaType
FS_MediaType
Media types.
Definition: fs.h:35
NIMS_GetProgress
Result NIMS_GetProgress(NIM_TitleProgress *tp)
Checks the status of the current active download.
NIMS_UnregisterTask
Result NIMS_UnregisterTask(u64 titleId)
Unregisters a background download task.
nimsInitWithTIN
Result nimsInitWithTIN(void *buffer, size_t buffer_len, const char *TIN)
Initializes nim:s with the given TIN.
NIMS_SetAttribute
Result NIMS_SetAttribute(const char *attr, const char *val)
Sets an attribute.
NIMS_StartDownloadSimple
Result NIMS_StartDownloadSimple(const NIM_TitleConfig *cfg)
Starts an active download with NIM with default installation mode; cannot reinstall titles.
NIMS_IsTaskRegistered
Result NIMS_IsTaskRegistered(u64 titleId, bool *registered)
Checks whether a background download task for the given title is registered with NIM.
NIMS_RegisterTask
Result NIMS_RegisterTask(const NIM_TitleConfig *cfg, const char *name, const char *maker)
Registers a background download task with NIM.
NIMS_StartDownload
Result NIMS_StartDownload(const NIM_TitleConfig *cfg, NIM_InstallationMode mode)
Starts an active download with NIM.
NIMS_MakeTitleConfig
void NIMS_MakeTitleConfig(NIM_TitleConfig *cfg, u64 titleId, u32 version, u8 ratingAge, FS_MediaType mediaType)
Makes a TitleConfig struct for use with NIMS_RegisterTask, NIMS_StartDownload or NIMS_StartDownloadSi...
nimsInit
Result nimsInit(void *buffer, size_t buffer_len)
Initializes nim:s.
nimsExit
void nimsExit(void)
Exits nim:s.
NIMS_CancelDownload
Result NIMS_CancelDownload(void)
Cancels the current active download with NIM.
nimsGetSessionHandle
Handle * nimsGetSessionHandle(void)
Gets the current nim:s session handle.
NIMS_WantUpdate
Result NIMS_WantUpdate(bool *want_update)
Checks if nim wants a system update.
NIM_InstallationMode
NIM_InstallationMode
Mode that NIM downloads/installs a title with.
Definition: nim.h:19
IM_UNKNOWN1
@ IM_UNKNOWN1
Unknown.
Definition: nim.h:21
IM_REINSTALL
@ IM_REINSTALL
Reinstall currently installed title; use this if the title is already installed (including updates)
Definition: nim.h:23
IM_DEFAULT
@ IM_DEFAULT
Initial installation.
Definition: nim.h:20
IM_UNKNOWN2
@ IM_UNKNOWN2
Unknown.
Definition: nim.h:22
NIM_DownloadState
NIM_DownloadState
Current state of a NIM download/installation.
Definition: nim.h:28
DS_CANNOT_RECOVER
@ DS_CANNOT_RECOVER
Irrecoverable error encountered (e.g. out of space)
Definition: nim.h:39
DS_CREATE_CONTEXT
@ DS_CREATE_CONTEXT
Creating the .ctx file?
Definition: nim.h:38
DS_COMMITTING
@ DS_COMMITTING
Running AM_CommitImportTitles.
Definition: nim.h:35
DS_DOWNLOAD_CONTENTS
@ DS_DOWNLOAD_CONTENTS
Downloading and installing contents.
Definition: nim.h:33
DS_INVALID
@ DS_INVALID
Invalid state.
Definition: nim.h:40
DS_DOWNLOAD_TMD
@ DS_DOWNLOAD_TMD
Downloading and installing TMD.
Definition: nim.h:31
DS_PREPARE_SAVE_DATA
@ DS_PREPARE_SAVE_DATA
Initializing save data.
Definition: nim.h:32
DS_VERSION_ERROR
@ DS_VERSION_ERROR
(unknown error regarding title version)
Definition: nim.h:37
DS_NOT_INITIALIZED
@ DS_NOT_INITIALIZED
Download not yet initialized.
Definition: nim.h:29
DS_FINISHED
@ DS_FINISHED
Title installation finished.
Definition: nim.h:36
DS_WAIT_COMMIT
@ DS_WAIT_COMMIT
Waiting before calling AM_CommitImportTitles.
Definition: nim.h:34
DS_INITIALIZED
@ DS_INITIALIZED
Download initialized.
Definition: nim.h:30
NIM_TitleConfig
Input configuration for NIM download/installation tasks.
Definition: nim.h:45
NIM_TitleConfig::unknown_1
u32 unknown_1
Unknown input, seems to be always 0.
Definition: nim.h:52
NIM_TitleConfig::version
u32 version
Title version.
Definition: nim.h:47
NIM_TitleConfig::mediaType
u8 mediaType
Media type, see FS_MediaType enum.
Definition: nim.h:50
NIM_TitleConfig::titleId
u64 titleId
Title ID.
Definition: nim.h:46
NIM_TitleConfig::ratingAge
u8 ratingAge
Age for the HOME Menu parental controls.
Definition: nim.h:49
NIM_TitleConfig::unknown_0
u32 unknown_0
Always 0.
Definition: nim.h:48
NIM_TitleProgress
Output struct for NIM downloads/installations in progress.
Definition: nim.h:57
NIM_TitleProgress::state
u32 state
State, see NIM_DownloadState enum.
Definition: nim.h:58
NIM_TitleProgress::downloadedSize
u64 downloadedSize
Amount of bytes that have been downloaded.
Definition: nim.h:60
NIM_TitleProgress::totalSize
u64 totalSize
Amount of bytes that need to be downloaded in total.
Definition: nim.h:61
NIM_TitleProgress::lastResult
Result lastResult
Last result code in NIM.
Definition: nim.h:59
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
u32
uint32_t u32
32-bit unsigned integer
Definition: types.h:23