CTR Pia  4.11.3
Game Communication Engine
clone_EventCloneElement.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: clone_EventCloneElement.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/clone/clone_definitions.h>
18 #include <pia/clone/clone_EventCloneElementBase.h>
19 #include <pia/clone/clone_SerializePolicyDefinition.h>
20 
21 namespace nn
22 {
23 namespace pia
24 {
25 namespace clone
26 {
27 
28 
29 /*!
30 @brief Manages the sending and receiving of events.
31 
32 @tparam Value_ Specifies the value type to specify when raising an event. You must specify a value even if none is required.
33 @tparam BUFFER_SIZE Specifies the size of the event buffer. Specify a positive value.
34 @tparam SerializePolicy_ Specifies the algorithm to use for serializing \a Value.
35 
36 @date 2013-07-18 Initial version.
37 */
38 template <typename Value_, size_t BUFFER_SIZE, typename SerializePolicy_ = HostByteOrderSerializePolicy<Value_> >
40 {
41 public:
42 /*!
43 @brief Specifies the argument type to be sent with this event.
44 */
45  typedef Value_ Value;
46 
47 /*!
48 @brief Specifies the algorithm to use for serializing \a Value.
49 */
50  typedef SerializePolicy_ SerializePolicy;
51 
52 
53 /*!
54 @brief Instantiates the object with default parameters (default constructor).
55 */
57 
58 
59 /*!
60 @brief Destroys the object.
61 */
63  {
64  }
65 
66 
67 /*!
68 @brief Raises an event.
69 @param[in] value The event's value.
70 @param[in] isEnableSendDelay Specifying <tt>true</tt> defers the sending of data. The data is then sent along with other immediate-send items among the elements registered to the same clone.
71 The maximum deferment time can be specified using the <tt>CloneProtocol::SetMaxSendDelay</tt> function. After that time elapses, the data is sent even if there is no other data to send.
72 This feature can reduce the number of packets sent, but also delays the arrival of packets by the deferment time.
73 Specify <tt>false</tt> to send the data immediately.
74 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
75 @retval ResultInvalidState Specifies that the registered clone cannot send in its current state. Programming error. Fix your program so that this error is not returned.
76 @retval ResultBufferIsFull Specifies that the event cannot be raised because the buffer is full. Handle appropriately in the application.
77 */
78  nn::Result SetValue(const Value& value, bool isEnableSendDelay = false);
79 
80 
81 /*!
82 @brief References the next event.
83 @details The event currently being referenced can be accessed until the <tt>HandleNext</tt> function is called again.
84 @return Returns the value for the newly referenced event. Returns <tt>NULL</tt> when there is no next event.
85 */
86  const Value* HandleNext()
87  {
88  HandleNextCore();
89  return GetValue();
90  }
91 
92 
93 /*!
94 @brief Gets the pointer to the value for when the current event was raised.
95 @return Returns the pointer to the value for when the current event was raised. The return value is the same as the value returned when <tt>HandleNext</tt> was last called. Returns <tt>NULL</tt> when no event is being referenced.
96 */
97  const Value* GetValue() const
98  {
99  return (GetHandlingEventToken() != NULL) ? &(static_cast<const EventToken*>(GetHandlingEventToken())->GetValue()) : NULL;
100  }
101 
102 
103 /*!
104 @brief Gets the pointer to the issued time for when the current event was raised.
105 @return Returns the pointer to the issued time for when the current event was raised. Returns <tt>NULL</tt> when no event is being referenced.
106 */
107  const ClockValue* GetClock() const
108  {
109  return (GetHandlingEventToken() != NULL) ? (&GetHandlingEventToken()->GetClock()) : NULL;
110  }
111 
112 
113 /*!
114 @brief Gets the index of the station that raised the event being referenced.
115 @return Returns the index of the station that raised the event being referenced. If no event is being referenced, <tt>STATION_INDEX_INVALID</tt> is returned.
116 */
118  {
119  return (GetHandlingEventToken() != NULL) ? GetHandlingEventToken()->GetSetterStationIndex() : STATION_INDEX_INVALID;
120  }
121 
122 
123 /*!
124 @brief Gets the index of the event currently being referenced.
125 @return Returns the index of the event currently being referenced. If no event is being referenced, <tt>0</tt> is returned.
126 */
127  Index GetEventIndex() const
128  {
129  return (GetHandlingEventToken() != NULL) ? GetHandlingEventToken()->GetIndex() : 0;
130  }
131 
132 protected:
133  virtual size_t GetSize() const
134  {
135  return SerializePolicy::GetSize();
136  }
137 
138 
139 private:
140  class EventToken : public EventTokenBase
141  {
142  public:
143  EventToken()
144  : EventTokenBase(), m_Value()
145  {
146  }
147  void SetValue(const Value& value)
148  {
149  m_Value = value;
150  }
151  const Value& GetValue() const
152  {
153  return m_Value;
154  }
155 
156  virtual void Serialize(void* pBuffer) const;
157  virtual void Deserialize(const void* cpBuffer);
158 
159  private:
160  Value m_Value;
161  };
162 
163 
164  class EventTokenBuffer : public EventTokenBufferBase
165  {
166  public:
167  explicit EventTokenBuffer(EventCloneElementBase* pElement);
168 
169  protected:
170  virtual EventTokenBase* At(int idx)
171  {
172  return &m_EventTokenArray[idx];
173  }
174  virtual const EventTokenBase* At(int idx) const
175  {
176  return &m_EventTokenArray[idx];
177  }
178 
179  private:
180  EventToken m_EventTokenArray[BUFFER_SIZE];
181  };
182 
183 
184  EventTokenBuffer m_EventTokenBuffer;
185 };
186 
187 
188 //! @cond
189 
190 template <typename Value, size_t BUFFER_SIZE, typename SerializePolicy>
192  : EventCloneElementBase(&m_EventTokenBuffer),
193  m_EventTokenBuffer(this)
194 {
195  PIA_COMPILE_ASSERT(BUFFER_SIZE >= cBufferSizeMin && BUFFER_SIZE <= cBufferSizeMax);
196 }
197 
198 
199 template <typename Value, size_t BUFFER_SIZE, typename SerializePolicy>
200 nn::Result EventCloneElement<Value, BUFFER_SIZE, SerializePolicy>::SetValue(const Value& value, bool isEnableSendDelay)
201 {
202  EventTokenBase* pTokenBase;
203  Result r = SetValueCore(&pTokenBase, isEnableSendDelay);
204  if (r.IsSuccess() && pTokenBase != NULL)
205  {
206  EventToken* pToken = static_cast<EventToken*>(pTokenBase);
207  pToken->SetValue(value);
208  }
209  return r;
210 }
211 
212 
213 template <typename Value, size_t BUFFER_SIZE, typename SerializePolicy>
215 {
216  SerializePolicy::Serialize(pBuffer, m_Value);
217 }
218 
219 
220 template <typename Value, size_t BUFFER_SIZE, typename SerializePolicy>
222 {
223  SerializePolicy::Deserialize(&m_Value, cpBuffer);
224 }
225 
226 
227 template <typename Value, size_t BUFFER_SIZE, typename SerializePolicy>
229  : EventTokenBufferBase(BUFFER_SIZE)
230 {
231  for (u32 i = 0; i < BUFFER_SIZE; ++i)
232  {
233  m_EventTokenArray[i].Init(pElement);
234  m_EventTokenArray[i].SetState(EventTokenBase::EVENT_TOKEN_STATE_EMPTY);
235  m_EventTokenArray[i].SetIndex(static_cast<Index>(i));
236  }
237 }
238 
239 //! @endcond
240 }
241 }
242 } // end of namespace nn::pia::clone
SerializePolicy_ SerializePolicy
Specifies the algorithm to use for serializing Value.
Definition: clone_EventCloneElement.h:50
Index GetEventIndex() const
Gets the index of the event currently being referenced.
Definition: clone_EventCloneElement.h:127
StationIndex GetSetterStationIndex() const
Gets the index of the station that raised the event being referenced.
Definition: clone_EventCloneElement.h:117
This is the base class for managing the sending and receiving of events.
Definition: clone_EventCloneElementBase.h:37
u32 ClockValue
Defines a type that holds a clock value.
Definition: clone_definitions.h:44
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition: assert.h:115
EventCloneElement()
Instantiates the object with default parameters (default constructor).
ID indicating a station that is not present in the session.
Definition: platformCtr.h:59
nn::Result SetValue(const Value &value, bool isEnableSendDelay=false)
Raises an event.
Manages the sending and receiving of events.
Definition: clone_EventCloneElement.h:39
const Value * GetValue() const
Gets the pointer to the value for when the current event was raised.
Definition: clone_EventCloneElement.h:97
virtual ~EventCloneElement()
Destroys the object.
Definition: clone_EventCloneElement.h:62
Value_ Value
Specifies the argument type to be sent with this event.
Definition: clone_EventCloneElement.h:45
const Value * HandleNext()
References the next event.
Definition: clone_EventCloneElement.h:86
const ClockValue * GetClock() const
Gets the pointer to the issued time for when the current event was raised.
Definition: clone_EventCloneElement.h:107