nn::nex::MatchmakeExtensionClient::AutoMatchmake Member Function

Syntax

qBool AutoMatchmake(
     ProtocolCallContext * pContext,
     const GatheringHolder & matchmakingSession,
     GatheringHolder * joinedMatchmakingSession,
     const String strMessage = _T("")
);

qBool AutoMatchmake(
     ProtocolCallContext * pContext,
     const qList< MatchmakeSessionSearchCriteria > & searchCriteriaList,
     const GatheringHolder & matchmakingSession,
     GatheringHolder * joinedMatchmakingSession,
     const String strMessage = _T("")
);

qBool AutoMatchmake(
     ProtocolCallContext * pContext,
     const qList< GatheringID > gidList,
     const GatheringHolder & matchmakingSession,
     GatheringHolder * joinedMatchmakingSession,
     const String strMessage = _T("")
);

qBool AutoMatchmake(
     ProtocolCallContext * pContext,
     const AutoMatchmakeParam & autoMatchmakeParam,
     MatchmakeSession * joinedMatchmakingSession
);

Overloaded Member Functions

AutoMatchmake ( ProtocolCallContext *, const GatheringHolder &, GatheringHolder *, const String ) Automatically searches for and joins matchmaking sessions.
AutoMatchmake ( ProtocolCallContext *, const qList< MatchmakeSessionSearchCriteria > &, const GatheringHolder &, GatheringHolder *, const String ) Automatically searches for and joins matchmaking sessions.
AutoMatchmake ( ProtocolCallContext *, const qList< GatheringID >, const GatheringHolder &, GatheringHolder *, const String ) Joins the specified gathering.
AutoMatchmake ( ProtocolCallContext *, const AutoMatchmakeParam &, MatchmakeSession * ) Automatically searches for and joins matchmaking sessions.

Description of AutoMatchmake ( ProtocolCallContext *, const GatheringHolder &, GatheringHolder *, const String )

We recommend using the overload that takes AutoMatchmakeParam as an argument. A search is made for a matchmaking session (gathering) from among the specified matchmaking session information. If a matchmaking session that matches the information is found, the station joins that session. If a matching session is not found, a matchmaking session is created, and the station joins that session and the local host becomes the host.
A search is made for a joinable session that matches all of the following:
・Game mode
・Minimum and maximum number of participants
・Matchmaking system type
・Search attributes
However, the three most recently joined matchmaking sessions are removed from the server as possible sessions to join. This helps prevent the problem of joining the same matchmaking session multiple times, which can result from auto matchmaking even though a P2P connection cannot be established (because, for example, NAT traversal is not possible). The participant record on the server side becomes invalid after about one hour. If the local user is the creator of the matchmaking session, that system is not included in the participant record. Sessions that do not yet have a host for P2P communication are also excluded from the join targets. If you want to include matchmaking sessions without a host in the joinable sessions because, for example, P2P communication is not used, use the overload that takes MatchmakeSessionSearchCriteria as a parameter and call MatchmakeSessionSearchCriteria::SetExcludeNonHostPid(false).

The asynchronous process might return the following results.

Pass the following error to the Error/EULA applet. Errors must be removed during debugging.

QERROR(Core, InvalidArgument): The string or buffer that was to be sent is too large. MATCHMAKE_SYSTEM_TYPE_PERSISTENT_GATHERING or MATCHMAKE_SYSTEM_TYPE_OLV_COMMUNITY was specified for the matchmaking system type, but the gathering ID of the persistent gathering was not set as the 0th attribute or as a related persistent gathering ID.

You can choose to either handle the following error in the application or pass it to the error/EULA applet.

QERROR(RendezVous, GameServerMaintenance): This error occurs when the function is called between the GameServerMaintenance notification event and when game server maintenance takes place.

Description of AutoMatchmake ( ProtocolCallContext *, const qList< MatchmakeSessionSearchCriteria > &, const GatheringHolder &, GatheringHolder *, const String )

We recommend using the overload that takes AutoMatchmakeParam as an argument. A search is made for a matchmaking session (gathering) based on the specified search conditions. If a search match is found, that session is joined. If there is no match to the search conditions, a new matchmaking session is created based on the specified matchmaking session information and the station joins that newly created session as the host.
However, the three most recently joined matchmaking sessions are removed from the server as possible sessions to join. This helps prevent the problem of joining multiple times into the same matchmaking session, which can result from auto matchmaking even though a P2P connection cannot be established (because, for example, NAT traversal is not possible). The participant record on the server side becomes invalid after about one hour. If the local host is the creator of the matchmaking session, that system is not included in the participant record.

When multiple search conditions are passed as a list, the game server conducts the search starting from the top of the list. (The search is ended when a session is joined.) In other words, you can search for matchmaking sessions as gradually easing your search conditions.

Sessions that are locked to participants or full are automatically excluded from the search. Up to two search criteria can be specified. If three or more are specified, a QERROR(Core, InvalidArgument) occurs.

