Nintendo 3DS Miiverse Library  1.3.2
(OLV/Olive)
olv_Api.h
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*
2 Project: OLV
3 File: olv_Api.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_API_H_
15 #define __OLV_API_H_
16 
17 /*! @file
18 @brief These are API declarations for the OLV library.
19 */
20 
21 #include <nn/olv/olv_Types.h>
22 #include <nn/olv/olv_Result.h>
23 
24 /// <span>nn</span>
25 namespace nn {
26 
27 /// <span>olv</span>
28 namespace olv {
29 
30 /*@defgroup function Static Functions
31  * @{
32  */
33 
34 /*!
35 @brief Initializes the OLV library.
36 
37 You must call this function before calling any of the functions in the <tt>nn::olv</tt> namespace. <br />
38 Note that the working buffer specified for the <span class="argument">initializeParam</span> argument with the <tt>@ref nn::olv::InitializeParam::SetWork</tt> function must not be cleared until the <tt>@ref nn::olv::Finalize</tt> function is called. <br />
39 
40 - OLV Access Key Settings<br />
41 To use the OLV library at the development stage, configure and build the application with the unique ID issued by Nintendo, and then set the OLV access key issued by Nintendo using the CTR Config tool before starting the application.
42 This prevents people who are not involved in application development from posting to the viewable communities.
43 
44 @param[out] initializedData The class that stores the initialization results.
45 @param[in] initializeParam The class that stores the parameters used for initialization.
46 
47 @return Returns the result of the operation. <br />
48 For information about how to handle the results, see the OLV library reference.
49 */
50 nn::olv::Result Initialize(nn::olv::InitializedData* initializedData, const nn::olv::InitializeParam* initializeParam);
51 
52 /*!
53 @brief Finalizes the OLV library.
54 */
55 void Finalize();
56 
57 /*!
58 @brief Processes OLV library connections.
59 
60 This function causes Internet communication, during which time processing is blocked. <br />
61 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 />
62 
63 @param[out] connectedData The class that stores the connection results.
64 @param[in] connectParam The class that stores the parameters used for the connection.
65 
66 @return Returns the result of the operation. <br />
67 For information about how to handle the results, see the OLV library reference.
68 */
69 nn::olv::Result Connect(nn::olv::ConnectedData* connectedData, const nn::olv::ConnectParam* connectParam);
70 
71 /*!
72 @brief Cancels the Internet communication process.
73 
74 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.
75 
76 @return Returns the result of the operation. <br />
77 For information about how to handle the results, see the OLV library reference.
78 */
79 nn::olv::Result Cancel();
80 
81 /*!
82 @brief Determines whether the OLV library has been initialized.
83 
84 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.
85 
86 @return Returns <tt>true</tt> if the library is initialized, and <tt>false</tt> otherwise.
87 */
88 bool IsInitialized();
89 
90 /*!
91 @brief Determines whether the OLV library has been connected to.
92 
93 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.
94 
95 @return Returns <tt>true</tt> if the library has been connected to, and <tt>false</tt> otherwise.
96 */
97 bool IsConnected();
98 
99 /*!
100 @brief Gets the error code.
101 
102 This function is thread safe.
103 
104 @param[in] result Specifies the result obtained from the OLV library API.
105 
106 @return Returns the error code corresponding to the specified result. <br />
107 Returns <tt>0</tt> if the specified result is not from the OLV library API.
108 @retval 0 There are no OLV-related corresponding error codes.
109 @retval Anything else The error code.
110 */
111 u32 GetErrorCode(const nn::olv::Result& result);
112 
113 /*!
114 @brief Starts the Miiverse application.
115 
116 If this function succeeds, you must call the <tt>nn::applet::WaitForStarting</tt> function to wait for the start event of the application. <br />
117 Note that the working buffer specified for the <span class="argument">startParam</span> argument with the <tt>@ref nn::olv::StartPortalAppParam::SetWork</tt> function must not be cleared until either the <tt>@ref nn::olv::Resume</tt> or the <tt>nn::olv::Finalize</tt> function is called after the start event of the application.
118 
119 @param[in] startParam The class that stores the parameters used when starting the Miiverse application.
120 
121 @return Returns the result of the operation. <br />
122 For information about how to handle the results, see the OLV library reference.
123 */
124 nn::olv::Result StartPortalApp(const nn::olv::StartPortalAppParam* startParam);
125 
126 /*!
127 @brief Handles recovery operations.
128 
129 Call this function when the start event of the application comes after the OLV library has been initialized or the <tt>@ref nn::olv::StartPortalApp</tt> function has been called. <br />
130 If system parameters are being passed from the Miiverse application, that data can be received.
131 
132 @param[out] resumedData The class that stores the recovery process results.
133 @param[in] resumeParam The class that stores the parameters used for the recovery process.
134 
135 @return Returns the result of the operation. <br />
136 For information about how to handle the results, see the OLV library reference.
137 */
138 nn::olv::Result Resume(nn::olv::ResumedData* resumedData, const nn::olv::ResumeParam* resumeParam);
139 
140 /*!
141 @brief Downloads post data.
142 
143 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
144 This function initiates Internet communication, during which time processing is blocked. <br />
145 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 />
146 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.
147 
148 @param[out] topicData The class that stores the downloaded topic tags.
149 @param[out] postDataList An array of classes that stores the downloaded post data. <br />
150 Specify the number of arrays in the <span class="argument">downloadParam</span> argument of the <tt>@ref nn::olv::DownloadPostDataListParam::SetPostDataMaxNum</tt> function.
151 @param[out] downloadedPostDataNum The buffer that stores the number of downloaded posts.
152 @param[in] downloadParam The class that stores the parameters used when downloading posts.
153 
154 @return Returns the result of the operation. <br />
155 For information about how to handle the results, see the OLV library reference.
156 */
157 nn::olv::Result DownloadPostDataList(nn::olv::DownloadedTopicData* topicData, nn::olv::DownloadedPostData* postDataList, u32* downloadedPostDataNum, const nn::olv::DownloadPostDataListParam* downloadParam);
158 
159 /*!
160 @brief Downloads comment data.
161 
162 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
163 This function initiates Internet communication, during which time processing is blocked. <br />
164 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 />
165 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.
166 
167 @param[out] commentDataList An array of classes that store the downloaded comment data. <br />
168 Specify the number of arrays using the <tt>@ref nn::olv::DownloadCommentDataListParam::SetCommentDataMaxNum</tt> function in the <span class="argument">downloadParam</span> parameter.
169 @param[out] downloadedCommentDataNum The buffer that stores the amount of downloaded comment data.
170 @param[in] downloadParam The class that stores the parameters used when downloading comments.
171 
172 @return Returns the result of the operation. <br />
173 For information about how to handle the results, see the OLV library reference.
174 */
175 nn::olv::Result DownloadCommentDataList(nn::olv::DownloadedCommentData* commentDataList, u32* downloadedCommentDataNum, const nn::olv::DownloadCommentDataListParam* downloadParam);
176 
177 
178 /*!
179 @brief Downloads community data.
180 
181 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
182 This function initiates Internet communication, during which time processing is blocked. <br />
183 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 />
184 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.
185 
186 @param[out] communityDataList An array of classes that store the downloaded community data. <br />
187 Specify the number of arrays in the <span class="argument">downloadParam</span> argument of the <tt>@ref nn::olv::DownloadCommunityDataListParam::SetCommunityDataMaxNum</tt> function.
188 @param[out] downloadedCommunityDataNum The buffer that stores the number of downloaded communities.
189 @param[in] downloadParam The class that stores the parameters used when downloading community data.
190 
191 @return Returns the result of the operation. <br />
192 For information about how to handle the results, see the OLV library reference.
193 */
194 nn::olv::Result DownloadCommunityDataList(nn::olv::DownloadedCommunityData* communityDataList, u32* downloadedCommunityDataNum, const nn::olv::DownloadCommunityDataListParam* downloadParam);
195 
196 /*!
197 @brief Downloads user data.
198 
199 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
200 This function initiates Internet communication, during which time processing is blocked. <br />
201 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 />
202 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.
203 
204 @param[out] userDataList An array of classes that store the downloaded user data. <br />
205 Specify the number of arrays using the <tt>@ref nn::olv::DownloadUserDataListParam::SetUserDataMaxNum</tt> function in the <span class="argument">downloadParam</span> parameter.
206 @param[out] downloadedUserDataNum The buffer that stores the amount of downloaded user data.
207 @param[in] downloadParam The class that stores the parameters used when downloading user data.
208 
209 @return Returns the result of the operation. <br />
210 For information about how to handle the results, see the OLV library reference.
211 */
212 nn::olv::Result DownloadUserDataList(nn::olv::DownloadedUserData* userDataList, u32* downloadedUserDataNum, const nn::olv::DownloadUserDataListParam* downloadParam);
213 
214 /*!
215 @brief Creates, updates, or deletes community data.
216 
217 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
218 This function initiates Internet communication, during which time processing is blocked. <br />
219 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 />
220 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.
221 
222 @param[out] uploadedData The class that stores the results of creating or updating community data. <br />
223 You can specify <tt>NULL</tt> if not needed. <br />
224 Nothing is stored if the community data is deleted.
225 @param[in] uploadParam The class that stores the parameters used when sending community data.
226 
227 @return Returns the result of the operation. <br />
228 For information about how to handle the results, see the OLV library reference.
229 */
230 nn::olv::Result UploadCommunityData(nn::olv::UploadedCommunityData* uploadedData, const nn::olv::UploadCommunityDataParam* uploadParam);
231 
232 /*!
233 @brief Gives a Yeah to a post or removes a Yeah from a post.
234 
235 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
236 This function initiates Internet communication, during which time processing is blocked. <br />
237 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 />
238 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.
239 
240 @param[in] uploadParam The class that stores the parameters used when giving a Yeah to a post or removing a Yeah from a post.
241 
242 @return Returns the result of the operation. <br />
243 For information about how to handle the results, see the OLV library reference.
244 */
245 nn::olv::Result UploadEmpathyToPostData(const nn::olv::UploadEmpathyToPostDataParam* uploadParam);
246 
247 /*!
248 @brief Registers a community as a favorite or removes a community as a favorite.
249 
250 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
251 This function initiates Internet communication, during which time processing is blocked. <br />
252 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 />
253 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.
254 
255 @param[in] uploadParam The class that stores the parameters used when registering a community as a favorite or removing a community as a favorite.
256 
257 @return Returns the result of the operation. <br />
258 For information about how to handle the results, see the OLV library reference.
259 */
261 
262 /*!
263 @brief Uploads whether to follow a user or to stop following a user.
264 
265 This function can only be used when a connection to the OLV library has already been made with the <tt>@ref nn::olv::Connect</tt> function. <br />
266 This function initiates Internet communication, during which time processing is blocked. <br />
267 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 />
268 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.
269 
270 @param[in] uploadParam The class that stores the parameters when uploading to follow a user or to stop following a user.
271 
272 @return Returns the result of the operation. <br />
273 For information about how to handle the results, see the OLV library reference.
274 */
275 nn::olv::Result UploadFollowToUserData(const nn::olv::UploadFollowToUserDataParam* uploadParam);
276 
277 
278 /** @} */
279 
280 } // namespace olv
281 } // namespace nn
282 #endif