CTR Pia  4.11.3
Game Communication Engine
common_CallContext.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_CallContext.h
4 
5  Copyright 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 
15 #pragma once
16 
17 #include <pia/common/common_RootObject.h>
18 
19 #define USE_CANCEL_REQUEST 1 // n1769
20 
21 
22 namespace nn
23 {
24 namespace pia
25 {
26 namespace common
27 {
28 
29 
30 /*!
31 @brief Represents the calling context.
32 
33 @details The calling context is primarily used to log the execution status of asynchronous functions.
34 
35 @date 2013-12-16 Removed a previous prohibition on calling the <tt>Cancel</tt> function in the <tt>CallContext</tt> passed to the Pia API that does not support cancellations.
36 @date 2013-12-13 Added the <tt>IsInProgress</tt> function.
37 @date 2013-12-13 Made the <tt>GetState</tt> function private.
38 @date 2012-09-21 No longer inherits <tt>Event</tt>.
39 @date 2012-09-20 Added a description of the conditions under which <tt>Cancel</tt> can be called.
40 @date 2012-05-14 Added the <tt>CompletionCallback</tt> parameter so values can be specified by applications.
41 @date 2012-05-14 Initial version.
42 */
43 class CallContext : public RootObject
44 {
45 public:
46  //n1589:todo2: It would be better to allow the user to select an arbitrary argument.
47 /*!
48 @brief This <tt>typedef</tt> defines the callback function that is executed when the asynchronous operation finishes.
49 
50 @details Register the callback using the <tt>CompletionCallback</tt> or <tt>RegisterCompletionCallback</tt> function so that a callback function is called when asynchronous processing completes.
51 
52 @see RegisterCompletionCallback
53 
54 */
55  typedef void (*CompletionCallback)(nn::Result result, void* pUserArg);
56 
57 /*!
58 @cond PRIVATE
59 @brief Enumerates <tt>@ref CallContext</tt> states.
60 */
61  enum State
62  {
63  Available, //!< Indicates that execution is possible.
64  CallInProgress, //!< Indicates that the operation is executing. Indicates that a context in this state cannot be used as the <tt>Context</tt> of another asynchronous process.
65  CallSuccess, //!< Indicates that the operation succeeded and ended.
66  CallFailure, //!< Indicates that the operation failed and ended.
67  CallCancelled //!< Indicates that the process was canceled.
68  };
69  //! @endcond
70 
71 /*!
72 @brief Instantiates the object (constructor).
73 
74 @details The state is set to <tt>Available</tt>.
75 */
76  CallContext(void);
77 
78 
79 /*!
80 @brief Destroys the object.
81 
82 @details The destructor asserts if the <tt>CallContext</tt> state is <tt>CallInProgress</tt> when it is called.
83 */
84  ~CallContext(void);
85 
86 
87 /*!
88 @brief Sets the callback function executed when asynchronous processing completes.
89 
90 @param[in] pCallback Specifies a pointer to the callback function called when asynchronous processing completes.
91 @param[in] pUserArg Specifies the value given in the second argument when calling <span class="argument">pCallback</span>.
92 @see CompletionCallback
93 */
94  void RegisterCompletionCallback(CompletionCallback pCallback, void* pUserArg = NULL);
95 
96 /*!
97 @cond PRIVATE
98 @brief
99 */
100  bool InitiateCall();
101  //! @endcond
102 
103 
104 /*!
105 @cond PRIVATE
106 @brief
107 */
108  void SignalSuccess(nn::Result result);
109  //! @endcond
110 
111 
112 /*!
113 @cond PRIVATE
114 @brief
115 */
116  void SignalFailure(nn::Result result);
117 //! @endcond
118 
119 
120 #if USE_CANCEL_REQUEST
121 /*!
122 @cond PRIVATE
123 @brief
124 */
125  void SignalCancel();
126 //! @endcond
127 #else
128 /*!
129 @cond PRIVATE
130 @brief
131 */
132  void ForceCancel();
133 //! @endcond
134 #endif
135 
136 
137 #if USE_CANCEL_REQUEST
138 /*!
139 @brief Requests the cancellation of asynchronous processing.
140 
141 @details Note that calling this API function does not mean that the asynchronous process is canceled immediately.
142 After this API function is called, you must periodically call the <tt>IsCompleted</tt> function to check the state of completion. Wait until <tt>true</tt> is returned.
143 
144 @see IsCompleted, GetResult
145 
146 
147 */
148  void Cancel(void);
149 #else
150 /*!
151 @brief Cancels asynchronous processing.
152 
153 @details If this function is called in a <tt>CallContext</tt> other than <tt>CallInProgress</tt>, it does nothing and returns.
154 
155 After asynchronous processing is terminated using this function, the valued obtained by <tt>GetResult</tt> is <tt>ResultCancelled</tt>.
156 
157 Asynchronous processes can only be canceled at those times clearly indicated in the description of asynchronous processes that use this <tt>CallContext</tt>.
158 Do not call this function on other asynchronous processes.
159 
160 @see GetResult
161 
162 
163 */
164  void Cancel(void);
165 #endif
166 
167 
168 /*!
169 @cond PRIVATE
170 @brief
171 */
172  void Complete(nn::Result result);
173  //! @endcond
174 
175 
176 /*!
177 @brief Determines whether an asynchronous process is in progress.
178 
179 @return Returns <tt>true</tt> if an asynchronous process is in progress, and <tt>false</tt> otherwise.
180 */
181  bool IsInProgress() const
182  {
183  return m_State == CallInProgress;
184  }
185 
186 
187 /*!
188 @brief Determines whether an asynchronous process has completed.
189 
190 @return Returns <tt>true</tt> if the asynchronous process has completed (including cases where it has failed); returns <tt>false</tt> otherwise.
191 */
192  bool IsCompleted() const
193  {
194  return m_State == CallSuccess ||
195  m_State == CallFailure ||
196  m_State == CallCancelled;
197  }
198 
199 
200 /*!
201 @cond PRIVATE
202 @brief Sets the state.
203 
204 @param[in] state Specifies the state to set.
205 @see GetState
206 */
207  void SetState(State state);
208  //! @endcond
209 
210 
211 /*!
212 @cond PRIVATE
213 @brief Gets the current state.
214 
215 @return Returns the current <tt>CallContext</tt>.
216 */
217  State GetState() const
218  {
219  return m_State;
220  }
221  //! @endcond
222 
223 
224 /*!
225 @cond PRIVATE
226 @brief Sets the <tt>nn::Result</tt> value representing the execution result of the asynchronous process.
227 
228 @param[in] result Specifies the <tt>nn::Result</tt> value of the asynchronous process.
229 */
230  void SetResult(nn::Result result);
231  //! @endcond
232 
233 
234 /*!
235 @brief Gets the <tt>nn::Result</tt> value representing the execution result of the asynchronous process.
236 
237 @return Returns the <tt>nn::Result</tt> value of the asynchronous process.
238 */
239  nn::Result GetResult() const
240  {
241  return m_Result;
242  }
243 
244 
245 #if USE_CANCEL_REQUEST
246 /*!
247 @cond PRIVATE
248 @brief Determines whether the <tt>Cancel</tt> function has been called.
249 */
250  bool IsCancelRequested() const
251  {
252  return m_bCancelRequested;
253  }
254 //! @endcond
255 #endif
256 
257  void Reset();
258 
259 protected:
260  State m_State;
261  nn::Result m_Result;
262  CompletionCallback m_CompletionCallback;
263  void* m_pUserArg;
264 #if USE_CANCEL_REQUEST
265  bool m_bCancelRequested;
266 #endif
267 
268 private:
269 /*!
270 @brief This copy constructor is private.
271 */
272  CallContext(const CallContext&);
273 
274 /*!
275 @brief This assignment operator is private.
276 */
277  CallContext& operator=(const CallContext&);
278 };
279 
280 
281 typedef CallContext AsyncContext;
282 }
283 }
284 } // end of namespace nn::pia::common
bool IsInProgress() const
Determines whether an asynchronous process is in progress.
Definition: common_CallContext.h:181
~CallContext(void)
Destroys the object.
CallContext(void)
Instantiates the object (constructor).
Definition: assert.h:115
bool IsCompleted() const
Determines whether an asynchronous process has completed.
Definition: common_CallContext.h:192
Represents the calling context.
Definition: common_CallContext.h:43
void RegisterCompletionCallback(CompletionCallback pCallback, void *pUserArg=NULL)
Sets the callback function executed when asynchronous processing completes.
void Cancel(void)
Requests the cancellation of asynchronous processing.
void(* CompletionCallback)(nn::Result result, void *pUserArg)
This typedef defines the callback function that is executed when the asynchronous operation finishes...
Definition: common_CallContext.h:55
nn::Result GetResult() const
Gets the nn::Result value representing the execution result of the asynchronous process.
Definition: common_CallContext.h:239
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40