CTR Pia  4.11.3
Game Communication Engine
inet_Api.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: inet_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/inet/inet_definitions.h>
18 
19 
20 // This is the group of non-member functions for the <tt>inet</tt> module.
21 
22 namespace nn
23 {
24 namespace pia
25 {
26 namespace inet
27 {
28 
29 
30 /*!
31  @brief Indicates whether the <tt>inet</tt> module is initialized.
32 
33  @return Returns <tt>true</tt> if initialized, or <tt>false</tt> otherwise.
34 */
35 bool IsInitialized(void);
36 
37 
38 /*!
39  @brief Stores parameters used by the <tt>Initialize</tt> function.
40 */
41 struct Setting
42 {
43  size_t mtuSize; //!< Specify the MTU of a packet. The value is in bytes. Specify a value in the range from <tt>@ref MIN_MTU_SIZE</tt> through <tt>@ref MAX_MTU_SIZE</tt>.
44 };
45 
46 const size_t MAX_MTU_SIZE = 1364; //!< Defines the maximum MTU that can be specified in <tt>@ref Setting</tt>.
47 const size_t MIN_MTU_SIZE = 576; //!< Defines the minimum MTU that can be specified in <tt>@ref Setting</tt>
48 const size_t DEFAULT_MTU_SIZE = 1240; //!< Defines the default MTU that is specified in <tt>@ref Setting</tt>.
49 
50 /*!
51  @brief (For debugging.) This structure stores the debug feature settings that are passed to <tt>@ref nn::pia::inet::SetDebugSetting</tt>.
52 */
54 {
55  DebugSetting(bool argIsEnableNatTraversalFailureEmulation = false)
56  : isEnableNatTraversalFailureEmulation(argIsEnableNatTraversalFailureEmulation)
57  {
58  }
59  bool isEnableNatTraversalFailureEmulation; //!< This setting makes NAT transversal fail for debugging purposes.
60 };
61 
62 /*!
63  @brief Initializes the <tt>inet</tt> module.
64 
65  @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.
66 
67  @retval nn::pia::ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
68  @retval nn::pia::ResultAlreadyInitialized Indicates that the module is already initialized. Programming error. Fix your program so that this error is not returned.
69 
70  @see Setting
71 */
72 nn::Result Initialize(const Setting& setting);
73 
74 
75 /*!
76  @brief Finalizes the <tt>inet</tt> module.
77 */
78 void Finalize(void);
79 
80 
81 /*!
82  @brief Declares the start of setup.
83 
84  @details Call this function before creating a singleton in the <tt>inet</tt> module.
85  Call this function and the <tt>@ref EndSetup</tt> function even when the application
86  does not create any singletons in the <tt>inet</tt> module.
87 
88  @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.
89 
90  @retval nn::pia::ResultNotInitialized Indicates that the function for initializing the <tt>inet</tt> module has not been called. Programming error. Fix your program so that this error is not returned.
91  @retval nn::pia::ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
92 */
93 nn::Result BeginSetup(void);
94 
95 
96 /*!
97  @brief Declares the end of setup.
98 
99  @details Call this function after creation of a singleton in the <tt>inet</tt> module is complete.
100  Calling this function configures memory to be used by the <tt>inet</tt> module singletons,
101  and optimizes memory management within the library.
102  Always call the <tt>@ref BeginSetup</tt> function and this function even if the application
103  does not create any singletons in the <tt>inet</tt> module.
104 
105  @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.
106 
107  @retval nn::pia::ResultNotInitialized Indicates that the function for initializing the <tt>inet</tt> module has not been called. Programming error. Fix your program so that this error is not returned.
108  @retval nn::pia::ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
109 */
110 nn::Result EndSetup(void);
111 
112 
113 /*!
114  @cond PRIVATE
115  @brief Gets whether an application is executing code between calls to the <tt>BeginSetup()</tt> and <tt>EndSetup()</tt> functions.
116  @endcond
117 */
118 bool IsInSetupMode(void);
119 
120 /*!
121  @brief (For debugging.) Configures the <tt>inet</tt> debugging feature.
122 
123  @details This function can be called when there is no <tt>inet</tt> instance.
124 
125  If <tt><var>isEnableNatErrorEmulation</var></tt> of the <tt>DebugSetting</tt> structure is set to <tt>true</tt>, this setting makes NAT transversal fail on an error.
126 
127  If this function is not called, all related debugging features are disabled.
128 
129  @attention Do not call this function in retail ROMs.
130 
131  @return Returns the result of the function. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. This function always succeeds.
132 */
133 nn::Result SetDebugSetting(const DebugSetting& debugSetting);
134 
135 /*!
136  @cond PRIVATE
137  @brief Returns the setting for the debugging feature.
138  @endcond
139 */
140 DebugSetting* GetDebugSetting();
141 
142 /*!
143  @if CAFE_DOC
144  @brief Stops the network interface.
145  @details Use this function to debug the handling of abnormal disconnection
146  of the network interface during communication.
147 
148  If the network interface is stopped, it is automatically restarted.
149  Note, however, that the other communication-related libraries continue to run while the interface is stopped and
150  fall into an inoperable state. This necessitates a restart of those libraries.
151  @endif
152 */
153 void ControlNetworkIfDown();
154 
155 }
156 }
157 } // end of namespace nn::pia::inet
bool IsInitialized(void)
Indicates whether the inet module is initialized.
size_t mtuSize
Specify the MTU of a packet. The value is in bytes. Specify a value in the range from MIN_MTU_SIZE th...
Definition: inet_Api.h:43
const size_t MAX_MTU_SIZE
Defines the maximum MTU that can be specified in Setting.
Definition: inet_Api.h:46
nn::Result Initialize(const Setting &setting)
Initializes the inet module.
Definition: assert.h:115
Stores parameters used by the Initialize function.
Definition: inet_Api.h:41
nn::Result EndSetup(void)
Declares the end of setup.
nn::Result SetDebugSetting(const DebugSetting &debugSetting)
(For debugging.) Configures the inet debugging feature.
nn::Result BeginSetup(void)
Declares the start of setup.
const size_t DEFAULT_MTU_SIZE
Defines the default MTU that is specified in Setting.
Definition: inet_Api.h:48
const size_t MIN_MTU_SIZE
Defines the minimum MTU that can be specified in Setting
Definition: inet_Api.h:47
bool isEnableNatTraversalFailureEmulation
This setting makes NAT transversal fail for debugging purposes.
Definition: inet_Api.h:59
(For debugging.) This structure stores the debug feature settings that are passed to nn::pia::inet::S...
Definition: inet_Api.h:53
void Finalize(void)
Finalizes the inet module.