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.
Handle * | nimsGetSessionHandle (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:

- "active" downloads, which are downloads started with NIMS_StartDownload or NIMS_StartDownloadSimple. The process must keep polling the current status using NIMS_GetProgress.
- "tasks", which are downloads started with NIMS_RegisterTask. These are only processed in sleep mode.

## Enumeration Type Documentation

## NIM_DownloadState

enum 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

enum 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

  tp | Title 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

  titleId | Title ID to check for.
  registered | Whether 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

  cfg | Struct to initialize.
  titleId | Title ID to download and install.
  version | Version of the title to download and install.
  ratingAge | Age for which the title is aged; used by parental controls in HOME Menu.
  mediaType | Media 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

  cfg | Title config to use. See NIMS_MakeTitleConfig.
  name | Name of the title in UTF-8. Will be displayed on the HOME Menu. Maximum 73 characters.
  maker | Name 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

  attr | Name of the attribute.
  val | Value 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

  cfg | Title config to use. See NIMS_MakeTitleConfig.
  mode | The 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

  cfg | Title config to use. See NIMS_MakeTitleConfig.

## NIMS_UnregisterTask()

Result NIMS_UnregisterTask | ( | u64 | titleId | ) |

Unregisters a background download task.

Parameters

  titleId | Title ID whose background download task to cancel.

## NIMS_WantUpdate()

Result NIMS_WantUpdate | ( | bool * | want_update | ) |

Checks if nim wants a system update.

Parameters

  want_update | Set 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

  buffer | A buffer for internal use. It must be at least 0x20000 bytes long.
  buffer_len | Length 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

  buffer | A buffer for internal use. It must be at least 0x20000 bytes long.
  buffer_len | Length of the passed buffer.
  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 nimsInit instead.