Nintendo 3DS Miiverse Library  1.3.2
(OLV/Olive)
olv_TypesDownloadCommentData.h
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*
2 Project: OLV
3 File: olv_TypesDownloadCommentData.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_COMMENTDATA_H_
15 #define __OLV_TYPES_DOWNLOAD_COMMENTDATA_H_
16 
17 /*! @file
18 @brief Declaration of types related to downloading OLV comment 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 comment data.
40 */
42 {
43 public:
44  /*!
45 @brief Flags that can be specified in the <tt>@ref SetFlags</tt> function.
46 
47 - You can specify either <tt>@ref FLAG_FILTER_BY_BODY_TEXT</tt> or <tt>@ref FLAG_FILTER_BY_BODY_MEMO</tt> to filter the comments to download.
48 - Currently <tt>@ref FLAG_FILTER_BY_SELF</tt>, <tt>@ref FLAG_FILTER_BY_FRIEND</tt>, and <tt>@ref FLAG_FILTER_BY_FOLLOW</tt> are ignored if specified. (Support is planned for future versions.)
49 - Specify <tt>@ref FLAG_WITH_SPOILER</tt> to download comments that include spoilers.
50 - If you specify a comment ID using the <tt>@ref SetCommentId</tt> function, the only flag that can be specified is <tt>@ref FLAG_WITH_MII_DATA</tt>.
51  */
52  enum
53  {
54  FLAG_NONE = 0, //!< This is the state when no flags are specified.
55  FLAG_FILTER_BY_FRIEND = (1<<0), //!< Download comments from users who are friends.
56  FLAG_FILTER_BY_FOLLOW = (1<<1), //!< Download comments from users you are following.
57  FLAG_FILTER_BY_SELF = (1<<2), //!< Download your own comments.
58  FLAG_FILTER_BY_BODY_TEXT = (1<<3), //!< Download only text comments.
59  FLAG_FILTER_BY_BODY_MEMO = (1<<4), //!< Download only handwritten memo comments.
60  FLAG_DISTINCT_PID = (1<<5), //!< Get only a single comment from each user.
61  FLAG_WITH_MII_DATA = (1<<6), //!< Include Mii character data in the downloaded comment data.
62  FLAG_WITH_SPOILER = (1<<8) //!< Also download comments that include spoilers.
63  };
64 
65  /*!
66 @brief Instantiates the object.
67  */
69 
70  /*!
71 @brief Reverts parameters to their initial state.
72  */
73  void Reset();
74 
75  /*!
76 @brief Sets flags.
77 
78 Specifying this option is not required.
79 
80 @param[in] flags Flags (<tt>FLAG_*</tt>).
81  */
82  void SetFlags(u32 flags);
83 
84  /*!
85 @brief Sets the post ID for the comment data to download. <br />
86 
87 You must specify this option.
88 
89 @param[in] postId The post ID. <br />
90  */
91  void SetPostId(const char* postId);
92 
93  /*!
94 @brief Sets the comment ID. <br />
95 
96 Specifying this option is not required. <br />
97 If you specify a comment ID, only the comment with the set ID is downloaded. <br />
98 
99 @param[in] commentId The comment ID. <br />
100  */
101  void SetCommentId(const char* commentId);
102 
103  /*!
104 @brief Sets the date the comment was made.
105 
106 Specifying this option is not required. <br />
107 If you specify a date, only comments that were made on the specified date are downloaded. <br />
108 Set a date that adjusts for the difference from the time zone of the account.
109 
110 @param[in] postDate The date the comment was made.
111  */
112  void SetPostDate(const nn::fnd::DateTime postDate);
113 
114  /*!
115 @brief Sets the language ID.
116 
117 Specifying this option is not required. If no language ID is set, comments in the language set in System Settings are downloaded. <br />
118 See <tt>nn::cfg::CfgLanguageCode</tt> for the language IDs. <br />
119 Specify <tt>@ref nn::olv::LANGUAGE_ID_ALL</tt> to download comments in all languages. <br />
120 
121 @param[in] languageId The language ID.
122  */
123  void SetLanguageId(u8 languageId);
124 
125  /*!
126 @brief Sets the maximum length of text data.
127 
128 Specifying this option is not required. If not specified, the maximum length defaults to 100 characters. <br />
129 Text data that exceeds the maximum character length is truncated at the maximum number of characters and downloaded.
130 
131 @param[in] bodyTextMaxLength The maximum character length for text data. <br />
132 The range of values that can be specified is from <tt>1</tt> to <tt>@ref nn::olv::BODY_TEXT_MAX_LENGTH</tt>.
133  */
134  void SetBodyTextMaxLength(u32 bodyTextMaxLength);
135 
136  /*!
137 @brief Sets the maximum number of comments to download.
138 
139 You must specify this option.
140 
141 @param[in] commentDataMaxNum The maximum number of comments to download. <br />
142 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">commentDataList</span> argument to the <tt>@ref nn::olv::DownloadCommentDataList</tt> function. <br />
143 
144  */
145  void SetCommentDataMaxNum(u32 commentDataMaxNum);
146 
147  /*!
148 @brief Gets the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommentDataList</tt> function.
149 
150 Call this function after all of the various parameters have been specified, with the exception of the <tt>@ref SetWork</tt> function. <br />
151 This function returns fixed values.
152 
153 @return Returns the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommentDataList</tt> function.
154  */
155  u32 GetWorkSize() const;
156 
157  /*!
158 @brief Sets the size of the working buffer used by the <tt>@ref nn::olv::DownloadCommentDataList</tt> function.
159 
160 You must specify this option. <br />
161 Specify a buffer of at least the size obtained with the <tt>GetWorkSize</tt> function. <br />
162 
163 @param[in] work The working buffer.
164 @param[in] workSize The size of the working buffer.
165  */
166  void SetWork(u8* work, u32 workSize);
167 
168 private:
169  u32 m_Flags;
170  u8* m_Work;
171  u32 m_WorkSize;
172  u8 m_LanguageId;
173  s8 m_IsSetLanguageId;
174  s8 m_IsSetBodyTextMaxLength;
175  NN_PADDING1;
176  nn::fnd::DateTime m_PostDate;
177  u32 m_BodyTextMaxLength;
178  u32 m_CommentDataMaxNum;
179  char m_PostId[nn::olv::POST_ID_BUFF_LENGTH];
180  char m_CommentId[nn::olv::COMMENT_ID_BUFF_LENGTH];
181  u8 m_Reserved[1024-96];
182 
183  friend class nn::olv::internal::Main;
184 };
185 
186 /*!
187 @brief A class that stores the downloaded comment data.
188 */
189 class DownloadedCommentData : public DownloadedDataBase
190 {
191 public:
192  /*!
193 @brief Flags that can be specified in the <tt>TestFlags</tt> function.
194  */
195  enum
196  {
197  FLAG_NONE = 0, //!< This is the state when no flags are specified.
198  FLAG_WITH_BODY_TEXT = DOWNLOAD_FLAG_VALUE_WITH_BODY_TEXT, //!< A flag indicating that the comment is a text comment.
199  FLAG_WITH_BODY_MEMO = DOWNLOAD_FLAG_VALUE_WITH_BODY_MEMO, //!< A flag indicating that the comment is a handwritten memo comment.
200  FLAG_WITH_EXTERNAL_IMAGE_DATA = DOWNLOAD_FLAG_VALUE_WITH_EXTERNAL_IMAGE_DATA, //!< A flag indicating that the comment includes an attached image.
201  FLAG_WITH_MII_DATA = DOWNLOAD_FLAG_VALUE_WITH_MII_DATA, //!< A flag indicating that the comment includes attached Mii character data.
202  FLAG_WITH_APP_DATA = DOWNLOAD_FLAG_VALUE_WITH_APP_DATA, //!< A flag indicating that the comment includes application data.
203  FLAG_FREE_FORMAT = DOWNLOAD_FLAG_VALUE_FREE_FORMAT, //!< A flag indicating that the comment is a free text comment.
204  FLAG_SPOILER = DOWNLOAD_FLAG_VALUE_SPOILER //!< A flag indicating that the comment includes spoilers.
205  };
206 
207  /*!
208 @brief Instantiates the object.
209  */
211 
212  /*!
213 @brief Reverts parameters to their initial state.
214  */
215  void Reset();
216 
217  /*!
218 @brief Tests flags.
219 
220 @param[in] flags Flags (<tt>FLAG_*</tt>).
221 
222 @return Returns <tt>true</tt> if any of the flags are set; returns <tt>false</tt> otherwise.
223  */
224  bool TestFlags(u32 flags) const;
225 
226  /*!
227 @brief Gets the principal ID of the user.
228 
229 @return Returns the principal ID of the user.
230  */
231  u32 GetUserPid() const;
232 
233  /*!
234 @brief Gets the date the comment was made.
235 
236 The date returned reflects the difference in the time zone of the account.
237 
238 @return Returns the date the comment was made.
239  */
240  nn::fnd::DateTime GetPostDate() const;
241 
242  /*!
243 @brief Gets the mood.
244 
245 @return Returns the mood.
246  */
247  s8 GetFeeling() const;
248 
249  /*!
250 @brief Gets the region ID.
251 
252 @return Returns the region ID.
253  */
254  u32 GetRegionId() const;
255 
256  /*!
257 @brief Gets the platform ID.
258 
259 @return Returns the platform ID.
260  */
261  u8 GetPlatformId() const;
262 
263  /*!
264 @brief Gets the language ID.
265 
266 See <tt>nn::cfg::CfgLanguageCode</tt> for the language IDs.
267 
268 @return Returns the language ID.
269  */
270  u8 GetLanguageId() const;
271 
272  /*!
273 @brief Gets the country ID.
274 
275 See <tt>nn::cfg::CfgCountryCode</tt> for the country IDs.
276 
277 @return Returns the country ID.
278  */
279  u8 GetCountryId() const;
280 
281  /*!
282 @brief Gets the Mii data of the user.
283 
284 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 />
285 <br />
286 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 />
287 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_MII_DATA</tt> specified yields a return value of <tt>false</tt>.
288 - If <tt>NULL</tt> is specified for the <span class="argument">storeData</span> argument.
289 
290 @param[out] storeData The buffer that stores the Mii data. <br />
291  */
292  void GetMiiData(nn::mii::StoreData* storeData) const;
293 
294  /*!
295 @brief Gets the nickname of the Mii character of the user.
296 
297 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 />
298 - If <tt>NULL</tt> is specified for the <span class="argument">miiNickname</span> argument.
299 - 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.
300 
301 @param[out] miiNickname The buffer that stores the nickname of the Mii character. <br />
302 @param[in] miiNicknameMaxLength The length of the buffer that stores the nickname of the Mii character, including the terminating null character. <br />
303 Make sure that you specify a size of at least <tt>@ref nn::olv::MII_NICKNAME_BUFF_LENGTH</tt>.
304  */
305  void GetMiiNickname(wchar_t* miiNickname, u32 miiNicknameMaxLength) const;
306 
307  /*!
308 @brief Gets text data.
309 
310 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_BODY_TEXT</tt> is specified. <br />
311 <br />
312 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 />
313 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_BODY_TEXT</tt> specified yields a return value of <tt>false</tt>.
314 - If <tt>NULL</tt> is specified for the <span class="argument">bodyText</span> argument.
315 - If a value less than that of <tt>@ref nn::olv::BODY_TEXT_BUFF_LENGTH</tt> is specified for the <span class="argument">bodyTextMaxLength</span> argument.
316 
317 @param[out] bodyText The buffer that stores the text data.
318 @param[in] bodyTextMaxLength The length of the buffer that stores the text data, including the terminating null character. <br />
319 Make sure that you specify a size of at least <tt>@ref nn::olv::BODY_TEXT_BUFF_LENGTH</tt>.
320  */
321  void GetBodyText(wchar_t* bodyText, u32 bodyTextMaxLength) const;
322 
323  /*!
324 @brief Gets the handwritten memo data.
325 
326 This function can only be used when the <tt>@ref TestFlags</tt> function is set to <tt>@ref FLAG_WITH_BODY_MEMO</tt> and returns <tt>true</tt>.
327 <br />
328 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 />
329 - When the <tt>@ref TestFlags</tt> function is set to <tt>@ref FLAG_WITH_BODY_MEMO</tt> and returns <tt>false</tt>.
330 - When the <span class="argument">bodyMemo</span> parameter is set to <tt>NULL</tt>.
331 - When a value less than <tt>@ref nn::olv::BODY_MEMO_BUFF_LENGTH</tt> is specified for the <span class="argument">bodyMemoMaxSize</span> parameter.
332 
333 @param[out] bodyMemo The buffer that stores the handwritten memo data.
334 @param[out] bodyMemoSize The buffer that stores the size of the handwritten memo data.
335 @param[in] bodyMemoMaxSize The size of the buffer that stores the handwritten memo data. <br />
336 Make sure that you specify a size of at least <tt>@ref nn::olv::BODY_MEMO_BUFF_LENGTH</tt>.
337  */
338  void GetBodyMemo(u8* bodyMemo, u32* bodyMemoSize, u32 bodyMemoMaxSize) const;
339 
340  /*!
341 @brief Gets application data.
342 
343 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.
344 <br />
345 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 />
346 - 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>.
347 - If <tt>NULL</tt> is specified for the <span class="argument">appData</span> argument.
348 - If a value less than that returned by the <tt>@ref GetAppDataSize</tt> function is specified for the <span class="argument">appDataMaxSize</span> argument.
349 
350 @param[out] appData The buffer that stores the application data.
351 @param[out] appDataSize The buffer that stores the size of the application data.
352 @param[in] appDataMaxSize The size of the buffer that stores the application data. <br />
353 Make sure that you specify a value of at least that returned by the <tt>@ref GetAppDataSize</tt> function.
354  */
355  void GetAppData(u8* appData, u32* appDataSize, u32 appDataMaxSize) const;
356 
357  /*!
358 @brief Gets the size of the application data.
359 
360 @return Returns the size of the application data.
361  */
362  u32 GetAppDataSize() const;
363 
364  /*!
365 @brief Gets the size of the attached image data.
366 
367 @return Returns the size of the attached image data.
368  */
369  u32 GetExternalImageDataSize() const;
370 
371  /*!
372 @brief Downloads the attached image data.
373 
374 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_EXTERNAL_IMAGE_DATA</tt> is specified. <br />
375 This function causes Internet communication, during which time processing is blocked. <br />
376 While this function is being called, you can call the <tt>@ref nn::olv::Cancel</tt> function from another thread to cancel communication processes. <br />
377 This function is thread safe. However, be careful not to call functions in the OLV library that are not thread safe from other threads while this function is being called.
378 
379 @param[out] externalImageData The buffer that stores the attached image data.
380 @param[out] externalImageDataSize The buffer that stores the size of the attached image data.
381 @param[in] externalImageDataMaxSize The size of the buffer that stores the attached image data.
382 
383 @return Returns the result of the operation. <br />
384 For information about how to handle the results, see the OLV library reference.
385  */
386  nn::olv::Result DownloadExternalImageData(void* externalImageData, u32* externalImageDataSize, u32 externalImageDataMaxSize) const;
387 
388  /*!
389 @brief Gets the comment ID.
390 
391 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 />
392 - If <tt>NULL</tt> is specified for the <span class="argument">commentId</span> argument.
393 - If a value less than that of <tt>@ref nn::olv::COMMENT_ID_BUFF_LENGTH</tt> is specified for the <span class="argument">commentIdMaxLength</span> argument.
394 
395 @param[out] commentId The buffer that stores the comment ID.
396 @param[in] commentIdMaxLength The length of the buffer that stores the comment ID, including the terminating null character. <br />
397 Make sure that you specify a size of at least <tt>@ref nn::olv::COMMENT_ID_BUFF_LENGTH</tt>.
398  */
399  void GetCommentId(char* commentId, u32 commentIdMaxLength) const;
400 
401  friend class nn::olv::internal::Main;
402 };
403 
404 /** @} */
405 
406 } // namespace olv
407 } // namespace nn
408 #endif