EMoneySound.h

[詳解]

/// @file
/// @brief 電子マネーのサウンド情報を提供するクラス EMoneySound のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_EMONEYSOUND_H
#define AMDAEMON_EMONEYSOUND_H

#include "amdaemon/env.h"

#include <memory>

namespace amdaemon
{
/// @addtogroup g_emoney
/// @{

    // 内部クラスの前方宣言
    class InnerIndexHolder;

    /// @brief 電子マネーのサウンド情報を提供するクラス。
    /// @see EMoney, EMoney#setSoundHook
    ///
    /// EMoney クラスのメンバ関数 EMoney#setSoundHook に設定したコールバックへ受け渡される。
    ///
    /// @par サウンド再生について
    /// 一般業務用の電子マネー対応アプリでは、
    /// メンバ関数 #getFilePath が返すWAVEファイルパスを用いてサウンド再生を行うが、
    /// この方法はゲーム用途にはそぐわない場合が多い。
    /// @par
    /// そこで、メンバ関数 #getId などの情報を用いて、
    /// ゲームアプリにとって最適な手段でサウンド再生を行っても構わない。
    /// 当然ながら、再生されるサウンドは本来のWAVEファイルと同等のものにすること。
    /// @par
    /// いずれの場合でも、メンバ関数 #isStopRequired が true を返す場合は、
    /// 再生中の電子マネー関連サウンドの停止処理を行うこと。
    class EMoneySound
    {
    public:
        /// @brief コンストラクタ。
        /// @param[in] stopRequired 停止処理要求フラグ。
        /// @param[in] filePath
        ///     サウンドWAVEファイルパス。 stopRequired が true ならば無視される。
        EMoneySound(bool stopRequired, const wchar_t* filePath);

        /// @brief コピーコンストラクタ。
        /// @param[in] src コピー元。
        EMoneySound(const EMoneySound& src);

        /// @brief ムーブコンストラクタ。
        /// @param[in] src ムーブ元。
        EMoneySound(EMoneySound&& src);

        /// デストラクタ。
        ‾EMoneySound();

        /// @brief コピー代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        EMoneySound& operator=(const EMoneySound& r);

        /// @brief ムーブ代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        EMoneySound& operator=(EMoneySound&& r);

        /// @brief サウンド停止処理要求であるか否かを取得する。
        /// @retval true  サウンド停止処理要求である場合。
        /// @retval false サウンド再生処理要求である場合。
        ///
        /// この関数が true を返す場合、電子マネー関連サウンドの停止処理を行うこと。
        /// 既に停止済みである場合は何も行わなくてよい。
        ///
        /// この関数が true を返す場合、メンバ関数 #getId および #getFilePath は nullptr を返す。
        bool isStopRequired() const
        {
            return (this->getFilePath() == nullptr);
        }

        /// @brief サウンドIDを取得する。
        /// @return サウンドID。停止処理要求の場合は nullptr 。
        ///
        /// サウンドWAVEファイルパスのファイル名部分を抜き出した文字列を返す。
        /// ただし停止指示の場合は nullptr を返す。
        ///
        /// 例えば "0001-02-00" といった文字列になる。
        /// ゲームアプリで再生するサウンドを決定するためのキーとして利用できる。
        ///
        /// この関数の返す文字列にはファイル拡張子は含まれない。
        /// 拡張子を含めたファイル名を取得したい場合は、 #getFilePath の戻り値に対して
        /// util::Path クラスの静的メンバ関数 util::Path::getName を用いて抜き出すとよい。
        const wchar_t* getId() const;

        /// @brief サウンドWAVEファイルパスを取得する。
        /// @return サウンドWAVEファイルパス。停止処理要求の場合は nullptr 。
        ///
        /// 設定ファイルで指定したリソースディレクトリ以下にある、
        /// サウンドWAVEファイルの絶対パスを返す。
        /// ただし停止指示の場合は nullptr を返す。
        ///
        /// サウンド再生については EMoneySound クラスの説明を参照すること。
        ///
        /// ファイル名のみ利用したい場合、 util::Path クラスの静的メンバ関数
        /// util::Path::getName を用いるとよい。
        const wchar_t* getFilePath() const;

    private:
        struct Data;

        /// 内部データ。
        std::unique_ptr<Data> _data;
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_EMONEYSOUND_H