CTR Pia  4.11.3
Game Communication Engine
inet_NexCreateSessionSetting.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: inet_NexCreateSessionSetting.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/session/session_CreateSessionSetting.h>
18 #include <pia/inet/inet_NexSessionTypes.h>
19 
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace inet
25 {
26 /*!
27  @brief Class that manages settings specific to session creation.
28 
29  @date 2015-03-20 Added APIs to set parameters for scored matchmaking.
30  @date 2014-05-16 Added the <tt>SetSessionUserPassword()</tt> function.
31  @date 2014-02-03 Initial version.
32 
33  @see nn::pia::session::CreateSessionSetting
34  */
36 {
37 public:
38 /*!
39  @brief The default constructor.
40 */
42 
43 /*!
44  @brief The destructor.
45 */
46  virtual ~NexCreateSessionSetting();
47 
48 /*!
49  @brief Sets the game mode for the new session.
50  @param[in] gameMode Specifies the game mode for the new session.
51 */
52  void SetGameMode(u32 gameMode);
53 /*!
54  @brief Gets the specified game mode.
55  @return Returns the specified game mode.
56 */
57  u32 GetGameMode() const;
58 
59 /*!
60  @brief Sets the session type for the new session.
61  @param[in] sessionType Specifies the session type for the new session.
62 */
63  void SetSessionType(SessionType sessionType);
64 /*!
65  @brief Gets the specified session type.
66  @return Returns the specified session type.
67 */
69 
70 /*!
71  @brief Sets the description string for the new session.
72  @param[in] description Specifies the description string for the new session.
73 */
74  void SetDescription(const wchar_t* description);
75 /*!
76  @brief Gets the specified description string.
77  @return Returns the specified description string.
78 */
79  const wchar_t* GetDescription() const;
80 
81 /*!
82  @brief Sets the attributes for the new session.
83  @param[in] index Specifies the index of the attribute for the new session.
84  @param[in] value Specifies the value of the attribute for the new session.
85 */
86  void SetAttribute(u32 index, u32 value);
87 /*!
88  @brief Gets the specified attribute.
89  @param[in] index Specifies the index for the attribute to get.
90  @return Returns the specified attribute value.
91 */
92  u32 GetAttribute(u32 index) const;
93 
94 /*!
95  @brief Sets application-defined data.
96  @details Specify a size that does not exceed <tt>inet::APPLICATION_DATA_BUFFER_MAX_SIZE</tt>.
97  @param[in] pData Specifies the buffer for the application-defined data for the new session.
98  @param[in] size Specifies the size of the application-defined data the new session.
99  @return Returns a <tt>Result</tt> value indicating success if the application-defined data is set successfully.
100 
101  @retval nn::pia::ResultInvalidArgument Indicates that either the buffer pointer was <tt>NULL</tt> or the specified data size was too big. Programming error. Fix your program so that this error is not returned.
102 */
103  nn::Result SetApplicationData(const u8* pData, size_t size);
104 /*!
105  @brief Gets specified application-defined data.
106  @param[in] pDataBuf Specifies a pointer to a buffer from which to copy the specified application-defined data.
107  @param[in] pDataSize Specifies the size of the data written to the copy buffer.
108  @param[in] dataBufSize Specifies the copy buffer size.
109  @return Returns a <tt>Result</tt> value indicating success if the application-defined data is acquired successfully.
110 
111  @retval nn::pia::ResultInvalidArgument Indicates that either the buffer pointer is <tt>NULL</tt> or the pointer returned by the copied size is <tt>NULL</tt>. Programming error. Fix your program so that this error is not returned.
112  @retval nn::pia::ResultInvalidState Indicates that no application-defined data is set. Programming error. Fix your program so that this error is not returned.
113  @retval nn::pia::ResultBufferShortage Indicates that the set application-defined data cannot be copied because it is greater in size than the buffer. Programming error. Fix your program so that this error is not returned.
114 */
115  nn::Result GetApplicationData(u8* pDataBuf, size_t* pDataSize, size_t dataBufSize) const;
116 
117 /*!
118  @brief Gets the size of the specified application-defined data.
119  @return Returns the size of the application-defined data.
120 */
121  size_t GetApplicationDataSize() const
122  {
123  return m_ApplicationDataSize;
124  }
125 /*!
126  @brief Sets whether participation in this session is possible.
127 
128  @details Sets whether the new session is to be created as joinable. When not set, it is created as not joinable.
129 
130  @param[in] isOpen When set to <tt>true</tt>, the new session created by this <tt>NexCreateSessionSetting</tt> function is joinable.
131 */
132  void SetOpenParticipation(bool isOpen);
133 
134 /*!
135  @cond PRIVATE
136  @brief Gets whether participation in this session is possible.
137 
138  @return Returns <tt>true</tt> if the session is joinable.
139 */
140  bool GetOpenParticipation() const;
141  //! @endcond
142 
143 /*!
144  @brief Sets the user password.
145 
146  @details Sets a user password for the new session.
147 
148  @param[in] pUserPassword Specifies the user password.
149  @param[in] passwordLength Specifies the string length of the user password.
150 */
151  void SetSessionUserPassword(const wchar_t* pUserPassword, size_t passwordLength);
152 
153 /*!
154  @cond PRIVATE
155  @brief
156 */
157  const wchar_t* GetSessionUserPassword() const;
158  //! @endcond
159 
160 /*!
161  @brief Sets the matchmaking priority when a session with the same requirements is found.
162 
163  @details Sets the matchmaking priority for the new session.
164  If unspecified, it is set to <tt>0</tt>.
165  Enabled only when searches are done with
166  <tt>nn::pia::inet::SELECTION_METHOD_BROADEN_RANGE_WITH_SELECTION_PRIORITY</tt> or <tt>SELECTION_METHOD_SCORE_BASED</tt>.
167  If a value that exceeds <tt>nn::pia::inet::SESSION_MAX_SELECTION_PRIORITY</tt> is provided as an argument, <tt>nn::pia::inet::SESSION_MAX_SELECTION_PRIORITY</tt> is set instead.
168 
169  @param[in] priority Specifies the matchmaking priority.
170 */
171  void SetSelectionPriority(u8 priority);
172 
173 /*!
174  @cond PRIVATE
175  @brief Gets the matchmaking priority.
176 
177  @details Gets the matchmaking priority for the new session.
178 
179  @return Returns the matchmaking priority.
180 */
181  u8 GetSelectionPriority() const;
182  //! @endcond
183 
184 /*!
185  @brief Sets the rating value to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
186  @param[in] ratingValue Specifies the rating value.
187 */
188  void SetRatingValue(u32 ratingValue);
189 /*!
190  @cond PRIVATE
191 */
192  u32 GetRatingValue() const;
193  bool IsSetRatingValue() const;
194  //! @endcond
195 
196 /*!
197  @brief Sets the disconnection rate to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
198  @details We recommend using NEX's <tt>MatchmakeReferee</tt> feature.
199  @param[in] disconnectionRate Specifies the disconnection rate.
200 */
201  void SetDisconnectionRate(u32 disconnectionRate);
202 /*!
203  @cond PRIVATE
204 */
205  u32 GetDisconnectionRate() const;
206  bool IsSetDisconnectionRate() const;
207  //! @endcond
208 
209 /*!
210  @brief Sets the violation rate to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
211  @details We recommend using NEX's <tt>MatchmakeReferee</tt> feature.
212  @param[in] violationRate Specifies the violation rate.
213 */
214  void SetViolationRate(u32 violationRate);
215 /*!
216  @cond PRIVATE
217 */
218  u32 GetViolationRate() const;
219  bool IsSetViolationRate() const;
220  //! @endcond
221 
222 /*!
223  @brief Sets whether to use position information (longitude and latitude, country code) for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
224  @details When not setting whether to use position information, the score for comparing distance uses the default score for rating.
225  @param[in] b Specifies whether to use position information.
226 */
227  void UseGeoIp(bool b);
228 /*!
229  @cond PRIVATE
230 */
231  bool GetUseGeoIp() const;
232  bool IsSetUseGeoIp() const;
233  //! @endcond
234 
235 /*!
236  @brief Sets the country code to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
237  @details Sets the country code to use when you have configured to not use location information with <tt>UseGeoIP()</tt> or when you have configured to use that location information but it was not available.
238  The specified country code is not used when location information is available.
239  When a country code is not set, and when you have configured to not use location information with <tt>UseGeoIP()</tt> or when you have configured to use that location information but it was not available, the default value is used as the score for comparing country codes.
240  @param[in] countryCode Specifies the country code.
241 */
242  void SetNintendoCountryCode(u32 countryCode);
243 /*!
244  @cond PRIVATE
245 */
246  u32 GetNintendoCountryCode() const;
247  bool IsSetNintendoCountryCode() const;
248  //! @endcond
249 
250 /*!
251  @brief Sets the IP address for debugging to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
252  @details Use this IP address instead of your own to get location information using <tt>GeoIP</tt>. Only available for debugging.
253  @param[in] pIpAddress Specifies the replacement IP address.
254  @param[in] ipAddressLength Specifies the IP address string length.
255 */
256 
257  void SetOverrideIpAddress(const wchar_t* pIpAddress, size_t ipAddressLength);
258 
259 /*!
260  @cond PRIVATE
261 */
262  const wchar_t* GetOverrideIpAddress() const;
263  bool IsSetOverrideIpAddress() const;
264  //! @endcond
265 
266 /*!
267  @cond PRIVATE
268  @brief Determines whether to set parameters for score-based matching.
269 */
270  bool IsSetScoreBasedParameter() const;
271  //! @endcond
272 
273 /*!
274  @cond PRIVATE
275  @brief Updates the header information that indicates the usage state of the application-defined data region.
276 */
277  void UpdateApplicationDataHeader(const u8* pData, size_t dataSize);
278  //! @endcond
279 
280 /*!
281  @cond PRIVATE
282  @brief Gets data from the application-defined data.
283 */
284  void GetApplicationDataInternal(void* pVectorTmp) const;
285  //! @endcond
286 
287 /*!
288  @cond PRIVATE
289  @brief Copies the application-defined data.
290 */
291  void CopyApplicationDataToVector(void* pVectorTmp) const;
292  //! @endcond
293 
294  // Prints information that is useful for debugging.
295  void Trace(u64 flag) const;
296 
297 
298 /*!
299  @cond PRIVATE
300 */
301  void SetExtraParticipants(u16 num);
302  u16 GetExtraParticipants() const;
303  //! @endcond
304 
305 /*!
306  @brief Sets the associated community ID.
307  @details This session can only be found in the search results for players who used the same community ID for searching in <tt>inet::NexSessionSearchCriteria::SetCommunityId</tt>.
308  In addition, it is required when linking with the NEX ranking feature. For information about linking with the ranking feature, see the documentation about persistent gathering for the NEX.
309 */
310  void SetCommunityId(u32 gid);
311 /*!
312  @cond PRIVATE
313  @brief Gets the associated community ID.
314 */
315  u32 GetCommunityId();
316  //! @endcond
317 
318  // SetApplicationBuffer
319  // OpenParticipate
320 
321 protected:
322  // Game mode.
323  u32 m_GameMode;
324 
325  SessionType m_SessionType;
326 
327  // The description string.
328  wchar_t m_Description[DESCRIPTION_DATA_BUFFER_MAX_SIZE + 1];
329 
330  // Attributes.
331  u32 m_Attribute[ATTRIBUTE_MAX_SIZE];
332 
333  u8 m_ApplicationDataBuffer[APPLICATION_DATA_BUFFER_MAX_SIZE_INTERNAL];
334  size_t m_ApplicationDataSize;
335  size_t m_ApplicationDataInternalOffset;
336 
337  bool m_OpenParticipation;
338 
339  u8 m_ProgressScore;
340 
341  // Parameters for score-based matching.
342  u32 m_RatingValue;
343  bool m_IsSetRatingValue;
344 
345  u32 m_ViolationRate;
346  bool m_IsSetViolationRate;
347 
348  u32 m_DisconnectionRate;
349  bool m_IsSetDisconnectionRate;
350 
351  bool m_UseGeoIp;
352  bool m_IsSetUseGeoIp;
353 
354  u32 m_CountryCode;
355  bool m_IsSetCountryCode;
356 
357  wchar_t m_OverrideIpAddress[MAX_IP_ADDRESS_LENGTH + 1];
358  bool m_IsSetOverrideIpAddress;
359 
360  u16 m_ExtraParticipants;
361 
362  u32 m_CommunityId;
363 
364 #if NN_PIA_NEX_NEW_FEATURE_FOR_MATCHMAKE
365  // Pointer to the user password configured for the new session.
366  wchar_t m_UserPassword[nn::pia::inet::SESSION_USER_PASSWORD_LENGTH + 1];
367 #endif
368 
369 private:
370  // The copy constructor is sealed.
372 
373  // The assignment operator is sealed.
375 };
376 }
377 }
378 } // End of namespace nn::pia::inet.
const size_t ATTRIBUTE_MAX_SIZE
The number of attributes that can be specified in a session.
Definition: inet_NexSessionTypes.h:39
nn::Result SetApplicationData(const u8 *pData, size_t size)
Sets application-defined data.
void SetSessionType(SessionType sessionType)
Sets the session type for the new session.
Definition: assert.h:115
void SetSelectionPriority(u8 priority)
Sets the matchmaking priority when a session with the same requirements is found. ...
void SetNintendoCountryCode(u32 countryCode)
Sets the country code to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED.
const wchar_t * GetDescription() const
Gets the specified description string.
void SetRatingValue(u32 ratingValue)
Sets the rating value to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED.
Base class that manages settings specific to session creation.
Definition: session_CreateSessionSetting.h:38
void SetDisconnectionRate(u32 disconnectionRate)
Sets the disconnection rate to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED...
const u32 SESSION_USER_PASSWORD_LENGTH
The user password&#39;s string length.
Definition: inet_NexSessionTypes.h:52
NexCreateSessionSetting()
The default constructor.
size_t GetApplicationDataSize() const
Gets the size of the specified application-defined data.
Definition: inet_NexCreateSessionSetting.h:121
u32 GetAttribute(u32 index) const
Gets the specified attribute.
SessionType GetSessionType() const
Gets the specified session type.
nn::Result GetApplicationData(u8 *pDataBuf, size_t *pDataSize, size_t dataBufSize) const
Gets specified application-defined data.
void SetAttribute(u32 index, u32 value)
Sets the attributes for the new session.
Class that manages settings specific to session creation.
Definition: inet_NexCreateSessionSetting.h:35
void SetOpenParticipation(bool isOpen)
Sets whether participation in this session is possible.
SessionType
Enumerates the session types.
Definition: inet_NexSessionTypes.h:78
virtual ~NexCreateSessionSetting()
The destructor.
u32 GetGameMode() const
Gets the specified game mode.
void SetGameMode(u32 gameMode)
Sets the game mode for the new session.
void UseGeoIp(bool b)
Sets whether to use position information (longitude and latitude, country code) for comparison during...
void SetDescription(const wchar_t *description)
Sets the description string for the new session.
void SetCommunityId(u32 gid)
Sets the associated community ID.
void SetViolationRate(u32 violationRate)
Sets the violation rate to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED.
void SetOverrideIpAddress(const wchar_t *pIpAddress, size_t ipAddressLength)
Sets the IP address for debugging to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_...
void SetSessionUserPassword(const wchar_t *pUserPassword, size_t passwordLength)
Sets the user password.