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_BOSS_BOSS_DATASTOREUPLOADSETTING_H_ 14 #define NN_BOSS_BOSS_DATASTOREUPLOADSETTING_H_ 15 16 #include <nn/boss/boss_Const.h> 17 #include <nn/boss/boss_DataStoreConst.h> 18 #include <nn/boss/boss_Result.h> 19 #include <nn/boss/boss_Types.h> 20 #include <nn/boss/boss_RawUlTaskSetting.h> 21 22 #ifdef __cplusplus 23 24 namespace nn { 25 namespace boss { 26 27 /*! 28 @addtogroup nn_boss_api 29 @{ 30 */ 31 32 /*! 33 @brief Represents settings for <tt>DataStore</tt> upload tasks. These settings are used when registering a task. 34 */ 35 class DataStoreUploadSetting : public RawUlTaskSetting 36 { 37 public: 38 /*! 39 @brief Instantiates an object. 40 */ 41 explicit DataStoreUploadSetting(void); 42 43 /*! 44 @brief Destroys the object. 45 */ 46 virtual ~DataStoreUploadSetting(void); 47 48 /*! 49 @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. 50 51 @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. 52 @param[in] uploadDataSize Specifies the size of the data to upload. Set this parameter to <tt>0</tt> when uploading only metabinary data. 53 @param[in] gameId Specifies the ID for the game server. (For more information, see the documentation in the NEX library.) 54 @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.) 55 @param[in] dstKind Specifies the message data destination type. (For more information, see the documentation in the NEX library.) 56 @param[in] dataType Specifies a value representing the data type. 57 @param[in] period Specifies the number of days before the data is automatically deleted. (For more information, see the documentation in the NEX library.) 58 @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. 59 @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. 60 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 61 @retval Result::IsSuccess Indicates successful retrieval. 62 @retval ResultInvalidParameter Indicates an invalid parameter. 63 */ 64 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); 65 66 /*! 67 @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. 68 69 @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. 70 @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. 71 @param[in] uploadWorkBufferSize Specifies the size of <var>pUploadWorkBuffer</var>. 72 @param[in] gameId Specifies the ID for the game server. (For more information, see the documentation in the NEX library.) 73 @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.) 74 @param[in] dstKind Specifies the message data destination type. (For more information, see the documentation in the NEX library.) 75 @param[in] dataType Specifies a value representing the data type. 76 @param[in] period Specifies the number of days before the data is automatically deleted. (For more information, see the documentation in the NEX library.) 77 @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. 78 @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. 79 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 80 @retval Result::IsSuccess Indicates successful retrieval. 81 @retval ResultInvalidParameter Indicates an invalid parameter. 82 */ 83 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); 84 85 /*! 86 @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. 87 88 In a <tt>DataStore</tt>, the data destination is specified by principal ID. <br/> 89 (For more information, see the documentation in the NEX library. ) <br /> 90 The most that can be added is defined as <tt>@ref datastore::DESTINATION_PRINCIPAL_ID_MAX_COUNT</tt>. <br/> 91 92 @param[in] principalId Specifies the principal ID of the data destination. 93 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 94 @retval Result::IsSuccess Successfully set. 95 @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>. 96 @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>. 97 */ 98 nn::Result AddDestination( u32 principalId ); 99 100 /*! 101 @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. 102 103 For information about the ID to set, see the API reference for <tt>@ref AddDestination</tt>. <br /> 104 105 @param[in] principalIds Specifies an array of the principal IDs of the data destinations. 106 @param[in] principalIdCount Specifies the number of data destinations. 107 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 108 @retval Result::IsSuccess Successfully set. 109 @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>. 110 @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>. 111 */ 112 nn::Result SetDestinations( u32 principalIds[], u32 principalIdCount); 113 114 /*! 115 @brief Clears all data destinations. 116 */ 117 void ClearDestinations(void); 118 119 /*! 120 @brief Adds a tag. 121 122 In a <tt>DataStore</tt>, multiple tags can be set on send data. <br /> 123 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 /> 124 Specify multiple-byte characters as a UTF-8 byte string using the <tt>\\x</tt> hexadecimal notation. <br /> 125 (For more information about tags, see the documentation in the NEX library. ) <br /> 126 The maximum number of tags that can be set is defined as <tt>@ref datastore::TAG_MAX_COUNT</tt>. <br /> 127 128 @param[in] tag Specifies the tag value to add. 129 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 130 @retval Result::IsSuccess Successfully set. 131 @retval ResultFull The maximum number of tags is already set. The maximum count is defined as <tt>@ref datastore::TAG_MAX_COUNT</tt>. 132 */ 133 nn::Result AddTag( const char tag[datastore::TAG_MAX_CHAR_LENGTH_WITH_NULL]); 134 135 /*! 136 @brief Clears all tags. 137 */ 138 void ClearTags(void); 139 140 /*! 141 @brief Sets a meta-binary. 142 143 With a <tt>DataStore</tt>, meta-binary data can be sent along with send data. <br /> 144 (For more information, see the documentation in the NEX library. ) <br /> 145 There can only be one meta-binary with a maximum size of 1 KB. <br /> 146 The meta-binary data is copied to BOSS storage when registering the task. <br /> 147 For this reason, do not clear the buffer set in the <var>pMetaBinary</var> parameter until task registration is complete. <br /> 148 149 @param[in] pMetaBinary Specifies a pointer to the buffer that stores the meta-binary data to set. 150 @param[in] metaBinarySize Specifies the size of the data stored in <var>pMetaBinary</var>. 151 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 152 @retval Result::IsSuccess Successfully set. 153 @retval ResultAlreadyExist Meta-binary data is already set. If you want to reset the data, call <tt>@ref ClearMetaBinary</tt> before calling this function. 154 */ 155 nn::Result SetMetaBinary( const u8* pMetaBinary, size_t metaBinarySize ); 156 157 /*! 158 @brief Clears the set meta-binary. 159 160 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. 161 */ 162 void ClearMetaBinary(void); 163 164 /*! 165 @brief Sets the data ID. Used only for updating data that has already been uploaded. Specify the ID of the data to update. 166 167 @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. 168 */ 169 void SetDataId( u64 id ); 170 171 /*! 172 @brief Clears the set data ID. 173 */ 174 void ClearDataId(void); 175 176 /*! 177 @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). 178 179 @param[in] updatePermission Specifies the update permissions to set. The uploaded data matching the specified <tt>@ref datastore::DestinationKind</tt> can be updated. 180 */ 181 void SetUpdatePermission( datastore::DestinationKind updatePermission ); 182 183 /*! 184 @brief Clears the set update permissions. 185 */ 186 void ClearUpdatePermission(void); 187 188 /*! 189 @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>. 190 191 For more information about update permissions, see the documentation in the NEX library. <br /> 192 The most that can be added is defined as <tt>@ref datastore::MAX_COUNT_OF_PRINCIPAL_ID_WITH_UPDATE_PERMISSION</tt>. <br /> 193 194 @param[in] principalId Specifies the principal ID of the user to give update permission. 195 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 196 @retval Result::IsSuccess Successfully set. 197 @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>. 198 @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>. 199 */ 200 nn::Result AddIdWithUpdatePermission( u32 principalId ); 201 202 /*! 203 @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>. 204 205 For information about the ID to set, see the API reference for <tt>@ref AddIdWithUpdatePermission</tt>. <br /> 206 207 @param[in] principalIds Specifies an array of principal IDs of the users to give update permission. 208 @param[in] principalIdCount Specifies the number of users to given update permission. 209 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 210 @retval Result::IsSuccess Successfully set. 211 @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>. 212 @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>. 213 */ 214 nn::Result SetIdsWithUpdatePermission( u32 principalIds[], u32 principalIdCount); 215 216 /*! 217 @brief Clears all users that are set to be given update permission. 218 */ 219 void ClearIdsWithUpdatePermission(void); 220 221 /*! 222 @brief Specifies processing options. 223 224 @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. 225 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 226 @retval Result::IsSuccess Indicates successfully specified. 227 @retval ResultInvalidParameter Indicates an invalid parameter. 228 */ 229 nn::Result SetOption(u32 option); 230 231 232 private: 233 virtual nn::Result RegisterPreprocess( nn::boss::AccountID accountId, nn::boss::TitleID titleId, const char* taskId ); 234 235 nn::Result AddLargeHttpHeader(const char* label, const char* value); 236 void ClearLargeHttpHeader(void); 237 238 const u8* m_pMetaBinary; 239 size_t m_MetaBinarySize; 240 char* m_pWorkBufferForTag; 241 size_t m_SizeOfWorkBufferForTag; 242 u32 m_TagCount; 243 size_t m_WrittenBufferSizeForTag; 244 }; 245 246 //! @} 247 248 } // end of namespace boss 249 } // end of namespace nn 250 251 #endif // __cplusplus 252 253 #endif /* NN_BOSS_BOSS_DATASTOREUPLOADSETTING_H_ */ 254