CTR Pia  4.11.3
Game Communication Engine
inet_NexSessionSearchCriteria.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: inet_NexSessionSearchCriteria.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_SessionSearchCriteria.h>
18 #include <pia/inet/inet_NexSessionTypes.h>
19 
20 #if NN_PIA_CTR
21 #pragma diag_suppress 1300 //n1769: Pragma for ARMCC.
22 #endif
23 #include <nex.h>
24 #if NN_PIA_CTR
25 #pragma diag_warning 1300 //n1769: Pragma for ARMCC.
26 #endif
27 
28 namespace nn
29 {
30 namespace pia
31 {
32 namespace inet
33 {
34 
35 /*!
36  @brief The search condition class used when searching for a session.
37 
38  @date 2015-03-20 Added APIs to set parameters for scored matchmaking.
39  @date 2014-02-03 Initial version.
40 
41  @see nn::pia::session::SessionSearchCriteria
42 */
44 {
45 public:
46  enum NexCondMask
47  {
48  NexCondMask_MinParticipation = 0,
49  NexCondMask_MaxParticipation,
50  NexCondMask_OpenedOnly,
51  NexCondMask_VacantOnly,
52  NexCondMask_GameMode,
53  NexCondMask_SessionType,
54  NexCondMask_Attribute,
55  NexCondMask_ExcludeNonHost,
56  NexCondMask_ExcludeUserPassword,
57  NexCondMask_ScoreBasedSettingIndex,
58  NexCondMask_ScoreBasedRatingValue,
59  NexCondMask_ScoreBasedDisconnectionRate,
60  NexCondMask_ScoreBasedViolationRate,
61  NexCondMask_ScoreBasedCountryCode,
62  NexCondMask_ScoreBasedGeoIp,
63  NexCondMask_ScoreBasedOverrideIp,
64  NexCondMask_Community,
65  NexCondMask_Max
66  };
67 
68 /*!
69  @brief The default constructor.
70 */
72 
73 /*!
74  @brief The destructor.
75 */
76  virtual ~NexSessionSearchCriteria();
77 
78 /*!
79  @brief Sets the minimum participants in the search criteria.
80  @param[in] min The minimum participants value to set in the search criteria.
81 */
82  void SetMinParticipants(u16 min);
83 
84 /*!
85  @brief Sets a range of minimum participants in the search criteria.
86  @param[in] min The minimum value of the range to set for minimum participants in the search criteria.
87  @param[in] max The maximum value of the range to set for minimum participants in the search criteria.
88 */
89  void SetMinParticipantsRange(u16 min, u16 max);
90 
91 /*!
92  @brief Sets the maximum participants in the search criteria.
93  @param[in] max The maximum participants value to set in the search criteria.
94 */
95  void SetMaxParticipants(u16 max);
96 
97 /*!
98  @brief Sets a range of maximum participants in the search criteria.
99  @param[in] min The minimum value of the range to set for maximum participants in the search criteria.
100  @param[in] max The maximum value of the range to set for maximum participants in the search criteria.
101 */
102  void SetMaxParticipantsRange(u16 min, u16 max);
103 
104 /*!
105  @brief Sets whether to search only for sessions that are open to participants in the search criteria.
106  @param[in] bOpenedOnly Specify <tt>true</tt> to search only for sessions that are open to participants.
107 */
108  void SetOpenedOnly(bool bOpenedOnly);
109 
110 /*!
111  @brief Sets whether to search only for sessions that have openings in the search criteria.
112  @param[in] bVacantOnly Specify <tt>true</tt> to search only for sessions that have openings.
113 */
114  void SetVacantOnly(bool bVacantOnly);
115 
116 /*!
117  @brief Sets the search conditions to game mode.
118  @details When no search conditions are set, it matches the game mode of any value.
119  @param[in] gameMode Specifies the game mode search conditions.
120 */
121  void SetGameMode(u32 gameMode);
122 
123 /*!
124  @brief Sets the session type search conditions.
125  @details If no conditions are specified, the default value (<tt>SESSION_TYPE_ANYBODY</tt>) will be used.
126  @param[in] sessionType Specifies the session type search conditions.
127 */
128  void SetSessionType(SessionType sessionType);
129 
130 /*!
131  @brief Sets a value to use when searching for a single attribute.
132  @param[in] index Specifies the index of an attribute.
133  @param[in] value Specifies the value of an attribute.
134 */
135  void SetAttribute(u32 index, u32 value);
136 /*!
137  @brief Sets multiple values to use when searching for a single attribute.
138  @param[in] index Specifies the index of an attribute.
139  @param[in] value Specifies a list of values for an attribute.
140  @param[in] attributeNum Specifies the number of values for an attribute.
141 */
142  void SetAttribute(u32 index, u32* value, size_t attributeNum);
143 /*!
144  @brief Sets a range of values to use when searching for a single attribute.
145  @param[in] index Specifies the index of an attribute.
146  @param[in] min Specifies the minimum value of an attribute.
147  @param[in] max Specifies the maximum value of an attribute.
148 */
149  void SetAttributeRange(u32 index, u32 min, u32 max);
150 /*!
151  @brief Sets the selection methods for joining sessions when random matchmaking is in effect.
152  @param[in] selectionMethod Specifies the selection method to set for the session.
153 */
154  void SetRandomSessionSelectionMethod(SelectionMethod selectionMethod);
155 
156 /*!
157  @brief Sets whether to exclude sessions with no hosts from the search. (By default, they are excluded.)
158  @param[in] bExclude Specifies whether to exclude sessions with no hosts from the search. Set to <tt>true</tt> to enable.
159 */
160  void SetExcludeNonHostPid(bool bExclude);
161 
162 /*!
163  @brief Sets whether to exclude sessions for which a user password was set from the search. (By default, they are excluded.)
164  @param[in] bExclude Specifies whether to exclude sessions for which a user password was set from the search. Set to <tt>true</tt> to enable.
165 */
166  void SetExcludeUserPasswordSet(bool bExclude);
167 
168 /*!
169  @brief Sets the setting index for the score calculation method to use during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
170  @details <tt>0</tt> is used when a setting index is not set.
171  @param[in] settingIndex Specifies the score calculation setting index.
172 */
173  void SetScoreSettingIndex(u32 settingIndex);
174 
175 /*!
176  @brief Sets the rating value to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
177  @details When not set, the score for the rating value difference uses a default score to rate.
178  @param[in] ratingValue Specifies the rating value.
179 */
180  void SetRatingValue(u32 ratingValue);
181 
182 /*!
183  @brief Sets the disconnection rate to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
184  @details When not set, the score for the disconnection rate difference uses a default score to rate. We recommend using NEX's <tt>MatchmakeReferee</tt> feature.
185  @param[in] disconnectionRate Specifies the disconnection rate.
186 */
187  void SetDisconnectionRate(u32 disconnectionRate);
188 
189 /*!
190  @brief Sets the violation rate to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
191  @details When not set, the score for the violation rate difference uses a default score to rate. We recommend using NEX's <tt>MatchmakeReferee</tt> feature.
192  @param[in] violationRate Specifies the violation rate.
193 */
194  void SetViolationRate(u32 violationRate);
195 
196 /*!
197  @brief Sets whether to use position information (longitude and latitude, country code) for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
198  @details When not setting whether to use position information, the score for comparing distance uses the default score for rating.
199  @param[in] b Specifies whether to use position information.
200 */
201  void SetUseGeoIp(bool b);
202 
203 /*!
204  @brief Sets the country code to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
205  @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.
206  The specified country code is not used when location information is available.
207  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.
208  @param[in] countryCode Specifies the country code.
209 */
210  void SetNintendoCountryCode(u32 countryCode);
211 
212 /*!
213  @brief Sets the IP address for debugging to use for comparison during <tt>nn::pia::inet::SELECTION_METHOD_SCORE_BASED</tt>.
214  @details Use this IP address instead of your own to get location information using <tt>GeoIP</tt>. Only available for debugging.
215  @param[in] pIpAddress Specifies the replacement IP address.
216  @param[in] ipAddressLength Specifies the IP address string length.
217 */
218  void SetOverrideIpAddress(const wchar_t* pIpAddress, size_t ipAddressLength);
219 
220 /*!
221  @brief Sets the ID for the associated community (persistent gathering).
222 */
223  void SetCommunityId(u32 gid);
224 /*!
225  @cond PRIVATE
226  @brief Gets the ID for the associated community (persistent gathering).
227 */
228  u32 GetCommunityId();
229  //! @endcond
230 
231 /*!
232  @cond PRIVATE
233  @brief Converts the configured information to the condition and search range criteria used by the NEX classes.
234 */
235  void ConvertToNexMatchmakeSessionSearchCriteria(
236  nn::nex::MatchmakeSessionSearchCriteria* pCriteria,
237  nn::nex::MatchmakeParam* pParam,
238  nn::nex::ResultRange* pResultRange,
239  int reportNum = 2);
240  //! @endcond
241 
242 /*!
243  @brief Assignment operator.
244  @param[in] r The object to assign.
245  @return See this object.
246 */
248 
249 /*!
250  @cond PRIVATE
251  @brief Prints information that is useful for debugging.
252 */
253  virtual void Trace(u64 flag) const;
254  //! @endcond
255 
256 private:
257  // The copy constructor is sealed.
259 
260  // Invalid number of participants setting.
261  static const u16 INVALID_PARICIPANTS_NUM = 0xffff;
262 
263  // Minimum participants range.
264  u16 m_MinParticipantsRangeMax;
265  u16 m_MinParticipantsRangeMin;
266 
267  // Maximum participants range.
268  u16 m_MaxParticipantsRangeMax;
269  u16 m_MaxParticipantsRangeMin;
270 
271  // Whether to list only open sessions.
272  bool m_bOpenedOnly;
273  // Whether to remove full sessions from the results.
274  bool m_bVacantOnly;
275 
276  // Game mode.
277  u32 m_GameMode;
278  // Session type.
279  SessionType m_SessionType;
280 
281  // Attributes.
282  u32 m_AttributeList[ATTRIBUTE_MAX_SIZE][ATTRIBUTE_ARRAY_MAX_SIZE];
283  size_t m_AttributeSizeList[ATTRIBUTE_MAX_SIZE];
284  u32 m_AttributeRangeMin[ATTRIBUTE_MAX_SIZE];
285  u32 m_AttributeRangeMax[ATTRIBUTE_MAX_SIZE];
286  bool m_bAttributeRangeUsed[ATTRIBUTE_MAX_SIZE];
287 
288  // Exclude sessions for which a host is not yet set.
289  bool m_bExcludeNonHostPid;
290  // Exclude sessions for which a user password is set.
291  bool m_bExcludeUserPasswordSet;
292  // Set the way to choose the session to join from the search results.
293  SelectionMethod m_SelectionMethod;
294 
295  u32 m_ScoreBasedSettingIndex;
296  u32 m_ScoreBasedRatingValue;
297  u32 m_ScoreBasedDisconnectionRate;
298  u32 m_ScoreBasedViolationRate;
299  u32 m_ScoreBasedCountryCode;
300  bool m_IsScoreBasedGeoIpUsed;
301 
302  wchar_t m_IpAddress[MAX_IP_ADDRESS_LENGTH + 1];
303 
304  u32 m_CommunityId;
305 
306  u32 m_SetCondMask;
307 };
308 }
309 }
310 } // 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
NexSessionSearchCriteria & operator=(const NexSessionSearchCriteria &r)
Assignment operator.
void SetViolationRate(u32 violationRate)
Sets the violation rate to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED.
Definition: assert.h:115
The base class for the search criteria used when searching for sessions.
Definition: session_SessionSearchCriteria.h:34
void SetMinParticipants(u16 min)
Sets the minimum participants in the search criteria.
SelectionMethod
Enumerates the selection methods for joining sessions when random matchmaking is in force...
Definition: inet_NexSessionTypes.h:87
void SetAttributeRange(u32 index, u32 min, u32 max)
Sets a range of values to use when searching for a single attribute.
void SetOpenedOnly(bool bOpenedOnly)
Sets whether to search only for sessions that are open to participants in the search criteria...
void SetExcludeNonHostPid(bool bExclude)
Sets whether to exclude sessions with no hosts from the search. (By default, they are excluded...
void SetMinParticipantsRange(u16 min, u16 max)
Sets a range of minimum participants in the search criteria.
void SetRatingValue(u32 ratingValue)
Sets the rating value to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED.
void SetMaxParticipantsRange(u16 min, u16 max)
Sets a range of maximum participants in the search criteria.
NexSessionSearchCriteria()
The default constructor.
void SetScoreSettingIndex(u32 settingIndex)
Sets the setting index for the score calculation method to use during nn::pia::inet::SELECTION_METHOD...
void SetAttribute(u32 index, u32 value)
Sets a value to use when searching for a single attribute.
The search condition class used when searching for a session.
Definition: inet_NexSessionSearchCriteria.h:43
void SetCommunityId(u32 gid)
Sets the ID for the associated community (persistent gathering).
SessionType
Enumerates the session types.
Definition: inet_NexSessionTypes.h:78
void SetMaxParticipants(u16 max)
Sets the maximum participants in the search criteria.
void SetNintendoCountryCode(u32 countryCode)
Sets the country code 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 SetRandomSessionSelectionMethod(SelectionMethod selectionMethod)
Sets the selection methods for joining sessions when random matchmaking is in effect.
void SetExcludeUserPasswordSet(bool bExclude)
Sets whether to exclude sessions for which a user password was set from the search. (By default, they are excluded.)
void SetGameMode(u32 gameMode)
Sets the search conditions to game mode.
void SetVacantOnly(bool bVacantOnly)
Sets whether to search only for sessions that have openings in the search criteria.
void SetUseGeoIp(bool b)
Sets whether to use position information (longitude and latitude, country code) for comparison during...
virtual ~NexSessionSearchCriteria()
The destructor.
void SetDisconnectionRate(u32 disconnectionRate)
Sets the disconnection rate to use for comparison during nn::pia::inet::SELECTION_METHOD_SCORE_BASED...
void SetSessionType(SessionType sessionType)
Sets the session type search conditions.