Aimeリーダー単体の処理を提供するクラス。 [詳解]

#include <AimeUnit.h>

公開メンバ関数
	AimeUnit (InnerIndexHolder)
	コンストラクタ。 [詳解]

bool	start (AimeCommand command)
	ポーリング処理を開始する。 [詳解]

bool	cancel ()
	ポーリング処理の中断を開始する。 [詳解]

bool	isBusy () const
	ポーリング処理中または中断処理中であるか否かを取得する。 [詳解]

AimeCommand	getBusyCommand () const
	ポーリング処理中または中断処理中の処理コマンドを取得する。 [詳解]

bool	hasConfirm () const
	Aime登録に関する要確認事項が存在するか否かを取得する。 [詳解]

AimeConfirm	getConfirm () const
	Aime登録に関する要確認事項を取得する。 [詳解]

bool	acceptConfirm ()
	Aime登録に関する要確認事項が承諾されたことを通知する。 [詳解]

bool	hasResult () const
	ポーリング処理の結果が存在するか否かを取得する。 [詳解]

const AimeResult &	getResult () const
	ポーリング処理の結果を取得する。 [詳解]

bool	hasError () const
	ポーリング処理中にエラーが発生したか否かを取得する。 [詳解]

const AimeErrorInfo &	getErrorInfo () const
	ポーリング処理中に発生したエラー情報を取得する。 [詳解]

AimeLedStatus	getLedStatus () const
	現在のLED点灯ステータスを取得する。 [詳解]

bool	setLedStatus (AimeLedStatus status)
	LED点灯ステータスを設定する。 [詳解]

bool	setLed (bool onR, bool onG, bool onB)
	LEDの点灯状態をRGB別に設定する。 [詳解]

詳解

Aimeリーダー単体の処理を提供するクラス。

参照: Aime

このクラスのインスタンスをアプリ側で直接生成することはできない。 Aime クラスのメンバ関数 Aime::getUnit から取得すること。

一部の関数は処理完了まで呼び出し元スレッドをブロックする。

UID値読み取り手順

メンバ関数 start を、引数に AimeCommand::Scan を渡して呼び出す。
下記のいずれかの状態になるまで待機する。
- メンバ関数 hasConfirm が true を返す。
- メンバ関数 isBusy が false を返す。
メンバ関数 hasConfirm が true を返す場合はプレイヤーへの要確認事項がある。
- メンバ関数 getConfirm で内容を確認し、アプリ側で適切な確認表示を行う。
- プレイヤーが承諾した場合はメンバ関数 acceptConfirm を呼び出し、再び待機する。
- プレイヤーが拒否した場合はメンバ関数 cancel を呼び出し、処理を中断する。
メンバ関数 isBusy が false を返す場合は処理が完了している。
メンバ関数 hasError が true を返す場合はエラーが発生している。メンバ関数 getErrorInfo でエラー情報を取得し、アプリ側で適切に処理する。
メンバ関数 getResult で結果情報を得る。処理に成功していれば getResult().getAimeId() によってUID値を取得できる。

ポーリング処理途中の結果情報取得: メンバ関数 start 呼び出しによるポーリング処理途中であっても、内部フェーズの進行により下記のように情報が取得可能になる。

hasResult() == true である場合(即ち getResult().valid() == true である場合)、 getResult().isReaderDetected() の値は有効である。
getResult().getOfflineId().valid() == true である場合、 getResult().getOfflineId(), getResult().isMobile() の値は有効である。
getResult().getAccessCode().valid() == true である場合、 getResult().getAccessCode() の値は有効である。
getResult().getAimeId().valid() == true である場合、 getResult().getAimeId(), getResult().isPortalRegistered(), getResult().isSegaIdRegistered() の値は有効である。

: エラーが発生した場合も、エラー発生手前までの情報は取得可能である。

Daemonプロセス初期化時のAimeリーダー接続チェック

Daemonプロセスの初期化時、Aimeリーダーの接続チェックが自動的に開始される。
- 初期化時とは、Daemonプロセス起動時と、ゲームテストモード終了時を指す。ゲームテストモード状態の設定は Sequence クラスで行う。
接続チェックが完了すると hasResult() == true となり、 getResult().isReaderDetected() によってチェック結果を取得できる。
通常の初期化時は即座に接続チェックが開始されるが、 Aimeリーダーのファームウェア更新処理が必要な場合はそちらが優先され、ファームウェア更新処理が完了してから接続チェックが行われる。
- ファームウェア更新処理中であるか否かは Aime クラスのメンバ関数 Aime::isFirmUpdating で判別できる。

LED点灯処理

