libctru  v1.6.0
Data Structures | Enumerations | Functions
nim.h File Reference

NIM (network installation management) service. More...

#include <3ds/services/fs.h>

Go to the source code of this file.

Data Structures

struct  NIM_TitleConfig
 Input configuration for NIM download/installation tasks. More...
 
struct  NIM_TitleProgress
 Output struct for NIM downloads/installations in progress. More...
 

Enumerations

enum  NIM_InstallationMode {
  IM_DEFAULT = 0,
  IM_UNKNOWN1,
  IM_UNKNOWN2,
  IM_REINSTALL
}
 Mode that NIM downloads/installs a title with. More...
 
enum  NIM_DownloadState {
  DS_NOT_INITIALIZED = 0,
  DS_INITIALIZED,
  DS_DOWNLOAD_TMD,
  DS_PREPARE_SAVE_DATA,
  DS_DOWNLOAD_CONTENTS,
  DS_WAIT_COMMIT,
  DS_COMMITTING,
  DS_FINISHED,
  DS_VERSION_ERROR,
  DS_CREATE_CONTEXT,
  DS_CANNOT_RECOVER,
  DS_INVALID
}
 Current state of a NIM download/installation. More...
 

Functions

Result nimsInit (void *buffer, size_t buffer_len)
 Initializes nim:s. More...
 
Result nimsInitWithTIN (void *buffer, size_t buffer_len, const char *TIN)
 Initializes nim:s with the given TIN. More...
 
void nimsExit (void)
 Exits nim:s.
 
HandlenimsGetSessionHandle (void)
 Gets the current nim:s session handle.
 
Result NIMS_SetAttribute (const char *attr, const char *val)
 Sets an attribute. More...
 
Result NIMS_WantUpdate (bool *want_update)
 Checks if nim wants a system update. More...
 
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_StartDownloadSimple. More...
 
Result NIMS_RegisterTask (const NIM_TitleConfig *cfg, const char *name, const char *maker)
 Registers a background download task with NIM. More...
 
Result NIMS_IsTaskRegistered (u64 titleId, bool *registered)
 Checks whether a background download task for the given title is registered with NIM. More...
 
Result NIMS_UnregisterTask (u64 titleId)
 Unregisters a background download task. More...
 
Result NIMS_StartDownload (const NIM_TitleConfig *cfg, NIM_InstallationMode mode)
 Starts an active download with NIM. More...
 
Result NIMS_StartDownloadSimple (const NIM_TitleConfig *cfg)
 Starts an active download with NIM with default installation mode; cannot reinstall titles. More...
 
Result NIMS_GetProgress (NIM_TitleProgress *tp)
 Checks the status of the current active download. More...
 
Result NIMS_CancelDownload (void)
 Cancels the current active download with NIM.
 

Detailed Description

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:

Enumeration Type Documentation

◆ NIM_DownloadState

Current state of a NIM download/installation.

Enumerator
DS_NOT_INITIALIZED 

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_InstallationMode

Mode that NIM downloads/installs a title with.

Enumerator
IM_DEFAULT 

Initial installation.

IM_UNKNOWN1 

Unknown.

IM_UNKNOWN2 

Unknown.

IM_REINSTALL 

Reinstall currently installed title; use this if the title is already installed (including updates)

Function Documentation

◆ NIMS_GetProgress()

Result NIMS_GetProgress ( NIM_TitleProgress tp)

Checks the status of the current active download.

Parameters
tpTitle progress struct to write to. See NIM_TitleProgress.

◆ NIMS_IsTaskRegistered()

Result NIMS_IsTaskRegistered ( u64  titleId,
bool *  registered 
)

Checks whether a background download task for the given title is registered with NIM.

Parameters
titleIdTitle ID to check for.
registeredWhether there is a background download task registered.

◆ 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_StartDownloadSimple.

Parameters
cfgStruct to initialize.
titleIdTitle ID to download and install.
versionVersion of the title to download and install.
ratingAgeAge for which the title is aged; used by parental controls in HOME Menu.
mediaTypeMedia type of the title to download and install.

◆ NIMS_RegisterTask()

Result NIMS_RegisterTask ( const NIM_TitleConfig cfg,
const char *  name,
const char *  maker 
)

Registers a background download task with NIM.

These are processed in sleep mode only.

Parameters
cfgTitle config to use. See NIMS_MakeTitleConfig.
nameName of the title in UTF-8. Will be displayed on the HOME Menu. Maximum 73 characters.
makerName of the maker/publisher in UTF-8. Will be displayed on the HOME Menu. Maximum 37 characters.

◆ NIMS_SetAttribute()

Result NIMS_SetAttribute ( const char *  attr,
const char *  val 
)

Sets an attribute.

Parameters
attrName of the attribute.
valValue of the attribute.

◆ NIMS_StartDownload()

Result NIMS_StartDownload ( const NIM_TitleConfig cfg,
NIM_InstallationMode  mode 
)

Starts an active download with NIM.

Progress can be checked with NIMS_GetProcess. Do not exit the process while a download is in progress without calling NIMS_CancelDownload.

Parameters
cfgTitle config to use. See NIMS_MakeTitleConfig.
modeThe installation mode to use. See NIM_InstallationMode.

◆ NIMS_StartDownloadSimple()

Result NIMS_StartDownloadSimple ( const NIM_TitleConfig cfg)

Starts an active download with NIM with default installation mode; cannot reinstall titles.

Progress can be checked with NIMS_GetProcess. Do not exit the process while a download is in progress without calling NIMS_CancelDownload.

Parameters
cfgTitle config to use. See NIMS_MakeTitleConfig.

◆ NIMS_UnregisterTask()

Result NIMS_UnregisterTask ( u64  titleId)

Unregisters a background download task.

Parameters
titleIdTitle ID whose background download task to cancel.

◆ NIMS_WantUpdate()

Result NIMS_WantUpdate ( bool *  want_update)

Checks if nim wants a system update.

Parameters
want_updateSet to true if a system update is required. Can be NULL.

◆ nimsInit()

Result nimsInit ( void *  buffer,
size_t  buffer_len 
)

Initializes nim:s.

This uses networking and is blocking.

Parameters
bufferA buffer for internal use. It must be at least 0x20000 bytes long.
buffer_lenLength of the passed buffer.

◆ nimsInitWithTIN()

Result nimsInitWithTIN ( void *  buffer,
size_t  buffer_len,
const char *  TIN 
)

Initializes nim:s with the given TIN.

This uses networking and is blocking.

Parameters
bufferA buffer for internal use. It must be at least 0x20000 bytes long.
buffer_lenLength of the passed buffer.
TINThe TIN to initialize nim:s with. If you do not know what a TIN is or why you would want to change it, use nimsInit instead.