public interface

# RealTimeMultiplayer

com.google.android.gms.games.multiplayer.realtime.RealTimeMultiplayer

## Class Overview

Entry point for real-time multiplayer functionality.

## Summary

Nested Classes
interface | RealTimeMultiplayer.ReliableMessageSentCallback | The listener for callback that is called when a reliable message is sent successfully.

Constants
int | REAL_TIME_MESSAGE_FAILED | Return value indicating immediate failure.

Public Methods
abstract void | create(GoogleApiClient apiClient, RoomConfig config) Create a real-time room for the current game.
abstract void | declineInvitation(GoogleApiClient apiClient, String invitationId) Decline an invitation for a real-time room.
abstract void | dismissInvitation(GoogleApiClient apiClient, String invitationId) Dismiss an invitation to a real-time room.
abstract Intent | getSelectOpponentsIntent(GoogleApiClient apiClient, int minPlayers, int maxPlayers, boolean allowAutomatch) Returns an intent that will let the user select opponents to send an invitation to for a real-time multiplayer match.
abstract Intent | getSelectOpponentsIntent(GoogleApiClient apiClient, int minPlayers, int maxPlayers) Returns an intent that will let the user select opponents to send an invitation to for a real-time multiplayer match.
abstract Intent | getWaitingRoomIntent(GoogleApiClient apiClient, Room room, int minParticipantsToStart) Returns an intent that will display a "waiting room" screen that shows the progress of participants joining a real-time multiplayer room.
abstract void | join(GoogleApiClient apiClient, RoomConfig config) Join a real-time room by accepting an invitation.
abstract void | leave(GoogleApiClient apiClient, RoomUpdateListener listener, String roomId) Leave the specified room.
abstract int | sendReliableMessage(GoogleApiClient apiClient, RealTimeMultiplayer.ReliableMessageSentCallback listener, byte[] messageData, String roomId, String recipientParticipantId) Send a message to a participant in a real-time room reliably.
abstract int | sendUnreliableMessage(GoogleApiClient apiClient, byte[] messageData, String roomId, String recipientParticipantId) Send a message to a participant in a real-time room.
abstract int | sendUnreliableMessage(GoogleApiClient apiClient, byte[] messageData, String roomId, List<String> recipientParticipantIds) Send a message to one or more participants in a real-time room.
abstract int | sendUnreliableMessageToOthers(GoogleApiClient apiClient, byte[] messageData, String roomId) Send a message to all participants in a real-time room, excluding the current player.

## Constants

#### public static final int REAL_TIME_MESSAGE_FAILED

Return value indicating immediate failure. Returned by `sendUnreliableMessage(GoogleApiClient, byte[], String, String)` and `sendReliableMessage(GoogleApiClient, ReliableMessageSentCallback, byte[], String, String)` methods when the message send operation failed due to an error.

Constant Value: -1 (0xffffffff)

## Public Methods

#### public abstract void create (GoogleApiClient apiClient, RoomConfig config)

Create a real-time room for the current game. The lifetime of the current game's connection to the room is bound to this `GoogleApiClient`'s lifecycle. When the client disconnects, the player will leave the room and any peer-to-peer connections for this player will be torn down. The result is delivered by the callback `onRoomCreated(int, Room)` to the given RoomUpdateListener in the `RoomConfig`. The listener is called on the main thread.

The room created by this API is a resource that needs to be released by `leave(GoogleApiClient, RoomUpdateListener, String)` when the caller is done with it.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
config | The real-time room configuration.

#### public abstract void declineInvitation (GoogleApiClient apiClient, String invitationId)

Decline an invitation for a real-time room.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
invitationId | The ID of the invitation to decline.

#### public abstract void dismissInvitation (GoogleApiClient apiClient, String invitationId)

Dismiss an invitation to a real-time room. Dismissing an invitation will not change the state of the room for the other participants.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
invitationId | The ID of the invitation to dismiss.

#### public abstract Intent getSelectOpponentsIntent (GoogleApiClient apiClient, int minPlayers, int maxPlayers, boolean allowAutomatch)

Returns an intent that will let the user select opponents to send an invitation to for a real-time multiplayer match. Note that this must be invoked with `startActivityForResult(Intent, int)`, so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, `minPlayers` would be 1 and `maxPlayers` would be 3.

Players may be preselected by specifying a list of player IDs in the `EXTRA_PLAYER_IDS` extra on the returned intent.