通常シーケンスでの明示的なLED点灯処理にはメンバ関数 setLedStatus を用いること。
ゲームテストモードでのLED点灯確認処理にはメンバ関数 setLed を用いること。
Daemonプロセスは下記のLED点灯処理を自動で行う。
- ポーリング処理によってAimeリーダーの接続が確認できた時、 setLedStatus(AimeLedStatus::Scanning) 相当のLED白点灯処理を行う。
- ポーリング処理中にエラーが発生し、そのエラーカテゴリが AimeErrorCategory::Warning である場合、 setLedStatus(AimeLedStatus::Error) 相当のLED赤点灯処理を行う。
上記以外のLED自動点灯処理は一切行わない。
- たとえ読み取りに成功した場合であっても、ゲーム固有サーバとの通信成否等によって点灯させるべきLED色が異なるため、自動化することができない。
基本的にはAime作成基準に準拠し、例えば下記のように実装すること。
- 次の場合は setLedStatus(AimeLedStatus::Success) を呼び出す。
  - 読み取り成功し、各種ネットワークサービスも正常に受けられる場合。
- 次の場合は setLedStatus(AimeLedStatus::Warning) を呼び出す。
  - 読み取り成功したが、一部ネットワークサービスを受けられない状態の場合。
  - 読み取り失敗したが、 AimeOfflineId を用いたオフラインプレイを行える場合。
- 次の場合は setLedStatus(AimeLedStatus::Error) を呼び出す。
  - 読み取り失敗し、黄点灯および自動赤点灯の条件を満たさない場合。
上記のLED点灯処理が完了してから続けてポーリング処理等を行いたい場合、メンバ関数 getLedStatus で現在のLED点灯ステータスを毎フレーム確認し、ステータスが AimeLedStatus::None に戻るまで待機すること。

構築子と解体子

amdaemon::AimeUnit::AimeUnit ( InnerIndexHolder )

explicit

コンストラクタ。

覚え書き: アプリ側からは利用できない。

関数詳解

bool amdaemon::AimeUnit::start ( AimeCommand command )

ポーリング処理を開始する。

引数

[in] command ポーリング処理コマンド。

戻り値

true	正常にポーリング開始できた場合。
false	ポーリング開始できなかった場合。

例外

Exception 引数 command に不正な値を指定した場合。

下記のいずれかを満たす場合、この関数は即座に false を返す。

既にポーリング処理中または中断処理中である場合。即ちメンバ関数 isBusy が true を返す場合。
ファームウェア更新処理中である場合。即ち Aime クラスのメンバ関数 Aime::isFirmUpdating が true を返す場合。

Daemonプロセスがポーリング開始するまで呼び出し元スレッドをブロックする。

正常にポーリング開始された場合、開始直後は下記のようになる。

メンバ関数 isBusy は true を返す。
メンバ関数 hasError は false を返す。
メンバ関数 hasResult は false を返す。

ポーリングが進むことでこれらのメンバ関数が返す値は変化する。詳細は各メンバ関数の説明を参照すること。

bool amdaemon::AimeUnit::cancel ( )

ポーリング処理の中断を開始する。

戻り値

true	正常に中断開始できた場合。
false	中断開始できなかった場合。

この関数は中断開始するのみであり、呼び出しただけでは中断完了しない。メンバ関数 isBusy が false を返すようになって初めて中断完了となる。

下記のいずれかを満たす場合、この関数は即座に false を返す。

ポーリング処理中ではない場合。即ちメンバ関数 isBusy が false を返す場合。
ファームウェア更新の実処理中である場合。即ち Aime クラスのメンバ関数 Aime::isFirmUpdating が true を返す場合。

中断開始済みかつ中断未完了の状態でこの関数を呼び出した場合、この関数は true を返すが、内部的には何も行われない。

Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。

bool amdaemon::AimeUnit::isBusy ( ) const

ポーリング処理中または中断処理中であるか否かを取得する。

戻り値

true	ポーリング処理中または中断処理中である場合。
false	ポーリング処理中でも中断処理中でもない場合。

ポーリング処理中であっても各メンバ関数が返す値は変化する場合がある。詳細は各メンバ関数の説明を参照すること。

AimeCommand amdaemon::AimeUnit::getBusyCommand ( ) const

ポーリング処理中または中断処理中の処理コマンドを取得する。

戻り値: ポーリング処理中または中断処理中の処理コマンド。

参照: isBusy

ポーリング処理中または中断処理中ではない場合、この関数は不定値を返す。

bool amdaemon::AimeUnit::hasConfirm ( ) const

inline

Aime登録に関する要確認事項が存在するか否かを取得する。

戻り値

true	要確認事項が存在する場合。
false	要確認事項が存在しない場合。

条件式 (getConfirm() != AimeConfirm::None) の結果を返す。

メンバ関数 start を AimeCommand::Scan を引数として呼び出した後、そのポーリング処理中にこの関数が true を返す場合がある。

リーダーにかざされたAimeがFeliCaDBやAimeDBに未登録である場合、それらのDBへ登録して構わないかプレイヤーに確認を取る必要がある。そういった要確認事項が発生した場合にこの関数が true を返す。

具体的な確認事項はメンバ関数 getConfirm で取得できる。

AimeConfirm amdaemon::AimeUnit::getConfirm ( ) const

Aime登録に関する要確認事項を取得する。

戻り値: Aime登録に関する要確認事項。存在しない場合は AimeConfirm::None 。

