Nintendo 3DS Miiverse Library  1.3.2
(OLV/Olive)
olv_TypesDownloadCommunityData.h
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*
2 Project: OLV
3 File: olv_TypesDownloadCommunityData.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_DOWNLOAD_COMMUNITY_H_
15 #define __OLV_TYPES_DOWNLOAD_COMMUNITY_H_
16 
17 /*! @file
18 @brief Declaration of types related to downloading OLV community data.
19 */
20 
22 
23 /// <span>nn</span>
24 namespace nn {
25 
26 /// <span>olv</span>
27 namespace olv {
28 
29 namespace internal
30 {
31 class Main;
32 }
33 
34 /*/* @defgroup class Classes
35  * @{
36  */
37 
38 /*!
39 @brief Represents the parameters when downloading community data.
40 */
42 {
43 public:
44  /*!
45 @brief Flags that can be specified in the <tt>SetFlags</tt> function.
46 
47 - If not using the <tt>@ref SetCommunityId</tt> function, make sure that you specify one of the following: <tt>@ref FLAG_FILTER_BY_FAVORITE</tt>, <tt>@ref FLAG_FILTER_BY_OFFICIAL</tt>, or <tt>@ref FLAG_FILTER_BY_SELF</tt>. <br />
48 - If the <tt>@ref SetCommunityId</tt> function is used to specify a community ID, you cannot specify <tt>FLAG_FILTER_BY_*</tt>.
49  */
50  enum Flags
51  {
52  FLAG_NONE = 0, //!< This is the state when no flags are specified.
53  FLAG_FILTER_BY_FAVORITE = (1<<0), //!< Downloads the community data for communities registered as favorites (communities that you have created are treated as favorites and are downloaded).
54  FLAG_FILTER_BY_OFFICIAL = (1<<1), //!< Downloads the community data for official communities.
55  FLAG_FILTER_BY_SELF = (1<<2), //!< Downloads the community data for communities that you have created.
56  FLAG_WITH_MII_DATA = (1<<3), //!< Includes the Mii character data for the user who created the community in the community data to download.
57  FLAG_WITH_ICON_DATA = (1<<4) //!< Includes icon data in the community data to download.
58  };
59 
60  /*!
61 @brief Instantiates the object.
62  */
64 
65  /*!
66 @brief Reverts parameters to their initial state.
67  */
68  void Reset();
69 
70  /*!
71 @brief Sets flags.
72 
73 You must specify this option when the <tt>@ref SetCommunityId</tt> function is not used.
74 
75 @param[in] flags Flags (<tt>FLAG_*</tt>).
76  */
77  void SetFlags(u32 flags);
78 
79  /*!
80 @brief Sets the maximum number of communities to download.
81 
82 You must specify this option.
83 
84 @param[in] communityDataMaxNum The maximum number of communities to download. <br />
85 Make sure that you specify a value of <tt>1</tt> or greater. <br />
86 If you have specified community IDs with the <tt>@ref SetCommunityId</tt> function, make sure that you specify the number of communities beyond the ones specified to download. <br />
87 Make sure that you specify a value equal to or greater than this maximum value for the number of arrays in the <span class="argument">communityDataList</span> argument to the <tt>@ref nn::olv::DownloadCommunityDataList</tt> function. <br />
88  */
89  void SetCommunityDataMaxNum(u32 communityDataMaxNum);
90 
91  /*!
92 @brief Sets the community ID.
93 
94 Specifying this option is not required. <br />
95 If you specify a community ID, only the community with the specified ID is downloaded. <br />
96 Up to a maximum of <tt>@ref nn::olv::COMMUNITY_ID_MAX_NUM</tt> community IDs can be specified.
97 
98 @param[in] communityId The community ID.
99 @param[in] index The index. <br />
100 The range of values that can be specified is from <tt>0</tt> to <tt>@ref nn::olv::COMMUNITY_ID_MAX_NUM - 1</tt>.
101  */
102  void SetCommunityId(u32 communityId, u8 index);
103 
104  /*!
105 @brief Gets the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommunityDataList</tt> function.
106 
107 Call this function after all of the various parameters have been specified, with the exception of the <tt>@ref SetWork</tt> function. <br />
108 This function returns fixed values.
109 
110 @return Returns the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommunityDataList</tt> function.
111  */
112  u32 GetWorkSize() const;
113 
114  /*!
115 @brief Sets the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommunityDataList</tt> function.
116 
117 You must specify this option. <br />
118 Specify a buffer of at least the size obtained with the <tt>@ref GetWorkSize</tt> function. <br />
119 
120 @param[in] work The working buffer.
121 @param[in] workSize The size of the working buffer.
122  */
123  void SetWork(u8* work, u32 workSize);
124 
125 private:
126  u32 m_Flags;
127  u8* m_Work;
128  u32 m_WorkSize;
129  u32 m_CommunityDataMaxNum;
130  u32 m_CommunityIds[COMMUNITY_ID_MAX_NUM];
131  s8 m_IsSetCommunityIds[COMMUNITY_ID_MAX_NUM];
132  NN_PADDING2;
133  u8 m_Reserved[256-168];
134 
135  friend class nn::olv::internal::Main;
136 };
137 
138 /*!
139 @brief A class that stores the downloaded community data.
140 */
142 {
143 public:
144  /*!
145 @brief Flags that can be specified in the <tt>TestFlags</tt> function.
146  */
147  enum Flags
148  {
149  FLAG_NONE = 0, //!< This is the state when no flags are specified.
150  FLAG_WITH_TITLE_TEXT = DOWNLOAD_FLAG_VALUE_WITH_TITLE_TEXT, //!< A flag indicating that the community name is included in the community data.
151  FLAG_WITH_DESCRIPTION_TEXT = DOWNLOAD_FLAG_VALUE_WITH_DESCRIPTION_TEXT, //!< A flag indicating that the community description is included in the community data.
152  FLAG_WITH_APP_DATA = DOWNLOAD_FLAG_VALUE_WITH_APP_DATA, //!< A flag indicating that application data is included in the community data.
153  FLAG_WITH_ICON_DATA = DOWNLOAD_FLAG_VALUE_WITH_ICON_DATA, //!< A flag indicating that icon data is included in the community data.
154  FLAG_WITH_MII_DATA = DOWNLOAD_FLAG_VALUE_WITH_MII_DATA //!< A flag indicating that the Mii character data for the user who created the community is included in the community data.
155  };
156 
157  /*!
158 @brief Instantiates the object.
159  */
161 
162  /*!
163 @brief Reverts parameters to their initial state.
164  */
165  void Reset();
166 
167  /*!
168 @brief Tests flags.
169 
170 @param[in] flags Flags (<tt>FLAG_*</tt>).
171 
172 @return Returns <tt>true</tt> if any of the flags are set; returns <tt>false</tt> otherwise.
173  */
174  bool TestFlags(u32 flags) const;
175 
176  /*!
177 @brief Gets the community ID.
178 
179 @return Returns the community ID.
180  */
181  u32 GetCommunityId() const;
182 
183  /*!
184 @brief Gets the community code.
185 
186 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 />
187 - If <tt>NULL</tt> is specified for the <span class="argument">communityCode</span> argument.
188 - 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.
189 
190 @param[out] communityCode The buffer for storing the community code.
191 @param[in] communityCodeMaxLength The length of the buffer that stores the community code, including the terminating null character. <br />
192 Make sure that you specify a size of at least <tt>@ref nn::olv::COMMUNITY_CODE_BUFF_LENGTH</tt>.
193  */
194  void GetCommunityCode(char* communityCode, u32 communityCodeMaxLength) const;
195 
196  /*!
197 @brief Gets the principal ID of the user who created the community.
198 
199 @return Returns the principal ID of the user who created the community.
200  */
201  u32 GetOwnerPid() const;
202 
203  /*!
204 @brief Gets the community name.
205 
206 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 />
207 <br />
208 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 />
209 - 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>.
210 - If <tt>NULL</tt> is specified for the <span class="argument">titleText</span> argument.
211 - 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.
212 
213 @param[out] titleText The buffer for storing the community name.
214 @param[in] titleTextMaxLength The length of the buffer that stores the community name, including the terminating null character. <br />
215 Make sure that you specify a size of at least <tt>@ref nn::olv::TITLE_TEXT_BUFF_LENGTH</tt>.
216  */
217  void GetTitleText(wchar_t* titleText, u32 titleTextMaxLength) const;
218 
219  /*!
220 @brief Gets the community description.
221 
222 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 />
223 <br />
224 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 />
225 - 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>.
226 - If <tt>NULL</tt> is specified for the <span class="argument>descriptionText</span> argument.
227 - 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.
228 
229 @param[out] descriptionText The buffer for storing the community description.
230 @param[in] descriptionTextMaxLength The length of the buffer that stores the community description, including the terminating null character. <br />
231 Make sure that you specify a size of at least <tt>@ref nn::olv::DESCRIPTION_TEXT_BUFF_LENGTH</tt>.
232  */
233  void GetDescriptionText(wchar_t* descriptionText, u32 descriptionTextMaxLength) const;
234 
235  /*!
236 @brief Gets application data.
237 
238 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 />
239 <br />
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 calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_APP_DATA</tt> specified yields a return value of <tt>false</tt>.
242 - If <tt>NULL</tt> is specified for the <span class="argument">appData</span> argument.
243 - If a value less than that returned by the <tt>@ref GetAppData</tt> function is specified for the <span class="argument">appDataMaxSize</span> argument.
244 
245 @param[out] appData The buffer that stores the application data.
246 @param[out] appDataSize The buffer that stores the size of the application data.
247 @param[in] appDataMaxSize The size of the buffer that stores the application data. <br />
248 Make sure that you specify a value of at least that returned by the <tt>@ref GetAppData</tt> function.
249  */
250  void GetAppData(u8* appData, u32* appDataSize, u32 appDataMaxSize) const;
251 
252  /*!
253 @brief Gets the size of the application data.
254 
255 @return Returns the size of the application data.
256  */
257  u32 GetAppDataSize(void) const;
258 
259  /*!
260 @brief Gets icon data.
261 
262 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.
263 
264 @param[out] iconData The buffer that stores the icon data.
265 @param[out] iconDataSize The buffer that stores the size of the icon data.
266 @param[in] iconDataMaxSize The size of the buffer that stores the icon data. <br />
267 Make sure that you specify a size of at least <tt>@ref nn::olv::ICON_DATA_BUFF_LENGTH</tt>.
268 
269 @return Returns the result of the operation. <br />
270 For information about how to handle the results, see the OLV library reference.
271  */
272  nn::olv::Result GetIconData(u8* iconData, u32* iconDataSize, u32 iconDataMaxSize) const;
273 
274  /*!
275 @brief Gets the Mii character data of the user who created the community.
276 
277 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_MII_DATA</tt> is specified. <br />
278 <br />
279 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 />
280 - 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>.
281 - If <tt>NULL</tt> is specified for the <span class="argument">storeData</span> argument.
282 
283 @param[out] storeData The buffer that stores the Mii data of the user who created the community. <br />
284  */
285  void GetOwnerMiiData(nn::mii::StoreData* storeData) const;
286 
287  /*!
288 @brief Gets the nickname of the Mii character of the user who created the community.
289 
290 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 />
291 - If <tt>NULL</tt> is specified for the <span class="argument">miiNickname</span> argument.
292 - If a value less than that of <tt>@ref nn::olv::MII_NICKNAME_BUFF_LENGTH</tt> is specified for the <span class="argument">miiNicknameMaxLength</span> argument.
293 
294 @param[out] miiNickname The buffer that stores the nickname of the Mii character. <br />
295 @param[in] miiNicknameMaxLength The length of the buffer that stores the nickname of the Mii character, including the terminating null character. <br />
296 Make sure that you specify a size of at least <tt>@ref nn::olv::MII_NICKNAME_BUFF_LENGTH</tt>.
297  */
298  void GetOwnerMiiNickname(wchar_t* miiNickname, u32 miiNicknameMaxLength) const;
299 
300 private:
301  u32 m_Flags;
302  u32 m_CommunityId;
303  u32 m_OwnerPid;
304  wchar_t m_TitleText[TITLE_TEXT_BUFF_LENGTH];
305  u32 m_TitleTextLength;
306  wchar_t m_DescriptionText[DESCRIPTION_TEXT_BUFF_LENGTH];
307  u32 m_DescriptionTextLength;
308  u8 m_AppData[APP_DATA_BUFF_LENGTH];
309  u32 m_AppDataSize;
310  u8 m_IconData[COMPRESSED_ICON_DATA_BUFF_LENGTH];
311  s32 m_IconDataSize;
312  u8 m_MiiData[MII_DATA_BUFF_LENGTH];
313  wchar_t m_MiiNickname[MII_NICKNAME_BUFF_LENGTH];
314  u8 m_Reserved[12288-11240];
315 
316  friend class nn::olv::internal::Main;
317 };
318 
319 /** @} */
320 
321 } // namespace olv
322 } // namespace nn
323 #endif