Nintendo 3DS Miiverse Library  1.3.2
(OLV/Olive)
olv_TypesUploadCommunityData.h
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*
2 Project: OLV
3 File: olv_TypesUploadCommunityData.h
4 
5 Copyright (C) 2009-2013 Nintendo. All rights reserved.
6 
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12 
13  *---------------------------------------------------------------------------*/
14 #ifndef __OLV_TYPES_UPLOAD_COMMUNITYDATA_H_
15 #define __OLV_TYPES_UPLOAD_COMMUNITYDATA_H_
16 
17 /*! @file
18 @brief Declaration of types related to uploading OLV community data.
19 */
20 
21 #include <nn/config.h>
22 #include <nn/types.h>
23 #include <nn/mii/mii_StoreData.h>
24 #include <nn/olv/olv_Const.h>
25 #include <nn/olv/olv_Result.h>
26 
27 /// <span>nn</span>
28 namespace nn {
29 
30 /// <span>olv</span>
31 namespace olv {
32 
33 namespace internal
34 {
35 class Main;
36 }
37 
38 /*/* @defgroup class Classes
39  * @{
40  */
41 
42 /*!
43 @brief The class representing the parameters used when creating, updating, and deleting community data.
44 */
46 {
47 public:
48  /*!
49 @brief Flags that can be specified in the <tt>@ref SetFlags</tt> function.
50  */
51  enum
52  {
53  FLAG_NONE = 0, //!< This is the state when no flags are specified.
54  FLAG_DELETE = UPLOAD_FLAG_VALUE_DELETE //!< Specify this flag when deleting community data.
55  };
56 
57  /*!
58 @brief Instantiates the object.
59  */
61 
62 
63  /*!
64 @brief Reverts parameters to their initial state.
65  */
66  void Reset();
67 
68  /*!
69 @brief Sets flags.
70 
71 @param[in] flags Flags (<tt>FLAG_*</tt>).
72  */
73  void SetFlags(u32 flags);
74 
75  /*!
76 @brief Sets the community ID.
77 
78 You must specify this option when updating or deleting community data. If not specified, new community data is created by default.
79 
80 @param[in] communityId The community ID.
81  */
82  void SetCommunityId(u32 communityId);
83 
84  /*!
85 @brief Sets the community name.
86 
87 You must specify this option when creating new community data.
88 
89 @param[in] titleText The community name. <br />
90 Use UTF-16LE for the encoding. <br />
91 The maximum number of characters that can be specified is <tt>@ref nn::olv::TITLE_TEXT_BUFF_LENGTH - 1</tt>.
92  */
93  void SetTitleText(const wchar_t* titleText);
94 
95  /*!
96 @brief Sets the community description.
97 
98 Specifying this option is not required.
99 
100 @param[in] descriptionText The community description. <br />
101 Use UTF-16LE for the encoding. <br />
102 The maximum number of characters that can be specified is <tt>@ref nn::olv::DESCRIPTION_TEXT_BUFF_LENGTH - 1</tt>.
103  */
104  void SetDescriptionText(const wchar_t* descriptionText);
105 
106  /*!
107 @brief Specifies the maximum number of characters that can be posted from the Miiverse application.
108 
109 Specifying this option is not required. <br />
110 If nothing is specified, 100 characters is set as the default.
111 
112 @param[in] length The maximum number of characters that can be posted from the Miiverse application. <br />
113 The maximum number of characters that can be specified is <tt>@ref nn::olv::BODY_TEXT_MAX_LENGTH</tt>.
114  */
115  void SetPostTextMaxLength(u32 length);
116 
117  /*!
118 @brief Specifies the maximum number of characters for comments that can be posted from the Miiverse application.
119 
120 Specifying this option is not required. <br />
121 If nothing is specified, 100 characters is set as the default.
122 
123 @param[in] length The maximum number of characters for comments posted from the Miiverse application. <br />
124 The maximum number of characters that can be specified is <tt>@ref nn::olv::BODY_TEXT_MAX_LENGTH</tt>.
125  */
126  void SetCommentTextMaxLength(u32 length);
127 
128  /*!
129 @brief Sets the icon data.
130 
131 Specifying this option is not required.
132 
133 @param[in] iconData The icon data. <br />
134 Note that only the address value is stored, so this data must be valid until the call to the <tt>@ref nn::olv::UploadCommunityData</tt> function ends. <br />
135 @param[in] iconDataSize The size of the icon data. <br />
136 The maximum value that can be specified is <tt>@ref nn::olv::ICON_DATA_BUFF_LENGTH</tt>.
137  */
138  void SetIconData(const u8* iconData, u32 iconDataSize);
139 
140  /*!
141 @brief Sets the application data.
142 
143 Specifying this option is not required.
144 
145 @param[in] appData The application data. <br />
146 Note that only the address value is stored, so this data must be valid until the call to the <tt>@ref nn::olv::UploadCommunityData</tt> function ends.
147 @param[in] appDataSize The size of the application data. <br />
148 The maximum value that can be specified is <tt>@ref nn::olv::APP_DATA_BUFF_LENGTH</tt>.
149  */
150  void SetAppData(const u8* appData, u32 appDataSize);
151 
152  /*!
153 @brief Gets the size of the working buffer used by the <tt>@ref nn::olv::UploadCommunityData</tt> function.
154 
155 Call this function after all of the various parameters have been specified, with the exception of the <tt>@ref SetWork</tt> function. <br />
156 This function returns fixed values.
157 
158 @return Returns the size of the working buffer used by the <tt>@ref nn::olv::UploadCommunityData</tt> function.
159  */
160  u32 GetWorkSize() const;
161 
162  /*!
163 @brief Sets the size of the working buffer used by the <tt>@ref nn::olv::UploadCommunityData</tt> function.
164 
165 You must specify this option. <br />
166 Specify a buffer of at least the size obtained with the <tt>@ref GetWorkSize</tt> function. <br />
167 
168 @param[in] work The working buffer.
169 @param[in] workSize The size of the working buffer.
170  */
171  void SetWork(u8* work, u32 workSize);
172 
173 private:
174  u32 m_Flags;
175  u8* m_Work;
176  u32 m_WorkSize;
177  u32 m_CommunityId;
178  bool m_IsSetCommunityId;
179  NN_PADDING3;
180  wchar_t m_TitleText[TITLE_TEXT_BUFF_LENGTH];
181  wchar_t m_DescriptionText[DESCRIPTION_TEXT_BUFF_LENGTH];
182  const u8* m_AppData;
183  u32 m_AppDataSize;
184  const u8* m_IconData;
185  u32 m_IconDataSize;
186  u32 m_PostTextMaxLength;
187  u32 m_CommentTextMaxLength;
188  u8 m_Reserved[1024-812];
189 
190  friend class nn::olv::internal::Main;
191 };
192 
193 /*!
194 @brief The class for storing the results when community data is created or uploaded.
195 */
197 {
198 public:
199  /*!
200 @brief Flags that can be specified in the <tt>TestFlags</tt> function.
201  */
202  enum Flags
203  {
204  FLAG_NONE = 0, //!< This is the state when no flags are specified.
205  FLAG_WITH_TITLE_TEXT = DOWNLOAD_FLAG_VALUE_WITH_TITLE_TEXT, //!< A flag indicating that the community name is included in the community data.
206  FLAG_WITH_DESCRIPTION_TEXT = DOWNLOAD_FLAG_VALUE_WITH_DESCRIPTION_TEXT, //!< A flag indicating that the community description is included in the community data.
207  FLAG_WITH_APP_DATA = DOWNLOAD_FLAG_VALUE_WITH_APP_DATA, //!< A flag indicating that application data is included in the community data.
208  FLAG_WITH_ICON_DATA = DOWNLOAD_FLAG_VALUE_WITH_ICON_DATA //!< A flag indicating that icon data is included in the community data.
209  };
210 
211  /*!
212 @brief Instantiates the object.
213  */
215 
216  /*!
217 @brief Reverts parameters to their initial state.
218  */
219  void Reset();
220 
221  /*!
222 @brief Tests flags.
223 
224 @param[in] flags Flags (<tt>FLAG_*</tt>).
225 
226 @return Returns <tt>true</tt> if any of the flags are set; returns <tt>false</tt> otherwise.
227  */
228  bool TestFlags(u32 flags) const;
229 
230  /*!
231 @brief Gets the community ID.
232 
233 @return Returns the community ID.
234  */
235  u32 GetCommunityId() const;
236 
237  /*!
238 @brief Gets the community code.
239 
240 Note that if you call this function in one of the following invalid states, it will stop on an assertion in the debug/development versions, and return without doing anything in the release version. <br />
241 - If <tt>NULL</tt> is specified for the <span class="argument">communityCode</span> argument.
242 - If a value less than that of <tt>@ref nn::olv::COMMUNITY_CODE_BUFF_LENGTH</tt> is specified for the <span class="argument">communityCodeMaxLength</span> argument.
243 
244 @param[out] communityCode The buffer for storing the community code.
245 @param[in] communityCodeMaxLength The length of the buffer that stores the community code, including the terminating null character. <br />
246 Make sure that you specify a size of at least <tt>@ref nn::olv::COMMUNITY_CODE_BUFF_LENGTH</tt>.
247  */
248  void GetCommunityCode(char* communityCode, u32 communityCodeMaxLength) const;
249 
250  /*!
251 @brief Gets the principal ID of the user who created the community.
252 
253 @return Returns the principal ID of the user who created the community.
254  */
255  u32 GetOwnerPid() const;
256 
257  /*!
258 @brief Gets the community name.
259 
260 This function can only be used when the return value from the <tt>@ref TestFlags</tt> function is <tt>true</tt> when <tt>@ref FLAG_WITH_TITLE_TEXT</tt> is specified. <br />
261 <br />
262 Note that if you call this function in one of the following invalid states, it will stop on an assertion in the debug/development versions, and return without doing anything in the release version. <br />
263 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_TITLE_TEXT</tt> specified yields a return value of <tt>false</tt>.
264 - If <tt>NULL</tt> is specified for the <span class="argument">titleText</span> argument.
265 - If a value less than that of <tt>@ref nn::olv::TITLE_TEXT_BUFF_LENGTH</tt> is specified for the <span class="argument">titleTextMaxLength</span> argument.
266 
267 @param[out] titleText The buffer for storing the community name.
268 @param[in] titleTextMaxLength The length of the buffer that stores the community name, including the terminating null character. <br />
269 Make sure that you specify a size of at least <tt>@ref nn::olv::TITLE_TEXT_BUFF_LENGTH</tt>.
270  */
271  void GetTitleText(wchar_t* titleText, u32 titleTextMaxLength) const;
272 
273  /*!
274 @brief Gets the community description.
275 
276 This function can only be used when the return value from the <tt>@ref TestFlags</tt> function is <tt>true</tt> when <tt>@ref FLAG_WITH_DESCRIPTION_TEXT</tt> is specified. <br />
277 <br />
278 Note that if you call this function in one of the following invalid states, it will stop on an assertion in the debug/development versions, and return without doing anything in the release version. <br />
279 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_DESCRIPTION_TEXT</tt> specified yields a return value of <tt>false</tt>.
280 - If <tt>NULL</tt> is specified for the <span class="argument>descriptionText</span> argument.
281 - If a value less than that of <tt>@ref nn::olv::DESCRIPTION_TEXT_BUFF_LENGTH</tt> is specified for the <span class="argument">descriptionTextMaxLength</span> argument.
282 
283 @param[out] descriptionText The buffer for storing the community description.
284 @param[in] descriptionTextMaxLength The length of the buffer that stores the community description, including the terminating null character. <br />
285 Make sure that you specify a size of at least <tt>@ref nn::olv::DESCRIPTION_TEXT_BUFF_LENGTH</tt>.
286  */
287  void GetDescriptionText(wchar_t* descriptionText, u32 descriptionTextMaxLength) const;
288 
289  /*!
290 @brief Gets application data.
291 
292 This function can only be used when the return value from the <tt>@ref TestFlags</tt> function is <tt>true</tt> when <tt>@ref FLAG_WITH_APP_DATA</tt> is specified. <br />
293 <br />
294 Note that if you call this function in one of the following invalid states, it will stop on an assertion in the debug/development versions, and return without doing anything in the release version. <br />
295 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_APP_DATA</tt> specified yields a return value of <tt>false</tt>.
296 - If <tt>NULL</tt> is specified for the <span class="argument">appData</span> argument.
297 - If a value less than that returned by the <tt>@ref GetAppData</tt> function is specified for the <span class="argument">appDataMaxSize</span> argument.
298 
299 @param[out] appData The buffer that stores the application data.
300 @param[out] appDataSize The buffer that stores the size of the application data.
301 @param[in] appDataMaxSize The size of the buffer that stores the application data. <br />
302 Make sure that you specify a value of at least that returned by the <tt>@ref GetAppData</tt> function.
303  */
304  void GetAppData(u8* appData, u32* appDataSize, u32 appDataMaxSize) const;
305 
306  /*!
307 @brief Gets the size of the application data.
308 
309 @return Returns the size of the application data.
310  */
311  u32 GetAppDataSize(void) const;
312 
313  /*!
314 @brief Gets icon data.
315 
316 This function can only be used when the return value from the <tt>@ref TestFlags</tt> function is <tt>true</tt> when <tt>@ref FLAG_WITH_ICON_DATA</tt> is specified.
317 
318 @param[out] iconData The buffer that stores the icon data.
319 @param[out] iconDataSize The buffer that stores the size of the icon data.
320 @param[in] iconDataMaxSize The size of the buffer that stores the icon data. <br />
321 Make sure that you specify a size of at least <tt>@ref nn::olv::ICON_DATA_BUFF_LENGTH</tt>.
322 
323 @return Returns the result of the operation. <br />
324 For information about how to handle the results, see the OLV library reference.
325  */
326  nn::olv::Result GetIconData(u8* iconData, u32* iconDataSize, u32 iconDataMaxSize) const;
327 
328 private:
329  u32 m_Flags;
330  u32 m_CommunityId;
331  u32 m_OwnerPid;
332  wchar_t m_TitleText[TITLE_TEXT_BUFF_LENGTH];
333  u32 m_TitleTextLength;
334  wchar_t m_DescriptionText[DESCRIPTION_TEXT_BUFF_LENGTH];
335  u32 m_DescriptionTextLength;
336  u8 m_AppData[APP_DATA_BUFF_LENGTH];
337  u32 m_AppDataSize;
338  u8 m_IconData[COMPRESSED_ICON_DATA_BUFF_LENGTH];
339  s32 m_IconDataSize;
340  u8 m_MiiData[MII_DATA_BUFF_LENGTH];
341  wchar_t m_MiiNickname[MII_NICKNAME_BUFF_LENGTH];
342  u8 m_Reserved[12288-11240];
343 
344  friend class nn::olv::internal::Main;
345 };
346 
347 /** @} */
348 
349 } // namespace olv
350 } // namespace nn
351 #endif