メンバ関数 hasConfirm が true を返す場合、この関数によって具体的な確認事項を取得し、アプリ側で適切な確認画面表示を行う。

その結果、確認事項が承諾された場合はメンバ関数 acceptConfirm を呼び出してポーリング処理を継続すること。拒否された場合はメンバ関数 cancel を呼び出してポーリング処理を中断すること。

bool amdaemon::AimeUnit::acceptConfirm ( )

Aime登録に関する要確認事項が承諾されたことを通知する。

戻り値

true	正常に通知できた場合。
false	通知できなかった場合。

メンバ関数 getConfirm によって取得できる要確認事項に対し、プレイヤーがその内容を承諾した場合にこの関数を呼び出すこと。この関数を呼び出すことでポーリング処理が継続される。

要確認事項が存在しない場合は即座に false を返す。

Daemonプロセスが通知を受理するまで呼び出し元スレッドをブロックする。

bool amdaemon::AimeUnit::hasResult ( ) const

inline

ポーリング処理の結果が存在するか否かを取得する。

戻り値

true	ポーリング処理の結果が存在する場合。
false	ポーリング処理の結果が存在しない場合。

getResult().valid() を返す。

ポーリング処理中であっても、途中経過として結果が設定される場合がある。そのため、この関数の戻り値でポーリング処理の完了判定を行ってはならない。ポーリング処理の完了判定はメンバ関数 isBusy で行うこと。

const AimeResult& amdaemon::AimeUnit::getResult ( ) const

inline

ポーリング処理の結果を取得する。

戻り値: ポーリング処理の結果。

メンバ関数 start 呼び出しによるポーリング処理中であっても、内部的なフェーズ完了ごとに情報が更新される。例えば AimeCommand::Scan を引数としてメンバ関数 start を呼び出した場合、下記のタイミングで情報が更新される。

Aimeリーダーの接続確認が完了した時。
オフラインID情報(アクセスコードまたはFeliCaID)の取得が完了した時。

メンバ関数 isBusy が false を返す場合、この関数も最終的な結果を返す。

また、ポーリング処理中にエラーが発生した場合や中断された場合であっても、成功済みの内部フェーズ分の情報は取得可能である。

bool amdaemon::AimeUnit::hasError ( ) const

inline

ポーリング処理中にエラーが発生したか否かを取得する。

戻り値

true	エラーが発生した場合。
false	エラーが発生していない場合。

getErrorInfo().isOccurred() を返す。

const AimeErrorInfo& amdaemon::AimeUnit::getErrorInfo ( ) const

inline

ポーリング処理中に発生したエラー情報を取得する。

戻り値: エラー情報。

AimeLedStatus amdaemon::AimeUnit::getLedStatus ( ) const

現在のLED点灯ステータスを取得する。

戻り値: 現在のLED点灯ステータス。

メンバ関数 setLedStatus で設定したか、もしくはDaemonプロセスが自動で設定したLED点灯ステータスを取得できる。

AimeLedStatus::Scanning 以外の点灯ステータスは、一定時間点灯後に自動で消灯して AimeLedStatus::None を返すようになる。そのため、LEDが自動消灯するまで待機するためにこの関数を利用することもできる。

bool amdaemon::AimeUnit::setLedStatus ( AimeLedStatus status )

LED点灯ステータスを設定する。

引数

[in] status 要求するLED点灯ステータス。

戻り値

true	正常に処理要求できた場合。
false	処理要求に失敗した場合。

例外

Exception 引数 status に不正な値を指定した場合。

LED点灯処理の詳細は、当クラスの説明およびAime作成基準を参照すること。

引数 status に AimeLedStatus::Scanning 以外の点灯ステータスを渡した場合、一定時間点灯後にDaemonプロセスが自動で消灯処理を行い、点灯ステータスを AimeLedStatus::None に移行させる。そのため明示的に消灯処理を行う必要はない。

ファームウェア更新処理中である場合、この関数は即座に false を返す。更新処理中であるか否かは Aime クラスのメンバ関数 Aime::isFirmUpdating で取得できる。

Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。

bool amdaemon::AimeUnit::setLed	(	bool	onR,
		bool	onG,
		bool	onB
	)

LEDの点灯状態をRGB別に設定する。

引数

[in]	onR	赤成分を点灯させるならば true 。
[in]	onG	緑成分を点灯させるならば true 。
[in]	onB	青成分を点灯させるならば true 。

戻り値

true	正常に点灯させることができた場合。
false	処理に失敗した場合。

覚え書き: ゲームテストモード用。

この関数はゲームテストモードでのLED点灯確認処理のために用意されている。通常シーケンスではこちらではなくメンバ関数 setLedStatus を用いること。

この関数が成功すると、LED点灯ステータスは AimeLedStatus::None となる。

ファームウェア更新処理中である場合、この関数は即座に false を返す。更新処理中であるか否かは Aime クラスのメンバ関数 Aime::isFirmUpdating で取得できる。

Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。

このクラス詳解は次のファイルから抽出されました:

AimeUnit.h

公開メンバ関数

詳解

構築子と解体子

関数詳解