/*---------------------------------------------------------------------------*

Copyright (C) Nintendo.  All rights reserved.

These coded instructions, statements, and computer programs contain
proprietary information of Nintendo of America Inc. and/or Nintendo
Company Ltd., and are protected by Federal copyright law.  They may
not be disclosed to third parties or copied or duplicated in any form,
in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

#ifndef NN_AOC_API_H_
#define NN_AOC_API_H_

#include <nn/aoc/aoc_Types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@ingroup  nn_aoc
@defgroup nn_aoc_api  Add-on Content (AOC) API
@brief  Members of the Add-on Content (AOC) library API. (Includes only C API members.)
    @{
*/

/*!
@brief  Initializes the Add-on Content (AOC) library.

@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_ALREADY_INITIALIZED  Indicates that the library is already initialized.
                
*/
AOCStatus AOC_Initialize(void);


/*!
@brief  Finalizes the Add-on Content (AOC) library.

@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_TITLE_STILL_OPENED  Indicates that a title is still open.
                
*/
AOCStatus AOC_Finalize(void);






/*!
@brief  Lists the downloadable content titles.
Use this API function with the assumption that it does not return from processing for a long time.
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>.

@param[out] pNumTitles  Specifies the buffer that stores the number of titles obtained.
@param[out] pTitleList  Specifies the buffer that stores the information on the titles obtained.
@param[in] maxListNum  Specifies the maximum number of titles to get.
@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.
Also, the first address in each buffer must be 64-byte aligned.
@param[in] bufferSize  Specifies the size of the work buffer.
                    
@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_INVALID_PARAM  Indicates that one of the arguments is invalid.
There may be a <tt>NULL</tt> pointer or the buffer may be too small.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.

@details  An application can access only the downloadable content titles listed when this function is called.
                    
Only titles that meet the following conditions are listed.
- 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.
- The title is installed in either NAND memory or USB storage.
- Titles that have been purchased from the eShop but have not been installed yet are not listed.
- If the application was started with <tt>caferun</tt>, the PCFS emulation is searched instead of NAND memory.
- Where the application was started from (DISC, NAND, or USB) determines whether the function searches NAND memory or USB storage.
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.


*/
AOCStatus AOC_ListTitle(u32*                pNumTitles, 
                        AOC_TitleListType*  pTitleList,
                        u32                 maxListNum,
                        void*               pWorkBuffer,
                        u32                 bufferSize);

/*!
@brief  Calculates the size of the working buffer.
    
@param[in] maxListNum  Specifies the same value that was passed to <var>maxListNum</var> when calling <tt>AOC_ListTitle</tt>.
    
@return  Returns the buffer size.

*/
u32       AOC_CalculateWorkBufferSize(u32 maxListNum);



/*!
@brief  Opens a downloadable content title.
Use this API function with the assumption that it does not return from processing for a long time.

@param[out] pPath  Specifies the path to the content directory.
@param[in] pTarget  Specifies information about the target content title.
@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.
Also, the first address in each buffer must be 64-byte aligned.
@param[in] bufferSize  Specifies the size of the work buffer.
                    
@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_INVALID_PARAM  Indicates that one of the arguments is invalid.
There may be a <tt>NULL</tt> pointer or the buffer may be too small.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_ALREADY_OPENED  Indicates the title is already open.
@retval ::AOC_STATUS_EXCEED_LIMIT  Indicates that the limit on the number of open titles has been exceeded.
@retval ::AOC_STATUS_NOT_FOUND_TITLE  Indicates that the title specified in <var>pTarget</var> does not exist.
@retval ::AOC_STATUS_ACCESS_DENIED  Indicates that an unauthorized <tt>TitleId</tt> was specified.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.

@details  This functions opens downloadable content titles so that they can be accessed by the application.
Make sure to call the <tt>AOC_CloseTitle</tt> function explicitly before exiting from the application.

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.
In this root directory, there is a DLC directory that contains only DLC that has been purchased and installed.
The application performs a file system operation on the path contained in <var>pPath</var> to open the DLC.


*/
AOCStatus AOC_OpenTitle(char*                       pPath,
                        const AOC_TitleListType*    pTarget,
                        void*                       pWorkBuffer,
                        u32                         bufferSize);


/*!
@brief  Closes the downloadable content title.
Call this function when ending access to downloadable content opened with the <tt>AOC_OpenTitle</tt> function.

@param[in] pTarget  Specifies information about the target content title.
                    
@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_INVALID_PARAM  Indicates that one of the arguments is invalid.
There may be a <tt>NULL</tt> pointer or the buffer may be too small.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_NOT_OPENED  Indicates the title is not open.
@retval ::AOC_STATUS_CLOSE_FAILURE  Indicates that a directory or file within the title is open.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.

*/
AOCStatus AOC_CloseTitle(const AOC_TitleListType* pTarget);


/*!
@brief  Deletes downloadable content.
    
@param[in] titleId  Specifies the <tt>TitleId</tt> of the downloadable content.
@param[in] contentIndexes  Specifies the array that stores the <tt>ContentIndex</tt> of the downloadable content to delete.
@param[in] numContents  Specifies the number of <var>contentIndexes</var>.
@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.
Also, the first address in each buffer must be 64-byte aligned.
@param[in] bufferSize  Specifies the size of the work buffer.
    
@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_NOT_OPENED  Indicates the title is not open.
@retval ::AOC_STATUS_NOT_FOUND_CONTENT  Indicates that the <tt>ContentIndex</tt> specified in <var>contentIndexes</var> has no content.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.
*/
AOCStatus AOC_DeleteContent(u64         titleId,
                            u16         contentIndexes[],
                            u32         numContents,
                            void*       pWorkBuffer,
                            u32         bufferSize);
 
 
