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

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_BOSS_BOSS_DATASTOREUPLOADSETTING_H_
#define NN_BOSS_BOSS_DATASTOREUPLOADSETTING_H_

#include <nn/boss/boss_Const.h>
#include <nn/boss/boss_DataStoreConst.h>
#include <nn/boss/boss_Result.h>
#include <nn/boss/boss_Types.h>
#include <nn/boss/boss_RawUlTaskSetting.h>

#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup  nn_boss_api
  @{
*/

/*!
@brief  Represents settings for <tt>DataStore</tt> upload tasks. These settings are used when registering a task.
*/
class DataStoreUploadSetting : public RawUlTaskSetting
{
public:
/*!
@brief  Instantiates an object.
*/
    explicit DataStoreUploadSetting(void);

/*!
@brief  Destroys the object.
*/
    virtual ~DataStoreUploadSetting(void);

/*!
@brief  Initializes settings for a <tt>DataStore</tt> upload task. If initialization succeeds, you can register the information using the <tt>@ref Task::Register</tt> function.

@param[in] pUploadData  Specifies a pointer to the beginning of the data to upload. Do not free this data until the <tt>@ref Task::Register</tt> function completes. Set this parameter to <tt>NULL</tt> when uploading only metabinary data.
@param[in] uploadDataSize  Specifies the size of the data to upload. Set this parameter to <tt>0</tt> when uploading only metabinary data.
@param[in] gameId  Specifies the ID for the game server. (For more information, see the documentation in the NEX library.)
@param[in] accessKey  Specifies the key for accessing the game server. (Specify no more than 8 characters. For more information, see the documentation in the NEX library.)
@param[in] dstKind  Specifies the message data destination type. (For more information, see the documentation in the NEX library.)
@param[in] dataType  Specifies a value representing the data type.
@param[in] period  Specifies the number of days before the data is automatically deleted. (For more information, see the documentation in the NEX library.)
@param[in] pWorkBufferForTag  Specifies a pointer to the beginning of the working buffer than must be specified when using tags. This parameter can be omitted (set to <tt>NULL</tt>) when tags are not used. When using tags, specify a work buffer that is at least as large of the total size of all strings used for tags, including the <tt>NULL</tt> terminators. The maximum total size is <tt> @ref datastore::TAG_MAX_CHAR_LENGTH_WITH_NULL * @ref datastore::TAG_MAX_COUNT</tt>. If you set a working buffer of 10 KB or more, you can use the buffer for any tag set.
@param[in] SizeOfWorkBufferForTag  Specifies the size of <var>pWorkBufferForTag</var>. This parameter can be omitted (set to <tt>0</tt>) when tags are not used.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful retrieval.
@retval ResultInvalidParameter  Indicates an invalid parameter.
*/
    nn::Result Initialize( const u8* pUploadData, s64 uploadDataSize, u32 gameId, const wchar_t accessKey[], datastore::DestinationKind dstKind, u16 dataType, u16 period, void* pWorkBufferForTag = NULL, size_t SizeOfWorkBufferForTag = 0);

/*!
@brief  Initializes settings for a <tt>DataStore</tt> upload task. If initialization succeeds, you can register the information using the <tt>@ref Task::Register</tt> function.

@param[in] uploadFilePath  Specifies the file path to the data to upload. Do not delete this file until the <tt>@ref Task::Register</tt> function completes.
@param[in] pUploadWorkBuffer  Specifies a pointer to the start of memory to use as a working buffer during upload. It is used to copy the data uploaded using <tt>@ref Task::Register</tt>. It is also used as the <var>dest</var> argument of the <tt>FSReadFile</tt> function, so the buffer alignment must be compatible with this function. The larger the size of the buffer that you provide, the faster the <tt>@ref Task::Register</tt> function completes. Do not free this memory until the <tt>@ref Task::Register</tt> function completes.
@param[in] uploadWorkBufferSize  Specifies the size of <var>pUploadWorkBuffer</var>.
@param[in] gameId  Specifies the ID for the game server. (For more information, see the documentation in the NEX library.)
@param[in] accessKey  Specifies the key for accessing the game server. (Specify no more than 8 characters. For more information, see the documentation in the NEX library.)
@param[in] dstKind  Specifies the message data destination type. (For more information, see the documentation in the NEX library.)
@param[in] dataType  Specifies a value representing the data type.
@param[in] period  Specifies the number of days before the data is automatically deleted. (For more information, see the documentation in the NEX library.)
@param[in] pWorkBufferForTag  Specifies a pointer to the beginning of the working buffer than must be specified when using tags. This parameter can be omitted (set to <tt>NULL</tt>) when tags are not used. When using tags, specify a work buffer that is at least as large of the total size of all strings used for tags, including the <tt>NULL</tt> terminators. The maximum total size is <tt> @ref datastore::TAG_MAX_CHAR_LENGTH_WITH_NULL * @ref datastore::TAG_MAX_COUNT</tt>. If you set a working buffer of 10 KB or more, you can use the buffer for any tag set.
@param[in] SizeOfWorkBufferForTag  Specifies the size of <var>pWorkBufferForTag</var>. This parameter can be omitted (set to <tt>0</tt>) when tags are not used.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful retrieval.
@retval ResultInvalidParameter  Indicates an invalid parameter.
*/
    nn::Result Initialize( const char* uploadFilePath, u8* pUploadWorkBuffer, s64 uploadWorkBufferSize, u32 gameId, const wchar_t accessKey[], datastore::DestinationKind dstKind, u16 dataType, u16 period, void* pWorkBufferForTag = NULL, size_t SizeOfWorkBufferForTag = 0);

/*!
@brief  Adds a data destination. This function can only be used if the <var>dstKind</var> parameter of <tt>@ref Initialize</tt> was set to <tt>@ref datastore::DSTKIND_SPECIFIED </tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>. Data is sent to the added user.

In a <tt>DataStore</tt>, the data destination is specified by principal ID. <br/>
(For more information, see the documentation in the NEX library. ) <br />
The most that can be added is defined as <tt>@ref datastore::DESTINATION_PRINCIPAL_ID_MAX_COUNT</tt>. <br/>

@param[in] principalId  Specifies the principal ID of the data destination.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultFull  The maximum number of <tt>DataStore</tt> data destinations was exceeded. The maximum count is defined as <tt>@ref datastore::DESTINATION_PRINCIPAL_ID_MAX_COUNT</tt>.
@retval ResultInvalidParameter  The <var>dstKind</var> parameter in <tt>@ref Initialize</tt> was neither <tt>@ref datastore::DSTKIND_SPECIFIED</tt> nor <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.
*/
    nn::Result AddDestination( u32 principalId );

/*!
@brief  Adds multiple data destinations. This function can only be used if the <var>dstKind</var> parameter of <tt>@ref Initialize</tt> was set to <tt>@ref datastore::DSTKIND_SPECIFIED </tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>. This allows the data to be sent to the configured users.

For information about the ID to set, see the API reference for <tt>@ref AddDestination</tt>. <br />

@param[in] principalIds  Specifies an array of the principal IDs of the data destinations.
@param[in] principalIdCount  Specifies the number of data destinations.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultFull  The maximum number of <tt>DataStore</tt> data destinations was exceeded. When this value is returned, no destinations are set in this function call. (Any destinations that were added beforehand remain that way. ) The maximum count is defined as <tt>@ref datastore::DESTINATION_PRINCIPAL_ID_MAX_COUNT</tt>.
@retval ResultInvalidParameter  The <var>dstKind</var> parameter in <tt>@ref Initialize</tt> was neither <tt>@ref datastore::DSTKIND_SPECIFIED</tt> nor <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.
*/
    nn::Result SetDestinations( u32 principalIds[], u32 principalIdCount);

/*!
@brief  Clears all data destinations.
*/
    void ClearDestinations(void);

/*!
@brief  Adds a tag.

In a <tt>DataStore</tt>, multiple tags can be set on send data. <br />
A single tag string can be set to either ASCII characters or multiple-byte characters. The maximum length of the string is defined as <tt>@ref datastore::TAG_MAX_CHARACTER_COUNT</tt>. <br />
Specify multiple-byte characters as a UTF-8 byte string using the <tt>\\x</tt> hexadecimal notation. <br />
(For more information about tags, see the documentation in the NEX library. ) <br />
The maximum number of tags that can be set is defined as <tt>@ref datastore::TAG_MAX_COUNT</tt>. <br />

@param[in] tag  Specifies the tag value to add.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultFull  The maximum number of tags is already set. The maximum count is defined as <tt>@ref datastore::TAG_MAX_COUNT</tt>.
*/
    nn::Result AddTag( const char tag[datastore::TAG_MAX_CHAR_LENGTH_WITH_NULL]);

/*!
@brief  Clears all tags.
*/
    void ClearTags(void);

/*!
@brief  Sets a meta-binary.

With a <tt>DataStore</tt>, meta-binary data can be sent along with send data. <br />
(For more information, see the documentation in the NEX library. ) <br />
There can only be one meta-binary with a maximum size of 1 KB. <br />
The meta-binary data is copied to BOSS storage when registering the task. <br />
For this reason, do not clear the buffer set in the <var>pMetaBinary</var> parameter until task registration is complete. <br />

@param[in] pMetaBinary  Specifies a pointer to the buffer that stores the meta-binary data to set.
@param[in] metaBinarySize  Specifies the size of the data stored in <var>pMetaBinary</var>.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultAlreadyExist  Meta-binary data is already set. If you want to reset the data, call <tt>@ref ClearMetaBinary</tt> before calling this function.
*/
    nn::Result SetMetaBinary( const u8* pMetaBinary, size_t metaBinarySize );

/*!
@brief  Clears the set meta-binary.

This function only clears the setting. The content of the buffer specified in the <var>pMetaBinary</var> parameter of <tt>@ref SetMetaBinary</tt> is not cleared.
*/
    void ClearMetaBinary(void);

/*!
@brief  Sets the data ID. Used only for updating data that has already been uploaded. Specify the ID of the data to update.

@param[in] id  Specifies the ID of the uploaded data to update. You can get the ID of data uploaded in a <tt>DataStore</tt> upload task by calling <tt>@ref Task::GetOptionResult</tt> with <tt>@ref datastore::UPLOAD_DATA_ID</tt> specified as the argument after the task is successfully complete.
*/
    void SetDataId( u64 id );

/*!
@brief  Clears the set data ID.
*/
    void ClearDataId(void);

/*!
@brief  Sets the update permissions. If this function is not used to set the permission explicitly, the permission to update the uploaded data defaults to <tt>@ref datastore::DSTKIND_PRIVATE</tt> (only the sender can update).

@param[in] updatePermission  Specifies the update permissions to set. The uploaded data matching the specified <tt>@ref datastore::DestinationKind</tt> can be updated.
*/
    void SetUpdatePermission( datastore::DestinationKind updatePermission );

/*!
@brief  Clears the set update permissions.
*/
    void ClearUpdatePermission(void);

/*!
@brief  Adds the principal ID of a user to be given update permission. You can only use this function when <tt>@ref SetUpdatePermission</tt> is set to either <tt>@ref datastore::DSTKIND_SPECIFIED</tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.

For more information about update permissions, see the documentation in the NEX library. <br />
The most that can be added is defined as <tt>@ref datastore::MAX_COUNT_OF_PRINCIPAL_ID_WITH_UPDATE_PERMISSION</tt>. <br />

@param[in] principalId  Specifies the principal ID of the user to give update permission.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultFull  The maximum number of users to be given update permissions was exceeded. The maximum count is defined as <tt>@ref datastore::MAX_COUNT_OF_PRINCIPAL_ID_WITH_UPDATE_PERMISSION</tt>.
@retval ResultInvalidParameter  <tt>@ref SetUpdatePermission</tt> has not been called, or was called with a value other than <tt>@ref datastore::DSTKIND_SPECIFIED</tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.
*/
    nn::Result AddIdWithUpdatePermission( u32 principalId );

/*!
@brief  Sets the principal IDs of multiple users to be given update permission. You can only use this function when <tt>@ref SetUpdatePermission</tt> is set to either <tt>@ref datastore::DSTKIND_SPECIFIED</tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.

For information about the ID to set, see the API reference for <tt>@ref AddIdWithUpdatePermission</tt>. <br />

@param[in] principalIds  Specifies an array of principal IDs of the users to give update permission.
@param[in] principalIdCount  Specifies the number of users to given update permission.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultFull  The maximum number of users to be given update permissions was exceeded. When this value is returned, no users are set in this function call. (Any users that were added beforehand remain that way.) The maximum count is defined as <tt>@ref datastore::MAX_COUNT_OF_PRINCIPAL_ID_WITH_UPDATE_PERMISSION</tt>.
@retval ResultInvalidParameter  <tt>@ref SetUpdatePermission</tt> has not been called, or was called with a value other than <tt>@ref datastore::DSTKIND_SPECIFIED</tt> or <tt>@ref datastore::DSTKIND_SPECIFIED_FRIEND</tt>.
*/
    nn::Result SetIdsWithUpdatePermission( u32 principalIds[], u32 principalIdCount);

/*!
@brief  Clears all users that are set to be given update permission.
*/
    void ClearIdsWithUpdatePermission(void);

/*!
@brief  Specifies processing options.

@param[in] option  Specifies the option value. Acceptable values are defined as <tt>datastore::DATASTORE_UPLOAD_OPTION_</tt><i><tt>xxx</tt></i> bit flag constants.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successfully specified.
@retval ResultInvalidParameter  Indicates an invalid parameter.
*/
    nn::Result SetOption(u32 option);


private:
    virtual nn::Result RegisterPreprocess( nn::boss::AccountID accountId, nn::boss::TitleID titleId, const char* taskId );

    nn::Result AddLargeHttpHeader(const char* label, const char* value);
    void ClearLargeHttpHeader(void);

    const u8* m_pMetaBinary;
    size_t  m_MetaBinarySize;
    char* m_pWorkBufferForTag;
    size_t m_SizeOfWorkBufferForTag;
    u32 m_TagCount;
    size_t m_WrittenBufferSizeForTag;
};

//! @}

} // end of namespace boss
} // end of namespace nn

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_DATASTOREUPLOADSETTING_H_ */