1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: friends_Api.h 4 5 Copyright 2009 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Rev: 36664 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef NN_FRIENDS_CTR_FRIENDS_API_H_ 17 #define NN_FRIENDS_CTR_FRIENDS_API_H_ 18 19 /*! @file 20 @brief フレンドプレゼンス機能に関する API の宣言 21 */ 22 23 #include <nn/types.h> 24 25 #include <nn/friends/friends_Result.h> 26 #include <nn/friends/CTR/friends_Types.h> 27 28 #include <nn/uds/CTR/uds_Type.h> 29 30 #ifdef __cplusplus 31 32 namespace nn { 33 namespace friends { 34 namespace CTR { 35 36 namespace detail 37 { 38 // ライブラリの初期化・終了 39 Result Initialize(); 40 Result Finalize(); 41 42 // ライブラリ状態確認 43 bool IsInitialized(); 44 bool HasLoggedIn(); 45 46 // 接続管理 47 Result Login( os::Event* pEvent ); 48 Result Logout(); 49 50 // 自分情報取得（ローカル） 51 PrincipalId GetMyPrincipalId(); 52 Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame ); 53 Result GetMyProfile( Profile* pProfile ); 54 Result GetMyPresence( MyPresence* pMyPresence ); 55 Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] ); 56 Result GetMyMii( MiiData* pMiiData ); 57 58 // 友達情報取得 59 Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset, size_t size ); 60 Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size ); 61 Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size ); 62 Result GetFriendScreenName( char16 (*pScreenNameList)[SCREEN_NAME_SIZE], const FriendKey* pFriendKeyList, size_t size, bool replaceForeignCharacters, u8* pFontRegionList ); 63 Result GetFriendScreenName( char16 (*pScreenNameList)[SCREEN_NAME_SIZE], const PrincipalId* pPrincipalIdList, size_t size, bool replaceForeignCharacters, u8* pFontRegionList ); 64 Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size ); 65 Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size ); 66 Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size ); 67 Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size ); 68 Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size ); 69 Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size ); 70 Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size ); 71 72 // 自分情報更新 73 Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] ); 74 75 // 通知内容取得 76 Result AttachToEventNotification( nn::os::Event* pEvent ); 77 Result SetNotificationMask( bit32 mask ); 78 u32 GetEventNotification( EventNotification* pEventNotificationList, size_t size, bool* pHasOverflowed ); 79 Result GetLastResponseResult(); 80 81 // エラーコード取得 82 u32 ResultToErrorCode( const Result& result ); 83 } 84 85 namespace 86 { 87 static const char PORT_NAME_USER[] = "frd:u"; 88 } 89 90 /*------------------------------------------------------------------- 91 ライブラリの初期化/終了 92 -------------------------------------------------------------------*/ 93 94 /*! 95 @brief フレンドプレゼンスライブラリの初期化を行い、プレゼンス機能を使用可能な状態にします。 96 97 @return 処理の結果が返ってきます。<BR> 98 99 @retval ResultSuccess 成功しました。 100 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 101 */ 102 Result Initialize(); Initialize()103 inline Result Initialize() 104 { 105 return detail::Initialize(); 106 } 107 108 /*! 109 @brief フレンドプレゼンスライブラリを終了します。 110 111 複数回 @ref nn::friends::CTR::Initialize 関数を呼んだ場合、この関数も同じ回数呼ぶ必要があります。 112 <BR> 113 ライブラリが未初期化の状態でコールしても成功します。<BR> 114 115 @return 処理の結果が返ってきます。<BR> 116 117 @retval ResultSuccess 成功しました。 118 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 119 */ 120 Result Finalize(); Finalize()121 inline Result Finalize() 122 { 123 return detail::Finalize(); 124 } 125 126 /*! 127 @brief フレンドプレゼンスライブラリが初期化済みか否かを確認します。 128 129 @return フレンドプレゼンスライブラリが初期化済みであれば true 、未初期化であれば false が返ってきます。 130 131 @retval true フレンドプレゼンスライブラリは初期化済みです。 132 @retval false フレンドプレゼンスライブラリは初期化されていません。 133 */ 134 bool IsInitialized(); IsInitialized()135 inline bool IsInitialized() 136 { 137 return detail::IsInitialized(); 138 } 139 140 /*! 141 @brief 自アプリのログイン状態を確認します。 142 143 自アプリが @ref nn::friends::CTR::Login 関数を呼んだ上でオンライン状態になっているかを確認します。 144 145 @return 自アプリがログイン中であれば true 、ログインしていなければ false が返ってきます。 146 この関数の結果が true であれば必ずオンライン状態ですが、結果が false であってもシステムがログイン要求を出している場合があり、オフライン状態とは限りません。 147 148 @retval true 自アプリがフレンドサーバにログインしています。 149 @retval false 自アプリはフレンドサーバにログインしていません。 150 */ 151 bool HasLoggedIn(); HasLoggedIn()152 inline bool HasLoggedIn() 153 { 154 return detail::HasLoggedIn(); 155 } 156 157 /*! 158 @brief サーバへのログインを要求します。 159 160 この関数が成功で返った場合は非同期処理が発生し、非同期処理が完了した時点で引数に指定した @ref nn::os::Event がシグナルされます。 161 非同期処理の結果は @ref nn::friends::CTR::GetLastResponseResult で取得できます。 162 この関数が失敗で返った場合は、非同期処理が発生することはありません。<BR> 163 <BR> 164 この関数を呼ぶには、事前に @ref nn::ac::Connect もしくは @ref nn::ac::ConnectAsync 関数を呼んで AP との接続を確立しておく必要があります。 165 AP との接続を確立せずに呼んだ場合は @ref nn::friends::ResultAcNotConnected を返します。<BR> 166 <BR> 167 バックグラウンドでサーバからの切断処理が走っていた場合、この関数は一時的に @ref nn::friends::ResultTemporarilyBusy を返します。 168 その場合は比較的短時間が経過した後に再試行することで成功する可能性があります。<BR> 169 <BR> 170 すでにログインしている状態でコールしても成功します。その場合、非同期処理は瞬時に成功で完了します。<BR> 171 <BR> 172 非同期処理が成功した場合、必ずオンライン状態になります。 173 174 @param[in] pEvent 非同期処理の完了を通知する @ref nn::os::Event へのポインタを指定します。事前に @ref nn::os::Event::Initialize で初期化しておいてください。 175 176 @return 処理の結果が返ってきます。 177 178 @retval ResultSuccess 非同期処理の開始に成功しました。 179 @retval ResultAlreadyDone 非同期処理の開始に成功しました。 180 @retval ResultTemporarilyBusy 内部状態が一時的にビジーなため、非同期処理の開始に失敗しました。 181 @retval ResultAcNotConnected ac への接続要求を出していません。 182 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 183 @retval ResultInvalidHandle 引数に渡した @ref nn::os::Event のハンドルが無効です。 184 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 185 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 186 */ 187 Result Login( os::Event* pEvent ); Login(os::Event * pEvent)188 inline Result Login( os::Event* pEvent ) 189 { 190 return detail::Login( pEvent ); 191 } 192 193 /*! 194 @brief サーバへのログイン要求を撤回します。 195 196 すでにログアウトしている状態でコールしても成功します。<BR> 197 <BR> 198 この関数が成功しても、オフライン状態であることは保証されません。<BR> 199 <BR> 200 何らかの要因によりサーバとの接続が切断された場合、この関数をコール済みの状態へ暗黙的に遷移します。 201 202 @return 処理の結果が返ってきます。 203 204 @retval ResultSuccess 成功しました。 205 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 206 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 207 */ 208 Result Logout(); Logout()209 inline Result Logout() 210 { 211 return detail::Logout(); 212 } 213 214 /*! 215 @brief 自分のプリンシパル ID を取得します。 216 217 @return 自分のプリンシパル ID が返ってきます。<BR> 218 <BR> 219 ライブラリが未初期化であったり、まだ一度もサーバに接続したことがないと @ref nn::friends::CTR::INVALID_PRINCIPAL_ID が返ってきます。 220 221 @retval INVALID_PRINCIPAL_ID 無効なプリンシパル ID です。 222 @retval その他 自分のプリンシパル ID です。 223 */ 224 PrincipalId GetMyPrincipalId(); GetMyPrincipalId()225 inline PrincipalId GetMyPrincipalId() 226 { 227 return detail::GetMyPrincipalId(); 228 } 229 230 /*! 231 @brief 自分の情報の公開レベルを取得します。 232 233 @param[out] pIsPublicMode 公開モードを格納するバッファへのポインタを指定します。 234 @param[out] pIsShowGameName 遊んでいるゲームを公開するかを格納するバッファへのポインタを指定します。 235 @param[out] pIsShowPlayedGame ゲーム履歴を公開するかを格納するバッファへのポインタを指定します。 236 237 @return 処理の結果が返ってきます。 238 239 @retval ResultSuccess 成功しました。 240 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 241 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 242 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 243 */ 244 Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame ); GetMyPreference(bool * pIsPublicMode,bool * pIsShowGameName,bool * pIsShowPlayedGame)245 inline Result GetMyPreference( bool* pIsPublicMode, bool* pIsShowGameName, bool* pIsShowPlayedGame ) 246 { 247 return detail::GetMyPreference( pIsPublicMode, pIsShowGameName, pIsShowPlayedGame ); 248 } 249 250 /*! 251 @brief 自分のプロフィール情報を取得します。 252 253 @param[out] pProfile 自分のプロフィール情報を格納する構造体へのポインタを指定します。 254 255 @return 処理の結果が返ってきます。 256 257 @retval ResultSuccess 成功しました。 258 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 259 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 260 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 261 */ 262 Result GetMyProfile( Profile* pProfile ); GetMyProfile(Profile * pProfile)263 inline Result GetMyProfile( Profile* pProfile ) 264 { 265 return detail::GetMyProfile( pProfile ); 266 } 267 268 /*! 269 @brief 自分のプレゼンス情報を取得します。 270 271 @param[out] pMyPresence 自分のプレゼンス情報を格納する構造体へのポインタを指定します。 272 273 @return 処理の結果が返ってきます。 274 275 @retval ResultSuccess 成功しました。 276 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 277 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 278 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 279 */ 280 Result GetMyPresence( MyPresence* pMyPresence ); GetMyPresence(MyPresence * pMyPresence)281 inline Result GetMyPresence( MyPresence* pMyPresence ) 282 { 283 return detail::GetMyPresence( pMyPresence ); 284 } 285 286 /*! 287 @brief 自分の表示名を取得します。 288 289 @param[out] screenName 自分の表示名を格納するバッファを指定します。 290 291 「Mii スタジオ」で「じぶんの Mii」を設定していない場合、空の表示名が取得されます。 292 この場合も、関数自体は成功を返します。 293 294 @return 処理の結果が返ってきます。 295 296 @retval ResultSuccess 成功しました。 297 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 298 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 299 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 300 */ 301 Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] ); GetMyScreenName(char16 screenName[SCREEN_NAME_SIZE])302 inline Result GetMyScreenName( char16 screenName[SCREEN_NAME_SIZE] ) 303 { 304 return detail::GetMyScreenName( screenName ); 305 } 306 307 /*! 308 @brief 自分の Mii データを取得します。 309 310 「Mii スタジオ」で「じぶんの Mii」を設定していない場合、空の Mii データが取得されます。 311 この場合も、関数自体は成功を返します。<BR> 312 <BR> 313 取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。 314 315 @param[out] pMiiData 自分の Mii データを格納する構造体へのポインタを指定します。 316 317 @return 処理の結果が返ってきます。 318 319 @retval ResultSuccess 成功しました。 320 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 321 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 322 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 323 */ 324 Result GetMyMii( MiiData* pMiiData ); GetMyMii(MiiData * pMiiData)325 inline Result GetMyMii( MiiData* pMiiData ) 326 { 327 return detail::GetMyMii( pMiiData ); 328 } 329 330 /*! 331 @brief フレンドリストに登録されたフレンドキーのリストを取得します。 332 333 取得されるフレンドキーには、まだフレンド関係が成立していないものも含まれます。 334 335 @param[out] pFriendKeyList 取得したフレンドキーを格納するバッファへのポインタを指定します。 336 @param[out] pNum 実際に取得された数を格納するバッファへのポインタを指定します。 337 @param[in] offset 取得を開始するフレンドキーのインデックスを指定します。 338 @param[in] size 取得するフレンドキーの最大数（バッファの要素数）を指定します。 339 340 @return 処理の結果が返ってきます。 341 342 @retval ResultSuccess 成功しました。 343 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 344 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 345 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 346 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 347 */ 348 Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset = 0, size_t size = FRIEND_LIST_SIZE ); GetFriendKeyList(FriendKey * pFriendKeyList,size_t * pNum,size_t offset,size_t size)349 inline Result GetFriendKeyList( FriendKey* pFriendKeyList, size_t* pNum, size_t offset, size_t size) 350 { 351 return detail::GetFriendKeyList( pFriendKeyList, pNum, offset, size ); 352 } 353 354 /*! 355 @brief フレンドプレゼンスのリストを取得します。 356 357 自分と異なる合流ゲーム ID を指定しているフレンドのゲームモードとお誘いフラグは取得できません。<BR> 358 <BR> 359 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空のプレゼンスが返されます。 360 この場合も、関数自体は成功を返します。 361 362 @param[out] pFriendPresenceList 取得したフレンドプレゼンスを格納するバッファへのポインタを指定します。 363 @param[in] pFriendKeyList フレンドキーのリストへのポインタを指定します。 364 @param[in] size フレンドキーのリストの要素数（バッファの要素数）を指定します。 365 366 @return 処理の結果が返ってきます。 367 368 @retval ResultSuccess 成功しました。 369 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 370 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 371 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 372 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 373 */ 374 Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size = 1 ); GetFriendPresence(FriendPresence * pFriendPresenceList,const FriendKey * pFriendKeyList,size_t size)375 inline Result GetFriendPresence( FriendPresence* pFriendPresenceList, const FriendKey* pFriendKeyList, size_t size) 376 { 377 return detail::GetFriendPresence( pFriendPresenceList, pFriendKeyList, size ); 378 } 379 380 /*! 381 @brief フレンドプレゼンスのリストを取得します。 382 383 自分と異なる合流ゲーム ID を指定したフレンドのゲームモードとお誘いフラグは取得できません。<BR> 384 <BR> 385 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空のプレゼンスが返されます。 386 この場合も、関数自体は成功を返します。 387 388 @param[out] pFriendPresenceList 取得したフレンドプレゼンスを格納するバッファへのポインタを指定します。 389 @param[in] pPrincipalIdList プリンシパル ID のリストへのポインタを指定します。 390 @param[in] size プリンシパル ID のリストの要素数（バッファの要素数）を指定します。 391 392 @return 処理の結果が返ってきます。 393 394 @retval ResultSuccess 成功しました。 395 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 396 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 397 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 398 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 399 */ 400 Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size = 1 ); GetFriendPresence(FriendPresence * pFriendPresenceList,const PrincipalId * pPrincipalIdList,size_t size)401 inline Result GetFriendPresence( FriendPresence* pFriendPresenceList, const PrincipalId* pPrincipalIdList, size_t size) 402 { 403 return detail::GetFriendPresence( pFriendPresenceList, pPrincipalIdList, size ); 404 } 405 406 /*! 407 @brief フレンドの表示名のリストを取得します。 408 409 この関数を使用すると、「似顔絵ライブラリ」を使用せずにフレンドの Mii の名前を直接取得することができます。 410 また、対象がフレンド関係成立待ち状態で Mii が取得できない場合でも、自分が仮登録した表示名が取得されます。<BR> 411 <BR> 412 フレンドの Mii がブラックリストに含まれていた場合でも生の名前が取得されますが、 413 フレンドの Mii の名前が NG ネームだった場合は ??? に置換されて取得されます。<BR> 414 <BR> 415 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空の表示名が返されます。 416 この場合も、関数自体は成功を返します。 417 418 @param[out] pScreenNameList 取得した表示名を格納するバッファへのポインタを指定します。 419 @param[in] pFriendKeyList フレンドキーのリストへのポインタを指定します。 420 @param[in] size フレンドキーのリストの要素数（バッファの要素数）を指定します。 421 @param[in] replaceForeignCharacters フレンドの表示名のフォントリージョンが自分と異なる場合に、 ASCII 以外の文字を ? で置換するかを指定します。 422 @param[in] pFontRegionList フレンドの表示名のフォントリージョンを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。 423 424 @return 処理の結果が返ってきます。 425 426 @retval ResultSuccess 成功しました。 427 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 428 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 429 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 430 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 431 */ 432 Result GetFriendScreenName( 433 char16 (*pScreenNameList)[SCREEN_NAME_SIZE], 434 const FriendKey* pFriendKeyList, 435 size_t size = 1, 436 bool replaceForeignCharacters = true, 437 u8* pFontRegionList = NULL 438 ); GetFriendScreenName(char16 (* pScreenNameList)[SCREEN_NAME_SIZE],const FriendKey * pFriendKeyList,size_t size,bool replaceForeignCharacters,u8 * pFontRegionList)439 inline Result GetFriendScreenName( 440 char16 (*pScreenNameList)[SCREEN_NAME_SIZE], 441 const FriendKey* pFriendKeyList, 442 size_t size, 443 bool replaceForeignCharacters, 444 u8* pFontRegionList 445 ) 446 { 447 return detail::GetFriendScreenName( pScreenNameList, pFriendKeyList, size, replaceForeignCharacters, pFontRegionList ); 448 } 449 450 /*! 451 @brief フレンドの表示名のリストを取得します。 452 453 この関数を使用すると、「似顔絵ライブラリ」を使用せずにフレンドの Mii の名前を直接取得することができます。 454 また、対象がフレンド関係成立待ち状態で Mii が取得できない場合でも、自分が仮登録した表示名が取得されます。<BR> 455 <BR> 456 フレンドの Mii がブラックリストに含まれていた場合でも生の名前が取得されますが、 457 フレンドの Mii の名前が NG ネームだった場合は ??? に置換されて取得されます。<BR> 458 <BR> 459 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空の表示名が返されます。 460 この場合も、関数自体は成功を返します。 461 462 @param[out] pScreenNameList 取得した表示名を格納するバッファへのポインタを指定します。 463 @param[in] pPrincipalIdList プリンシパル ID のリストへのポインタを指定します。 464 @param[in] size プリンシパル ID のリストの要素数（バッファの要素数）を指定します。 465 @param[in] replaceForeignCharacters フレンドの表示名のフォントリージョンが自分と異なる場合に、 ASCII 以外の文字を ? で置換するかを指定します。 466 @param[in] pFontRegionList フレンドの表示名のフォントリージョンを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。 467 468 @return 処理の結果が返ってきます。 469 470 @retval ResultSuccess 成功しました。 471 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 472 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 473 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 474 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 475 */ 476 Result GetFriendScreenName( 477 char16 (*pScreenNameList)[SCREEN_NAME_SIZE], 478 const PrincipalId* pPrincipalIdList, 479 size_t size = 1, 480 bool replaceForeignCharacters = true, 481 u8* pFontRegionList = NULL 482 ); GetFriendScreenName(char16 (* pScreenNameList)[SCREEN_NAME_SIZE],const PrincipalId * pPrincipalIdList,size_t size,bool replaceForeignCharacters,u8 * pFontRegionList)483 inline Result GetFriendScreenName( 484 char16 (*pScreenNameList)[SCREEN_NAME_SIZE], 485 const PrincipalId* pPrincipalIdList, 486 size_t size, 487 bool replaceForeignCharacters, 488 u8* pFontRegionList 489 ) 490 { 491 return detail::GetFriendScreenName( pScreenNameList, pPrincipalIdList, size, replaceForeignCharacters, pFontRegionList ); 492 } 493 494 /*! 495 @brief フレンドの Mii データのリストを取得します。 496 497 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空の Mii データが返されます。 498 この場合も、関数自体は成功を返します。<BR> 499 <BR> 500 取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。 501 502 @param[out] pMiiDataList 取得した Mii データを格納するバッファへのポインタを指定します。 503 @param[in] pFriendKeyList フレンドキーのリストへのポインタを指定します。 504 @param[in] size フレンドキーのリストの要素数（バッファの要素数）を指定します。 505 506 @return 処理の結果が返ってきます。 507 508 @retval ResultSuccess 成功しました。 509 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 510 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 511 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 512 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 513 */ 514 Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size = 1 ); GetFriendMii(MiiData * pMiiDataList,const FriendKey * pFriendKeyList,size_t size)515 inline Result GetFriendMii( MiiData* pMiiDataList, const FriendKey* pFriendKeyList, size_t size) 516 { 517 return detail::GetFriendMii( pMiiDataList, pFriendKeyList, size ); 518 } 519 520 /*! 521 @brief フレンドの Mii データのリストを取得します。 522 523 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空の Mii データが返されます。 524 この場合も、関数自体は成功を返します。<BR> 525 <BR> 526 取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。 527 528 @param[out] pMiiDataList 取得した Mii データを格納するバッファへのポインタを指定します。 529 @param[in] pPrincipalIdList プリンシパル ID のリストへのポインタを指定します。 530 @param[in] size プリンシパル ID のリストの要素数（バッファの要素数）を指定します。 531 532 @return 処理の結果が返ってきます。 533 534 @retval ResultSuccess 成功しました。 535 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 536 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 537 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 538 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 539 */ 540 Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size = 1); GetFriendMii(MiiData * pMiiDataList,const PrincipalId * pPrincipalIdList,size_t size)541 inline Result GetFriendMii( MiiData* pMiiDataList, const PrincipalId* pPrincipalIdList, size_t size) 542 { 543 return detail::GetFriendMii( pMiiDataList, pPrincipalIdList, size ); 544 } 545 546 /*! 547 @brief フレンドのプロフィール情報のリストを取得します。 548 549 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空のプロフィール情報が返されます。 550 また、相手が一度もオンライン状態を公開していない場合にも、空のプロフィール情報が返されることがあります。 551 これらの場合も、関数自体は成功を返します。@n 552 553 空のプロフィール情報ではプラットフォームコードが必ず 0 になります。 554 リージョンコードなどは、単体では有効な値かを区別できないことがありますので、必ずプラットフォームコードで判別してください。 555 556 @param[out] pProfileList 取得したプロフィール情報を格納するバッファへのポインタを指定します。 557 @param[in] pFriendKeyList フレンドキーのリストへのポインタを指定します。 558 @param[in] size フレンドキーのリストの要素数（バッファの要素数）を指定します。 559 560 @return 処理の結果が返ってきます。 561 562 @retval ResultSuccess 成功しました。 563 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 564 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 565 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 566 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 567 */ 568 Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size = 1 ); GetFriendProfile(Profile * pProfileList,const FriendKey * pFriendKeyList,size_t size)569 inline Result GetFriendProfile( Profile* pProfileList, const FriendKey* pFriendKeyList, size_t size) 570 { 571 return detail::GetFriendProfile( pProfileList, pFriendKeyList, size ); 572 } 573 574 /*! 575 @brief フレンドのプロフィール情報のリストを取得します。 576 577 引数で与えられたキーに対応するフレンドが存在しないと、該当のバッファには空のプロフィール情報が返されます。 578 また、相手が一度もオンライン状態を公開していない場合にも、空のプロフィール情報が返されることがあります。 579 これらの場合も、関数自体は成功を返します。@n 580 581 空のプロフィール情報ではプラットフォームコードが必ず 0 になります。 582 リージョンコードなどは、単体では有効な値かを区別できないことがありますので、必ずプラットフォームコードで判別してください。 583 584 @param[out] pProfileList 取得したプロフィール情報を格納するバッファへのポインタを指定します。 585 @param[in] pPrincipalIdList プリンシパル ID のリストへのポインタを指定します。 586 @param[in] size プリンシパル ID のリストの要素数（バッファの要素数）を指定します。 587 588 @return 処理の結果が返ってきます。 589 590 @retval ResultSuccess 成功しました。 591 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 592 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 593 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 594 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 595 */ 596 Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size = 1 ); GetFriendProfile(Profile * pProfileList,const PrincipalId * pPrincipalIdList,size_t size)597 inline Result GetFriendProfile( Profile* pProfileList, const PrincipalId* pPrincipalIdList, size_t size) 598 { 599 return detail::GetFriendProfile( pProfileList, pPrincipalIdList, size ); 600 } 601 602 /*! 603 @brief フレンドの関係のリストを取得します。 604 605 フレンド関係は、属性のビットの OR であらわされます。 606 一度でもフレンド関係が成立したことがあるフレンドは @ref nn::friends::CTR::ATTRIBUTE_FLAG_ESTABLISHED ビットが 1 になります。 607 608 @param[out] pAttributeFlagsList 取得した関係情報を格納するバッファへのポインタを指定します。 609 @param[in] pFriendKeyList フレンドキーのリストへのポインタを指定します。 610 @param[in] size フレンドキーのリストの要素数（バッファの要素数）を指定します。 611 612 @return 処理の結果が返ってきます。 613 614 @retval ResultSuccess 成功しました。 615 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 616 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 617 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 618 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 619 */ 620 Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size = 1 ); GetFriendAttributeFlags(bit32 * pAttributeFlagsList,const FriendKey * pFriendKeyList,size_t size)621 inline Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const FriendKey* pFriendKeyList, size_t size) 622 { 623 return detail::GetFriendAttributeFlags( pAttributeFlagsList, pFriendKeyList, size ); 624 } 625 626 /*! 627 @brief フレンドの関係のリストを取得します。 628 629 フレンド関係は、属性のビットの OR であらわされます。 630 一度でもフレンド関係が成立したことがあるフレンドは @ref nn::friends::CTR::ATTRIBUTE_FLAG_ESTABLISHED ビットが 1 になります。 631 632 @param[out] pAttributeFlagsList 取得した関係情報を格納するバッファへのポインタを指定します。 633 @param[in] pPrincipalIdList プリンシパル ID のリストへのポインタを指定します。 634 @param[in] size プリンシパル ID のリストの要素数（バッファの要素数）を指定します。 635 636 @return 処理の結果が返ってきます。 637 638 @retval ResultSuccess 成功しました。 639 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 640 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 641 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 642 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 643 */ 644 Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size = 1 ); GetFriendAttributeFlags(bit32 * pAttributeFlagsList,const PrincipalId * pPrincipalIdList,size_t size)645 inline Result GetFriendAttributeFlags( bit32* pAttributeFlagsList, const PrincipalId* pPrincipalIdList, size_t size) 646 { 647 return detail::GetFriendAttributeFlags( pAttributeFlagsList, pPrincipalIdList, size ); 648 } 649 650 /*! 651 @brief フレンドの暗号化ローカルフレンドコードを復号します。 652 653 フレンドのものでない暗号化ローカルフレンドコードを指定した場合、無効なローカルフレンドコードが返ってきます。 654 この場合も、関数自体は成功を返します。 655 656 @param[out] pLocalFriendCodeList 復号したローカルフレンドコードを格納するバッファへのポインタを指定します。 657 @param[in] pScrambledLocalFriendCodeList 暗号化ローカルフレンドコードのリストへのポインタを指定します。 658 @param[in] size 暗号化ローカルフレンドコードのリストの要素数（バッファの要素数）を指定します。 659 660 @return 処理の結果が返ってきます。 661 662 @retval ResultSuccess 成功しました。 663 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 664 @retval ResultTooLarge 引数に渡したサイズの値が大きすぎます。 665 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 666 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 667 */ 668 Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size = 1); UnscrambleLocalFriendCode(LocalFriendCode * pLocalFriendCodeList,const uds::CTR::ScrambledLocalFriendCode * pScrambledLocalFriendCodeList,size_t size)669 inline Result UnscrambleLocalFriendCode( LocalFriendCode* pLocalFriendCodeList, const uds::CTR::ScrambledLocalFriendCode* pScrambledLocalFriendCodeList, size_t size ) 670 { 671 return detail::UnscrambleLocalFriendCode( pLocalFriendCodeList, pScrambledLocalFriendCodeList, size ); 672 } 673 674 /*! 675 @brief ゲームモード説明文字列を更新します。 676 677 ここで設定した文字列は、オンライン時にフレンドへ送信され、相手のフレンドリストに表示されます。<BR> 678 <BR> 679 引数に渡せる文字列は改行や終端文字を含めて @ref nn::friends::CTR::MODE_DESCRIPTION_SIZE 文字までですが、 680 フレンドリストでの表示は全角16文字分の幅×2行までとなり、それを超えた分は切れて表示されません。<BR> 681 <BR> 682 本体リージョンと、フレンドリストで表示できる文字の関係は以下のとおりです。<BR> 683 @li 日米欧：内蔵フォントの日米欧文字に含まれる文字<BR> 684 @li 中：内蔵フォントの簡体字に含まれる文字<BR> 685 @li 韓：内蔵フォントのハングルに含まれる文字<BR> 686 @li 台：内蔵フォントの繁体字に含まれる文字<BR> 687 ここに含まれない文字は、任天堂外字の「?」 (L'\\xE011') に置き換えられて表示されます。 688 各フォントに含まれる文字セットの詳細については、「CTR オーバービュー」を参照してください。<BR> 689 <BR> 690 改行には L'\\n' を使用してください。 691 692 @param[in] description ゲームモード説明文字列を指定します。 693 694 @return 処理の結果が返ってきます。 695 696 @retval ResultSuccess 成功しました。 697 @retval ResultRmcNotCalled 成功しました。ただし、接続状況や送信頻度制限によりサーバやフレンドへの通知は遅れて行われます。 698 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 699 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 700 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 701 */ 702 Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] ); UpdateGameModeDescription(const char16 description[MODE_DESCRIPTION_SIZE])703 inline Result UpdateGameModeDescription( const char16 description[MODE_DESCRIPTION_SIZE] ) 704 { 705 return detail::UpdateGameModeDescription( description ); 706 } 707 708 709 /*! 710 @brief 自分のログイン状態や、フレンドの状態変更を通知するイベントを指定します。 711 712 この関数を複数回呼んだ場合、最後に指定した @ref nn::os::Event のみがシグナルします。 713 714 @param[out] pEvent 変更を通知する @ref nn::os::Event へのポインタを指定します。事前に @ref nn::os::Event::Initialize で初期化しておいてください。 715 716 @return 処理の結果が返ってきます。 717 718 @retval ResultSuccess 成功しました。 719 @retval ResultInvalidPointer 引数に渡したポインタが無効です。 720 @retval ResultInvalidHandle 引数に渡した @ref nn::os::Event のハンドルが無効です。 721 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 722 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 723 */ 724 Result AttachToEventNotification( nn::os::Event* pEvent ); AttachToEventNotification(nn::os::Event * pEvent)725 inline Result AttachToEventNotification( nn::os::Event* pEvent ) 726 { 727 return detail::AttachToEventNotification( pEvent ); 728 } 729 730 /*! 731 @brief 受け取る通知の種類を指定します。 732 733 @ref nn::friends::CTR::AttachToEventNotification で指定したイベントをシグナルさせたり、 734 @ref nn::friends::CTR::GetEventNotification で取得される履歴に含める通知の種類を指定します。 735 736 初期状態ではこの関数に @ref nn::friends::CTR::NOTIFICATION_MASK_DEFAULT を指定したのと同じ状態になっています。 737 738 @param[in] mask 受け取る通知の種類のビットマスクを指定します。 @ref nn::friends::CTR::NotificationMask 列挙体メンバの OR を指定してください。 739 740 @return 処理の結果が返ってきます。 741 742 @retval ResultSuccess 成功しました。 743 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 744 @retval その他 デーモンの内部状態などにより、その他の結果が返ることがあります。 745 */ 746 Result SetNotificationMask( bit32 mask ); SetNotificationMask(bit32 mask)747 inline Result SetNotificationMask( bit32 mask ) 748 { 749 return detail::SetNotificationMask( mask ); 750 } 751 752 /*! 753 @brief 自分のオンライン状態や、フレンドの状態変更の通知の履歴を取得します。 754 755 この関数を呼ぶと、まだ取得していない通知の内容を古いものから順に取得します。 756 返値が 0 になるまで繰り返し呼ぶことで、たまっている通知を時系列順に取得することができます。<BR> 757 <BR> 758 ライブラリが保存できる通知は128件までです。 759 128件を超えた通知は古いほうから削除されます。 760 通知の保存件数は今後調整される可能性があります。 761 762 @param[out] pEventNotificationList 取得した通知の内容を格納するバッファへのポインタを指定します。 763 @param[in] size バッファの要素数を指定します。 764 @param[out] pHasOverflowed 取得できずにあふれた通知があったかを格納するバッファへのポインタを指定します。不要な場合は NULL を指定してください。 765 766 @return 実際に取得できた通知の数が返ってきます。 767 */ 768 u32 GetEventNotification( 769 EventNotification* pEventNotificationList, 770 size_t size = 1, 771 bool* pHasOverflowed = NULL 772 ); GetEventNotification(EventNotification * pEventNotificationList,size_t size,bool * pHasOverflowed)773 inline u32 GetEventNotification( 774 EventNotification* pEventNotificationList, 775 size_t size, 776 bool* pHasOverflowed 777 ) 778 { 779 return detail::GetEventNotification( pEventNotificationList, size, pHasOverflowed ); 780 } 781 782 /*! 783 @brief 完了した非同期処理の結果を取得します。 784 785 複数の非同期処理を走らせると、取得される結果は最後に開始した非同期処理のものでその都度上書きされます。 786 ある非同期処理の完了前に別の非同期処理を開始した場合、後者の完了前に前者が完了したとしても、その結果を取得することはできません。 787 原則として、複数の非同期処理を並行して走らせることは避けてください。 788 789 @return 非同期処理の処理の結果が返ってきます。 790 791 @retval ResultSuccess 成功しました。 792 @retval ResultNotInitialized フレンドプレゼンスライブラリが初期化されていません。 793 @retval その他 デーモンの内部状態や通信状態などにより、その他の結果が返ることがあります。 794 */ 795 Result GetLastResponseResult(); GetLastResponseResult()796 inline Result GetLastResponseResult() 797 { 798 return detail::GetLastResponseResult(); 799 } 800 801 /*! 802 @brief フレンドプレゼンスライブラリの API の結果からエラーコードを取得します。 803 804 @param[in] result フレンドプレゼンスライブラリの API から取得した結果を指定します。 805 806 @return 指定した結果に対応するエラーコードが返ってきます。 807 <BR> 808 エラーコードを表示する必要がない結果や、 FRIENDS ライブラリ API 以外の結果を指定した場合は 0 が返ってきます。 809 810 @retval 0 フレンド関連の対応するエラーコードがありません。 811 @retval その他 エラーコードです。 812 */ 813 u32 ResultToErrorCode( const Result& result ); ResultToErrorCode(const Result & result)814 inline u32 ResultToErrorCode( const Result& result ) 815 { 816 return detail::ResultToErrorCode( result ); 817 } 818 819 } // end of namespace CTR 820 } // end of namespace friends 821 } // end of namespace nn 822 823 #endif // __cplusplus 824 825 // 以下、C 用宣言 826 827 #include <nn/util/detail/util_CLibImpl.h> 828 829 /*! 830 @addtogroup nn_friends friends 831 832 @{ 833 */ 834 835 836 837 /*! 838 @} 839 */ 840 841 #endif // ifndef NN_FRIENDS_CTR_FRIENDS_API_H_ 842