CTR Pia  4.11.3
Game Communication Engine
transport_StationManager.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_StationManager.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/transport/transport_definitions.h>
18 
19 #include <pia/transport/transport_Singleton.h>
20 #include <pia/transport/transport_Station.h>
21 
22 #include <pia/common/common_ObjList.h>
23 #include <pia/common/common_SimpleContainer.h>
24 
25 
26 // Forward declarations (<tt>PiaCommon</tt>).
27 namespace nn
28 {
29 namespace pia
30 {
31 namespace common
32 {
33 class InetAddress;
34 }
35 }
36 }
37 
38 
39 namespace nn
40 {
41 namespace pia
42 {
43 namespace transport
44 {
45 
46 
47 /*!
48 @brief Represents a class for unifying multiple <tt>Station</tt> instances.
49 @details The <tt>Transport</tt> class constructs and destroys the <tt>StationManager</tt> instance.
50 There is no need for the application to call the <tt>CreateInstance</tt> or <tt>DestroyInstance</tt> functions of the <tt>StationManager</tt> class.
51 @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.
52 @date 2014-07-15 Changed how the <tt>GetStationAddress</tt> and <tt>GetStation</tt> functions operate when they are passed invalid arguments.
53 @date 2012-06-28 Clearly indicated which functions are thread-safe.
54 @date 2012-04-06 Initial version.
55 
56 
57 
58 */
60 {
61 public:
62  typedef common::ObjList<Station> TStationList;
63  typedef common::SimpleContainer<Station*, static_cast<int>(MAX_STATION_NUM)> TStationPtrArray;
64 
65 /*!
66 @brief Represents an iterator for referring to the <tt>Station</tt>s participating in a session (non-<tt>const</tt> version).
67 */
68  class Iterator
69  {
70  public:
71  Iterator(TStationPtrArray::Iterator it)
72  : m_Iterator(it)
73  {
74  }
75  Station& operator*(void)
76  {
77  return **m_Iterator;
78  }
79  Station* operator->(void)
80  {
81  return *m_Iterator;
82  }
83  bool operator==(const Iterator& rhs) const
84  {
85  return m_Iterator == rhs.m_Iterator;
86  }
87  bool operator!=(const Iterator& rhs) const
88  {
89  return !(*this == rhs);
90  }
91  Iterator& operator++(void)
92  {
93  ++m_Iterator;
94  return *this;
95  }
96 
97  private:
98  TStationPtrArray::Iterator m_Iterator;
99  };
100 
101 /*!
102 @brief Represents an iterator for referring to the <tt>Station</tt>s participating in a session (<tt>const</tt> version).
103 */
105  {
106  public:
107  ConstIterator(TStationPtrArray::ConstIterator it)
108  : m_ConstIterator(it)
109  {
110  }
111  const Station& operator*(void)
112  {
113  return **m_ConstIterator;
114  }
115  const Station* operator->(void)
116  {
117  return *m_ConstIterator;
118  }
119  bool operator==(const ConstIterator& rhs) const
120  {
121  return m_ConstIterator == rhs.m_ConstIterator;
122  }
123  bool operator!=(const ConstIterator& rhs) const
124  {
125  return !(*this == rhs);
126  }
127  ConstIterator& operator++(void)
128  {
129  ++m_ConstIterator;
130  return *this;
131  }
132 
133  private:
134  TStationPtrArray::ConstIterator m_ConstIterator;
135  };
136 
137 
138 /*!
139 @brief Creates the <tt>StationManager</tt> class instance (singleton pattern).
140 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully.
141 @retval ResultNotInitialized Indicates that the <tt>transport</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
142 @retval ResultInvalidState Indicates that the timing at which the <tt>CreateInstance</tt> function was called is incorrect. Make this call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
143 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
144 @see DestroyInstance, GetInstance
145 
146 */
147  static nn::Result CreateInstance(void);
148 
149 
150 /*!
151 @brief Destroys the <tt>StationManager</tt> class instance (singleton pattern).
152 @see CreateInstance, GetInstance
153 */
154  static void DestroyInstance(void);
155 
156 
157 /*!
158 @brief Gets the <tt>StationManager</tt> class instance (singleton pattern).
159 This function returns a <tt>NULL</tt> pointer if the instance has not yet been created using the <tt>@ref CreateInstance</tt> function.
160 This function is thread-safe.
161 @return Returns a pointer to the instance.
162 @see CreateInstance, DestroyInstance
163 
164 
165 */
167  {
168  return s_pInstance;
169  }
170 
171 
172 /*!
173 @cond PRIVATE
174 @brief Instantiates the object with default parameters (default constructor).
175 */
176  StationManager(void);
177  //! @endcond
178 
179 
180 /*!
181 @cond PRIVATE
182 @brief Destroys the object.
183 */
184  ~StationManager(void);
185  //! @endcond
186 
187 
188 /*!
189 @cond PRIVATE
190 @brief Initializes the <tt>StationManager</tt> instance.
191 @param[in] pFactory Specifies a pointer to an instance of a concrete class that inherits <tt>NetworkFactory</tt> (factory pattern).
192 @param[in] maxStations Specifies the maximum number of stations to manage.
193 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
194 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
195 @retval ResultAllocationFailed Indicates that the function failed to allocate memory. Either provide more memory when calling the <tt>common::Initialize</tt> function, or set the <tt>maxStations</tt> argument to a smaller value. Programming error. Fix your program so that this error is not returned.
196 @see Finalize
197 
198 */
199  nn::Result Initialize(NetworkFactory* pFactory, size_t maxStations);
200  //! @endcond
201 
202 
203 /*!
204 @cond PRIVATE
205 @brief Destroys the <tt>StationManager</tt> instance.
206 @see Initialize
207 
208 */
209  void Finalize(void);
210  //! @endcond
211 
212 
213 /*!
214 @brief Returns the iterator of the <tt>Station</tt> instance (non-<tt>const</tt> version).
215 @return Returns the iterator for the first element of <tt>Station</tt> instances managed by <tt>StationManager</tt>.
216 @see End
217 
218 
219 */
221  {
222  return Iterator(m_ValidStationPtr.Begin());
223  }
224 
225 
226 /*!
227 @brief Returns the iterator of the <tt>Station</tt> instance (non-<tt>const</tt> version).
228 @return Returns the iterator for the last element of <tt>Station</tt> instances managed by <tt>StationManager</tt>.
229 @see Begin
230 
231 
232 */
233  Iterator End(void)
234  {
235  return Iterator(m_ValidStationPtr.End());
236  }
237 
238 
239 /*!
240 @brief Returns the iterator of the <tt>Station</tt> instance ( <tt>const</tt> version).
241 @return Returns the iterator for the first element of <tt>Station</tt> instances managed by <tt>StationManager</tt>.
242 @see End
243 
244 
245 */
246  ConstIterator Begin(void) const
247  {
248  return ConstIterator(m_ValidStationPtr.Begin());
249  }
250 
251 
252 /*!
253 @brief Returns the iterator of the <tt>Station</tt> instance ( <tt>const</tt> version).
254 @return Returns the iterator for the last element of <tt>Station</tt> instances managed by <tt>StationManager</tt>.
255 @see Begin
256 
257 
258 */
259  ConstIterator End(void) const
260  {
261  return ConstIterator(m_ValidStationPtr.End());
262  }
263 
264 
265 /*!
266 @cond PRIVATE
267 @brief Creates a <tt>Session</tt> instance for the local station.
268 @return On success, returns a pointer to the created <tt>Station</tt> instance.
269 Returns <tt>NULL</tt> on failure (such as when a local station has already been created).
270 @see CreateStation
271 
272 */
273  Station* CreateLocalStation(void);
274  //! @endcond
275 
276 
277 /*!
278 @cond PRIVATE
279 @brief Creates a <tt>Station</tt> instance.
280 @return On success, returns a pointer to the created <tt>Station</tt> instance.
281 This function returns <tt>NULL</tt> if the number of stations has already reached the maximum number of stations specified when <tt>Initialize</tt> was called.
282 @see CreateLocalStation, Initialize
283 
284 
285 */
286  Station* CreateStation(void);
287  //! @endcond
288 
289 
290 /*!
291 @cond PRIVATE
292 @brief Destroys the specified <tt>Station</tt> instance.
293 @param[in] pStation Specifies a pointer to the <tt>Station</tt> instance to destroy. This pointer must have been obtained from the <tt>StationManager</tt> instance.
294 @see CreateStation, CreateLocalStation
295 
296 */
297  void DestroyStation(Station* pStation);
298  //! @endcond
299 
300 
301 /*!
302 @cond PRIVATE
303 @brief Destroys the <tt>Station</tt> instance with the specified <tt>StationIndex</tt>.
304 @param[in] idx Specifies the <tt>StationIndex</tt> of the station to destroy.
305 @see CreateStation, CreateLocalStation
306 
307 */
308  void DestroyStation(StationIndex idx);
309  //! @endcond
310 
311 
312 /*!
313 @brief Gets the local station (non-<tt>const</tt> version).
314 @details This function is thread-safe.
315 
316 @return Returns a valid pointer if a local station exists. If none exists, a <tt>NULL</tt> pointer is returned.
317 
318 */
320  {
321  return m_pLocalStation;
322  }
323 
324 
325 /*!
326 @brief Gets the local station ( <tt>const</tt> version).
327 @details This function is thread-safe.
328 
329 @return Returns a valid pointer if a local station exists. If none exists, a <tt>NULL</tt> pointer is returned.
330 
331 */
332  const Station* GetLocalStation(void) const
333  {
334  return m_pLocalStation;
335  }
336 
337 
338 /*!
339 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationId</tt> (non-<tt>const</tt> version).
340 @param[in] id Specifies the <tt>StationId</tt>.
341 @return If the <tt>Station</tt> corresponding to the specified <tt>StationId</tt> exists, a pointer to that <tt>Station</tt> is returned. A <tt>NULL</tt> pointer is returned if the <tt>StationId</tt> does not exist or is invalid.
342 @see GetStationByAddress
343 
344 */
345  Station* GetStation(StationId id);
346 
347 
348 /*!
349 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationId</tt> ( <tt>const</tt> version).
350 @param[in] id Specifies the <tt>StationId</tt>.
351 @return If the <tt>Station</tt> corresponding to the specified <tt>StationId</tt> exists, a pointer to that <tt>Station</tt> is returned. A <tt>NULL</tt> pointer is returned if the <tt>StationId</tt> does not exist or is invalid.
352 @see GetStationByAddress
353 
354 */
355  const Station* GetStation(StationId id) const;
356 
357 
358 /*!
359 @cond PRIVATE
360 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationIndex</tt> (non-<tt>const</tt> version).
361 @param[in] idx The <tt>StationIndex</tt>.
362 @return If the <tt>Station</tt> corresponding to the specified <tt>StationIndex</tt> exists, a pointer to that <tt>Station</tt> is returned. A <tt>NULL</tt> pointer is returned if the <tt>StationIndex</tt> does not exist or is invalid.
363 @see GetStationByAddress
364 
365 */
366  Station* GetStation(StationIndex idx);
367  //! @endcond
368 
369 
370 /*!
371 @cond PRIVATE
372 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationIndex</tt> ( <tt>const</tt> version).
373 @param[in] idx The <tt>StationIndex</tt>.
374 @return If the <tt>Station</tt> corresponding to the specified <tt>StationIndex</tt> exists, a pointer to that <tt>Station</tt> is returned. A <tt>NULL</tt> pointer is returned if the <tt>StationIndex</tt> does not exist or is invalid.
375 @see GetStationByAddress
376 
377 */
378  const Station* GetStation(StationIndex idx) const;
379  //! @endcond
380 
381 
382 /*!
383 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationAddress</tt> (non-<tt>const</tt> version).
384 @param[in] addr Specifies the station address.
385 @return If the <tt>Station</tt> with the specified station address exists, a pointer to that <tt>Station</tt> is returned. If none exists, a <tt>NULL</tt> pointer is returned.
386 @see GetStationByAddress
387 
388 */
389  Station* GetStation(const common::StationAddress& addr);
390 
391 
392 /*!
393 @brief Gets the <tt>Station</tt> corresponding to the <tt>StationAddress</tt> ( <tt>const</tt> version).
394 @param[in] addr Specifies the station address.
395 @return If the <tt>Station</tt> with the specified station address exists, a pointer to that <tt>Station</tt> is returned. If none exists, a <tt>NULL</tt> pointer is returned.
396 @see GetStationByAddress
397 
398 */
399  const Station* GetStation(const common::StationAddress& addr) const;
400 
401 
402 /*!
403 @brief Gets the station with the specified Internet address (non-<tt>const</tt> version).
404 @param[in] addr Specifies the Internet address.
405 @return If the <tt>Station</tt> corresponding to the specified Internet address exists, a pointer to that <tt>Station</tt> is returned. If none exists, a <tt>NULL</tt> pointer is returned.
406 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
407 @see GetStation
408 
409 */
410  Station* GetStationByAddress(const common::InetAddress& addr);
411 
412 
413 /*!
414 @brief Gets the <tt>Station</tt> corresponding to the Internet address ( <tt>const</tt> version).
415 @param[in] addr Specifies the Internet address.
416 @return If the <tt>Station</tt> corresponding to the specified Internet address exists, a pointer to that <tt>Station</tt> is returned. If none exists, a <tt>NULL</tt> pointer is returned.
417 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
418 @see GetStation
419 
420 */
421  const Station* GetStationByAddress(const common::InetAddress& addr) const;
422 
423 
424 /*!
425 @brief Gets the <tt>StationAddress</tt> for the <tt>Station</tt> corresponding to the <tt>StationId</tt>.
426 @param[out] pAddr Specifies a pointer to a <tt>StationAddress</tt> instance that will hold the result.
427 @param[in] id Specifies the <tt>StationId</tt>.
428 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
429 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. This <tt>Result</tt> is returned if the <tt>StationId</tt> is invalid. Programming error. Fix your program so that this error is not returned.
430 @retval ResultNotFound Indicates that the <tt>Station</tt> specified in the arguments was not found. Handle appropriately in the application.
431 
432 */
433  nn::Result GetStationAddress(common::StationAddress* pAddr, StationId id) const;
434 
435 
436 /*!
437 @cond PRIVATE
438 @brief Gets the <tt>StationAddress</tt> for the <tt>Station</tt> corresponding to the <tt>StationIndex</tt>.
439 @param[out] pAddr Specifies a pointer to a <tt>StationAddress</tt> instance that will hold the result.
440 @param[in] idx The <tt>StationIndex</tt>.
441 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
442 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. This <tt>Result</tt> is returned if the <tt>StationIndex</tt> is invalid. Programming error. Fix your program so that this error is not returned.
443 @retval ResultNotFound Indicates that the <tt>Station</tt> specified in the arguments was not found. Handle appropriately in the application.
444 
445 */
446  nn::Result GetStationAddress(common::StationAddress* pAddr, StationIndex idx) const;
447  //! @endcond
448 
449 
450 /*!
451 @cond PRIVATE
452 @brief Returns the number of currently valid <tt>Station</tt> instances.
453 @return Returns the number of currently valid <tt>Station</tt> instances.
454 
455 */
456  size_t GetValidStationNum(void) const;
457  //! @endcond
458 
459 
460 /*!
461 @cond PRIVATE
462 @brief Returns a bitmap with bits set corresponding to the <tt>StationIndex</tt> of the stations in the session.
463 @param[in] bIncludeMyself Specify <tt>true</tt> if you want to include the bit corresponding to the local station <tt>StationIndex</tt> in the bitmap.
464 
465 @return Returns a bitmap value. The least significant bit (LSB) corresponds to <tt>STATION_INDEX_1</tt>.
466 
467 */
468  u32 GetParticipatingStationBitmap(bool bIncludeMyself) const;
469  //! @endcond
470 
471 
472 /*!
473 @cond PRIVATE
474 @brief Gets called by <tt>session</tt>. Sets the <tt>StationIndex</tt> for the session host.
475 */
476  void SetHostStationIndex(StationIndex idx)
477  {
478  m_HostStationIndex = idx;
479  }
480  //! @endcond
481 
482 
483 /*!
484 @cond PRIVATE
485 @brief Gets the <tt>StationIndex</tt> of the host.
486 */
487  StationIndex GetHostStationIndex(void) const
488  {
489  return m_HostStationIndex;
490  }
491  //! @endcond
492 
493 
494 /*!
495 @brief Prints information that is useful for debugging.
496 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
497 
498 */
499  virtual void Trace(u64 flag) const;
500 
501 
502 private:
503  TStationList m_StationList; // Manage the station instance.
504  u8* m_pWorkBuf; // The buffer for <span class="argument">m_StationList</span>
505 
506  TStationPtrArray m_ValidStationPtr; // Manage the pointer to the currently enabled station.
507  TStationPtrArray m_InvalidStationPtr; // Manage the pointer to the currently disabled station.
508 
509  bool isInStationList(const Station* pStation) const;
510  bool isInPtrArray(const TStationPtrArray& ptrArray, const Station* pStation) const;
511 
512  Station* m_pLocalStation;
513 
514  StationIndex m_HostStationIndex;
515 
516  static StationManager* s_pInstance; // The only instantiation of this class
517 };
518 }
519 }
520 } // end of namespace nn::pia::transport
Station * GetLocalStation(void)
Gets the local station (non-const version).
Definition: transport_StationManager.h:319
void Finalize(void)
Finalizes the common module.
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
Definition: assert.h:115
Represents a station. A station refers to a machine participating in a Pia session.
Definition: transport_Station.h:75
Iterator Begin(void)
Returns the iterator of the Station instance (non-const version).
Definition: transport_StationManager.h:220
const Station * GetLocalStation(void) const
Gets the local station ( const version).
Definition: transport_StationManager.h:332
const size_t MAX_STATION_NUM
The maximum value for the number of stations that can participate in a Pia session.
Definition: platformCtr.h:64
Represents an iterator for referring to the Stations participating in a session (non-const version)...
Definition: transport_StationManager.h:68
Represents an address used to uniquely identify stations. .
Definition: common_StationAddress.h:43
An interface (factory pattern) for generating the classes needed by the network.
Definition: transport_NetworkFactory.h:89
Iterator End(void)
Returns the iterator of the Station instance (non-const version).
Definition: transport_StationManager.h:233
nn::Result Initialize(void *pMem, u32 size)
Initializes the common module.
Represents an iterator for referring to the Stations participating in a session (const version)...
Definition: transport_StationManager.h:104
Represents a class for unifying multiple Station instances.
Definition: transport_StationManager.h:59
Class that represents an Internet address.
Definition: common_InetAddress.h:52
ConstIterator End(void) const
Returns the iterator of the Station instance ( const version).
Definition: transport_StationManager.h:259
ConstIterator Begin(void) const
Returns the iterator of the Station instance ( const version).
Definition: transport_StationManager.h:246
static StationManager * GetInstance(void)
Gets the StationManager class instance (singleton pattern). This function returns a NULL pointer if t...
Definition: transport_StationManager.h:166
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40