If the user canceled, the result will be `RESULT_CANCELED`. If the user selected players, the result will be `RESULT_OK`, and the data intent will contain the selected player IDs in `EXTRA_PLAYER_IDS` and the minimum and maximum numbers of additional auto-match players in `EXTRA_MIN_AUTOMATCH_PLAYERS` and `EXTRA_MAX_AUTOMATCH_PLAYERS` respectively. The player IDs in `EXTRA_PLAYER_IDS` will include only the other players selected, not the current player.

If the `allowAutomatch` parameter is set to false, the UI will not display an option for selecting automatch players. Set this to false if your game does not support automatching.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
minPlayers | The minimum number of players to select (not including the current player).
maxPlayers | The maximum number of players to select (not including the current player).
allowAutomatch | Whether or not to display an option for selecting automatch players.

##### Returns

- An `Intent` that can be started to display the player selector.

##### See Also

- `create(GoogleApiClient, RoomConfig)`

#### public abstract Intent getSelectOpponentsIntent (GoogleApiClient apiClient, int minPlayers, int maxPlayers)

Returns an intent that will let the user select opponents to send an invitation to for a real-time multiplayer match. Note that this must be invoked with `startActivityForResult(Intent, int)`, so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, `minPlayers` would be 1 and `maxPlayers` would be 3.

Players may be preselected by specifying a list of player IDs in the `EXTRA_PLAYER_IDS` extra on the returned intent.

If the user canceled, the result will be `RESULT_CANCELED`. If the user selected players, the result will be `RESULT_OK`, and the data intent will contain the selected player IDs in `EXTRA_PLAYER_IDS` and the minimum and maximum numbers of additional auto-match players in `EXTRA_MIN_AUTOMATCH_PLAYERS` and `EXTRA_MAX_AUTOMATCH_PLAYERS` respectively. The player IDs in `EXTRA_PLAYER_IDS` will include only the other players selected, not the current player.

This method is the equivalent of calling `getSelectOpponentsIntent(GoogleApiClient, int, int, boolean)` with the `allowAutomatch` parameter set to true.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
minPlayers | The minimum number of players to select (not including the current player).
maxPlayers | The maximum number of players to select (not including the current player).

##### Returns

- An `Intent` that can be started to display the player selector.

##### See Also

- `create(GoogleApiClient, RoomConfig)`

#### public abstract Intent getWaitingRoomIntent (GoogleApiClient apiClient, Room room, int minParticipantsToStart)

Returns an intent that will display a "waiting room" screen that shows the progress of participants joining a real-time multiplayer room. Note that this must be invoked with `startActivityForResult(Intent, int)`, so that the identity of the calling package can be established.

If the necessary number of peers have connected and it's now OK to start the game, or if the user explicitly asked to start the game now, the activity result will be `RESULT_OK`. If the user bailed out of the waiting room screen without taking any action, the result will be `RESULT_CANCELED`. If the user explicitly chose to leave the room, the result will be `RESULT_LEFT_ROOM`. If the room no longer exists or is otherwise invalid the result will be `RESULT_INVALID_ROOM`.

Regardless of what the result code was, the waiting room activity will return a data intent containing a `Room` object in `EXTRA_ROOM` that represents the current state of the Room that you originally passed as a parameter here. Note that the returned room may be null if the room no longer exists.

If desired, the waiting room can allow the user to start playing the game even before the room is fully connected. This is controlled by the `minParticipantsToStart` parameter: if at least that many participants (including the current player) are connected to the room, a "Start playing" menu item will become enabled in the waiting room UI. Setting `minParticipantsToStart` to 0 means that "Start playing" will always be available, and a value of `MAX_VALUE` will disable the item completely. Note: if you do allow the user to start early, you'll need to handle that situation by explicitly telling the other connected peers that the game is now starting; see the developer documentation for more details.

Finally, note that the waiting room itself will never explicitly take any action to change the state of the room or its participants. So if the activity result is `RESULT_LEFT_ROOM`, it's the caller's responsibility to actually leave the room. Or if the result is `RESULT_CANCELED`, it's the responsibility of the caller to double-check the current state of the Room and decide whether to start the game, keep waiting, or do something else. But note that while the waiting room is active, the state of the Room will change as participants accept or decline invitations, and the number of participants may even change as auto-match players get added.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
room | The `Room` object to be displayed.
minParticipantsToStart | the minimum number of participants that must be connected to the room (including the current player) for the "Start playing" menu item to become enabled.

##### Returns

- An `Intent` that can be started to display the waiting room screen.

##### See Also

