1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_AOC_API_H_ 14 #define NN_AOC_API_H_ 15 16 #include <nn/aoc/aoc_Types.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /*! 23 @ingroup nn_aoc 24 @defgroup nn_aoc_api Add-on Content (AOC) API 25 @brief Members of the Add-on Content (AOC) library API. (Includes only C API members.) 26 @{ 27 */ 28 29 /*! 30 @brief Initializes the Add-on Content (AOC) library. 31 32 @return Returns the result of execution. 33 @retval ::AOC_STATUS_OK Indicates success. 34 @retval ::AOC_STATUS_ALREADY_INITIALIZED Indicates that the library is already initialized. 35 36 */ 37 AOCStatus AOC_Initialize(void); 38 39 40 /*! 41 @brief Finalizes the Add-on Content (AOC) library. 42 43 @return Returns the result of execution. 44 @retval ::AOC_STATUS_OK Indicates success. 45 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 46 @retval ::AOC_STATUS_TITLE_STILL_OPENED Indicates that a title is still open. 47 48 */ 49 AOCStatus AOC_Finalize(void); 50 51 52 53 54 55 56 /*! 57 @brief Lists the downloadable content titles. 58 Use this API function with the assumption that it does not return from processing for a long time. 59 Also, when using downloadable content on a USB device, sometimes the content cannot be found if <b>SystemConfigTool</b> > <b>Test</b> > <b>FindUSB</b> is not <tt>TRUE</tt>. 60 61 @param[out] pNumTitles Specifies the buffer that stores the number of titles obtained. 62 @param[out] pTitleList Specifies the buffer that stores the information on the titles obtained. 63 @param[in] maxListNum Specifies the maximum number of titles to get. 64 @param[in] pWorkBuffer Specifies the work buffer. The size of the work buffer must be at least the value obtained with the <tt>AOC_CalculateWorkBufferSize</tt> function. 65 Also, the first address in each buffer must be 64-byte aligned. 66 @param[in] bufferSize Specifies the size of the work buffer. 67 68 @return Returns the result of execution. 69 @retval ::AOC_STATUS_OK Indicates success. 70 @retval ::AOC_STATUS_INVALID_PARAM Indicates that one of the arguments is invalid. 71 There may be a <tt>NULL</tt> pointer or the buffer may be too small. 72 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 73 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 74 75 @details An application can access only the downloadable content titles listed when this function is called. 76 77 Only titles that meet the following conditions are listed. 78 - The <tt>UniqueId</tt> is contained in the <tt>addon_unique_idX</tt> element of the <tt>meta.xml</tt> file of the application that calls this function. 79 - The title is installed in either NAND memory or USB storage. 80 - Titles that have been purchased from the eShop but have not been installed yet are not listed. 81 - If the application was started with <tt>caferun</tt>, the PCFS emulation is searched instead of NAND memory. 82 - Where the application was started from (DISC, NAND, or USB) determines whether the function searches NAND memory or USB storage. 83 This occurs according to the combinations listed in the section on the debugging environment and the configuration of downloadable content in the E-Commerce Overview. 84 85 86 */ 87 AOCStatus AOC_ListTitle(u32* pNumTitles, 88 AOC_TitleListType* pTitleList, 89 u32 maxListNum, 90 void* pWorkBuffer, 91 u32 bufferSize); 92 93 /*! 94 @brief Calculates the size of the working buffer. 95 96 @param[in] maxListNum Specifies the same value that was passed to <var>maxListNum</var> when calling <tt>AOC_ListTitle</tt>. 97 98 @return Returns the buffer size. 99 100 */ 101 u32 AOC_CalculateWorkBufferSize(u32 maxListNum); 102 103 104 105 /*! 106 @brief Opens a downloadable content title. 107 Use this API function with the assumption that it does not return from processing for a long time. 108 109 @param[out] pPath Specifies the path to the content directory. 110 @param[in] pTarget Specifies information about the target content title. 111 @param[in] pWorkBuffer Specifies the work buffer. Requires the buffer size obtained when <tt>0</tt> is passed to the <tt>AOC_CalculateWorkBufferSize</tt> function. 112 Also, the first address in each buffer must be 64-byte aligned. 113 @param[in] bufferSize Specifies the size of the work buffer. 114 115 @return Returns the result of execution. 116 @retval ::AOC_STATUS_OK Indicates success. 117 @retval ::AOC_STATUS_INVALID_PARAM Indicates that one of the arguments is invalid. 118 There may be a <tt>NULL</tt> pointer or the buffer may be too small. 119 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 120 @retval ::AOC_STATUS_ALREADY_OPENED Indicates the title is already open. 121 @retval ::AOC_STATUS_EXCEED_LIMIT Indicates that the limit on the number of open titles has been exceeded. 122 @retval ::AOC_STATUS_NOT_FOUND_TITLE Indicates that the title specified in <var>pTarget</var> does not exist. 123 @retval ::AOC_STATUS_ACCESS_DENIED Indicates that an unauthorized <tt>TitleId</tt> was specified. 124 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 125 126 @details This functions opens downloadable content titles so that they can be accessed by the application. 127 Make sure to call the <tt>AOC_CloseTitle</tt> function explicitly before exiting from the application. 128 129 If the function successfully opens a downloadable content title, the <var>pPath</var> parameter stores the path to the root directory in which the DLC resides. 130 In this root directory, there is a DLC directory that contains only DLC that has been purchased and installed. 131 The application performs a file system operation on the path contained in <var>pPath</var> to open the DLC. 132 133 134 */ 135 AOCStatus AOC_OpenTitle(char* pPath, 136 const AOC_TitleListType* pTarget, 137 void* pWorkBuffer, 138 u32 bufferSize); 139 140 141 /*! 142 @brief Closes the downloadable content title. 143 Call this function when ending access to downloadable content opened with the <tt>AOC_OpenTitle</tt> function. 144 145 @param[in] pTarget Specifies information about the target content title. 146 147 @return Returns the result of execution. 148 @retval ::AOC_STATUS_OK Indicates success. 149 @retval ::AOC_STATUS_INVALID_PARAM Indicates that one of the arguments is invalid. 150 There may be a <tt>NULL</tt> pointer or the buffer may be too small. 151 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 152 @retval ::AOC_STATUS_NOT_OPENED Indicates the title is not open. 153 @retval ::AOC_STATUS_CLOSE_FAILURE Indicates that a directory or file within the title is open. 154 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 155 156 */ 157 AOCStatus AOC_CloseTitle(const AOC_TitleListType* pTarget); 158 159 160 /*! 161 @brief Deletes downloadable content. 162 163 @param[in] titleId Specifies the <tt>TitleId</tt> of the downloadable content. 164 @param[in] contentIndexes Specifies the array that stores the <tt>ContentIndex</tt> of the downloadable content to delete. 165 @param[in] numContents Specifies the number of <var>contentIndexes</var>. 166 @param[in] pWorkBuffer Specifies the work buffer. Requires the buffer size obtained when <tt>0</tt> is passed to the <tt>AOC_CalculateWorkBufferSize</tt> function. 167 Also, the first address in each buffer must be 64-byte aligned. 168 @param[in] bufferSize Specifies the size of the work buffer. 169 170 @return Returns the result of execution. 171 @retval ::AOC_STATUS_OK Indicates success. 172 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 173 @retval ::AOC_STATUS_NOT_OPENED Indicates the title is not open. 174 @retval ::AOC_STATUS_NOT_FOUND_CONTENT Indicates that the <tt>ContentIndex</tt> specified in <var>contentIndexes</var> has no content. 175 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 176 */ 177 AOCStatus AOC_DeleteContent(u64 titleId, 178 u16 contentIndexes[], 179 u32 numContents, 180 void* pWorkBuffer, 181 u32 bufferSize); 182 183 184 /*! 185 @brief Gets the size of the downloadable content. 186 This function can accurately get the size of content installed on a PC file system, but cannot correctly get the size of content installed in NAND memory. 187 The size it gets is larger than the actual file size. 188 189 @param[out] pOutSizes Specifies the buffer that stores the size obtained. 190 @param[in] titleId Specifies the <tt>TitleId</tt> of the downloadable content. 191 @param[in] contentIndexes Specifies the array that stores the <tt>ContentIndex</tt> of content to get the size of. 192 @param[in] numContents Specifies the number of <var>contentIndexes</var>. 193 @param[in] pWorkBuffer Specifies the work buffer. Requires the buffer size obtained when <tt>0</tt> is passed to the <tt>AOC_CalculateWorkBufferSize</tt> function. 194 Also, the first address in each buffer must be 64-byte aligned. 195 @param[in] bufferSize Specifies the size of the work buffer. 196 197 @return Returns the result of execution. 198 @retval ::AOC_STATUS_OK Indicates success. 199 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 200 @retval ::AOC_STATUS_NOT_OPENED Indicates that the title is not open. 201 @retval ::AOC_STATUS_NOT_FOUND_CONTENT Indicates that the <tt>ContentIndex</tt> specified in <var>contentIndexes</var> has no content. 202 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 203 204 @details This function exhibits the following differences in functionality when accessing content on PCFS and on NAND/USB. 205 206 <b>Retrievable size</b> 207 - When accessing PCFS: 208 - The total size of all files in the content. 209 - When accessing NAND/USB: 210 - A value larger than the total size of all files in the content. 211 212 <b>Conditions that return <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt></b> 213 - When accessing PCFS: 214 - Returns <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt> if even one of the content items specified in <var>contentIndexes</var> is not installed. 215 - When accessing NAND/USB: 216 - Returns <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt> if the content item specified in <span class="argument">contentIndexes[0]</span> is not installed. 217 - If the content item specified in <span class="argument">contentIndexes[0]</span> is installed, even if the content items specified in later elements are not installed, the function operates as if it is not installed and does not return an error. 218 219 220 */ 221 AOCStatus AOC_GetOccupiedSize(u64* pOutSizes, 222 u64 titleId, 223 u16 contentIndexes[], 224 u32 numContents, 225 void* pWorkBuffer, 226 u32 bufferSize); 227 228 229 /*! 230 @brief Gets the purchase information for the downloadable content. 231 Gets whether the specified downloadable content has already been purchased. 232 233 @param[out] pOutPurchaseInfo Specifies an array that stores the purchase information. The array contains <tt>TRUE</tt> for content that has already been purchased. 234 When the function ends in an error, the <var>pOutPurchaseInfo</var> region might be changed. Only use this value when the function succeeds. 235 236 @param[in] titleId Specifies the <tt>TitleId</tt> of the downloadable content. 237 @param[in] contentIndexes Specifies the array that stores the <tt>ContentIndex</tt> of content to get the purchase information for. 238 @param[in] numContents Specifies the number of <var>contentIndexes</var>. 239 @param[in] pWorkBuffer Specifies the work buffer. Requires the buffer size obtained when <tt>0</tt> is passed to the <tt>AOC_CalculateWorkBufferSize</tt> function. 240 Also, the first address in each buffer must be 64-byte aligned. 241 @param[in] bufferSize Specifies the size of the work buffer. 242 243 @return Returns the result of execution. 244 @retval ::AOC_STATUS_OK Indicates success. 245 @retval ::AOC_STATUS_INVALID_PARAM Indicates that one of the arguments is invalid. 246 There may be a <tt>NULL</tt> pointer or the buffer may be too small. 247 @retval ::AOC_STATUS_NOT_INITIALIZED Indicates that the library is not initialized. 248 @retval ::AOC_STATUS_ACCESS_DENIED Indicates that an unauthorized <tt>TitleId</tt> was specified. 249 @retval ::AOC_STATUS_INTERNAL_ERROR Indicates an unexpected error. 250 251 @details Purchase information can be stored internally by doing either of the following. 252 - Purchasing content from the eShop server. 253 - Installing a downloadable content title from the System Config Tool. 254 255 Note that you can mark a specific item of content as purchased using the former approach, but the latter approach marks all content as purchased. 256 257 To delete the purchase information, use the System Config Tool to uninstall the downloadable content. 258 259 260 261 */ 262 AOCStatus AOC_GetPurchaseInfo( BOOL* pOutPurchaseInfo, 263 u64 titleId, 264 u16 contentIndexes[], 265 u32 numContents, 266 void* pWorkBuffer, 267 u32 bufferSize); 268 269 270 271 /*! 272 @brief Switches the reference target for downloadable content. 273 274 @param[in] enable When you specify <tt>TRUE</tt>, applications always use the system memory for accessing downloadable content. 275 276 @return None. 277 278 279 @details When an application is run on development hardware, it looks for downloadable content from different places depending on the type of storage the application was started from. You can force the application to always reference the system memory by passing <tt>true</tt> to this function. 280 281 282 <table> 283 <tr> 284 <th>Application Startup Location</th><th>Standard Reference Target</th><th>Reference Target When This Function Is Called With <tt>true</tt></th> 285 </tr> 286 <tr> 287 <td>PCFS</td><td>PCFS, USB</td><td>MLC, USB</td> 288 </tr> 289 <tr> 290 <td>MLC</td><td>MLC</td><td>MLC</td> 291 </tr> 292 <tr> 293 <td>USB</td><td>USB</td><td>USB</td> 294 </tr> 295 </table> 296 297 298 When using the AOC library together with a module that always references system memory (such as ECDK), be sure to call this function to switch the reference target to system memory. 299 300 On non-development hardware, the reference target for downloadable content is automatically set to system memory. 301 Calling this API does not cause any problems, but it does not do anything either. 302 303 304 305 306 */ 307 void AOC_DebugRealDeviceAccess(BOOL enable); 308 309 /*! 310 @brief Gets error codes for display to the user. 311 312 Pass the value acquired from this function to the error viewer to display the error. @n 313 @n 314 The value obtained from this function must not be used for error handling. 315 316 @param[in] status Specifies the <tt>AOCStatus</tt> value returned by the AOC library. 317 318 @return Returns the error code as a seven-digit decimal number. 319 When <tt>AOC_STATUS_OK</tt> or an unexpected status is passed in, returns <tt>AOC_ERROR_CODE_UNKNOWN</tt>. 320 */ 321 u32 AOC_GetErrorCode(AOCStatus status); 322 323 /*! 324 @} 325 */ 326 327 #ifdef __cplusplus 328 } 329 #endif 330 331 #endif // NN_AOC_API_H_ 332