Nintendo 3DS Miiverse Library  1.3.2
(OLV/Olive)
olv_TypesDownloadPostData.h
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*
2 Project: OLV
3 File: olv_TypesDownloadPostData.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_POSTDATA_H_
15 #define __OLV_TYPES_DOWNLOAD_POSTDATA_H_
16 
17 /*! @file
18 @brief Declaration of types related to downloading OLV post 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 post 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 <tt>@ref FLAG_FILTER_BY_FRIEND</tt> / <tt>@ref FLAG_FILTER_BY_FOLLOW</tt> / <tt>@ref FLAG_FILTER_BY_SELF</tt> in combinations to filter the posts to download. <br />
48 These flags cannot be used while using the <tt>SetSearchPid</tt> function and specifying a principal ID. <br />
49 - You can specify either of <tt>@ref FLAG_FILTER_BY_BODY_TEXT</tt> or <tt>@ref FLAG_FILTER_BY_BODY_MEMO</tt> to filter the posts to download. <br />
50 - Specify <tt>@ref FLAG_WITH_SPOILER</tt> to download posts that include spoilers.
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 posts from users who are friends.
56  FLAG_FILTER_BY_FOLLOW = (1<<1), //!< Download posts from users you are following.
57  FLAG_FILTER_BY_SELF = (1<<2), //!< Download your own posts.
58  FLAG_FILTER_BY_BODY_TEXT = (1<<3), //!< Download only text posts.
59  FLAG_FILTER_BY_BODY_MEMO = (1<<4), //!< Download only handwritten memo posts.
60  FLAG_DISTINCT_PID = (1<<5), //!< Get only a single post from each user.
61  FLAG_WITH_MII_DATA = (1<<6), //!< Include Mii character data in the post data to download.
62  FLAG_WITH_EMPATHY_ADDED = (1<<7), //!< Include flags for whether you have already given Yeahs to posts in the post data to download.
63  FLAG_WITH_SPOILER = (1<<8) //!< Also download posts that include spoilers.
64  };
65 
66  /*!
67 @brief Instantiates the object.
68  */
70 
71  /*!
72 @brief Reverts parameters to their initial state.
73  */
74  void Reset();
75 
76  /*!
77 @brief Sets flags.
78 
79 Specifying this option is not required.
80 
81 @param[in] flags Flags (<tt>FLAG_*</tt>).
82  */
83  void SetFlags(u32 flags);
84 
85  /*!
86 @brief Sets the language ID.
87 
88 Specifying this option is not required. If no language ID is specified, posts in the language set in the System Settings are downloaded. <br />
89 See <tt>nn::cfg::CfgLanguageCode</tt> for the language IDs. <br />
90 Specify <tt>@ref nn::olv::LANGUAGE_ID_ALL</tt> to download posts in all languages. <br />
91 
92 @param[in] languageId The language ID.
93  */
94  void SetLanguageId(u8 languageId);
95 
96  /*!
97 @brief Sets the community ID.
98 
99 Specifying this option is not required. If no community ID is specified, posts from the general community are downloaded.
100 
101 @param[in] communityId The community ID.
102  */
103  void SetCommunityId(u32 communityId);
104 
105  /*!
106 @brief Sets the search key.
107 
108 Specifying this option is not required. <br />
109 If you specify a search key, only posts with the specified search key are downloaded.
110 
111 @param[in] searchKey The search key. <br />
112 Use UTF-16LE for the encoding. <br />
113 The maximum number of characters that can be specified is <tt>@ref nn::olv::SEARCH_KEY_MAX_LENGTH</tt>.
114  */
115  void SetSearchKey(const wchar_t* searchKey);
116 
117  /*!
118 @brief Sets the principal ID of the user.
119 
120 Specifying this option is not required. <br />
121 If you specify a principal ID, only the posts from the user with the specified principal ID are downloaded.
122 
123 @param[in] searchPid The principal ID of the user.
124  */
125  void SetSearchPid(u32 searchPid);
126 
127  /*!
128 @brief Sets the post ID.
129 
130 Specifying this option is not required. <br />
131 If you specify a post ID, only the post with the specified ID is downloaded. <br />
132 Up to a maximum of <tt>@ref nn::olv::POST_ID_MAX_NUM</tt> post IDs can be specified.
133 
134 @param[in] postId The post ID. <br />
135 The maximum number of characters that can be specified is <tt>@ref nn::olv::POST_ID_BUFF_LENGTH - 1</tt>.
136 @param[in] index The index. <br />
137 The range of values that can be specified is from <tt>0</tt> to <tt>@ref nn::olv::POST_ID_MAX_NUM - 1</tt>.
138  */
139  void SetPostId(const char* postId, u32 index);
140 
141  /*!
142 @brief Sets the date the post was made.
143 
144 Specifying this option is not required. <br />
145 If you specify a date, only posts that were made prior to the specified date are downloaded. <br />
146 Specify a date that adjusts for the difference from the time zone of the account.
147 
148 @param[in] postDate The date the post was made.
149  */
150  void SetPostDate(const nn::fnd::DateTime postDate);
151 
152  /*!
153 @brief Sets the maximum length of text data.
154 
155 Specifying this option is not required. If not specified, the maximum length defaults to 100 characters. <br />
156 Text data that exceeds the maximum character length is truncated at the maximum number of characters and downloaded.
157 
158 @param[in] bodyTextMaxLength The maximum character length for text data. <br />
159 The range of values that can be specified is from <tt>1</tt> to <tt>@ref nn::olv::BODY_TEXT_MAX_LENGTH</tt>.
160  */
161  void SetBodyTextMaxLength(u32 bodyTextMaxLength);
162 
163  /*!
164 @brief Sets the maximum number of posts to download.
165 
166 You must specify this option.
167 
168 @param[in] postDataMaxNum The maximum number of posts to download. <br />
169 If you specify post IDs with the <tt>@ref SetPostId</tt> function, make sure that you specify the number of posts greater than the number of the post IDs specified to download. <br />
170 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">postDataList</span> argument to the <tt>nn::olv::DownloadPostDataList</tt> function. <br />
171 
172  */
173  void SetPostDataMaxNum(u32 postDataMaxNum);
174 
175  /*!
176 @brief Gets the size of the working buffer used by the <tt>@ref nn::olv::DownloadPostDataList</tt> function.
177 
178 Call this function after all of the various parameters have been specified, with the exception of the <tt>@ref SetWork</tt> function. <br />
179 This function returns fixed values.
180 
181 @return Returns the size of the working buffer used by the <tt>@ref nn::olv::DownloadPostDataList</tt> function.
182  */
183  u32 GetWorkSize() const;
184 
185  /*!
186 @brief Sets the size of the working buffer used by the <tt>@ref nn::olv::DownloadPostDataList</tt> function.
187 
188 You must specify this option. <br />
189 Specify a buffer of at least the size obtained with the <tt>@ref GetWorkSize</tt> function. <br />
190 
191 @param[in] work The working buffer.
192 @param[in] workSize The size of the working buffer.
193  */
194  void SetWork(u8* work, u32 workSize);
195 
196 private:
197  u32 m_Flags;
198  u8* m_Work;
199  u32 m_WorkSize;
200  u32 m_BodyTextMaxLength;
201  u32 m_CommunityId;
202  u32 m_SearchPid;
203  u8 m_LanguageId;
204  s8 m_IsSetLanguageId;
205  s8 m_IsSetCommunityId;
206  s8 m_IsSetBodyTextMaxLength;
207  u32 m_PostDataMaxNum;
208  wchar_t m_SearchKey[SEARCH_KEY_BUFF_LENGTH];
209  char m_PostIds[POST_ID_MAX_NUM][POST_ID_BUFF_LENGTH];
210  nn::fnd::DateTime m_PostDate;
211  u8 m_Reserved[1024-984];
212 
213  friend class nn::olv::internal::Main;
214 };
215 
216 /*!
217 @brief A class that stores the downloaded topic data.
218 */
220 {
221 public:
222  /*!
223 @brief Instantiates the object.
224  */
226 
227  /*!
228 @brief Reverts parameters to their initial state.
229  */
230  void Reset();
231 
232  /*!
233 @brief Gets the community ID.
234 
235 @return Returns the community ID.
236  */
237  u32 GetCommunityId() const;
238 
239 private:
240  u32 m_CommunityId;
241  u8 m_Reserved[64-4];
242 
243  friend class nn::olv::internal::Main;
244 };
245 
246 /*!
247 @brief A class that stores the downloaded post data.
248 */
249 class DownloadedPostData : public DownloadedDataBase
250 {
251 public:
252  /*!
253 @brief Flags that can be specified in the <tt>@ref TestFlags</tt> function.
254  */
255  enum
256  {
257  FLAG_NONE = 0, //!< This is the state when no flags are specified.
258  FLAG_WITH_BODY_TEXT = DOWNLOAD_FLAG_VALUE_WITH_BODY_TEXT, //!< A flag indicating that the post is a text post.
259  FLAG_WITH_BODY_MEMO = DOWNLOAD_FLAG_VALUE_WITH_BODY_MEMO, //!< A flag indicating that the post is a handwritten memo post.
260  FLAG_WITH_EXTERNAL_IMAGE_DATA = DOWNLOAD_FLAG_VALUE_WITH_EXTERNAL_IMAGE_DATA, //!< A flag indicating that the post includes an attached image.
261  FLAG_WITH_MII_DATA = DOWNLOAD_FLAG_VALUE_WITH_MII_DATA, //!< A flag indicating that the post includes Mii character data.
262  FLAG_WITH_EXTERNAL_URL = DOWNLOAD_FLAG_VALUE_WITH_EXTERNAL_URL, //!< A flag indicating that the post includes an attached URL.
263  FLAG_WITH_APP_DATA = DOWNLOAD_FLAG_VALUE_WITH_APP_DATA, //!< A flag indicating that the post includes application data.
264  FLAG_EMPATHY_ADDED = DOWNLOAD_FLAG_VALUE_EMPATHY_ADDED, //!< A flag indicating that you have already given a Yeah to the post.
265  FLAG_FREE_FORMAT = DOWNLOAD_FLAG_VALUE_FREE_FORMAT, //!< A flag indicating that the post is a free text post.
266  FLAG_SPOILER = DOWNLOAD_FLAG_VALUE_SPOILER //!< A flag indicating that the post includes spoilers.
267  };
268 
269  /*!
270 @brief Instantiates the object.
271  */
273 
274  /*!
275 @brief Reverts parameters to their initial state.
276  */
277  void Reset();
278 
279  /*!
280 @brief Tests flags.
281 
282 @param[in] flags Flags (<tt>FLAG_*</tt>).
283 
284 @return Returns <tt>true</tt> if any of the flags are set; returns <tt>false</tt> otherwise.
285  */
286  bool TestFlags(u32 flags) const;
287 
288  /*!
289 @brief Gets the principal ID of the user.
290 
291 @return Returns the principal ID of the user.
292  */
293  u32 GetUserPid() const;
294 
295  /*!
296 @brief Gets the date the post was made.
297 
298 The date returned reflects the difference in the time zone of the account.
299 
300 @return Returns the date the post was made.
301  */
302  nn::fnd::DateTime GetPostDate() const;
303 
304  /*!
305 @brief Gets the mood.
306 
307 @return Returns the mood.
308  */
309  s8 GetFeeling() const;
310 
311  /*!
312 @brief Gets the region ID.
313 
314 @return Returns the region ID.
315  */
316  u32 GetRegionId() const;
317 
318  /*!
319 @brief Gets the platform ID.
320 
321 @return Returns the platform ID.
322  */
323  u8 GetPlatformId() const;
324 
325  /*!
326 @brief Gets the language ID.
327 
328 See <tt>nn::cfg::CfgLanguageCode</tt> for the language IDs.
329 
330 @return Returns the language ID.
331  */
332  u8 GetLanguageId() const;
333 
334  /*!
335 @brief Gets the country ID.
336 
337 See <tt>nn::cfg::CfgCountryCode</tt> for the country IDs.
338 
339 @return Returns the country ID.
340  */
341  u8 GetCountryId() const;
342 
343  /*!
344 @brief Gets the attached URL.
345 
346 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_URL</tt> is specified. <br />
347 <br />
348 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 />
349 - If calling the <tt>@ref TestFlags</tt> function with <tt>@ref FLAG_WITH_EXTERNAL_URL</tt> specified yields a return value of <tt>false</tt>.
350 - If <tt>NULL</tt> is specified for the <span class="argument">externalUrl</span> argument.
351 - If a value less than the value of <tt>@ref nn::olv::EXTERNAL_URL_BUFF_LENGTH</tt> is specified for the <span class="argument">externalUrlMaxLength</span> argument.
352 
353 @param[out] externalUrl The buffer that stores the attached URL. <br />
354 @param[in] externalUrlMaxLength The length of the buffer that stores the attached URL, including the terminating null character. <br />
355 Make sure that you specify a size of at least <tt>@ref nn::olv::EXTERNAL_URL_BUFF_LENGTH</tt>.
356  */
357  void GetExternalUrl(char* externalUrl, u32 externalUrlMaxLength) const;
358 
359  /*!
360 @brief Gets the Mii data of the user.
361 
362 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 />
363 <br />
364 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 />
365 - 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>.
366 - If <tt>NULL</tt> is specified for the <span class="argument">storeData</span> argument.
367 
368 @param[out] storeData The buffer that stores the Mii data. <br />
369  */
370  void GetMiiData(nn::mii::StoreData* storeData) const;
371 
372  /*!
373 @brief Gets the nickname of the Mii character of the user.
374 
375 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 />
376 - If <tt>NULL</tt> is specified for the <span class="argument">miiNickname</span> argument.
377 - 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.
378 
379 @param[out] miiNickname The buffer that stores the nickname of the Mii character. <br />
380 @param[in] miiNicknameMaxLength The length of the buffer that stores the nickname of the Mii character, including the terminating null character. <br />
381 Make sure that you specify a size of at least <tt>@ref nn::olv::MII_NICKNAME_BUFF_LENGTH</tt>.
382  */
383  void GetMiiNickname(wchar_t* miiNickname, u32 miiNicknameMaxLength) const;
384 
385  /*!
386 @brief Gets text data.
387 
388 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 />
389 <br />
390 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 />
391 - 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>.
392 - If <tt>NULL</tt> is specified for the <span class="argument">bodyText</span> argument.
393 - 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.
394 
395 @param[out] bodyText The buffer that stores the text data.
396 @param[in] bodyTextMaxLength The length of the buffer that stores the text data, including the terminating null character. <br />
397 Make sure that you specify a size of at least <tt>@ref nn::olv::BODY_TEXT_BUFF_LENGTH</tt>.
398  */
399  void GetBodyText(wchar_t* bodyText, u32 bodyTextMaxLength) const;
400 
401  /*!
402 @brief Gets the handwritten memo data.
403 
404 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>.
405 <br />
406 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 />
407 - When the <tt>@ref TestFlags</tt> function is set to <tt>@ref FLAG_WITH_BODY_MEMO</tt> and returns <tt>false</tt>.
408 - When the <span class="argument">bodyMemo</span> parameter is set to <tt>NULL</tt>.
409 - When a value less than <tt>@ref nn::olv::BODY_MEMO_BUFF_LENGTH</tt> is specified for the <span class="argument">bodyMemoMaxSize</span> parameter.
410 
411 @param[out] bodyMemo The buffer that stores the handwritten memo data.
412 @param[out] bodyMemoSize The buffer that stores the size of the handwritten memo data.
413 @param[in] bodyMemoMaxSize The size of the buffer that stores the handwritten memo data. <br />
414 Make sure that you specify a size of at least <tt>@ref nn::olv::BODY_MEMO_BUFF_LENGTH</tt>.
415  */
416  void GetBodyMemo(u8* bodyMemo, u32* bodyMemoSize, u32 bodyMemoMaxSize) const;
417 
418  /*!
419 @brief Gets topic tags.
420 
421 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 />
422 - If <tt>NULL</tt> is specified for the <span class="argument">topicTag</span> argument.
423 - If a value less than that of <tt>@ref nn::olv::TOPIC_TAG_BUFF_LENGTH</tt> is specified for the <span class="argument">topicTagMaxLength</span> argument.
424 
425 @param[out] topicTag The buffer that stores the topic tags.
426 @param[in] topicTagMaxLength The length of the buffer that stores the topic tags, including the terminating null character. <br />
427 Make sure that you specify a size of at least <tt>@ref nn::olv::TOPIC_TAG_BUFF_LENGTH</tt>.
428  */
429  void GetTopicTag(wchar_t* topicTag, u32 topicTagMaxLength) const;
430 
431  /*!
432 @brief Gets application data.
433 
434 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.
435 <br />
436 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 />
437 - 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>.
438 - If <tt>NULL</tt> is specified for the <span class="argument">appData</span> argument.
439 - If a value less than that returned by the <tt>@ref GetAppDataSize</tt> function is specified for the <span class="argument">appDataMaxSize</span> argument.
440 
441 @param[out] appData The buffer that stores the application data.
442 @param[out] appDataSize The buffer that stores the size of the application data.
443 @param[in] appDataMaxSize The size of the buffer that stores the application data. <br />
444 Make sure that you specify a value of at least that returned by the <tt>@ref GetAppDataSize</tt> function.
445  */
446  void GetAppData(u8* appData, u32* appDataSize, u32 appDataMaxSize) const;
447 
448  /*!
449 @brief Gets the size of the application data.
450 
451 @return Returns the size of the application data.
452  */
453  u32 GetAppDataSize() const;
454 
455  /*!
456 @brief Gets the size of the attached image data.
457 
458 @return Returns the size of the attached image data.
459  */
460  u32 GetExternalImageDataSize() const;
461 
462  /*!
463 @brief Downloads the attached image data.
464 
465 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 />
466 This function causes Internet communication, during which time processing is blocked. <br />
467 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 />
468 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.
469 
470 @param[out] externalImageData The buffer that stores the attached image data.
471 @param[out] externalImageDataSize The buffer that stores the size of the attached image data.
472 @param[in] externalImageDataMaxSize The size of the buffer that stores the attached image data.
473 
474 @return Returns the result of the operation. <br />
475 For information about how to handle the results, see the OLV library reference.
476  */
477  nn::olv::Result DownloadExternalImageData(void* externalImageData, u32* externalImageDataSize, u32 externalImageDataMaxSize) const;
478 
479  /*!
480 @brief Gets the community ID.
481 
482 @return Returns the community ID.
483  */
484  u32 GetCommunityId() const;
485 
486  /*!
487 @brief Gets the Yeah count.
488 
489 @return Returns the Yeah count.
490  */
491  u32 GetEmpathyCount() const;
492 
493  /*!
494 @brief Gets the number of comments.
495 
496 @return Returns the number of comments.
497  */
498  u32 GetCommentCount() const;
499 
500  /*!
501 @brief Gets the post ID.
502 
503 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 />
504 - If <tt>NULL</tt> is specified for the <span class="argument">postId</span> argument.
505 - If a value less than that of <tt>@ref nn::olv::POST_ID_BUFF_LENGTH</tt> is specified for the <span class="argument">postIdMaxLength</span> argument.
506 
507 @param[out] postId The buffer that stores the post ID.
508 @param[in] postIdMaxLength The length of the buffer that stores the post ID, including the terminating null character. <br />
509 Make sure that you specify a size of at least <tt>@ref nn::olv::POST_ID_BUFF_LENGTH</tt>.
510  */
511  void GetPostId(char* postId, u32 postIdMaxLength) const;
512 
513  friend class nn::olv::internal::Main;
514 };
515 
516 /** @} */
517 
518 } // namespace olv
519 } // namespace nn
520 #endif