AM Daemon ライブラリリファレンス
Sequence.h
[詳解]
1 /// @file
2 /// @brief ゲームシーケンスを管理するMonostateクラス Sequence のヘッダ。
3 ///
4 /// Copyright(C)SEGA
5 
6 #ifndef AMDAEMON_SEQUENCE_H
7 #define AMDAEMON_SEQUENCE_H
8 
9 #include "amdaemon/env.h"
14 #include "amdaemon/PlayEndParam.h"
15 #include "amdaemon/PlayErrorId.h"
16 #include "amdaemon/AimeId.h"
17 
18 #include <cstddef>
19 
20 namespace amdaemon
21 {
22 /// @addtogroup g_sequence
23 /// @{
24 
25  /// @brief ゲームシーケンスを管理するMonostateクラス。
26  ///
27  /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
28  /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
29  ///
30  /// @par ライブラリ利用アプリで実装すべきこと
31  /// - メンバ関数 #getBookkeeping で取得できるブックキーピング情報を利用している場合、
32  /// ゲームテストモードにバックアップクリア画面を用意し、
33  /// オペレータがクリアを指示した場合にメンバ関数 #clearBackup を呼び出すこと。
34  /// - ビデオタイトルでは、同時に Credit クラスのメンバ関数
35  /// Credit#clearBackup も呼び出すこと。
36  /// - ゲームプレイ状態変更をメンバ関数 #beginPlay, #continuePlay, #endPlay で通知すること。
37  /// - ただし電断再起動時もゲームプレイ状態を継続させたい場合(メダルタイトル等)、
38  /// これらのメンバ関数を用いずゲームアプリ側でゲームプレイ状態を管理すること。
39  /// その場合、メンバ関数 #getBookkeeping が返すブックキーピング情報は利用できない。
40  /// - ゲームテストモード開始時にメンバ関数 #beginTest を、
41  /// 終了時にメンバ関数 #endTest をそれぞれ呼び出すこと。
42  ///
43  /// @par プレイ状態変更
44  /// 各プレイヤーのプレイ開始/コンティニュー/終了処理を一括で行う。
45  /// @par
46  /// - メンバ関数 #beginPlay でプレイを開始する。
47  /// - メンバ関数 #continuePlay でコンティニューする。
48  /// - メンバ関数 #endPlay でプレイを終了する。
49  /// @par
50  /// いずれもゲームテストモード中に呼び出すことはできない。
51  /// @par
52  /// 引数に渡すパラメータによって下記の処理を一括して行わせることができる。
53  /// @par
54  /// - ブックキーピング更新
55  /// - ゲームコスト(クレジット)支払い
56  /// - ALL.Net課金プレイ開始/終了
57  /// - AimeのUID値紐付けとプレイログ送信
58  /// @par
59  /// 上記のうち、ゲームプレイ状態変更と同時に行わせたくない処理については、
60  /// allnet::Accounting クラスや Aime クラス等を用いて個別に処理することもできる。
61  ///
62  /// @par ゲームテストモード通知
63  /// Daemonプロセス側でのゲームテストモード対応のために行う通知。
64  /// @par
65  /// - メンバ関数 #beginTest でゲームテストモード開始を通知する。
66  /// - 通知に成功すると、全プレイヤーのプレイ状態は解除される。
67  /// - その時点でのプレイは無かったことになり、ブックキーピングに記録されない。
68  /// - メンバ関数 #endTest でゲームテストモード終了を通知する。
69  ///
70  /// @ingroup g_common
71  class Sequence
72  {
73  // 下記は暗黙の定義を用いる。
74  //Sequence() = default;
75  //‾Sequence() = default;
76  //Sequence(const Sequence&) = default;
77  //Sequence& operator=(const Sequence&) = default;
78 
79  public:
80  // ブックキーピング
81 
82  /// @brief ブックキーピングのクリア処理を要求する。
83  /// @retval true 成功した場合。
84  /// @retval false 失敗した場合。
85  ///
86  /// プレイ回数やプレイ時間等のブックキーピングのみがクリアされる。
87  /// クレジット関連のブックキーピングは
88  /// Credit クラスのメンバ関数 Credit#clearBackup でクリアできる。
89  ///
90  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
91  bool clearBackup();
92 
93  /// @brief プレイ回数やプレイ時間等のブックキーピングを取得する。
94  /// @return プレイ回数やプレイ時間等のブックキーピング。
95  ///
96  /// クレジット関連のブックキーピングは
97  /// Credit クラスのメンバ関数 Credit#getBookkeeping で取得できる。
98  const SequenceBookkeeping& getBookkeeping() const;
99 
100  public:
101  // プレイ状態
102 
103  /// @brief 有効プレイヤー数を取得する。
104  /// @return 有効プレイヤー数。
105  /// @see Core#getPlayerCount
106  ///
107  /// Core#getPlayerCount と同じ値を返す。
108  std::size_t getPlayerCount() const;
109 
110  /// @brief プレイ状態変更と連動するALL.Net課金の処理タイミングを取得する。
111  /// @return ALL.Net課金の処理タイミング。
112  ///
113  /// Daemonプロセスの設定ファイルで指定したALL.Net課金の処理タイミングを表す
114  /// 列挙値を返す。
116 
117  /// @brief プレイヤーのプレイ開始処理を行う。
118  /// @param[in] playerIndex プレイヤーインデックス。
119  /// @param[in] param プレイ開始処理パラメータ。
120  /// @retval true 成功した場合。
121  /// @retval false 失敗した場合。
122  /// @see Player
123  ///
124  /// @exception Exception
125  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
126  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
127  /// - プレイヤーが既にプレイ中である場合。
128  /// - ゲームテストモード中である場合。
129  /// - 引数 param に不正な値を指定した場合。
130  /// 詳しくは PlayBeginParam クラスの各メンバ関数の説明を参照すること。
131  ///
132  /// 引数 param に各種パラメータを設定しておくことで下記の処理を順番に一括で行う。
133  /// パラメータを設定しなかった項目については処理しない。
134  ///
135  /// -# ゲームコスト(クレジット)の支払い可否チェック。
136  /// -# ALL.Net課金プレイの開始。
137  /// -# ALL.Net課金プレイの終了。
138  /// - 1プレイの開始時にALL.Net課金プレイの開始と終了を一括で行うタイトル用。
139  /// -# ゲームコスト(クレジット)の支払い。
140  /// -# プレイ状態の変更。
141  /// -# ブックキーピングの更新。
142  /// - 引数 param の内容に依らず必ず行う。
143  /// -# Aime UID値の紐付けとAimeプレイログの送信開始。
144  /// - 処理の成否は無視される。
145  ///
146  /// 処理に失敗した場合、プレイ中状態には移行しない。下記の場合は必ず失敗する。
147  ///
148  /// - いずれかの引数が不正値である場合。
149  /// - 対象プレイヤーが既にプレイ中である場合。
150  /// - ゲームテストモード中である場合。
151  /// - 進行停止エラー発生中である場合。
152  ///
153  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
154  bool beginPlay(
155  std::size_t playerIndex,
156  const PlayBeginParam& param = PlayBeginParam())
157  {
159  return beginPlay(playerIndex, param, dummy);
160  }
161 
162  /// @brief プレイヤーのプレイ開始処理を行う。
163  /// @param[in] playerIndex プレイヤーインデックス。
164  /// @param[in] param プレイ開始処理パラメータ。
165  /// @param[out] errorId 処理失敗時のエラーID設定先。
166  /// @retval true 成功した場合。
167  /// @retval false 失敗した場合。
168  /// @see Player
169  ///
170  /// @exception Exception
171  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
172  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
173  /// - プレイヤーが既にプレイ中である場合。
174  /// - ゲームテストモード中である場合。
175  /// - 引数 param に不正な値を指定した場合。
176  /// 詳しくは PlayBeginParam クラスの各メンバ関数の説明を参照すること。
177  ///
178  /// 処理失敗時、引数 errorId に渡した変数に失敗原因を示すエラーID値が設定される。
179  ///
180  /// 上記以外の処理内容は
181  /// beginPlay(std::size_t, const PlayBeginParam&) オーバロードと同等である。
182  bool beginPlay(
183  std::size_t playerIndex,
184  const PlayBeginParam& param,
185  PlayErrorId& errorId);
186 
187  /// @brief プレイヤーのコンティニュー処理を行う。
188  /// @param[in] playerIndex プレイヤーインデックス。
189  /// @param[in] param コンティニュー処理パラメータ。
190  /// @retval true 成功した場合。
191  /// @retval false 失敗した場合。
192  /// @see Player
193  ///
194  /// @exception Exception
195  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
196  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
197  /// - プレイヤーがプレイ中ではない場合。
198  /// - ゲームテストモード中である場合。
199  /// - 引数 param に不正な値を指定した場合。
200  /// 詳しくは PlayContinueParam クラスの各メンバ関数の説明を参照すること。
201  ///
202  /// 引数 param に各種パラメータを設定しておくことで下記の処理を順番に一括で行う。
203  /// パラメータを設定しなかった項目については処理しない。
204  ///
205  /// -# ゲームコスト(クレジット)の支払い可否チェック。
206  /// -# コンティニュー前プレイ分のALL.Net課金プレイの開始。
207  /// - 1プレイの終了時にALL.Net課金プレイの開始と終了を一括で行うタイトル用。
208  /// -# コンティニュー前プレイ分のALL.Net課金プレイの終了。
209  /// -# コンティニュー後プレイ分のALL.Net課金プレイの開始。
210  /// -# コンティニュー後プレイ分のALL.Net課金プレイの終了。
211  /// - 1プレイの開始時にALL.Net課金プレイの開始と終了を一括で行うタイトル用。
212  /// -# ゲームコスト(クレジット)の支払い。
213  /// -# ブックキーピングの更新。
214  /// - 引数 param の内容に依らず必ず行う。
215  /// -# Aimeプレイログの送信開始。
216  /// - プレイ開始時にUID値を紐付けした場合のみ行う。
217  /// - 処理の成否は無視される。
218  ///
219  /// 処理に失敗した場合、コンティニューは行われない。下記の場合は必ず失敗する。
220  ///
221  /// - いずれかの引数が不正値である場合。
222  /// - 対象プレイヤーがプレイ中ではない場合。
223  /// - ゲームテストモード中である場合。
224  /// - 進行停止エラー発生中である場合。
225  ///
226  /// 処理の失敗箇所によって呼び出し後の状態は変化する。
227  /// 例えばALL.Net課金プレイの終了には成功したが開始には失敗した場合、
228  /// メンバ関数 #isAccountingPlaying が false を返す状態となる。
229  ///
230  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
232  std::size_t playerIndex,
233  const PlayContinueParam& param = PlayContinueParam())
234  {
236  return continuePlay(playerIndex, param, dummy);
237  }
238 
239  /// @brief プレイヤーのコンティニュー処理を行う。
240  /// @param[in] playerIndex プレイヤーインデックス。
241  /// @param[in] param コンティニュー処理パラメータ。
242  /// @param[out] errorId 処理失敗時のエラーID設定先。
243  /// @retval true 成功した場合。
244  /// @retval false 失敗した場合。
245  /// @see Player
246  ///
247  /// @exception Exception
248  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
249  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
250  /// - プレイヤーがプレイ中ではない場合。
251  /// - ゲームテストモード中である場合。
252  /// - 引数 param に不正な値を指定した場合。
253  /// 詳しくは PlayContinueParam クラスの各メンバ関数の説明を参照すること。
254  ///
255  /// 処理失敗時、引数 errorId に渡した変数に失敗原因を示すエラーID値が設定される。
256  ///
257  /// 上記以外の処理内容は
258  /// continuePlay(std::size_t, const PlayContinueParam&) オーバロードと同等である。
259  bool continuePlay(
260  std::size_t playerIndex,
261  const PlayContinueParam& param,
262  PlayErrorId& errorId);
263 
264  /// @brief プレイヤーのプレイ終了処理を行う。
265  /// @param[in] playerIndex プレイヤーインデックス。
266  /// @param[in] param プレイ終了処理パラメータ。
267  /// @retval true 成功した場合。
268  /// @retval false 失敗した場合。
269  /// @see Player
270  ///
271  /// @exception Exception
272  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
273  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
274  /// - プレイヤーが既にプレイ中ではない場合。
275  /// - ゲームテストモード中である場合。
276  /// - 引数 param に不正な値を指定した場合。
277  /// 詳しくは PlayEndParam クラスの各メンバ関数の説明を参照すること。
278  ///
279  /// 引数 param に各種パラメータを設定しておくことで下記の処理を順番に一括で行う。
280  /// パラメータを設定しなかった項目については処理しない。
281  ///
282  /// -# ALL.Net課金プレイの開始。
283  /// - 1プレイの終了時にALL.Net課金プレイの開始と終了を一括で行うタイトル用。
284  /// -# ALL.Net課金プレイの終了。
285  /// -# プレイ状態の変更。
286  /// -# ブックキーピングの更新。
287  /// - 引数 param の内容に依らず必ず行う。
288  /// -# Aimeプレイログの送信開始。
289  /// - プレイ開始時にUID値を紐付けした場合のみ行う。
290  /// - 処理の成否は無視される。
291  ///
292  /// 処理に失敗した場合、プレイ中状態は解除されない。下記の場合は必ず失敗する。
293  ///
294  /// - いずれかの引数が不正値である場合。
295  /// - 対象プレイヤーがプレイ中ではない場合。
296  /// - ゲームテストモード中である場合。
297  /// - 進行停止エラー発生中である場合。
298  ///
299  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
300  bool endPlay(std::size_t playerIndex, const PlayEndParam& param = PlayEndParam())
301  {
303  return endPlay(playerIndex, param, dummy);
304  }
305 
306  /// @brief プレイヤーのプレイ終了処理を行う。
307  /// @param[in] playerIndex プレイヤーインデックス。
308  /// @param[in] param プレイ終了処理パラメータ。
309  /// @param[out] errorId 処理失敗時のエラーID設定先。
310  /// @retval true 成功した場合。
311  /// @retval false 失敗した場合。
312  /// @see Player
313  ///
314  /// @exception Exception
315  /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
316  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
317  /// - プレイヤーが既にプレイ中ではない場合。
318  /// - ゲームテストモード中である場合。
319  /// - 引数 param に不正な値を指定した場合。
320  /// 詳しくは PlayEndParam クラスの各メンバ関数の説明を参照すること。
321  ///
322  /// 処理失敗時、引数 errorId に渡した変数に失敗原因を示すエラーID値が設定される。
323  ///
324  /// 上記以外の処理内容は
325  /// endPlay(std::size_t, const PlayEndParam&) オーバロードと同等である。
326  bool endPlay(
327  std::size_t playerIndex,
328  const PlayEndParam& param,
329  PlayErrorId& errorId);
330 
331  /// @brief プレイヤーがプレイ中であるか否かを取得する。
332  /// @param[in] playerIndex プレイヤーインデックス。
333  /// @retval true プレイ中である場合。
334  /// @retval false プレイ中ではない場合。
335  /// @see Player
336  ///
337  /// @exception Exception
338  /// 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
339  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
340  bool isPlaying(std::size_t playerIndex) const;
341 
342  /// @brief いずれかのプレイヤーがプレイ中であるか否かを取得する。
343  /// @retval true 1人以上のプレイヤーがプレイ中である場合。
344  /// @retval false どのプレイヤーもプレイ中ではない場合。
345  bool isPlayingAny() const;
346 
347  /// @brief プレイヤーがALL.Net課金プレイ中であるか否かを取得する。
348  /// @param[in] playerIndex プレイヤーインデックス。
349  /// @retval true ALL.Net課金プレイ中である場合。
350  /// @retval false ALL.Net課金プレイ中ではない場合。
351  /// @see Player
352  ///
353  /// @exception Exception
354  /// 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
355  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
356  ///
357  /// メンバ関数 #getPlayAccountingTiming の戻り値が
358  /// PlayAccountingTiming::Normal であり、なおかつメンバ関数 #beginPlay や
359  /// #continuePlay でALL.Net課金プレイを開始済みである場合に true を返すようになる。
360  ///
361  /// 上記メンバ関数の戻り値が PlayAccountingTiming::Normal 以外である場合や、
362  /// allnet::AccountingUnit クラスのメンバ関数 allnet::AccountingUnit#beginPlay を
363  /// 直接呼び出して課金プレイを開始した場合、この関数が true を返すことはない。
364  bool isAccountingPlaying(std::size_t playerIndex) const;
365 
366  /// @brief プレイ中のプレイヤーに紐付いているAimeのUID値を取得する。
367  /// @param[in] playerIndex プレイヤーインデックス。
368  /// @return AimeのUID値。紐付いていないかプレイ中でない場合は無効値。
369  /// @see Player
370  ///
371  /// @exception Exception
372  /// 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
373  /// 有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
374  ///
375  /// メンバ関数 #beginPlay で紐付けしたAimeのUID値を返す。
376  /// 紐付けしなかった場合は無効値のままとなる。
377  ///
378  /// メンバ関数 #endPlay を呼び出すと無効値に戻る。
379  AimeId getPlayingAimeId(std::size_t playerIndex) const;
380 
381  public:
382  // ゲームテストモード
383 
384  /// @brief ゲームテストモードを開始したことを通知する。
385  /// @retval true 成功した場合。
386  /// @retval false 失敗した場合。
387  ///
388  /// @exception Exception
389  /// 既にゲームテストモード中である場合。
390  ///
391  /// 通知に成功すると、全プレイヤーのプレイ中状態は解除される。
392  /// その時点でのプレイは無かったことになり、ブックキーピングに記録されない。
393  ///
394  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
395  bool beginTest();
396 
397  /// @brief ゲームテストモードを終了したことを通知する。
398  /// @retval true 成功した場合。
399  /// @retval false 失敗した場合。
400  ///
401  /// @exception Exception
402  /// 既にゲームテストモード中ではない場合。
403  ///
404  /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
405  bool endTest();
406 
407  /// @brief ゲームテストモード中であるか否かを取得する。
408  /// @retval true ゲームテストモード中である場合。
409  /// @retval false ゲームテストモード中ではない場合。
410  bool isTest() const;
411  };
412 
413 /// @}
414 } // namespace amdaemon
415 
416 #endif // AMDAEMON_SEQUENCE_H
ゲームシーケンスを管理するMonostateクラス。
Definition: Sequence.h:71
bool isAccountingPlaying(std::size_t playerIndex) const
プレイヤーがALL.Net課金プレイ中であるか否かを取得する。
AimeのUID値を保持する構造体。
Definition: AimeId.h:27
bool beginTest()
ゲームテストモードを開始したことを通知する。
bool clearBackup()
ブックキーピングのクリア処理を要求する。
AimeのUID値を保持する構造体 AimeId のヘッダ。
bool continuePlay(std::size_t playerIndex, const PlayContinueParam &param=PlayContinueParam())
プレイヤーのコンティニュー処理を行う。
Definition: Sequence.h:231
プレイ終了に用いるパラメータを保持するクラス PlayEndParam のヘッダ。
エラー無し。
std::size_t getPlayerCount() const
有効プレイヤー数を取得する。
bool isPlaying(std::size_t playerIndex) const
プレイヤーがプレイ中であるか否かを取得する。
プレイ開始に用いるパラメータを保持するクラス PlayBeginParam のヘッダ。
Daemonライブラリの環境定義を行うヘッダ。
AM Daemon ライブラリクラス群の基底名前空間。
Definition: Log.h:13
PlayAccountingTiming
プレイ状態変更と連動して行うALL.Net課金の処理タイミングを表す列挙。
Definition: PlayAccountingTiming.h:19
プレイ回数やプレイ時間関連のブックキーピング構造体 SequenceBookkeeping のヘッダ。 ...
const SequenceBookkeeping & getBookkeeping() const
プレイ回数やプレイ時間等のブックキーピングを取得する。
プレイ状態変更と連動して行うALL.Net課金の処理タイミングを表す列挙 PlayAccountingTiming のヘッダ。 ...
bool beginPlay(std::size_t playerIndex, const PlayBeginParam &param=PlayBeginParam())
プレイヤーのプレイ開始処理を行う。
Definition: Sequence.h:154
プレイ回数やプレイ時間関連のブックキーピング構造体。
Definition: SequenceBookkeeping.h:50
PlayAccountingTiming getPlayAccountingTiming() const
プレイ状態変更と連動するALL.Net課金の処理タイミングを取得する。
コンティニューに用いるパラメータを保持するクラス。
Definition: PlayContinueParam.h:21
bool isTest() const
ゲームテストモード中であるか否かを取得する。
プレイ終了に用いるパラメータを保持するクラス。
Definition: PlayEndParam.h:21
bool endTest()
ゲームテストモードを終了したことを通知する。
プレイ状態変更処理失敗時のエラー内容を表す列挙 PlayErrorId のヘッダ。
bool isPlayingAny() const
いずれかのプレイヤーがプレイ中であるか否かを取得する。
プレイ開始に用いるパラメータを保持するクラス。
Definition: PlayBeginParam.h:21
PlayErrorId
プレイ状態変更処理失敗時のエラー内容を表す列挙。
Definition: PlayErrorId.h:17
bool endPlay(std::size_t playerIndex, const PlayEndParam &param=PlayEndParam())
プレイヤーのプレイ終了処理を行う。
Definition: Sequence.h:300
コンティニューに用いるパラメータを保持するクラス PlayContinueParam のヘッダ。
AimeId getPlayingAimeId(std::size_t playerIndex) const
プレイ中のプレイヤーに紐付いているAimeのUID値を取得する。