/*!
@brief  Gets the size of the downloadable content.
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.
The size it gets is larger than the actual file size.

@param[out] pOutSizes  Specifies the buffer that stores the size obtained.
@param[in] titleId  Specifies the <tt>TitleId</tt> of the downloadable content.
@param[in] contentIndexes  Specifies the array that stores the <tt>ContentIndex</tt> of content to get the size of.
@param[in] numContents  Specifies the number of <var>contentIndexes</var>.
@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.
Also, the first address in each buffer must be 64-byte aligned.
@param[in] bufferSize  Specifies the size of the work buffer.

@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_NOT_OPENED  Indicates that the title is not open.
@retval ::AOC_STATUS_NOT_FOUND_CONTENT  Indicates that the <tt>ContentIndex</tt> specified in <var>contentIndexes</var> has no content.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.
                    
@details  This function exhibits the following differences in functionality when accessing content on PCFS and on NAND/USB.
                    
<b>Retrievable size</b>
- When accessing PCFS:
- The total size of all files in the content.
- When accessing NAND/USB:
- A value larger than the total size of all files in the content.
                    
<b>Conditions that return <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt></b>
- When accessing PCFS:
- Returns <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt> if even one of the content items specified in <var>contentIndexes</var> is not installed.
- When accessing NAND/USB:
- Returns <tt>AOC_STATUS_NOT_FOUND_CONTENT</tt> if the content item specified in <span class="argument">contentIndexes[0]</span> is not installed.
- 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.
    

*/
AOCStatus AOC_GetOccupiedSize(u64*          pOutSizes,
                              u64           titleId,
                              u16           contentIndexes[],
                              u32           numContents,
                              void*         pWorkBuffer,
                              u32           bufferSize);


/*!
@brief  Gets the purchase information for the downloadable content.
Gets whether the specified downloadable content has already been purchased.

@param[out] pOutPurchaseInfo  Specifies an array that stores the purchase information. The array contains <tt>TRUE</tt> for content that has already been purchased.
When the function ends in an error, the <var>pOutPurchaseInfo</var> region might be changed. Only use this value when the function succeeds.
                                                    
@param[in] titleId  Specifies the <tt>TitleId</tt> of the downloadable content.
@param[in] contentIndexes  Specifies the array that stores the <tt>ContentIndex</tt> of content to get the purchase information for.
@param[in] numContents  Specifies the number of <var>contentIndexes</var>.
@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.
Also, the first address in each buffer must be 64-byte aligned.
@param[in] bufferSize  Specifies the size of the work buffer.

@return  Returns the result of execution.
@retval ::AOC_STATUS_OK  Indicates success.
@retval ::AOC_STATUS_INVALID_PARAM  Indicates that one of the arguments is invalid.
There may be a <tt>NULL</tt> pointer or the buffer may be too small.
@retval ::AOC_STATUS_NOT_INITIALIZED  Indicates that the library is not initialized.
@retval ::AOC_STATUS_ACCESS_DENIED  Indicates that an unauthorized <tt>TitleId</tt> was specified.
@retval ::AOC_STATUS_INTERNAL_ERROR  Indicates an unexpected error.
    
@details  Purchase information can be stored internally by doing either of the following.
- Purchasing content from the eShop server.
- Installing a downloadable content title from the System Config Tool.
                    
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.

To delete the purchase information, use the System Config Tool to uninstall the downloadable content.



*/
AOCStatus AOC_GetPurchaseInfo(  BOOL*         pOutPurchaseInfo,
                                u64           titleId,
                                u16           contentIndexes[],
                                u32           numContents,
                                void*         pWorkBuffer,
                                u32           bufferSize);



/*!
@brief  Switches the reference target for downloadable content.

@param[in] enable  When you specify <tt>TRUE</tt>, applications always use the system memory for accessing downloadable content.
                            
@return  None.
                            
    
@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.


<table>
<tr>
<th>Application Startup Location</th><th>Standard Reference Target</th><th>Reference Target When This Function Is Called With <tt>true</tt></th>
</tr>
<tr>
<td>PCFS</td><td>PCFS, USB</td><td>MLC, USB</td>
</tr>
<tr>
<td>MLC</td><td>MLC</td><td>MLC</td>
</tr>
<tr>
<td>USB</td><td>USB</td><td>USB</td>
</tr>
</table>


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.

On non-development hardware, the reference target for downloadable content is automatically set to system memory.
Calling this API does not cause any problems, but it does not do anything either.
                    



*/
void AOC_DebugRealDeviceAccess(BOOL enable);

/*!
@brief  Gets error codes for display to the user.

Pass the value acquired from this function to the error viewer to display the error. @n
@n
The value obtained from this function must not be used for error handling.

@param[in] status  Specifies the <tt>AOCStatus</tt> value returned by the AOC library.

@return  Returns the error code as a seven-digit decimal number.
When <tt>AOC_STATUS_OK</tt> or an unexpected status is passed in, returns <tt>AOC_ERROR_CODE_UNKNOWN</tt>.
*/
u32 AOC_GetErrorCode(AOCStatus status);

/*!
    @}
*/

#ifdef __cplusplus
}
#endif

#endif // NN_AOC_API_H_