電子マネーの各種操作を行うクラス。 [詳解]

#include <EMoneyOperation.h>

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

bool	isDealAvailable () const
	取引操作を利用可能な状態であるか否かを取得する。 [詳解]

bool	canOperateDeal () const
	取引操作を開始可能な状態であるか否かを取得する。 [詳解]

bool	isBusy () const
	いずれかの操作、あるいはそのキャンセルを実施中であるか否かを取得する。 [詳解]

bool	isCancellable () const
	実施中の操作をキャンセル可能な状態であるか否かを取得する。 [詳解]

bool	cancel ()
	実施中の操作のキャンセルを開始する。 [詳解]

bool	isHeldOver () const
	実施中の操作でカードリーダーへのかざし操作が1回以上行われたか否かを取得する。 [詳解]

bool	isErrorOccurred () const
	直近の操作を実施中にエラーが発生したか否かを取得する。 [詳解]

bool	hasResult () const
	直近の操作、あるいはそのキャンセルの結果が存在するか否かを取得する。 [詳解]

const EMoneyResult &	getResult () const
	直近の操作、あるいはそのキャンセルの結果を取得する。 [詳解]

bool	checkDisplay ()
	付属ディスプレイの表示チェックを開始する。 [詳解]

bool	authTerminal ()
	端末認証操作を開始する。 [詳解]

bool	removeTerminal ()
	端末撤去操作を開始する。 [詳解]

bool	requestBalance (EMoneyBrandId brandId)
	残高照会操作を開始する。 [詳解]

bool	payToCoin (std::size_t playerIndex, EMoneyBrandId brandId, std::uint32_t coin)
	コイン購入支払操作を開始する。 [詳解]

詳解

電子マネーの各種操作を行うクラス。

参照: EMoney

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

プラットフォーム情報

ALLSシリーズの電子マネー対応版SDKでのみ利用可能である。
上記以外の場合、常に操作不可として扱われる。

支払操作未了時の挙動: 通信不良等により支払操作が未了となった場合、ブランドによっては支払操作の再要求や残高照会要求が自動的に開始され、かざし待ち状態に移行する場合がある。

: その際、メンバ関数 isBusy は true を返し続けるため、アプリ側からは支払操作が継続しているように見える。プレイヤー向けの情報は付属ディスプレイに随時表示されるため、通常はアプリ側でこの状態をケアする必要はなく、支払操作継続中であることを示す画面表示にしてしまって問題ない。

: 支払操作開始によるかざし待ちと操作未了時の自動処理によるかざし待ちを区別したい場合、メンバ関数 isCancellable と isHeldOver を組み合わせることで判別できる。メンバ関数 isCancellable が true を返すならば何らかのかざし待ち状態であり、その際にメンバ関数 isHeldOver が false を返すならば支払操作開始によるかざし待ち、 true を返すならば操作未了時の自動処理によるかざし待ちとなる。 (ただしPASELIは現状この方法で判別することはできず、他の判別方法も無い。)

: 支払操作が未了となり、その後の自動処理もすべて失敗もしくはキャンセルされた場合、未了取引確認待ち状態に移行する。未了取引確認待ち状態については後述する。

未了取引確認待ち状態について: 下記をすべて満たすと、未了取引確認待ち状態へ遷移する。

通信不良等により、支払操作が未了となった。
支払操作が未了となった際、ブランドによっては支払操作の再要求や残高照会要求が自動的に開始される場合があるが、それが正常に完了しなかった。またはキャンセルした。

: 未了取引確認待ち状態へ遷移すると、付属ディスプレイには係員を呼び出して欲しい旨を伝えるメッセージが表示される。

: この状態はゲームテストモードを開始するまで解除されない。また、メンバ関数 isDealAvailable が false を返すようになり、メンバ関数 checkDisplay による付属ディスプレイ表示チェック以外の操作は開始できない。

操作実施中にゲームテストモードを開始した場合の挙動: 各種操作を実施中に Sequence クラスのメンバ関数 Sequence::beginTest によってゲームテストモードを開始した場合、次のように動作する。

