CTR Pia  4.11.3
Game Communication Engine
common_StationAddress.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_StationAddress.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 
18 #include <pia/common/common_definitions.h>
19 
20 #include <pia/common/common_InetAddress.h>
21 
22 
23 namespace nn
24 {
25 namespace pia
26 {
27 namespace common
28 {
29 
30 /*!
31 @brief Represents an address used to uniquely identify stations.
32 @if CTR_DOC
33 @date 2014-05-29 Made the <tt>StationAddress::GetUdsNodeId</tt> and <tt>StationAddress::SetUdsNodeId</tt> functions private.
34 @endif
35 @if CAFE_DOC
36 @date 2013-07-11 Made the <tt>StationAddress::GetUdsNodeId</tt> and <tt>StationAddress::SetUdsNodeId</tt> functions private.
37 @endif
38 @date 2013-05-17 Changed the documentation because of the deprecation of <tt>StationAddress::GetUdsNodeId</tt> and <tt>StationAddress::SetUdsNodeId</tt>.
39 @date 2013-02-22 Added greater than and less than comparison functions and operators.
40 @date 2012-04-23 Removed an unneeded destructor.
41 @date 2012-04-19 Initial version.
42 */
44 {
45 public:
46  static const size_t SERIALIZE_SIZE_MAX =
47  common::InetAddress::SERIALIZE_SIZE_MAX + sizeof(u16); // m_Extension
48 
49 /*!
50 @brief Instantiates the object.
51 */
52  StationAddress(void);
53 
54 
55 /*!
56 @brief This is the copy constructor.
57 */
58  StationAddress(const StationAddress& rhs);
59 
60 
61 /*!
62 @cond PRIVATE
63 @if CTR_DOC
64 @brief Gets a UDS node ID. [Deprecated]
65 
66 @details This function is deprecated. It will be removed in a future release.
67 Although this function is retained for backward compatibility, use <tt>@ref local::UdsNode::ConvertStationAddressToUdsNodeId</tt> and other conversion functions.
68 
69 This function can be used to retrieve Node IDs from a valid <tt>StationAddress</tt>. Use <tt>UdsNodeId</tt> for local communication with host migration disabled and <tt>TransportNodeId</tt> when host migration is enabled.
70 
71 @return Returns the node ID.
72 
73 @see local::UdsNode::ConvertStationAddressToUdsNodeId, local::UdsNode::ConvertStationAddressToTransportNodeId
74 @endif
75 
76 */
77  u16 GetUdsNodeId(void) const
78  {
79  return m_Extension;
80  }
81  //! @endcond
82 
83 /*!
84 @cond PRIVATE
85 @if CTR_DOC
86 @brief Sets a UDS node ID. [Deprecated]
87 
88 @details This function is deprecated. It will be removed in a future release.
89 Although this function is retained for backward compatibility, use <tt>@ref local::UdsNode::ConvertUdsNodeIdToStationAddress</tt> and other conversion functions.
90 
91 @param[in] nodeId Specifies the UDS node ID.
92 @return This function always succeeds.
93 
94 @see local::UdsNode::ConvertUdsNodeIdToStationAddress, local::UdsNode::ConvertTransportNodeIdToStationAddress
95 @endif
96 */
97  nn::Result SetUdsNodeId(u16 nodeId);
98  //! @endcond
99 
100 /*!
101 @cond PRIVATE
102 @brief Gets the extension ID.
103 
104 @details This function can be used to retrieve the extension IDs from a valid <tt>StationAddress</tt>. Use <tt>UdsNodeId</tt> for local communication with host migration disabled and <tt>TransportNodeId</tt> when host migration is enabled.
105 
106 @return Returns the extension ID.
107 
108 */
109  u16 GetExtensionId(void) const
110  {
111  return m_Extension;
112  }
113  //! @endcond
114 
115 
116 /*!
117 @cond PRIVATE
118 @brief Sets the extension ID.
119 
120 @param[in] extensionId Specifies the extension ID to set.
121 @return This function always succeeds.
122 */
123  nn::Result SetExtensionId(u16 extensionId);
124  //! @endcond
125 
126 
127 /*!
128 @brief Gets a <tt>const</tt> reference to an <tt>nn::pia::common::InetAddress</tt> instance.
129 
130 @return Returns a <tt>const</tt> reference to an <tt>nn::pia::common::InetAddress</tt> instance.
131 */
133  {
134  return m_Address;
135  }
136 
137 
138 /*!
139 @brief Gets a reference to an <tt>nn::pia::common::InetAddress</tt> instance.
140 
141 @return Returns a reference to an <tt>nn::pia::common::InetAddress</tt> instance.
142 */
144  {
145  return m_Address;
146  }
147 
148 
149 /*!
150 @brief Sets the <tt>nn::pia::common::InetAddress</tt> instance.
151 
152 @param[in] addr Specifies the Internet address to set.
153 @return This function always succeeds.
154 */
155  nn::Result SetInetAddress(const nn::pia::common::InetAddress& addr);
156 
157 
158 /*!
159 @brief Clears the <tt>StationAddress</tt>.
160 */
161  void Clear(void);
162 
163 
164 /*!
165 @brief Gets the length of the object as a serialized byte array. The value is in bytes.
166 
167 @return Returns the length of the serialized data. The value is in bytes.
168 @see Serialize, Deserialize
169 */
170  size_t GetSerializedSize(void) const;
171 
172 
173 /*!
174 @brief Serializes the object.
175 
176 @param[out] pBuffer Pointer to a buffer for holding the serialized data.
177 @param[out] pDataLen Holds the length of the serialized data that was written to the buffer. The value is in bytes.
178 @param[in] bufferSize Specifies the size of the buffer that was specified in <span class="argument">pBuffer</span>.
179 @return On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function will return <tt>true</tt>. Your application's implementation must ensure that this function does not return any errors.
180 @retval ResultInvalidArgument Indicates that an argument is invalid. (For example, a NULL pointer was specified.) The function also returns this error if <span class="argument">pBuffer</span> or the size specified in <span class="argument">bufferSize</span> is too small. Programming error. Fix your program so that this error is not returned.
181 @see Deserialize, GetSerializedSize
182 */
183  nn::Result Serialize(bit8* pBuffer, size_t* pDataLen, size_t bufferSize) const;
184 
185 
186 /*!
187 @brief Restores an object from serialized data.
188 
189 @param[in] pData Pointer to the serialized data.
190 
191 @return On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function will return <tt>true</tt>. Your application's implementation must ensure that this function does not return any errors.
192 @retval ResultInvalidArgument Indicates that an argument is invalid. (For example, a NULL pointer was specified.) Programming error. Fix your program so that this error is not returned.
193 @see Serialize, GetSerializedSize
194 */
195  nn::Result Deserialize(const bit8* pData);
196 
197 
198 /*!
199 @cond PRIVATE
200 @brief Determines whether the specified address is valid.
201 
202 @return <tt>true</tt> if the address is valid, and <tt>false</tt> otherwise.
203 */
204  bool IsValid(void) const;
205  //! @endcond
206 
207 
208 /*!
209 @brief This is an equality operator. Determines whether two <tt>StationAddress</tt> objects are equal.
210 
211 @return Returns <tt>true</tt> if the objects are equal, and <tt>false</tt> otherwise.
212 */
213  bool operator==(const StationAddress& rhs) const;
214 
215 
216 /*!
217 @brief This is an equality operator. Determines whether two <tt>StationAddress</tt> objects are not equal.
218 
219 @return Returns <tt>true</tt> if the objects are not equal, and <tt>false</tt> otherwise.
220 */
221  bool operator!=(const StationAddress& rhs) const
222  {
223  return !(*this == rhs);
224  }
225 
226 
227 /*!
228 @brief This is the assignment operator.
229 
230 @return Returns a reference to the <tt>this</tt> object.
231 */
232  StationAddress& operator=(const StationAddress& rhs);
233 
234 
235 /*!
236 @brief Comparison operator.
237 
238 @return <tt>true</tt> if this object is smaller.
239 */
240  bool operator<(const StationAddress& rhs) const;
241 
242 
243 /*!
244 @brief Comparison operator.
245 
246 @return <tt>true</tt> if this object is larger.
247 */
248  bool operator>(const StationAddress& rhs) const;
249 
250 
251 /*!
252 @brief Comparison function (greater than/less than/equal).
253 @param[in] a The left-hand side object to compare.
254 @param[in] b The right-hand side object to compare.
255 @return Returns <tt>-1</tt> if <tt>b</tt> is less than <tt>a</tt>, <tt>1</tt> if <tt>b</tt> is greater than <tt>a</tt>, and <tt>0</tt> if they are equal.
256 */
257  static int Compare(const StationAddress& a, const StationAddress& b);
258 
259 /*!
260 @cond PRIVATE
261 @brief Gets the address string.
262 
263 @param[in] pString Pointer to the instance of the string class.
264 */
265  void GetAddressString(String* pString) const;
266  //! @endcond
267 
268 /*!
269 @brief Prints information useful for debugging.
270 
271 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
272 */
273  virtual void Trace(u64 flag) const;
274 
275 private:
276  common::InetAddress m_Address;
277  u16 m_Extension; // For expansion. At the current time, stores the UDS node ID.
278 };
279 }
280 }
281 } // end of namespace nn::pia::common
static int Compare(const StationAddress &a, const StationAddress &b)
Comparison function (greater than/less than/equal).
bool operator!=(const StationAddress &rhs) const
This is an equality operator. Determines whether two StationAddress objects are not equal...
Definition: common_StationAddress.h:221
nn::Result Serialize(bit8 *pBuffer, size_t *pDataLen, size_t bufferSize) const
Serializes the object.
Definition: assert.h:115
StationAddress(void)
Instantiates the object.
bool operator<(const StationAddress &rhs) const
Comparison operator.
Class for representing strings.
Definition: common_String.h:35
bool operator>(const StationAddress &rhs) const
Comparison operator.
nn::Result SetInetAddress(const nn::pia::common::InetAddress &addr)
Sets the nn::pia::common::InetAddress instance.
virtual void Trace(u64 flag) const
Prints information useful for debugging.
nn::Result Deserialize(const bit8 *pData)
Restores an object from serialized data.
const nn::pia::common::InetAddress & GetInetAddress(void) const
Gets a const reference to an nn::pia::common::InetAddress instance.
Definition: common_StationAddress.h:132
size_t GetSerializedSize(void) const
Gets the length of the object as a serialized byte array. The value is in bytes.
Represents an address used to uniquely identify stations. .
Definition: common_StationAddress.h:43
StationAddress & operator=(const StationAddress &rhs)
This is the assignment operator.
nn::pia::common::InetAddress & GetInetAddress(void)
Gets a reference to an nn::pia::common::InetAddress instance.
Definition: common_StationAddress.h:143
Class that represents an Internet address.
Definition: common_InetAddress.h:52
void Clear(void)
Clears the StationAddress.
bool operator==(const StationAddress &rhs) const
This is an equality operator. Determines whether two StationAddress objects are equal.
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40