/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     friends_Api.h

  Copyright 2009 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: 32714 $
 *---------------------------------------------------------------------------*/

#ifndef NN_FRIENDS_CTR_FRIENDS_API_H_
#define NN_FRIENDS_CTR_FRIENDS_API_H_

/*! @file
    @brief      フレンド・プレゼンス機能に関する API の宣言
*/

#include <nn/types.h>

#include <nn/friends/friends_Result.h>
#include <nn/friends/CTR/friends_Types.h>

#include <nn/uds/CTR/uds_Type.h>

#ifdef __cplusplus

namespace nn {
namespace friends {
namespace CTR {

    namespace detail
    {
        // ライブラリの初期化・終了
        Result Initialize();
        Result Finalize();

        // ライブラリ状態確認
        bool IsInitialized();
        bool HasLoggedIn();

        // 接続管理
        Result Login( os::Event* pEvent );
        Result Logout();

        // 自分情報取得（ローカル）
        PrincipalId     GetMyPrincipalId();
        Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame );
        Result GetMyProfile( Profile* pProfile );
        Result GetMyPresence( MyPresence* pMyPresence );
        Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] );
        Result GetMyMii( MiiData* pMiiData );

        // 友達情報取得
        Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset, size_t size );
        Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size );
        Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size );
        Result GetFriendScreenName( char16 (*pScreenNameList)[SCREEN_NAME_SIZE], const FriendKey* pFriendKeyList, size_t size, bool replaceForeignCharacters, u8* pFontRegionList );
        Result GetFriendScreenName( char16 (*pScreenNameList)[SCREEN_NAME_SIZE], const PrincipalId* pPrincipalIdList, size_t size, bool replaceForeignCharacters, u8* pFontRegionList );
        Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size );
        Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size );
        Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size );
        Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size );
        Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size );
        Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size );
        Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size );

        // 自分情報更新
        Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] );

        // 通知内容取得
        Result AttachToEventNotification( nn::os::Event* pEvent );
        Result SetNotificationMask( bit32 mask );
        u32 GetEventNotification( EventNotification* pEventNotificationList, size_t size, bool* pHasOverflowed );
        Result GetLastResponseResult();

        // エラーコード取得
        u32 ResultToErrorCode( const Result& result );
    }

    namespace
    {
        static const char PORT_NAME_USER[]  = "frd:u";
    }

    /*-------------------------------------------------------------------
    ライブラリの初期化/終了
    -------------------------------------------------------------------*/

    /*!
    @brief          フレンド・プレゼンスライブラリの初期化を行い、プレゼンス機能を使用可能な状態にします。

    @return         処理の結果が返ってきます。<BR>
    */
    Result Initialize();
    inline Result Initialize()
    {
        return detail::Initialize();
    }

    /*!
    @brief          フレンド・プレゼンスライブラリを終了します。

                    複数回 @ref nn::friends::CTR::Initialize 関数を呼んだ場合、この関数も同じ回数呼ぶ必要があります。

    @return         処理の結果が返ってきます。<BR>
    */
    Result Finalize();
    inline Result Finalize()
    {
        return detail::Finalize();
    }

    /*!
    @brief          フレンド・プレゼンスライブラリが初期化済みか否かを確認します。

    @return         フレンド・プレゼンスライブラリが初期化済みであれば true 、未初期化であれば false が返ってきます。
    */
    bool IsInitialized();
    inline bool IsInitialized()
    {
        return detail::IsInitialized();
    }

    /*!
    @brief          自分のログイン状態を確認します。

                    自分が @ref nn::friends::CTR::Login 関数を呼んだ上でオンライン状態になっているかを確認します。

    @return         自分がログイン中であれば true 、ログインしていなければ false が返ってきます。
                    この関数の結果が true であれば必ずオンライン状態ですが、結果が false であってもオフライン状態とは限りません。
    */
    bool HasLoggedIn();
    inline bool HasLoggedIn()
    {
        return detail::HasLoggedIn();
    }

    /*!
    @brief          サーバへのログインを要求します。

                    この関数が成功で返った場合は非同期処理が発生し、非同期処理が完了した時点で引数に指定した @ref nn::os::Event がシグナルされます。
                    非同期処理の結果は @ref nn::friends::CTR::GetLastResponseResult で取得できます。
                    この関数が失敗で返った場合は、非同期処理が発生することはありません。<BR>
                    <BR>
                    この関数を呼ぶには、事前に @ref nn::ac::Connect 関数を呼んで AP との接続を確立しておく必要があります。
                    AP との接続を確立せずに呼んだ場合は @ref nn::friends::ResultAcNotConnected を返します。<BR>
                    <BR>
                    バックグラウンドでサーバからの切断処理が走っていた場合、この関数は一時的に @ref nn::friends::ResultTemporarilyBusy を返します。
                    その場合は比較的短時間が経過した後に再試行することで成功する可能性があります。<BR>
                    <BR>
                    すでにログインしている状態でコールしても成功します。その場合、非同期処理は瞬時に成功で完了します。<BR>
                    <BR>
                    非同期処理が成功した場合、必ずオンライン状態になります。

    @param[in]      pEvent  非同期処理の完了を通知する @ref nn::os::Event へのポインタを指定します。事前に @ref nn::os::Event::Initialize で初期化しておいてください。

    @return         処理の結果が返ってきます。
    */
    Result Login( os::Event* pEvent );
    inline Result Login( os::Event* pEvent )
    {
        return detail::Login( pEvent );
    }

    /*!
    @brief          サーバへのログイン要求を撤回します。

                    すでにログアウトしている状態でコールしても成功します。<BR>
                    <BR>
                    この関数が成功しても、オフライン状態であることは保証されません。<BR>
                    <BR>
                    何らかの要因によりサーバとの接続が切断された場合、この関数をコール済みの状態へ暗黙的に遷移します。

    @return         処理の結果が返ってきます。
    */
    Result Logout();
    inline Result Logout()
    {
        return detail::Logout();
    }

    /*!
    @brief          自分のプリンシパル ID を取得します。

    @return         自分のプリンシパル ID が返ってきます。<BR>
                    <BR>
                    ライブラリが未初期化であったり、まだ一度もサーバに接続したことがないと @ref nn::friends::CTR::INVALID_PRINCIPAL_ID が返ってきます。
    */
    PrincipalId GetMyPrincipalId();
    inline PrincipalId GetMyPrincipalId()
    {
        return detail::GetMyPrincipalId();
    }

    /*!
    @brief          自分の情報の公開レベルを取得します。

    @param[out]     pIsPublicMode        公開モードを格納するバッファへのポインタを指定します。
    @param[out]     pIsShowGameName      遊んでいるゲームを公開するかを格納するバッファへのポインタを指定します。
    @param[out]     pIsShowPlayedGame    ゲーム履歴を公開するかを格納するバッファへのポインタを指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame );
    inline Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame )
    {
        return detail::GetMyPreference( pIsPublicMode, pIsShowGameName, pIsShowPlayedGame );
    }

    /*!
    @brief          自分のプロフィール情報を取得します。

    @param[out]     pProfile    自分のプロフィール情報を格納する構造体へのポインタを指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetMyProfile( Profile* pProfile );
    inline Result GetMyProfile( Profile* pProfile )
    {
        return detail::GetMyProfile( pProfile );
    }

    /*!
    @brief          自分のプレゼンス情報を取得します。

    @param[out]     pMyPresence     自分のプレゼンス情報を格納する構造体へのポインタを指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetMyPresence( MyPresence* pMyPresence );
    inline Result GetMyPresence( MyPresence* pMyPresence )
    {
        return detail::GetMyPresence( pMyPresence );
    }

    /*!
    @brief          自分の表示名を取得します。

    @param[out]     screenName  自分の表示名を格納するバッファを指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] );
    inline Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] )
    {
        return detail::GetMyScreenName( screenName );
    }

    /*!
    @brief          自分の Mii データを取得します。

                    「Mii スタジオ」で「じぶんの Mii」を設定していない場合、空の Mii データが取得されます。<BR>
                    <BR>
                    取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。

    @param[out]     pMiiData  自分の Mii データを格納する構造体へのポインタを指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetMyMii( MiiData* pMiiData );
    inline Result GetMyMii( MiiData* pMiiData )
    {
        return detail::GetMyMii( pMiiData );
    }

    /*!
    @brief          フレンドリストに登録されたフレンドキーのリストを取得します。

                    取得されるフレンドキーには、まだフレンド関係が成立していないものも含まれます。

    @param[out]     pFriendKeyList  取得したフレンドキーを格納するバッファへのポインタを指定します。
    @param[out]     pNum            実際に取得された数を格納するバッファへのポインタを指定します。
    @param[in]      offset          取得を開始するフレンドキーのインデックスを指定します。
    @param[in]      size            取得するフレンドキーの最大数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset = 0, size_t size = FRIEND_LIST_SIZE );
    inline Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset, size_t size)
    {
        return detail::GetFriendKeyList( pFriendKeyList, pNum, offset, size );
    }

    /*!
    @brief          フレンドプレゼンスのリストを取得します。

                    自分と異なる合流ゲーム ID を指定したフレンドのゲームモードとお誘いフラグは取得できません。<BR>
                    <BR>
                    引数で与えられたキーに対応するフレンドが存在しないと、空のプレゼンスが返されます。

    @param[out]     pFriendPresenceList     取得したフレンドプレゼンスを格納するバッファへのポインタを指定します。
    @param[in]      pFriendKeyList          フレンドキーのリストへのポインタを指定します。
    @param[in]      size                    フレンドキーのリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size = 1 );
    inline Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size)
    {
        return detail::GetFriendPresence( pFriendPresenceList, pFriendKeyList, size );
    }

    /*!
    @brief          フレンドプレゼンスのリストを取得します。

                    自分と異なる合流ゲーム ID を指定したフレンドのゲームモードとお誘いフラグは取得できません。<BR>
                    <BR>
                    引数で与えられたキーに対応するフレンドが存在しないと、空のプレゼンスが返されます。

    @param[out]     pFriendPresenceList     取得したフレンドプレゼンスを格納するバッファへのポインタを指定します。
    @param[in]      pPrincipalIdList        プリンシパル ID のリストへのポインタを指定します。
    @param[in]      size                    プリンシパル ID のリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size = 1 );
    inline Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size)
    {
        return detail::GetFriendPresence( pFriendPresenceList, pPrincipalIdList, size );
    }

    /*!
    @brief          フレンドの表示名のリストを取得します。

                    この関数を使用すると、「似顔絵ライブラリ」を使用せずにフレンドの Mii の名前を直接取得することができます。
                    また、対象がフレンド関係成立待ち状態で Mii が取得できない場合でも、自分が仮登録した表示名が取得されます。<BR>
                    <BR>
                    フレンドの Mii がブラックリストに含まれていた場合でも生の名前が取得されますが、
                    フレンドの Mii の名前が NG ネームだった場合は ??? に置換されて取得されます。<BR>
                    <BR>
                    引数で与えられたキーに対応するフレンドが存在しないと、空の表示名が返されます。

    @param[out]     pScreenNameList             取得した表示名を格納するバッファへのポインタを指定します。
    @param[in]      pFriendKeyList              フレンドキーのリストへのポインタを指定します。
    @param[in]      size                        フレンドキーのリストの要素数（バッファの要素数）を指定します。
    @param[in]      replaceForeignCharacters    フレンドの表示名のフォントリージョンが自分と異なる場合に、 ASCII 以外の文字を ? で置換するかを指定します。
    @param[in]      pFontRegionList             フレンドの表示名のフォントリージョンを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendScreenName(
        char16           (*pScreenNameList)[SCREEN_NAME_SIZE],
        const FriendKey* pFriendKeyList,
        size_t           size = 1,
        bool             replaceForeignCharacters = true,
        u8*              pFontRegionList = NULL
    );
    inline Result GetFriendScreenName(
        char16           (*pScreenNameList)[SCREEN_NAME_SIZE],
        const FriendKey* pFriendKeyList,
        size_t           size,
        bool             replaceForeignCharacters,
        u8*              pFontRegionList
    )
    {
        return detail::GetFriendScreenName( pScreenNameList, pFriendKeyList, size, replaceForeignCharacters, pFontRegionList );
    }

    /*!
    @brief          フレンドの表示名のリストを取得します。

                    この関数を使用すると、「似顔絵ライブラリ」を使用せずにフレンドの Mii の名前を直接取得することができます。
                    また、対象がフレンド関係成立待ち状態で Mii が取得できない場合でも、自分が仮登録した表示名が取得されます。<BR>
                    <BR>
                    フレンドの Mii がブラックリストに含まれていた場合でも生の名前が取得されますが、
                    フレンドの Mii の名前が NG ネームだった場合は ??? に置換されて取得されます。<BR>
                    <BR>
                    引数で与えられたキーに対応するフレンドが存在しないと、空の表示名が返されます。

    @param[out]     pScreenNameList             取得した表示名を格納するバッファへのポインタを指定します。
    @param[in]      pPrincipalIdList            プリンシパル ID のリストへのポインタを指定します。
    @param[in]      size                        プリンシパル ID のリストの要素数（バッファの要素数）を指定します。
    @param[in]      replaceForeignCharacters    フレンドの表示名のフォントリージョンが自分と異なる場合に、 ASCII 以外の文字を ? で置換するかを指定します。
    @param[in]      pFontRegionList             フレンドの表示名のフォントリージョンを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendScreenName(
        char16             (*pScreenNameList)[SCREEN_NAME_SIZE],
        const PrincipalId* pPrincipalIdList,
        size_t             size = 1,
        bool               replaceForeignCharacters = true,
        u8*                pFontRegionList = NULL
    );
    inline Result GetFriendScreenName(
        char16             (*pScreenNameList)[SCREEN_NAME_SIZE],
        const PrincipalId* pPrincipalIdList,
        size_t             size,
        bool               replaceForeignCharacters,
        u8*                pFontRegionList
    )
    {
        return detail::GetFriendScreenName( pScreenNameList, pPrincipalIdList, size, replaceForeignCharacters, pFontRegionList );
    }

    /*!
    @brief          フレンドの Mii データのリストを取得します。

                    引数で与えられたキーに対応するフレンドが存在しないと、空の Mii データが返されます。<BR>
                    <BR>
                    取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。

    @param[out]     pMiiDataList    取得した Mii データを格納するバッファへのポインタを指定します。
    @param[in]      pFriendKeyList  フレンドキーのリストへのポインタを指定します。
    @param[in]      size            フレンドキーのリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size = 1 );
    inline Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size)
    {
        return detail::GetFriendMii( pMiiDataList, pFriendKeyList, size );
    }

    /*!
    @brief          フレンドの Mii データのリストを取得します。

                    引数で与えられたキーに対応するフレンドが存在しないと、空の Mii データが返されます。<BR>
                    <BR>
                    取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。

    @param[out]     pMiiDataList        取得した Mii データを格納するバッファへのポインタを指定します。
    @param[in]      pPrincipalIdList    プリンシパル ID のリストへのポインタを指定します。
    @param[in]      size                プリンシパル ID のリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size = 1);
    inline Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size)
    {
        return detail::GetFriendMii( pMiiDataList, pPrincipalIdList, size );
    }

    /*!
    @brief          フレンドのプロフィール情報のリストを取得します。

                    引数で与えられたキーに対応するフレンドが存在しないと、空のプロフィール情報が返されます。

    @param[out]     pProfileList    取得したプロフィール情報を格納するバッファへのポインタを指定します。
    @param[in]      pFriendKeyList  フレンドキーのリストへのポインタを指定します。
    @param[in]      size            フレンドキーのリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size = 1 );
    inline Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size)
    {
        return detail::GetFriendProfile( pProfileList, pFriendKeyList, size );
    }

    /*!
    @brief          フレンドのプロフィール情報のリストを取得します。

                    引数で与えられたキーに対応するフレンドが存在しないと、空のプロフィール情報が返されます。

    @param[out]     pProfileList        取得したプロフィール情報を格納するバッファへのポインタを指定します。
    @param[in]      pPrincipalIdList    プリンシパル ID のリストへのポインタを指定します。
    @param[in]      size                プリンシパル ID のリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size = 1 );
    inline Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size)
    {
        return detail::GetFriendProfile( pProfileList, pPrincipalIdList, size );
    }

    /*!
    @brief          フレンドの関係のリストを取得します。

                    フレンド関係は、属性のビットの OR であらわされます。
                    一度でもフレンド関係が成立したことがあるフレンドは @ref nn::friends::CTR::ATTRIBUTE_FLAG_ESTABLISHED ビットが 1 になります。

    @param[out]     pAttributeFlagsList     取得した関係情報を格納するバッファへのポインタを指定します。
    @param[in]      pFriendKeyList          フレンドキーのリストへのポインタを指定します。
    @param[in]      size                    フレンドキーのリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size = 1 );
    inline Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size)
    {
        return detail::GetFriendAttributeFlags( pAttributeFlagsList, pFriendKeyList, size );
    }

    /*!
    @brief          フレンドの関係のリストを取得します。

                    フレンド関係は、属性のビットの OR であらわされます。
                    一度でもフレンド関係が成立したことがあるフレンドは @ref nn::friends::CTR::ATTRIBUTE_FLAG_ESTABLISHED ビットが 1 になります。

    @param[out]     pAttributeFlagsList     取得した関係情報を格納するバッファへのポインタを指定します。
    @param[in]      pPrincipalIdList        プリンシパル ID のリストへのポインタを指定します。
    @param[in]      size                    プリンシパル ID のリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size = 1 );
    inline Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size)
    {
        return detail::GetFriendAttributeFlags( pAttributeFlagsList, pPrincipalIdList, size );
    }

    /*!
    @brief          フレンドの暗号化ローカルフレンドコードを復号します。

                    フレンドのものでない暗号化ローカルフレンドコードを指定した場合、無効なローカルフレンドコードが返ってきます。

    @param[out]     pLocalFriendCodeList            復号したローカルフレンドコードを格納するバッファへのポインタを指定します。
    @param[in]      pScrambledLocalFriendCodeList   暗号化ローカルフレンドコードのリストへのポインタを指定します。
    @param[in]      size                            暗号化ローカルフレンドコードのリストの要素数（バッファの要素数）を指定します。

    @return         処理の結果が返ってきます。
    */
    Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size = 1);
    inline Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size )
    {
        return detail::UnscrambleLocalFriendCode( pLocalFriendCodeList, pScrambledLocalFriendCodeList, size );
    }

    /*!
    @brief          ゲームモード説明文字列を更新します。

                    ここで設定した文字列は、オンライン時にフレンドへ送信され、相手のフレンドリストに表示されます。<BR>
                    <BR>
                    本体リージョンと、フレンドリストで表示できる文字の関係は以下のとおりです。<BR>
                      @li 日米欧：内蔵フォントの日米欧文字に含まれる文字<BR>
                      @li 中：内蔵フォントの簡体字に含まれる文字<BR>
                      @li 韓：内蔵フォントのハングルに含まれる文字<BR>
                      @li 台：内蔵フォントの繁体字に含まれる文字<BR>
                    なお、各フォントに含まれる文字セットの詳細については、「 CTR オーバービュー」を参照してください。

    @param[in]      description     ゲームモード説明文字列を指定します。

    @return         処理の結果が返ってきます。
    */
    Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] );
    inline Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] )
    {
        return detail::UpdateGameModeDescription( description );
    }


    /*!
    @brief          自分のログイン状態や、フレンドの状態変更を通知するイベントを指定します。

                    この関数を複数回呼んだ場合、最後に指定した @ref nn::os::Event のみがシグナルします。

    @param[out]     pEvent   変更を通知する @ref nn::os::Event へのポインタを指定します。事前に @ref nn::os::Event::Initialize で初期化しておいてください。

    @return         処理の結果が返ってきます。
    */
    Result AttachToEventNotification( nn::os::Event* pEvent );
    inline Result AttachToEventNotification( nn::os::Event* pEvent )
    {
        return detail::AttachToEventNotification( pEvent );
    }

    /*!
    @brief          受け取る通知の種類を指定します。

                    @ref nn::friends::CTR::AttachToEventNotification で指定したイベントをシグナルさせたり、
                    @ref nn::friends::CTR::GetEventNotification で取得される履歴に含める通知の種類を指定します。

                    初期状態ではこの関数に @ref nn::friends::CTR::NOTIFICATION_MASK_DEFAULT を指定したのと同じ状態になっています。

    @param[in]      mask    受け取る通知の種類のビットマスクを指定します。 @ref nn::friends::CTR::NotificationMask 列挙体メンバの OR を指定してください。

    @return         処理の結果が返ってきます。
    */
    Result SetNotificationMask( bit32 mask );
    inline Result SetNotificationMask( bit32 mask )
    {
        return detail::SetNotificationMask( mask );
    }

    /*!
    @brief          自分のオンライン状態や、フレンドの状態変更の通知の履歴を取得します。

                    この関数を呼ぶと、まだ取得していない通知の内容を古いものから順に取得します。
                    返値が 0 になるまで繰り返し呼ぶことで、たまっている通知を時系列順に取得することができます。<BR>
                    <BR>
                    ライブラリが保存できる通知は128件までです。
                    128件を超えた通知は古いほうから削除されます。
                    通知の保存件数は今後調整される可能性があります。

    @param[out]     pEventNotificationList   取得した通知の内容を格納するバッファへのポインタを指定します。
    @param[in]      size                     バッファの要素数を指定します。
    @param[out]     pHasOverflowed           取得できずにあふれた通知があったかを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。

    @return         実際に取得できた通知の数が返ってきます。
    */
    u32 GetEventNotification(
        EventNotification* pEventNotificationList,
        size_t             size = 1,
        bool*              pHasOverflowed = NULL
    );
    inline u32 GetEventNotification(
        EventNotification* pEventNotificationList,
        size_t             size,
        bool*              pHasOverflowed
    )
    {
        return detail::GetEventNotification( pEventNotificationList, size, pHasOverflowed );
    }

    /*!
    @brief          完了した非同期処理の結果を取得します。

                    複数の非同期処理を走らせると、取得される結果は最後に開始した非同期処理のものでその都度上書きされます。
                    ある非同期処理の完了前に別の非同期処理を開始した場合、後者の完了前に前者が完了したとしても、その結果を取得することはできません。
                    原則として、複数の非同期処理を並行して走らせることは避けてください。

    @return         非同期処理の処理の結果が返ってきます。
    */
    Result GetLastResponseResult();
    inline Result GetLastResponseResult()
    {
        return detail::GetLastResponseResult();
    }

    /*!
    @brief          フレンド・プレゼンスライブラリの API の結果からエラーコードを取得します。

    @param[in]      result  フレンド・プレゼンスライブラリの API から取得した結果を指定します。

    @return         指定した結果に対応するエラーコードが返ってきます。
                    <BR>
                    エラーコードを表示する必要がない結果や、 FRIENDS ライブラリ API 以外の結果を指定した場合は 0 が返ってきます。
    */
    u32 ResultToErrorCode( const Result& result );
    inline u32 ResultToErrorCode( const Result& result )
    {
        return detail::ResultToErrorCode( result );
    }

} // end of namespace CTR
} // end of namespace friends
} // end of namespace nn

#endif // __cplusplus

// 以下、C 用宣言

#include <nn/util/detail/util_CLibImpl.h>

/*!
    @addtogroup   nn_friends   friends

    @{
*/



/*!
  @}
*/

#endif  // ifndef NN_FRIENDS_CTR_FRIENDS_API_H_