操作がキャンセル可能な状態であれば、Daemonプロセスによって自動的にキャンセルされる。
- 自動キャンセルの挙動はメンバ関数 cancel を呼び出した場合と同様である。
操作がキャンセル不可な状態であれば、単にそのまま操作継続する。

: 操作継続となった場合、たとえゲームテストモード中であっても、 EMoney クラスのメンバ関数 EMoney::setSoundHook で設定したフック関数は呼び出される。ゲームアプリはゲームテストモード中であってもサウンド再生/停止処理を実施すること。

構築子と解体子

amdaemon::EMoneyOperation::EMoneyOperation ( InnerIndexHolder )

explicit

コンストラクタ。

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

関数詳解

bool amdaemon::EMoneyOperation::isDealAvailable ( ) const

取引操作を利用可能な状態であるか否かを取得する。

戻り値

true	利用可能な状態である場合。
false	操作が無効な状態である場合。

参照: canOperateDeal, requestBalance, payToCoin

下記をすべて満たす状態であれば true を返す。

第3世代以降のAimeリーダーユニット、および付属ディスプレイが接続されている。
端末売上管理システム上で端末IDと基板が紐付けられており、 "利用可" の状態である。
EMoney クラスのメンバ関数 EMoney::isServiceAlive が true を返す。
EMoney クラスのメンバ関数 EMoney::isAuthCompleted が true を返す。
EMoney クラスのメンバ関数 EMoney::getAvailableBrandCount が 1 以上を返す。
Error クラスのメンバ関数 Error::isOccurred が false を返す。
未了取引確認待ち状態ではない。未了取引確認待ち状態については EMoneyOperation クラスの説明を参照すること。

この関数が false を返す場合、メンバ関数 requestBalance および payToCoin による取引操作を行うことはできない。付属ディスプレイには取引が行えない旨が表示される。

この関数が true を返す場合であっても、他の操作を実施中の場合や締め処理中である場合は取引操作を開始できない。取引操作を開始可能か否か調べるにはメンバ関数 canOperateDeal を用いること。

メンバ関数 checkDisplay, authTerminal, removeTerminal については、この関数の返す値に関わらず利用可能である。

bool amdaemon::EMoneyOperation::canOperateDeal ( ) const

取引操作を開始可能な状態であるか否かを取得する。

戻り値

true	開始可能な状態である場合。
false	開始可能な状態ではない場合。

参照: requestBalance, payToCoin

下記をすべて満たす状態であれば true を返す。

メンバ関数 isDealAvailable が true を返す。
メンバ関数 isBusy が false を返す。
EMoney クラスのメンバ関数 EMoney::isReporting が false を返す。

この関数で開始可否を判断できるのは、メンバ関数 requestBalance および payToCoin のみである。メンバ関数 checkDisplay, authTerminal, removeTerminal については、各関数の説明を参照すること。

bool amdaemon::EMoneyOperation::isBusy ( ) const

いずれかの操作、あるいはそのキャンセルを実施中であるか否かを取得する。

戻り値

true	いずれかの操作、あるいはそのキャンセルを実施中である場合。
false	いずれの操作も実施していない場合。

この関数が true を返す場合、他の操作を開始することはできない。

bool amdaemon::EMoneyOperation::isCancellable ( ) const

実施中の操作をキャンセル可能な状態であるか否かを取得する。

戻り値

true	キャンセル可能な状態である場合。
false	キャンセルできない状態であるか、操作実施中ではない場合。

参照: cancel

操作を実施中であっても常にキャンセル可能なわけではない。具体的なキャンセル可能タイミングについては各操作関数の説明を参照すること。

bool amdaemon::EMoneyOperation::cancel ( )

実施中の操作のキャンセルを開始する。

戻り値

true	キャンセル開始に成功した場合。
false	キャンセル開始に失敗したか、キャンセルできない状態である場合。

参照: isCancellable

メンバ関数 isCancellable が false を返す状態の場合、この関数は何も行わずに false を返す。

この関数を呼び出しても即座にキャンセル完了となるわけではない。この関数の成功後にメンバ関数 isBusy が false を返すようになって初めてキャンセル完了となる。

キャンセル完了時、メンバ関数 getResult はキャンセル結果を返す。通常は成功となる。

操作を実施中であっても常にキャンセル可能なわけではない。具体的なキャンセル可能タイミングについては各操作関数の説明を参照すること。

