CTR Pia  4.11.3
Game Communication Engine
common_Api.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_Api.h
4 
5  Copyright 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 
14 
15 #pragma once
16 
17 #include <pia/common/common_definitions.h>
18 
19 
20 // This macro is used to access the version number of the SDK used by <tt>NN_PIA_COMMON_SET_PROGRAM_INFORMATION</tt>.
21 #if NN_PIA_CTR
22 #define NN_PIA_SDK_VER NN_CURRENT_VERSION_NUMBER
23 #elif NN_PIA_CAFE
24 #define NN_PIA_SDK_VER CAFE_OS_SDK_VERSION
25 #elif NN_PIA_WIN || NN_PIA_NIN_WIN
26 #define NN_PIA_SDK_VER 0xffffffff
27 #else
28 #error "Invalid platform."
29 #endif
30 
31 // @addtogroup pia_common_debug_macro Definitions of Debugging Macros Provided by the Pia Library
32 // @brief Specifies the debugging macros provided by the Pia library.
33 //! @{
34 //! @name Others
35 //! @{
36 
37 /*!
38 @def NN_PIA_COMMON_SET_PROGRAM_INFORMATION
39 @brief This macro registers information about the SDK and NEX library used by the application with the PIA library.
40 
41 @details This macro is meant to be called after the <tt>common::Initialize</tt> function.
42 To access the constant that represents the NEX version number, you must first use the <CODE>#include</CODE> directive to process the NEX header files.
43 
44 */
45 #define NN_PIA_COMMON_SET_PROGRAM_INFORMATION() \
46  nn::pia::common::SetProgramInformation( \
47  NN_PIA_SDK_VER, \
48  NEX_VERSION_MAJOR, \
49  NEX_VERSION_MINOR, \
50  NEX_VERSION_MICRO)
51 
52 //! @}
53 //! @}
54 
55 
56 // Contains non-member functions in the common module.
57 
58 namespace nn
59 {
60 namespace pia
61 {
62 namespace common
63 {
64 
65 
66 /*!
67 @brief Indicates whether the <tt>common</tt> module is initialized.
68 
69 @return Returns <tt>true</tt> if initialized, and <tt>false</tt> otherwise.
70 */
71 bool IsInitialized(void);
72 
73 
74 /*!
75 @brief Initializes the <tt>common</tt> module.
76 
77 @details The heap used by the Pia library is configured during initialization.
78 Next, the function sets up an instance of the <tt>nn::pia::common::Log</tt> class so that macros like <tt>PIA_LOG</tt> can be used.
79 @if CTR_DOC
80 Pia uses thread-local storage implicitly to efficiently manage threads internally.
81 For more information, see the Programming Manual.
82 @endif
83 
84 @param[in] pMem Specifies a pointer to the start address of the memory block passed to the Pia library.
85 The buffer must be 4-byte aligned.
86 @param[in] size Specifies the size of the memory block passed in <span class="argument">pMem</span>. The value is in bytes.
87 The library asserts and stops execution if the size is not large enough to construct the heap.
88 
89 @return Returns a <tt>Result</tt> value indicating success if initialization succeeds. You must make sure that the implementation of this function in your application does not return any errors.
90 
91 @retval ResultInvalidArgument Specifies that an argument is invalid. Programming error. Fix your program so that this error is not returned.
92 @retval ResultAlreadyInitialized The module is already initialized. Programming error. Fix your program so that this error is not returned.
93 
94 
95 */
96 nn::Result Initialize(void* pMem, u32 size);
97 
98 
99 /*!
100 @brief Finalizes the <tt>common</tt> module.
101 
102 @details This function destroys the instance of <tt>nn::pia::common::Log</tt> created by the <tt>@ref Initialize</tt> function, and frees the memory supplied to the Pia library by the application in the call to <tt>@ref Initialize</tt>.
103 This function does nothing if the <tt>common</tt> module is not initialized when it is called.
104 
105 */
106 void Finalize(void);
107 
108 
109 /*!
110 @brief Declares the start of setup.
111 
112 @details Call this function before creating a singleton in the <tt>common</tt> module.
113 Always call this function and <tt>@ref EndSetup</tt> even if your application does not create any singletons in the <tt>common</tt> module.
114 
115 @return Returns a <tt>Result</tt> value indicating success if it is called at the right time. You must make sure that the implementation of this function in your application does not return any errors.
116 
117 @retval ResultNotInitialized The function for initializing the <tt>common</tt> module has not been called. Programming error. Fix your program so that this error is not returned.
118 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
119 
120 */
121 nn::Result BeginSetup(void);
122 
123 
124 /*!
125 @brief Declares the end of setup.
126 
127 @details Call this function after you are finished creating singletons and using other features of the <tt>common</tt> module.
128 Calling this function configures memory to be used by the <tt>common</tt> module singletons and optimizes memory management within the library.
129 Always call <tt>@ref BeginSetup</tt> and this function even if your application does not create any singletons in the <tt>common</tt> module.
130 
131 @return Returns a <tt>Result</tt> value indicating success if it is called at the right time. You must make sure that the implementation of this function in your application does not return any errors.
132 
133 @retval ResultNotInitialized The function for initializing the <tt>common</tt> module has not been called. Programming error. Fix your program so that this error is not returned.
134 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
135 
136 
137 */
138 nn::Result EndSetup(void);
139 
140 /*!
141 @brief Gets the amount of memory being used by the Pia library at the point this function is called.
142 
143 @details Do not call this function between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions of each module. If you call this function, an incorrect value is returned.
144 
145 @return Returns the amount of memory being used by the Pia library at the point this function was called.
146 If the <tt>common</tt> module is not set up, or if internal errors occur, <tt>0</tt> is returned.
147 
148 @retval 0 The Pia library has not been set up.
149 
150 
151 */
152 size_t GetMemoryUsage(void);
153 
154 
155 /*!
156 @cond PRIVATE
157 @brief Registers program information.
158 
159 @details Registers the NEX and SDK version numbers used by the application.
160 @endcond
161 */
162 void SetProgramInformation(u32 sdkVer, u8 nexMajorVer, u8 nexMinorVer, u8 nexMicroVer);
163 
164 
165 /*!
166 @cond PRIVATE
167 @brief Indicates whether an application is executing code between calls to the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions.
168 @endcond
169 */
170 bool IsInSetupMode(void);
171 
172 
173 /*!
174 @cond PRIVATE
175 @brief Prints debugging information.
176 @endcond
177 */
178 void PrintDebugInfo(void);
179 
180 
181 /*!
182 @cond PRIVATE
183 @brief Prints information about the environment.
184 @endcond
185 */
186 void PrintEnvironmentInfo(void);
187 
188 
189 /*!
190 @brief The callback type passed to <tt>RegisterInternalPrintCallback</tt>.
191 
192 @param[in] pStr Pointer to the head of the string. The string is not necessarily terminated by a null character.
193 @param[in] len The string length.
194 */
195 typedef void (*InternalPrintCallback)(const char* pStr, s32 len);
196 
197 
198 /*!
199 @brief Sets the callback that hooks the Pia console output.
200 
201 @param[in] pCallback Specifies a pointer to the callback function to register.
202 @return Returns a pointer to the callback function that was registered before this function was called.
203 <tt>NULL</tt> is returned if no callback function was registered.
204 */
206 
207 
208 #if NN_PIA_EXPERIMENT_USE_PRINT_HOOK
209 /*!
210 @cond PRIVATE
211 @brief Prints the string.
212 
213 @param[in] cpFormat Specifies the format string.
214 @param[in] varg Specifies the argument list.
215 */
216 void VPrintf(const char* cpFormat, va_list varg);
217 //! @endcond
218 
219 
220 /*!
221 @cond PRIVATE
222 @brief Prints the string.
223 
224 @param[in] cpFormat Specifies the format string.
225 @param[in] Specifies variable length arguments.
226 */
227  void Printf(const char* cpFormat, ...);
228 //! @endcond
229 #endif // end of NN_PIA_EXPERIMENT_USE_PRINT_HOOK
230 }
231 }
232 } // end of namespace nn::pia::common
void Finalize(void)
Finalizes the common module.
Definition: assert.h:115
nn::Result EndSetup(void)
Declares the end of setup.
bool IsInitialized(void)
Indicates whether the common module is initialized.
InternalPrintCallback RegisterInternalPrintCallback(InternalPrintCallback pCallback)
Sets the callback that hooks the Pia console output.
void(* InternalPrintCallback)(const char *pStr, s32 len)
The callback type passed to RegisterInternalPrintCallback.
Definition: common_Api.h:195
nn::Result Initialize(void *pMem, u32 size)
Initializes the common module.
nn::Result BeginSetup(void)
Declares the start of setup.
size_t GetMemoryUsage(void)
Gets the amount of memory being used by the Pia library at the point this function is called...