The asynchronous process might return the following results.

You can choose to either handle the following error in the application or pass it to the error/EULA applet.

QERROR(RendezVous, GameServerMaintenance): This error occurs when the function is called between the GameServerMaintenance notification event and when game server maintenance takes place.

Pass the following error to the Error/EULA applet. This error must be removed during debugging.
QERROR(Core, InvalidArgument): The application attempted to send a string that exceeds the buffer size. No gathering ID was set on the persistent gathering during persistent gathering matchmaking. MATCHMAKE_SYSTEM_TYPE_PERSISTENT_GATHERING or MATCHMAKE_SYSTEM_TYPE_OLV_COMMUNITY was specified for the matchmaking system type, but the gathering ID of the persistent gathering was not set as the 0th attribute or as a related persistent gathering ID.
QERROR(RendezVous, OutOfRatingRange): When MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE or MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE_WITH_PROGRESS_SCORE is set with the MatchmakeSessionSearchCriteria::SetSelectionMethod function, the attributes of the MATCHMAKE_SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX index are out of range.

Description of AutoMatchmake ( ProtocolCallContext *, const qList< GatheringID >, const GatheringHolder &, GatheringHolder *, const String )

We recommend using the overload that takes AutoMatchmakeParam as an argument. Joins the matchmaking session (gathering) with the specified gathering ID. You can specify multiple gathering IDs, and the function attempts to join the matchmaking session that corresponds to each gathering ID, starting from the beginning of the list. The function returns the first matchmaking session that can be joined.

If the specified matchmaking session cannot be joined, the function creates a new matchmaking session based on the specified matchmaking session, joins the session, and makes the local system the host.

In contrast with the other AutoMatchmake functions, this function does not remove the past three matchmaking sessions that were joined from the matchmaking sessions to attempt joining in.

Have the application search for a joinable session using the BrowseMatchmakeSession function and then filtering the search results. Then use this function to join the matchmaking session or implement code that allows creating one. Note that in most cases you can achieve the same result by using the AutoMatchmake function, which allows you to specify search conditions by appropriately specifying MatchmakeSessionSearchCriteria. First, consider using the AutoMatchmake function, which allows you to specify search conditions.

If you are also going to use this function, we strongly recommend that you implement code in such a way that matchmaking sessions are not unnecessarily created because the matchmaking session could not be joined (or another reason), and also so that multiple gathering IDs can be specified and the order of the list differs as much as possible for each client.

The asynchronous process might return the following results.

Pass the following error to the Error/EULA applet. This error must be removed during debugging.

QERROR(Core, InvalidArgument): The string or buffer that was to be sent is too large. MATCHMAKE_SYSTEM_TYPE_PERSISTENT_GATHERING or MATCHMAKE_SYSTEM_TYPE_OLV_COMMUNITY was specified for the matchmaking system type, but the gathering ID of the persistent gathering was not set as the 0th attribute or as a related persistent gathering ID.

You can choose to either handle the following error in the application or pass it to the error/EULA applet.

QERROR(RendezVous, GameServerMaintenance): This error occurs when the function is called between the GameServerMaintenance notification event and when game server maintenance takes place.

Description of AutoMatchmake ( ProtocolCallContext *, const AutoMatchmakeParam &, MatchmakeSession * )

A search is made for a matchmaking session (gathering) based on the specified content in AutoMatchmakeParam. If a search match is found, that session is joined. If a matching session is not found, a matchmaking session is created, and the station joins that session and the local user becomes the host.
This is the only overload of the MatchmakeExtensionClient::AutoMatchmake function that can add multiple users to a matchmaking session.

The following results may be returned as a result of asynchronous operation. Use the application to handle these results.

QERROR(RendezVous, NotParticipatedGathering): The user that the function attempted to add is not a participant of the gathering specified by the AutoMatchmakeParam::SetGatheringIdForParticipationCheck function.

Pass the following error to the Error/EULA applet. This error must be removed during debugging.

QERROR(Core, InvalidArgument): The string or buffer that was to be sent is too large. MATCHMAKE_SYSTEM_TYPE_PERSISTENT_GATHERING or MATCHMAKE_SYSTEM_TYPE_OLV_COMMUNITY was specified for the matchmaking system type, but the gathering ID of the persistent gathering was not set as the 0th attribute or as a related persistent gathering ID.
QERROR(RendezVous, OutOfRatingRange): When MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE or MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE_WITH_PROGRESS_SCORE is set with the MatchmakeSessionSearchCriteria::SetSelectionMethod function, the attribute of the MATCHMAKE_SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX index is out of range.
You can choose to either handle the following error in the application or pass it to the error/EULA applet.

QERROR(RendezVous, GameServerMaintenance): This error occurs when the function is called between the GameServerMaintenance notification event and when game server maintenance takes place.


CONFIDENTIAL