bool amdaemon::EMoneyOperation::isHeldOver ( ) const

実施中の操作でカードリーダーへのかざし操作が1回以上行われたか否かを取得する。

戻り値

true	かざし操作が1回以上行われた場合。
false	かざし操作が行われていないか、操作中ではない場合。

端末認証、残高照会、支払の操作において、カードリーダーが認証用カードまたは電子マネーデバイスを一度でも認識すると、それ以降 true を返すようになる。一旦 true を返すようになると、操作が完了してメンバ関数 isBusy が false を返すようになるまで、この関数の戻り値は true のままとなる。

通常ではかざし操作は一度しか行わないが、通信不良等により支払操作が未了となると、ブランドによっては支払操作の再要求や残高照会要求が自動的に開始され、再度かざし待ち状態となる場合がある。その場合であっても、この関数の返す値が false に戻ることはない。

対象外の操作(端末撤去等)が行われている場合、この関数の返す値は不定値となる。

bool amdaemon::EMoneyOperation::isErrorOccurred ( ) const

直近の操作を実施中にエラーが発生したか否かを取得する。

戻り値

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

いずれかの操作を開始すると、過去のエラー情報を破棄して false を返すようになる。操作内容は問わない。(操作結果を返さないものを含む)

操作の実施中にエラーが発生すると true を返すようになる。

bool amdaemon::EMoneyOperation::hasResult ( ) const

inline

直近の操作、あるいはそのキャンセルの結果が存在するか否かを取得する。

戻り値

true	直近の操作、あるいはそのキャンセルの結果が存在する場合。
false	結果が存在しない場合。

getResult().valid() を返す。

const EMoneyResult& amdaemon::EMoneyOperation::getResult ( ) const

inline

直近の操作、あるいはそのキャンセルの結果を取得する。

戻り値: 直近の操作、あるいはそのキャンセルの結果。まだ一度も操作開始していない場合は無効値。

いずれかの操作を開始すると、過去の操作結果を破棄して無効値を返すようになる。操作内容は問わない。(操作結果を返さないものを含む)

操作が完了するか、もしくはキャンセルされると、その結果を返すようになる。ただし、操作内容が残高照会でも支払でもない場合は操作結果を返さない。

操作が成功した場合とエラーが発生した場合とでは設定内容が異なる。 EMoneyResult クラスの説明を参照すること。

bool amdaemon::EMoneyOperation::checkDisplay ( )

付属ディスプレイの表示チェックを開始する。

戻り値

true	操作開始に成功した場合。
false	操作開始に失敗した場合。

メンバ関数 isBusy が true を返す状態である場合、この関数は何も行わずに false を返す。

この操作がエラー情報を返すことはない。実際に問題があるか否かは付属ディスプレイの表示状態による。

キャンセル可能タイミング: 常にキャンセル可能である。

bool amdaemon::EMoneyOperation::authTerminal ( )

端末認証操作を開始する。

戻り値

true	操作開始に成功した場合。
false	操作開始に失敗した場合。

下記のいずれかの状態である場合、この関数は何も行わずに false を返す。

メンバ関数 isBusy が true を返す。
EMoney クラスのメンバ関数 EMoney::isReporting が true を返す。

操作開始に成功した場合であっても、サービスサーバが生存していない等の理由で操作に失敗する可能性があるため、操作完了後は必ずメンバ関数 isErrorOccurred によってエラーの有無を確認すること。

アプリでは、ゲームテストモードに端末認証用の画面を用意し、オペレータの画面操作によってこの操作を開始すること。なお、操作を完了させるためには認証用カードをカードリーダーにかざす必要がある。

認証済みの端末であっても、利用可能な電子マネーを追加する際には再度この操作を実施する必要があるため、認証済みか否かに関わらず上記画面に遷移できるようにすること。

キャンセル可能タイミング

操作開始から認証用カードをかざすまでの間はキャンセル可能である。
カードリーダーが認証用カードを認識すると、それ以降はキャンセル不可となる。

: 現在キャンセル可能であるか否かはメンバ関数 isCancellable によって判別すること。

bool amdaemon::EMoneyOperation::removeTerminal ( )

