1
0
Fork 0
mirror of https://github.com/DarkMatterCore/nxdumptool.git synced 2024-10-30 07:21:46 +00:00
nxdumptool/include/core/title.h
Pablo Curiel 7ed5de9201 Uses a dynamically allocated buffer to hold the CSV data, which can then be written to an output file.
Changes include:

* nxdt_utils: add utilsEscapeCharacters().

* title: add titleGenerateTitleRecordsCsv().
* title: move core logic from titleGetUserApplicationData() into _titleGetUserApplicationData(). titleGetUserApplicationData() now only takes care of duplicating the retrieved data.
* title: update titleGetContentInfosByGameCardContentMetaContext() to make it write the forged NcmContentInfo entry for the Meta NCA at the end of the returned buffer.
* title: fix a bug in titleRefreshGameCardTitleInfo() that prevented a title info's metadata pointer to be updated after retrieving application metadata via ns.
* title: update titleGenerateGameCardApplicationMetadataArray() to add a logfile warning if an application entry doesn't have a valid application metadata pointer.
* title: make _titleGenerateGameCardFileName() a bit easier to read.
2024-08-24 20:10:16 +02:00

358 lines
17 KiB
C

/*
* title.h
*
* Copyright (c) 2020-2024, DarkMatterCore <pabloacurielz@gmail.com>.
*
* This file is part of nxdumptool (https://github.com/DarkMatterCore/nxdumptool).
*
* nxdumptool is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* nxdumptool is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
#pragma once
#ifndef __TITLE_H__
#define __TITLE_H__
#ifdef __cplusplus
extern "C" {
#endif
#define TITLE_PATCH_ID_OFFSET (u64)0x800
#define TITLE_ADDONCONTENT_ID_OFFSET (u64)0x1000
#define TITLE_ADDONCONTENT_CONVERSION_MASK (u64)0xFFFFFFFFFFFFF000
#define TITLE_ADDONCONTENT_MIN_INDEX 1
#define TITLE_ADDONCONTENT_MAX_INDEX 2000
#define TITLE_DELTA_ID_OFFSET (u64)0xC00
/// Generated using ns application records and/or ncm content meta keys.
/// Used by the UI to display title lists.
typedef struct {
u64 title_id; ///< Title ID from the application / system title this data belongs to.
NacpLanguageEntry lang_entry; ///< UTF-8 strings in the console language.
u32 icon_size; ///< JPEG icon size.
u8 *icon; ///< JPEG icon data.
} TitleApplicationMetadata;
/// Used to display gamecard-specific title information.
typedef struct {
TitleApplicationMetadata *app_metadata; ///< User application metadata.
bool has_patch; ///< Set to true if a patch is also available in the inserted gamecard for this user application.
Version version; ///< Reflects the title version stored in the inserted gamecard, either from a base application or a patch.
char display_version[32]; ///< Reflects the title display version from the NACP belonging to either a base application or a patch.
u32 dlc_count; ///< Reflects the number of DLCs available for this application in the inserted gamecard.
} TitleGameCardApplicationMetadata;
/// Generated using ncm calls.
/// User applications: the previous/next pointers reference other user applications with the same ID.
/// Patches: the previous/next pointers reference other patches with the same ID.
/// Add-on contents: the previous/next pointers reference sibling add-on contents.
/// Add-on content patches: the previous/next pointers reference other patches with the same ID and/or other patches for sibling add-on contents.
typedef struct _TitleInfo {
u8 storage_id; ///< NcmStorageId.
NcmContentMetaKey meta_key; ///< Used with ncm calls.
Version version; ///< Holds the same value from meta_key.version.
u32 content_count; ///< Content info count.
NcmContentInfo *content_infos; ///< Content info entries from this title.
u64 size; ///< Total title size.
char size_str[32]; ///< Total title size string.
TitleApplicationMetadata *app_metadata; ///< User application metadata.
struct _TitleInfo *previous, *next; ///< Linked lists.
} TitleInfo;
/// Used to deal with user applications stored in the eMMC, SD card and/or gamecard.
/// The previous and next pointers from the TitleInfo elements are used to traverse through multiple user applications, patches, add-on contents and or add-on content patches.
typedef struct {
TitleInfo *app_info; ///< Pointer to a TitleInfo element for the first detected user application entry matching the provided application ID.
TitleInfo *patch_info; ///< Pointer to a TitleInfo element for the first detected patch entry matching the provided application ID.
TitleInfo *aoc_info; ///< Pointer to a TitleInfo element for the first detected add-on content entry matching the provided application ID.
TitleInfo *aoc_patch_info; ///< Pointer to a TitleInfo element for the first detected add-on content patch entry matching the provided application ID.
} TitleUserApplicationData;
typedef enum {
TitleNamingConvention_Full = 0, ///< Individual titles: "{Name} [{Id}][v{Version}][{Type}]".
///< Gamecards: "{Name1} [{Id1}][v{Version1}] + ... + {NameN} [{IdN}][v{VersionN}]".
TitleNamingConvention_IdAndVersionOnly = 1, ///< Individual titles: "{Id}_v{Version}_{Type}".
///< Gamecards: "{TitleId1}_v{TitleVersion1}_{TitleType1} + ... + {TitleIdN}_v{TitleVersionN}_{TitleTypeN}".
TitleNamingConvention_Count = 2 ///< Total values supported by this enum.
} TitleNamingConvention;
typedef enum {
TitleFileNameIllegalCharReplaceType_None = 0,
TitleFileNameIllegalCharReplaceType_IllegalFsChars = 1,
TitleFileNameIllegalCharReplaceType_KeepAsciiCharsOnly = 2,
TitleFileNameIllegalCharReplaceType_Count = 3 ///< Total values supported by this enum.
} TitleFileNameIllegalCharReplaceType;
/// Initializes the title interface.
bool titleInitialize(void);
/// Closes the title interface.
void titleExit(void);
/// Returns a pointer to a ncm database handle using a NcmStorageId value.
NcmContentMetaDatabase *titleGetNcmDatabaseByStorageId(u8 storage_id);
/// Returns a pointer to a ncm storage handle using a NcmStorageId value.
NcmContentStorage *titleGetNcmStorageByStorageId(u8 storage_id);
/// Returns a pointer to a dynamically allocated array of pointers to TitleApplicationMetadata entries, as well as their count. Returns NULL if an error occurs.
/// If 'is_system' is true, TitleApplicationMetadata entries from available system titles (NcmStorageId_BuiltInSystem) will be returned.
/// Otherwise, TitleApplicationMetadata entries from user applications with available content data (NcmStorageId_BuiltInUser, NcmStorageId_SdCard, NcmStorageId_GameCard) will be returned.
/// The allocated buffer must be freed by the caller using free().
TitleApplicationMetadata **titleGetApplicationMetadataEntries(bool is_system, u32 *out_count);
/// Returns a pointer to a dynamically allocated array of TitleGameCardApplicationMetadata elements generated from gamecard user titles, as well as their count.
/// Returns NULL if an error occurs.
/// The allocated buffer must be freed by the caller using free().
TitleGameCardApplicationMetadata *titleGetGameCardApplicationMetadataEntries(u32 *out_count);
/// Returns a pointer to a dynamically allocated TitleInfo element with a matching storage ID and title ID. Returns NULL if an error occurs.
/// If NcmStorageId_Any is used, the first entry with a matching title ID is returned.
/// Use titleFreeTitleInfo() to free the returned data.
TitleInfo *titleGetTitleInfoEntryFromStorageByTitleId(u8 storage_id, u64 title_id);
/// Frees a dynamically allocated TitleInfo element.
void titleFreeTitleInfo(TitleInfo **info);
/// Populates a TitleUserApplicationData element with dynamically allocated data using a user application ID.
/// Use titleFreeUserApplicationData() to free the populated data.
bool titleGetUserApplicationData(u64 app_id, TitleUserApplicationData *out);
/// Frees data populated by titleGetUserApplicationData().
void titleFreeUserApplicationData(TitleUserApplicationData *user_app_data);
/// Takes an input TitleInfo object with meta type NcmContentMetaType_AddOnContent or NcmContentMetaType_DataPatch.
/// Returns a linked list of TitleInfo elements with title IDs matching the corresponding base/patch title ID, depending on the meta type of the input TitleInfo object.
/// Particularly useful to display add-on-content base/patch titles related to a specific add-on-content (patch) entry.
/// Use titleFreeTitleInfo() to free the returned data.
TitleInfo *titleGetAddOnContentBaseOrPatchList(TitleInfo *title_info);
/// Returns true if orphan titles are available.
/// Orphan titles are patches or add-on contents with no NsApplicationControlData available for their parent user application ID.
bool titleAreOrphanTitlesAvailable(void);
/// Returns a pointer to a dynamically allocated array of orphan TitleInfo entries, as well as their count. Returns NULL if an error occurs.
/// Use titleFreeOrphanTitles() to free the returned data.
TitleInfo **titleGetOrphanTitles(u32 *out_count);
/// Frees orphan title info data returned by titleGetInfoFromOrphanTitles().
void titleFreeOrphanTitles(TitleInfo ***orphan_info);
/// Checks if a gamecard status update has been detected by the background gamecard title info thread (e.g. after a new gamecard has been inserted, of after the current one has been taken out).
/// If this function returns true and functions such as titleGetTitleInfoEntryFromStorageByTitleId(), titleGetUserApplicationData() or titleGetInfoFromOrphanTitles() have been previously called:
/// 1. Their returned data must be freed.
/// 2. They must be called again.
bool titleIsGameCardInfoUpdated(void);
/// Returns a pointer to a dynamically allocated buffer that holds a filename string suitable for output title dumps. Returns NULL if an error occurs.
char *titleGenerateFileName(TitleInfo *title_info, u8 naming_convention, u8 illegal_char_replace_type);
/// Returns a pointer to a dynamically allocated buffer that holds a filename string suitable for output gamecard dumps. Returns NULL if an error occurs.
/// A valid gamecard must be inserted, and title info must have been loaded from it accordingly.
char *titleGenerateGameCardFileName(u8 naming_convention, u8 illegal_char_replace_type);
/// Returns a pointer to a dynamically allocated buffer that holds a CSV representation of all available user/system title records, depending on the 'is_system' argument.
/// 'out_csv_size' must be a valid pointer. It is used to store the size of the allocated buffer.
/// 'out_proc_title_cnt' may optionally be provided. If available, it will be used to store the number of processed title records.
/// If 'is_system' is false and 'use_gamecard' is true, gamecard title records will be appended to the output buffer.
/// Both 'is_system' and 'use_gamecard' may not be set to true at the same time.
/// Furthermore, if 'is_system' is set to false and orphan titles are available, their records will get appended to the output buffer.
/// Returns NULL if an error occurs.
char *titleGenerateTitleRecordsCsv(size_t *out_csv_size, u32 *out_proc_title_cnt, bool is_system, bool use_gamecard);
/// Returns a pointer to a string holding a user-friendly name for the provided NcmStorageId value. Returns NULL if the provided value is invalid.
const char *titleGetNcmStorageIdName(u8 storage_id);
/// Returns a pointer to a string holding the name of the provided NcmContentType value. Returns NULL if the provided value is invalid.
const char *titleGetNcmContentTypeName(u8 content_type);
/// Returns a pointer to a string holding the name of the provided NcmContentMetaType value. Returns NULL if the provided value is invalid.
const char *titleGetNcmContentMetaTypeName(u8 content_meta_type);
/// Miscellaneous functions.
NX_INLINE bool titleIsValidInfoBlock(TitleInfo *title_info)
{
return (title_info && title_info->storage_id >= NcmStorageId_GameCard && title_info->storage_id <= NcmStorageId_SdCard && title_info->meta_key.id && \
((title_info->meta_key.type >= NcmContentMetaType_SystemProgram && title_info->meta_key.type <= NcmContentMetaType_BootImagePackageSafe) || \
(title_info->meta_key.type >= NcmContentMetaType_Application && title_info->meta_key.type <= NcmContentMetaType_DataPatch)) && \
title_info->content_count && title_info->content_infos);
}
NX_INLINE u64 titleGetPatchIdByApplicationId(u64 app_id)
{
return (app_id + TITLE_PATCH_ID_OFFSET);
}
NX_INLINE u64 titleGetApplicationIdByPatchId(u64 patch_id)
{
return (patch_id - TITLE_PATCH_ID_OFFSET);
}
NX_INLINE bool titleCheckIfPatchIdBelongsToApplicationId(u64 app_id, u64 patch_id)
{
return (patch_id == titleGetPatchIdByApplicationId(app_id));
}
NX_INLINE u64 titleGetAddOnContentBaseIdByApplicationId(u64 app_id)
{
return ((app_id & TITLE_ADDONCONTENT_CONVERSION_MASK) + TITLE_ADDONCONTENT_ID_OFFSET);
}
NX_INLINE u64 titleGetAddOnContentMinIdByBaseId(u64 aoc_base_id)
{
return (aoc_base_id + TITLE_ADDONCONTENT_MIN_INDEX);
}
NX_INLINE u64 titleGetAddOnContentMaxIdByBaseId(u64 aoc_base_id)
{
return (aoc_base_id + TITLE_ADDONCONTENT_MAX_INDEX);
}
NX_INLINE u64 titleGetApplicationIdByAddOnContentId(u64 aoc_id)
{
return ((aoc_id - TITLE_ADDONCONTENT_ID_OFFSET) & TITLE_ADDONCONTENT_CONVERSION_MASK);
}
NX_INLINE bool titleIsAddOnContentIdValid(u64 aoc_id, u64 aoc_min_id, u64 aoc_max_id)
{
return (aoc_min_id <= aoc_id && aoc_id <= aoc_max_id);
}
NX_INLINE bool titleCheckIfAddOnContentIdBelongsToApplicationId(u64 app_id, u64 aoc_id)
{
u64 aoc_base_id = titleGetAddOnContentBaseIdByApplicationId(app_id);
u64 aoc_min_id = titleGetAddOnContentMinIdByBaseId(aoc_base_id);
u64 aoc_max_id = titleGetAddOnContentMaxIdByBaseId(aoc_base_id);
return titleIsAddOnContentIdValid(aoc_id, aoc_min_id, aoc_max_id);
}
NX_INLINE bool titleCheckIfAddOnContentIdsAreSiblings(u64 aoc_id_1, u64 aoc_id_2)
{
u64 app_id_1 = titleGetApplicationIdByAddOnContentId(aoc_id_1);
u64 app_id_2 = titleGetApplicationIdByAddOnContentId(aoc_id_2);
return (app_id_1 == app_id_2 && titleCheckIfAddOnContentIdBelongsToApplicationId(app_id_1, aoc_id_1) && titleCheckIfAddOnContentIdBelongsToApplicationId(app_id_2, aoc_id_2));
}
/// Nintendo uses one-based indexes for IDs... but we won't.
NX_INLINE u64 titleGetAddOnContentIdByApplicationIdAndIndex(u64 app_id, u16 idx)
{
return (titleGetAddOnContentBaseIdByApplicationId(app_id) + 1 + idx);
}
NX_INLINE u64 titleGetDeltaIdByApplicationId(u64 app_id)
{
return (app_id + TITLE_DELTA_ID_OFFSET);
}
NX_INLINE u64 titleGetApplicationIdByDeltaId(u64 delta_id)
{
return (delta_id - TITLE_DELTA_ID_OFFSET);
}
NX_INLINE bool titleCheckIfDeltaIdBelongsToApplicationId(u64 app_id, u64 delta_id)
{
return (delta_id == titleGetDeltaIdByApplicationId(app_id));
}
NX_INLINE u64 titleGetDataPatchIdByAddOnContentId(u64 aoc_id)
{
return (aoc_id + TITLE_PATCH_ID_OFFSET);
}
NX_INLINE u64 titleGetAddOnContentIdByDataPatchId(u64 data_patch_id)
{
return (data_patch_id - TITLE_PATCH_ID_OFFSET);
}
NX_INLINE bool titleCheckIfDataPatchIdBelongsToAddOnContentId(u64 aoc_id, u64 data_patch_id)
{
return (data_patch_id == titleGetDataPatchIdByAddOnContentId(aoc_id));
}
NX_INLINE u64 titleGetApplicationIdByDataPatchId(u64 data_patch_id)
{
return titleGetApplicationIdByAddOnContentId(titleGetAddOnContentIdByDataPatchId(data_patch_id));
}
NX_INLINE bool titleCheckIfDataPatchIdBelongsToApplicationId(u64 app_id, u64 data_patch_id)
{
return titleCheckIfAddOnContentIdBelongsToApplicationId(app_id, titleGetAddOnContentIdByDataPatchId(data_patch_id));
}
NX_INLINE bool titleCheckIfDataPatchIdsAreSiblings(u64 data_patch_id_1, u64 data_patch_id_2)
{
u64 app_id_1 = titleGetApplicationIdByDataPatchId(data_patch_id_1);
u64 app_id_2 = titleGetApplicationIdByDataPatchId(data_patch_id_2);
return (app_id_1 == app_id_2 && titleCheckIfDataPatchIdBelongsToApplicationId(app_id_1, data_patch_id_1) && titleCheckIfDataPatchIdBelongsToApplicationId(app_id_2, data_patch_id_2));
}
NX_INLINE u32 titleGetContentCountByType(TitleInfo *info, u8 content_type)
{
if (!info || !info->content_count || !info->content_infos || content_type > NcmContentType_DeltaFragment) return 0;
u32 cnt = 0;
for(u32 i = 0; i < info->content_count; i++)
{
if (info->content_infos[i].content_type == content_type) cnt++;
}
return cnt;
}
NX_INLINE NcmContentInfo *titleGetContentInfoByTypeAndIdOffset(TitleInfo *info, u8 content_type, u8 id_offset)
{
if (!info || !info->content_count || !info->content_infos || content_type > NcmContentType_DeltaFragment) return NULL;
for(u32 i = 0; i < info->content_count; i++)
{
NcmContentInfo *cur_content_info = &(info->content_infos[i]);
if (cur_content_info->content_type == content_type && cur_content_info->id_offset == id_offset) return cur_content_info;
}
return NULL;
}
NX_INLINE u32 titleGetCountFromInfoBlock(TitleInfo *title_info)
{
if (!title_info) return 0;
u32 count = 1;
TitleInfo *cur_info = title_info->previous;
while(cur_info)
{
count++;
cur_info = cur_info->previous;
}
cur_info = title_info->next;
while(cur_info)
{
count++;
cur_info = cur_info->next;
}
return count;
}
#ifdef __cplusplus
}
#endif
#endif /* __TITLE_H__ */