CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
common_Api.h
1 /*--------------------------------------------------------------------------------*
2  Copyright (C)Nintendo All rights reserved.
3 
4  These coded instructions, statements, and computer programs contain proprietary
5  information of Nintendo and/or its licensed developers and are protected by
6  national and international copyright laws. They may not be disclosed to third
7  parties or copied or duplicated in any form, in whole or in part, without the
8  prior written consent of Nintendo.
9 
10  The content herein is highly confidential and should be handled accordingly.
11  *--------------------------------------------------------------------------------*/
12 
13 
14 #pragma once
15 
16 #include <nn/pia/common/common_Definitions.h>
17 
18 
19 // NN_PIA_COMMON_SET_PROGRAM_INFORMATION で使用する SDK バージョン番号を参照するためのマクロ。
20 #if NN_PIA_CTR
21 #define NN_PIA_SDK_VER NN_CURRENT_VERSION_NUMBER
22 #elif NN_PIA_CAFE
23 #define NN_PIA_SDK_VER CAFE_OS_SDK_VERSION
24 #elif NN_PIA_WIN || NN_PIA_NINTENDOSDK || NN_PIA_A || NN_PIA_B
25 #define NN_PIA_SDK_VER 0xffffffff
26 #else
27 #error "Invalid platform."
28 #endif
29 
30 // @addtogroup pia_common_debug_macro Pia の提供するデバッグ用マクロ定義
31 // @brief Pia の提供するデバッグ用マクロです。
32 //! @{
33 //! @name その他
34 //! @{
35 
36 /*!
37  @def NN_PIA_COMMON_SET_PROGRAM_INFORMATION
38  @brief アプリケーションが使用する SDK や NEX の情報を Pia ライブラリに登録するマクロです。
39 
40  @details common::Initialize() 以降で呼び出してもらうことを想定しています。
41  NEX バージョン番号の定数を参照しているため、あらかじめ NEX のヘッダファイルを
42  #include しておく必要があります。
43  */
44 #define NN_PIA_COMMON_SET_PROGRAM_INFORMATION() \
45  nn::pia::common::SetProgramInformation( \
46  NN_PIA_SDK_VER, \
47  NEX_VERSION_MAJOR, \
48  NEX_VERSION_MINOR, \
49  NEX_VERSION_MICRO)
50 
51 //! @}
52 //! @}
53 
54 
55 // common モジュールの非メンバ関数群です。
56 
57 namespace nn
58 {
59 namespace pia
60 {
61 namespace common
62 {
63 
64 
65 /*!
66  @brief common モジュールが初期化された状態であるかどうかを返します。
67 
68  @return 初期化されていれば true 、されていなければ false が返されます。
69  */
70 bool IsInitialized(void);
71 
72 
73 /*!
74  @brief common モジュールを初期化します。
75 
76  @details 初期化により、Piaライブラリが使用するヒープがセットアップされます。
77  続いて nn::pia::common::Report インスタンスがセットアップされ、
78  PIA_REPORT()などが利用できるようになります。
79  @if CTR_DOC
80  Piaは内部のスレッド管理を効率的にするため、暗黙的にスレッドローカル
81  ストレージを使用しています。詳しくはプログラミングマニュアルを参照してください。
82  @endif
83 
84  @param[in] pMem Piaライブラリに渡すメモリブロックの先頭を指すポインタ。
85  32bit 環境であれば 4バイト、64bit 環境であれば 8バイトのアライメントが必要です。
86  @param[in] size pMemで渡されたメモリブロックのサイズ。単位はバイト。
87  ヒープを構築できるだけの十分なサイズがない場合、ライブラリ内部で
88  アサート停止します。
89 
90  @return 無事に初期化が完了すれば、成功の Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
91 
92  @retval ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
93  @retval ResultAlreadyInitialized 既に初期化は終了しています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
94  */
95 Result Initialize(void* pMem, uint32_t size);
96 
97 
98 /*!
99  @brief common モジュールを終了します。
100 
101  @details @ref Initialize 時にセットアップした nn::pia::common::Report インスタンスが破棄され、
102  アプリケーションが @ref Initialize でPiaライブラリに供給したメモリが解放されます。
103  common モジュールが初期化されていない状態の時にこの API を呼び出した場合は、何もしません。
104  */
105 void Finalize(void);
106 
107 
108 /*!
109  @brief セットアップの開始を宣言します。
110 
111  @details common モジュールのシングルトンなどを作成する前に呼ぶ必要があります。
112  アプリケーションが common モジュールのシングルトンを一つも作成しない場合であっても、
113  この API と @ref EndSetup は必ず呼び出す必要があります。
114 
115  @return この API を適切なタイミングで呼び出していれば、成功の Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
116 
117  @retval ResultNotInitialized common モジュールの初期化関数が呼ばれていません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
118  @retval ResultInvalidState この関数を呼び出すタイミングが誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
119  */
120 Result BeginSetup(void);
121 
122 
123 /*!
124  @brief セットアップの終了を宣言します。
125 
126  @details common モジュールのシングルトンなどを作成し終えた後に呼ぶ必要があります。
127  このAPI呼び出しにより、 common モジュールのシングルトンなどが消費する
128  メモリを確定し、ライブラリ内部でのメモリ管理を最適化します。
129  アプリケーションが common モジュールのシングルトンを一つも作成しない場合であっても、
130  @ref BeginSetup とこの API は必ず呼び出す必要があります。
131 
132  @return この API を適切なタイミングで呼び出していれば、成功の Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
133 
134  @retval ResultNotInitialized common モジュールの初期化関数が呼ばれていません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
135  @retval ResultInvalidState この関数を呼び出すタイミングが誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
136  */
137 Result EndSetup(void);
138 
139 /*!
140  @brief この API を呼び出した時点における Pia ライブラリのメモリ使用量を得ます。
141 
142  @details この API は、各モジュールの BeginSetup() ~ EndSetup() 間では
143  呼び出してはいけません。もし呼び出してしまうと、誤った値が返されます。
144 
145  @return この API を呼び出した時点での Pia ライブラリのメモリ使用量が返されます。
146  common モジュールのセットアップがされていないときや、内部でエラーが
147  発生した場合は、0 が返されます。
148 
149  @retval 0 Pia ライブラリがセットアップされていないとき
150  */
151 uint32_t GetMemoryUsage(void);
152 
153 
154 /*!
155  @cond PRIVATE
156  @brief プログラム情報を登録します。
157 
158  @details アプリケーションが使用する SDK や NEX のバージョン番号を登録します。
159  @endcond
160  */
161 void SetProgramInformation(uint32_t sdkVer, uint8_t nexMajorVer, uint8_t nexMinorVer, uint8_t nexMicroVer);
162 
163 
164 /*!
165  @cond PRIVATE
166  @brief BeginSetup() ~ EndSetup() 間の状態であるかどうかを返します。
167  @endcond
168  */
169 bool IsInSetupMode(void);
170 
171 
172 /*!
173  @cond PRIVATE
174  @brief デバッグ情報をプリントします。
175  @endcond
176  */
177 void PrintDebugInfo(void);
178 
179 
180 /*!
181  @cond PRIVATE
182  @brief 環境情報をプリントします。
183  @endcond
184  */
185 void PrintEnvironmentInfo(void);
186 
187 
188 /*!
189  @brief RegisterInternalPrintCallback に渡すコールバック型です。
190 
191  @param[in] pStr 文字列の先頭を指すポインタ。ヌル文字で終端されているとは限りません。
192  @param[in] len 文字列長。
193  */
194 typedef void (*InternalPrintCallback)(const char* pStr, int32_t len);
195 
196 
197 /*!
198  @brief Pia のコンソール出力をフックするコールバックを設定する関数です。
199 
200  @param[in] pCallback 登録するコールバック関数のポインタ。
201  @return この関数を呼び出す前に登録されていたコールバック関数のポインタが返されます。
202  何も登録されていなければ、NULL が返ります。
203  */
205 
206 
207 /*!
208  @cond PRIVATE
209  @brief 文字列をプリントします。
210 
211  @param[in] cpFormat フォーマット文字列です。
212  @param[in] varg 引数リストです。
213  */
214 void VPrintf(const char* cpFormat, va_list varg);
215 //! @endcond
216 
217 
218 /*!
219  @cond PRIVATE
220  @brief 文字列をプリントします。
221 
222  @param[in] cpFormat フォーマット文字列です。
223  @param[in] ... 可変長引数です。
224  */
225 void Printf(const char* cpFormat, ...);
226 //! @endcond
227 }
228 }
229 } // end of namespace nn::pia::common