- `create(GoogleApiClient, RoomConfig)`
- `leave(GoogleApiClient, RoomUpdateListener, String)`

#### public abstract void join (GoogleApiClient apiClient, RoomConfig config)

Join a real-time room by accepting an invitation. The lifetime of the current game's connection to the room is bound to this `GoogleApiClient`'s lifecycle. When the client disconnects, the player will leave the room and any peer-to-peer connections for this player will be torn down. The result is delivered by the callback `onJoinedRoom(int, Room)` to the given RoomUpdateListener in the `RoomConfig`. The listener is called on the main thread.

The room created by this API is a resource that needs to be released by `leave(GoogleApiClient, RoomUpdateListener, String)` when the caller is done with it.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
config | The real-time room configuration.

#### public abstract void leave (GoogleApiClient apiClient, RoomUpdateListener listener, String roomId)

Leave the specified room. This will disconnect the player from the room, but allow other players to continue playing the game. The result is delivered by the callback `onLeftRoom(int, String)` to the given listener on the main thread.

After this method is called, you cannot perform any further actions on the room. You can create or join another room only after `onLeftRoom(int, String)` is received.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
listener | The listener that is notified after the room has been left. The listener is called on the main thread.
roomId | ID of the room to leave.

#### public abstract int sendReliableMessage (GoogleApiClient apiClient, RealTimeMultiplayer.ReliableMessageSentCallback listener, byte[] messageData, String roomId, String recipientParticipantId)

Send a message to a participant in a real-time room reliably. The caller will receive a callback to report the status of the send message operation. Throws an `IllegalArgumentException` if recipientParticipantId is not a valid participant or belongs to the current player. The maximum message size supported is `MAX_RELIABLE_MESSAGE_LEN` bytes.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
listener | The listener that is notified when the message has been sent.
messageData | The message to be sent. Should be at most `MAX_RELIABLE_MESSAGE_LEN` bytes.
roomId | ID of the room for which the message is being sent.
recipientParticipantId | The participant ID to send the message to.

##### Returns

- The token for the message sent, which is returned in callback `onRealTimeMessageSent(int, int, String)`, or `REAL_TIME_MESSAGE_FAILED` if the message failed to send.

#### public abstract int sendUnreliableMessage (GoogleApiClient apiClient, byte[] messageData, String roomId, String recipientParticipantId)

Send a message to a participant in a real-time room. The message delivery is not reliable and will not report status after completion. Throws an `IllegalArgumentException` if recipientParticipantId is not a valid participant or belongs to the current player. The maximum message size supported is `MAX_UNRELIABLE_MESSAGE_LEN` bytes.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
messageData | The message to be sent. Should be at most `MAX_UNRELIABLE_MESSAGE_LEN` bytes.
roomId | ID of the room for which the message is being sent.
recipientParticipantId | The participant ID to send the message to.

##### Returns

- `STATUS_OK` on a successful attempt, `REAL_TIME_MESSAGE_FAILED` if the message failed to send.

#### public abstract int sendUnreliableMessage (GoogleApiClient apiClient, byte[] messageData, String roomId, List<String> recipientParticipantIds)

Send a message to one or more participants in a real-time room. The message delivery is not reliable and will not report status after completion. Throws an `IllegalArgumentException` if any participants in recipientParticipantIds are not valid or belong to the current player. The maximum message size supported is `MAX_UNRELIABLE_MESSAGE_LEN` bytes.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
messageData | The message to be sent. Should be at most `MAX_UNRELIABLE_MESSAGE_LEN` bytes.
roomId | ID of the room for which the message is being sent.
recipientParticipantIds | One or more participant IDs to send the message to.

##### Returns

- `STATUS_OK` on a successful attempt, `REAL_TIME_MESSAGE_FAILED` if the message failed to send.

#### public abstract int sendUnreliableMessageToOthers (GoogleApiClient apiClient, byte[] messageData, String roomId)

Send a message to all participants in a real-time room, excluding the current player. The message delivery is not reliable and will not report status after completion. The maximum message size supported is `MAX_UNRELIABLE_MESSAGE_LEN` bytes.

Required API: `API`
Required Scopes: `SCOPE_GAMES`

##### Parameters

apiClient | The `GoogleApiClient` to service the call.
messageData | The message to be sent. Should be at most `MAX_UNRELIABLE_MESSAGE_LEN` bytes.
roomId | ID of the room for which the message is being sent.

##### Returns

- `STATUS_OK` on a successful attempt, `REAL_TIME_MESSAGE_FAILED` if the message failed to send.