WiFi.h

[詳解]

/// @file
/// @brief ALL.Net Wi-Fi 情報を提供するMonostateクラス WiFi のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ALLNET_WIFI_H
#define AMDAEMON_ALLNET_WIFI_H

#include "amdaemon/env.h"
#include "amdaemon/allnet/WiFiUnit.h"
#include "amdaemon/allnet/WiFiDef.h"
#include "amdaemon/util/container.h"

#include <functional>
#include <vector>
#include <cstddef>

namespace amdaemon
{
namespace allnet
{
/// @addtogroup g_allnet
/// @{

    /// @brief ALL.Net Wi-Fi 情報を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// @par ゲームテストモードでのルータ情報表示
    /// このクラスは主にゲームテストモードでの ALL.Net Wi-Fi ルータ情報表示に用いるが、
    /// 最新値をそのまま表示しようとすると、表示処理中にメンバ関数 #getUnitCount や
    /// #getUnit の返す値が変化する可能性があり、処理が煩雑になる。
    /// @par
    /// そのため、ルータ情報を表示開始するタイミング(表示画面に入った時)でメンバ関数
    /// #saveUnitCache を呼び出し、キャッシュされた情報を表示するようにすることを推奨する。
    /// @par
    /// メンバ関数 #saveUnitCache を呼び出すと、
    /// メンバ関数 #getUnitCount や #getUnit の返す値が最新値ではなくキャッシュされた値となり、
    /// 表示処理中に値が変化する可能性を考慮する必要がなくなる。
    /// @par
    /// 表示を完了したタイミング(表示画面を抜けた時)では、メンバ関数
    /// #clearUnitCache を呼び出すことでキャッシュが破棄され再び最新値を取得可能になる。
    /// ただし最新値が不要であればこの呼び出しは行わなくともよい。
    ///
    /// @ingroup g_common
    class WiFi
    {
    public:
        // 下記は暗黙の定義を用いる。
        //WiFi() = default;
        //WiFi(const WiFi&) = default;
        //‾WiFi() = default;
        //WiFi& operator=(const WiFi&) = default;

        /// @brief ALL.Net Wi-Fi 機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        ///
        /// Daemonプロセスの設定ファイルで ALL.Net Wi-Fi 設定を有効にしている場合であっても、
        /// キーチップのALL.Net認証フラグが無効である場合は false を返す。
        bool isAvailable() const;

        /// @brief ALL.Net Wi-Fi ルータ情報の有効数を取得する。
        /// @return ALL.Net Wi-Fi ルータ情報の有効数。機能が無効である場合は 0 。
        /// @see #saveUnitCache, #clearUnitCache
        ///
        /// 仕様上、正常に応答しているルータだけしか存在を確認できないため、
        /// この関数の返す値は変化する可能性がある。 0 にもなりうる。
        ///
        /// ゲームテストモードでの情報表示に用いる場合、
        /// 表示処理中に有効数が変化すると不都合があるため、
        /// メンバ関数 #saveUnitCache によってキャッシュされた値を用いるようにするとよい。
        ///
        /// 詳しくは WiFi クラスの説明を参照すること。
        std::size_t getUnitCount() const;

        /// @brief ALL.Net Wi-Fi ルータ情報を取得する。
        /// @param[in] unitIndex 情報インデックス。
        /// @return ALL.Net Wi-Fi ルータ情報。
        /// @see #saveUnitCache, #clearUnitCache
        ///
        /// @exception Exception
        /// 引数 unitIndex に MaxWiFiUnitCount 以上の値を指定した場合。
        ///
        /// メンバ関数 #getUnitCount で取得できる有効数以上の値を引数 unitIndex に指定した場合、
        /// この関数は無効なルータ情報を返す。他クラスの類似関数とは異なり、例外は送出しない。
        ///
        /// この関数の返す情報は、ルータから定期的に送信される内容によって変化する。
        ///
        /// ゲームテストモードでの情報表示に用いる場合、
        /// 表示処理中に内容が変化すると不都合があるため、
        /// メンバ関数 #saveUnitCache によってキャッシュされた値を用いるようにするとよい。
        ///
        /// キャッシュに関して詳しくは WiFi クラスの説明を参照すること。
        const WiFiUnit& getUnit(std::size_t unitIndex) const;

        /// @brief ALL.Net Wi-Fi ルータ情報配列を取得する。
        /// @return ALL.Net Wi-Fi ルータ情報配列。
        /// @see #saveUnitCache, #clearUnitCache
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - ルータ情報の有効数を知りたいだけならばメンバ関数 #getUnitCount を用いること。
        /// - 特定のルータ情報を取得したいだけならばメンバ関数 #getUnit を用いること。
        std::vector<std::reference_wrapper<const WiFiUnit>> getUnits() const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getUnits())>(
                    this->getUnitCount(),
                    [this](std::size_t i) -> const WiFiUnit& { return this->getUnit(i); });
        }

        /// @brief ALL.Net Wi-Fi ルータ情報の現在値をキャッシュする。
        /// @see #getUnitCount, #getUnit, #getUnits
        ///
        /// この関数を呼び出した時点での ALL.Net Wi-Fi ルータ情報の最新値を内部でキャッシュする。
        ///
        /// 以降のメンバ関数 #getUnitCount, #getUnit, #getUnits 呼び出しにおいては、
        /// 最新値ではなくキャッシュされた値が返るようになる。
        /// もう一度この関数を呼び出すか、メンバ関数 #clearUnitCache を呼び出すまで、
        /// キャッシュされた値が変化することはない。
        ///
        /// 既にキャッシュされた情報が存在する状態でこの関数を呼び出した場合、
        /// 呼び出した時点での最新値で上書きキャッシュする。
        ///
        /// この関数は主にゲームテストモードでの情報表示のために用いる。
        /// 詳しくは WiFi クラスの説明を参照すること。
        void saveUnitCache();

        /// @brief ALL.Net Wi-Fi ルータ情報のキャッシュを破棄する。
        /// @see #getUnitCount, #getUnit, #getUnits
        ///
        /// メンバ関数 #saveUnitCache によって内部にキャッシュされた情報を破棄する。
        /// キャッシュされた情報が無い場合は何もしない。
        ///
        /// この関数を呼び出すと、以降のメンバ関数 #getUnitCount, #getUnit, #getUnits
        /// 呼び出しでは最新値が返るようになる。
        void clearUnitCache();

        /// @brief ALL.Net Wi-Fi ルータ情報がキャッシュされているか否かを取得する。
        /// @retval true  キャッシュされている場合。
        /// @retval false キャッシュされていない場合。(既定値)
        ///
        /// この関数は、メンバ関数 #saveUnitCache を呼び出すと true を返すようになる。
        /// その後はメンバ関数 #clearUnitCache が呼び出されるまで true を返し続ける。
        bool isUnitCacheSaved() const;
    };

/// @}
} // namespace allnet
} // namespace amdaemon

#endif // AMDAEMON_ALLNET_WIFI_H