CTR Pia  4.11.3
Game Communication Engine
local_LocalFacade.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: local_LocalFacade.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/local/local_definitions.h>
18 #include <pia/local/local_LocalNetworkSetting.h>
19 #include <pia/common/common_RootObject.h>
20 
21 namespace nn
22 {
23 namespace pia
24 {
25 namespace transport
26 {
27 
28 class StationConnectionInfo;
29 }
30 }
31 } // end of namespace nn::pia::transport
32 
33 namespace nn
34 {
35 namespace pia
36 {
37 namespace local
38 {
39 
40 
41 /*!
42 @class nn::pia::local::LocalFacade
43 @brief Represents the facade (interface wrapper) class for the local communication library.
44 @date 2014-09-18 Changed the specifications so that <tt>ResultAlreadyExists</tt> is returned if you call <tt>CreateInstance</tt> when an instance already exists.
45 @date 2014-03-03 Initial version.
46 
47 */
49 {
50 public:
51 /*!
52 @name Singleton Instance Control
53  @{
54 */
55 
56 /*!
57 @brief Creates the <tt>LocalFacade</tt> class instance (singleton pattern).
58 @details You must call this function after the <tt>@ref LocalNetwork::CreateInstance</tt> function.
59 
60 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully.
61 @retval ResultNotInitialized Indicates that the <tt>local</tt> module is not initialized.
62 @retval ResultInvalidState Indicates that the instance was created at the wrong time.
63 @retval ResultAlreadyExists Indicates that an instance has already been created.
64 
65 
66 */
67  static nn::Result CreateInstance(void);
68 
69 
70 /*!
71 @brief Destroys the <tt>LocalFacade</tt> class instance (singleton pattern).
72 */
73  static void DestroyInstance(void);
74 
75 /*!
76 @brief Gets the <tt>LocalFacade</tt> class instance (singleton pattern).
77 @details Returns a <tt>NULL</tt> pointer if the instance has not yet been created using the <tt>@ref CreateInstance</tt> function.
78 @return Returns a pointer to the <tt>LocalFacade</tt> instance.
79 
80 
81 
82 */
83  static LocalFacade* GetInstance(void)
84  {
85  return s_pInstance;
86  }
87 
88 /*!
89 end of name Singleton Instance Control
90  @}
91 */
92 /*!
93 @name Finish Initialization
94  @{
95 */
96 
97 /*!
98 @brief Starts the <tt>LocalFacade</tt>.
99 @details This function can only be called when directly manipulated by the <tt>session::Mesh</tt> class.
100 This function has the following requirements.
101 <ul>
102 <li> A <tt>@ref nn::pia::transport::Transport</tt> instance must be available. </li>
103 <li> You must be connected to a local network. </li>
104 </ul>
105 The function fails if these conditions are not met.
106 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if startup succeeds. The following results are returned on failure.
107 @retval ResultInvalidState Indicates that availability conditions have not been met.
108 
109 
110 */
111  virtual nn::Result Startup();
112 
113 
114 /*!
115 @brief Cleans up the <tt>LocalFacade</tt>.
116 @details This function can only be called when directly manipulated by the <tt>session::Mesh</tt> class.
117 
118 */
119  virtual void Cleanup();
120 
121 /*!
122 end of name Finish Initialization
123  @}
124 */
125 
126 /*!
127 @brief Gets the <tt>StationConnectionInfo</tt> of the session host.
128 @param[out] pStationConnectionInfo Stores the session host's <tt>StationConnectionInfo</tt>.
129 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function return <tt>true</tt> if conversion succeeds. The following results are returned on failure.
130 @retval ResultInvalidState The state of the session host is invalid.
131 @retval ResultInvalidArgument Indicates that an invalid pointer was specified as the storage destination.
132 
133 
134 */
135  nn::Result GetHostStationConnectionInfo(nn::pia::transport::StationConnectionInfo* pStationConnectionInfo) const;
136 
137  /// @cond PRIVATE
138 /*!
139 @brief Destructor.
140 */
141  virtual ~LocalFacade(void);
142  /// @endcond
143 
144 
145  /// @cond PRIVATE
146 /*!
147 @brief Prints information that is useful for debugging.
148 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
149 
150 */
151  virtual void Trace(u64 flag) const;
152  /// @endcond
153 
154 
155 /*!
156 @cond PRIVATE
157 */
158  static void LocalFacadeUpdateEventCallback(LocalUpdateEvent updateEvent, u8 transportId, void* pParam);
159 //! @endcond
160 
161 #if 0
162 /*!
163 @name Registering and Unregistering Event Callbacks
164  @{
165 */
166 
167 /*!
168 @brief Registers the callback function called when the UDS network state changes.
169 @details This function wraps the <tt>@ref UdsNode::RegisterUpdateEventCallback</tt> function.
170 If you are using <tt>PiaSession</tt> and register or unregister <tt>UdsUpdateEventCallback</tt> objects, use <tt>@ref RegisterUpdateEventCallback</tt> and <tt>@ref UnregisterUpdateEventCallback</tt>, regardless of whether the <tt>PiaSession</tt> module has been initialized.
171 This function is a static function, because it can register and unregister callbacks even if there is no instance of the <tt>LocalFacade</tt> class.
172 @param[in] callback Specifies a pointer to the callback function being registered.
173 @param[in] pParam Specifies the pointer passed to the callback function when it is called.
174 @see UnregisterUpdateEventCallback, UdsNode::RegisterUpdateEventCallback, UdsNode::UnregisterUpdateEventCallback
175 
176 
177 
178 
179 
180 */
181  static void RegisterUpdateEventCallback(UdsUpdateEventCallback callback, void* pParam);
182 
183 /*!
184 @brief Unregisters the registered callback function for network state changes.
185 @details This function wraps the <tt>@ref UdsNode::UnregisterUpdateEventCallback</tt> function.
186 If you are using <tt>PiaSession</tt> and register or unregister <tt>UdsUpdateEventCallback</tt> objects, use <tt>@ref RegisterUpdateEventCallback</tt> and <tt>@ref UnregisterUpdateEventCallback</tt>, regardless of whether the <tt>PiaSession</tt> module has been initialized.
187 This function is a static function, because it can register and unregister callbacks even if there is no instance of the <tt>UdsFacade</tt> class.
188 @see RegisterUpdateEventCallback, UdsNode::RegisterUpdateEventCallback, UdsNode::UnregisterUpdateEventCallback
189 
190 
191 
192 
193 */
194  static void UnregisterUpdateEventCallback();
195 
196 /*!
197 end of name Register and Unregister Event Callbacks
198  @}
199 */
200  static void PrepareNodeIdCallback(u16 localNodeId, u16 hostNodeId, void* pParam);
201 
202  NODE_ID_TYPE GetHostTransportNodeId();
203  NODE_ID_TYPE GetLocalTransportNodeId();
204 
205 #endif
206 
207 protected:
208 private:
209 /*!
210 @name Get StationConnectionInfo
211  @{
212 */
213 
214 /*!
215 @brief Converts a <tt>TransportId</tt> to a <tt>StationConnectionInfo</tt>.
216 @param[in] transportId Specifies the <tt>TransportId</tt> you want to convert.
217 @param[out] pStationConnectionInfo Specifies a pointer to the converted <tt>StationConnectionInfo</tt> instance.
218 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function return <tt>true</tt> if conversion succeeds. The following results are returned on failure.
219 @retval ResultInvalidArgument Indicates that an invalid <tt>TransportId</tt> was specified, or an invalid out pointer was specified.
220 
221 
222 */
223  nn::Result ConvertTransportIdToStationConnectionInfo(
224  u8 transportNodeId,
225  nn::pia::transport::StationConnectionInfo* pStationConnectionInfo) const;
226 
227 /*!
228 end of name Get <tt>StationConnectionInfo</tt>
229  @}
230 */
231 
232 private:
233  /// @cond PRIVATE
234 /*!
235 @brief This default constructor is private because this class implements the singleton pattern.
236 */
237  LocalFacade(void);
238  /// @endcond
239 
240  /// @cond PRIVATE
241 /*!
242 @brief This copy constructor is private because the singleton pattern is used.
243 */
244  LocalFacade(const LocalFacade&);
245  /// @endcond
246 
247  /// @cond PRIVATE
248 /*!
249 @brief This assignment operator is private because the singleton pattern is used.
250 */
251  LocalFacade& operator=(const LocalFacade&);
252  /// @endcond
253 
254 
255  // A pointer to a singleton instance.
256  static LocalFacade* s_pInstance;
257 
258 #if 0
259  common::CriticalSection m_Lock;
260  NODE_ID_TYPE m_HostTransportNodeId;
261  NODE_ID_TYPE m_LocalTransportNodeId;
262 #endif
263  bool m_IsStarted;
264 
265 #if 0
266  static UdsUpdateEventCallback s_pfAppUpdateEventCallback;
267  static void* s_pAppUpdateEventCallbackParam;
268 #endif
269 };
270 }
271 }
272 } // end of namespace nn::pia::local
Definition: assert.h:115
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
Represents an address used to uniquely identify stations.
Definition: transport_StationConnectionInfo.h:35
Represents the facade (interface wrapper) class for the local communication library. .
Definition: local_LocalFacade.h:48
static LocalFacade * GetInstance(void)
Gets the LocalFacade class instance (singleton pattern).
Definition: local_LocalFacade.h:83
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40