CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
common_CallContext.h
1 /*--------------------------------------------------------------------------------*
2  Copyright (C)Nintendo All rights reserved.
3 
4  These coded instructions, statements, and computer programs contain proprietary
5  information of Nintendo and/or its licensed developers and are protected by
6  national and international copyright laws. They may not be disclosed to third
7  parties or copied or duplicated in any form, in whole or in part, without the
8  prior written consent of Nintendo.
9 
10  The content herein is highly confidential and should be handled accordingly.
11  *--------------------------------------------------------------------------------*/
12 
13 
14 #pragma once
15 
16 #include <nn/pia/common/common_RootObject.h>
17 
18 #define USE_CANCEL_REQUEST 1 // n1769
19 
20 
21 namespace nn
22 {
23 namespace pia
24 {
25 namespace common
26 {
27 
28 
29 /*!
30  @brief 呼び出しコンテキストのクラスです。
31 
32  @details 呼び出しコンテキストは、主に非同期関数の実行状態を記録するのに用いられます。
33  <br>
34  */
35 class CallContext : public RootObject
36 {
37 public:
38  //n1589:todo2:引数にユーザ任意引数があった方がよさそう
39  /*!
40  @brief 非同期処理の完了時に実行するコールバック関数の typedef です。
41 
42  @details 非同期処理完了時にコールバック関数が呼び出されるようにするには、
43  CompletionCallback を RegisterCompletionCallback() で登録します。
44 
45  @see RegisterCompletionCallback
46  */
47  typedef void (*CompletionCallback)(Result result, void* pUserArg);
48 
49  /*!
50  @cond PRIVATE
51  @brief @ref CallContext の状態の列挙です。
52  */
53  enum State
54  {
55  State_Available, //!< 実行可能。
56  State_CallInProgress, //!< 処理を実行中。この状態のときは他の非同期処理の Context としては使用できません。
57  State_CallSuccess, //!< 処理が成功して終了しました。
58  State_CallFailure, //!< 処理が失敗して終了しました。
59  State_CallCancelled //!< 処理がキャンセルされました。
60  };
61  //! @endcond
62 
63  /*!
64  @brief コンストラクタです。
65 
66  @details 状態は State_Available にセットされます。
67  */
68  CallContext(void);
69 
70 
71  /*!
72  @brief デストラクタです。
73 
74  @details デストラクタ呼び出し時に、CallContext の状態が State_CallInProgress であった場合には、アサート停止します。
75  */
76  ~CallContext(void);
77 
78 
79  /*!
80  @brief 非同期処理の完了時に実行するコールバック関数を設定します。
81 
82  @param[in] pCallback 非同期処理完了時に呼び出されるコールバック関数へのポインタです。
83  @param[in] pUserArg pCallback を呼び出す際に第2引数に与える値を指定します。
84  @see CompletionCallback
85  */
86  void RegisterCompletionCallback(CompletionCallback pCallback, void* pUserArg = NULL);
87 
88  /*!
89  @cond PRIVATE
90  @brief
91  */
92  bool InitiateCall();
93  //! @endcond
94 
95 
96  /*!
97  @cond PRIVATE
98  @brief
99  */
100  void SignalSuccess(Result result);
101  //! @endcond
102 
103 
104  /*!
105  @cond PRIVATE
106  @brief
107  */
108  void SignalFailure(Result result);
109 //! @endcond
110 
111 
112 #if USE_CANCEL_REQUEST
113  /*!
114  @cond PRIVATE
115  @brief
116  */
117  void SignalCancel();
118 //! @endcond
119 #else
120  /*!
121  @cond PRIVATE
122  @brief
123  */
124  void ForceCancel();
125 //! @endcond
126 #endif
127 
128 
129 #if USE_CANCEL_REQUEST
130  /*!
131  @brief 非同期処理のキャンセルをリクエストします。
132 
133  @details ただし、この API 呼び出しによって即座に非同期処理がキャンセルされるわけでは
134  ないことに注意してください。
135  この API 呼び出し後は、定期的に IsCompleted() で終了状態をチェックし、
136  true を返すまで待つ必要があります。
137 
138  @see IsCompleted, GetResult
139  */
140  void Cancel(void);
141 #else
142  /*!
143  @brief 非同期処理のキャンセルを行います。
144 
145  @details ただし、 CallContext の状態が State_CallInProgress 以外であった場合は、
146  このAPI呼び出しは何もせずに返ります。
147  このAPIを用いて非同期処理を終了させた場合、 GetResult で取得される値は
148  ResultCancelled となります。
149 
150  この CallContext を使用する非同期処理の説明にキャンセルが可能だと
151  明記されている場合のみキャンセルすることができます。
152  その他の非同期処理ではこの関数を呼び出してはいけません。
153 
154  @see GetResult
155  */
156  void Cancel(void);
157 #endif
158 
159 
160  /*!
161  @cond PRIVATE
162  @brief
163  */
164  void Complete(Result result);
165  //! @endcond
166 
167 
168  /*!
169  @brief 非同期処理が進行中であるかどうかを判定します。
170 
171  @return 非同期処理が進行中の状態であれば true 、そうでなければ false を返します。
172  */
173  bool IsInProgress() const
174  {
175  return m_State == State_CallInProgress;
176  }
177 
178 
179  /*!
180  @brief 非同期処理が終了したかどうかを判定します。
181 
182  @return 非同期処理が終了した状態(失敗して終了した状態も含みます)であれば true 、そうでなければ false を返します。
183  */
184  bool IsCompleted() const
185  {
186  return m_State == State_CallSuccess ||
187  m_State == State_CallFailure ||
188  m_State == State_CallCancelled;
189  }
190 
191 
192  /*!
193  @cond PRIVATE
194  @brief 状態を設定します。
195 
196  @param[in] state 設定したい状態を指定します。
197  @see GetState
198  */
199  void SetState(State state);
200  //! @endcond
201 
202 
203  /*!
204  @cond PRIVATE
205  @brief 現在の状態を取得します。
206 
207  @return 現在の CallContext の状態。
208  */
209  State GetState() const
210  {
211  return m_State;
212  }
213  //! @endcond
214 
215 
216  /*!
217  @cond PRIVATE
218  @brief 非同期処理の実行結果の Result 値をセットします。
219 
220  @param[in] result 非同期処理の実行結果の Result 値。
221  */
222  void SetResult(Result result);
223  //! @endcond
224 
225 
226  /*!
227  @brief 非同期処理の実行結果の Result 値を取得します。
228 
229  @return 非同期処理の実行結果の Result 値。
230  */
232  {
233  return m_Result;
234  }
235 
236 
237 #if USE_CANCEL_REQUEST
238  /*!
239  @cond PRIVATE
240  @brief Cancel() 呼び出しが行われたかどうかを判定します。
241  */
242  bool IsCancelRequested() const
243  {
244  return m_IsCancelRequested;
245  }
246 //! @endcond
247 #endif
248 
249  void Reset();
250 
251 protected:
252  State m_State;
253  Result m_Result;
254  CompletionCallback m_CompletionCallback;
255  void* m_pUserArg;
256 #if USE_CANCEL_REQUEST
257  bool m_IsCancelRequested;
258 #endif
259 
260 private:
261  NN_PIA_DISALLOW_COPY(CallContext);
262 };
263 
264 
265 typedef CallContext AsyncContext;
266 }
267 }
268 } // end of namespace nn::pia::common