端末撤去操作を開始する。

戻り値

true	操作開始に成功した場合。
false	操作開始に失敗した場合。

下記のいずれかの状態である場合、この関数は何も行わずに false を返す。

メンバ関数 isBusy が true を返す。
EMoney クラスのメンバ関数 EMoney::isReporting が true を返す。

操作開始に成功した場合であっても、サービスサーバが生存していない等の理由で操作に失敗する可能性があるため、操作完了後は必ずメンバ関数 isErrorOccurred によってエラーの有無を確認すること。

アプリでは、ゲームテストモードに端末撤去用の画面を用意し、オペレータの画面操作によってこの操作を開始すること。

キャンセル可能タイミング: 常にキャンセル不可である。

bool amdaemon::EMoneyOperation::requestBalance ( EMoneyBrandId brandId )

残高照会操作を開始する。

引数

[in] brandId ブランドID。

戻り値

true	操作開始に成功した場合。
false	操作開始に失敗した場合。

例外

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

メンバ関数 canOperateDeal が false を返す場合や、引数 brandId に指定したブランドが有効ではない場合、この関数は何も行わずに false を返す。

キャンセル可能タイミング

操作開始から電子マネーデバイスをかざすまでの間はキャンセル可能である。
カードリーダーが電子マネーデバイスを認識すると、それ以降はキャンセル不可となる。

: 現在キャンセル可能であるか否かはメンバ関数 isCancellable によって判別すること。

bool amdaemon::EMoneyOperation::payToCoin	(	std::size_t	playerIndex,
		EMoneyBrandId	brandId,
		std::uint32_t	coin
	)

コイン購入支払操作を開始する。

引数

[in]	playerIndex	プレイヤーインデックス。
[in]	brandId	ブランドID。
[in]	coin	購入するコイン数。

戻り値

true	操作開始に成功した場合。
false	操作開始に失敗した場合。

例外

Exception

引数 playerIndex に有効プレイヤー数以上の値を指定した場合。有効プレイヤー数は Core クラスのメンバ関数 Core::getPlayerCount で取得できる。
引数 brandId に不正な値を指定した場合。
引数 coin に 0 もしくは 99 より大きい値を指定した場合。

電子マネーを支払い、コインを購入する。購入したコイン数などの情報はブックキーピングに記録される。

1コインあたりの金額はクレジット設定により決定される。 Credit クラスのメンバ関数 Credit::getConfig から取得したクレジット設定の CreditConfig::coinAmount メンバを参照する事。

下記の場合、この関数は何も行わずに false を返す。

メンバ関数 canOperateDeal が false を返す場合。
引数 brandId に指定したブランドが有効ではない場合。
現在ゲームテストモード中である場合。ゲームテストモード状態の管理は Sequence クラスで行える。

また、下記の場合はプロセス側で操作開始に失敗して false を返す。

クレジット機能が無効である場合。
コインを購入することで MAX CREDIT 値を超える場合。

MAX CREDIT 値を超えずに購入可能なコイン数は、 CreditUnit クラスのメンバ関数 CreditUnit::getAddableCoin によって取得できる。

// 購入可能なコイン数を事前チェックしてから payToCoin を呼び出すサンプル。
bool buyCoin(std::size_t playerIndex, EMoneyBrandId brandId, std::uint32_t coin)
{
    amdaemon::Credit credit;
    amdaemon::EMoney eMoney;
    // (追加可能なコイン数 < 購入予定コイン数) なら購入不可
    if (credit.getPlayer(playerIndex).getAddableCoin() < coin)
    {
        return false;
    }
    return eMoney.getOperation().payToCoin(playerIndex, brandId, coin);
}

キャンセル可能タイミング

操作開始から電子マネーデバイスをかざすまでの間はキャンセル可能である。
カードリーダーが電子マネーデバイスを認識すると、それ以降はキャンセル不可となる。
支払操作が未了となった場合は再びキャンセル可能となる場合がある。詳細は EMoneyOperation クラスの説明を参照すること。

: 現在キャンセル可能であるか否かはメンバ関数 isCancellable によって判別すること。

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

EMoneyOperation.h

公開メンバ関数

詳解

構築子と解体子

関数詳解