Photon C++ Client API  5.0.7.3
Public Member Functions | List of all members
RoomOptions Class Reference
Inheritance diagram for RoomOptions:
Inheritance graph
[legend]
Collaboration diagram for RoomOptions:
Collaboration graph
[legend]

Public Member Functions

 RoomOptions (bool isVisible=true, bool isOpen=true, nByte maxPlayers=0, const Common::Hashtable &customRoomProperties=Common::Hashtable(), const Common::JVector< Common::JString > &propsListedInLobby=Common::JVector< Common::JString >(), const Common::JString &lobbyName=Common::JString(), nByte lobbyType=LobbyType::DEFAULT, int playerTtl=0, int emptyRoomTtl=0, bool suppressRoomEvents=false, const Common::JVector< Common::JString > *pPlugins=NULL, bool publishUserID=false, nByte directMode=DirectMode::NONE)
 
 ~RoomOptions (void)
 
 RoomOptions (const RoomOptions &toCopy)
 
RoomOptionsoperator= (const RoomOptions &toCopy)
 
bool getIsVisible (void) const
 
RoomOptionssetIsVisible (bool isVisible)
 
bool getIsOpen (void) const
 
RoomOptionssetIsOpen (bool isOpen)
 
nByte getMaxPlayers (void) const
 
RoomOptionssetMaxPlayers (nByte maxPlayers)
 
const Common::HashtablegetCustomRoomProperties (void) const
 
RoomOptionssetCustomRoomProperties (const Common::Hashtable &customRoomProperties)
 
const Common::JVector< Common::JString > & getPropsListedInLobby (void) const
 
RoomOptionssetPropsListedInLobby (const Common::JVector< Common::JString > &propsListedInLobby)
 
const Common::JStringgetLobbyName (void) const
 
RoomOptionssetLobbyName (const Common::JString &lobbyName)
 
nByte getLobbyType (void) const
 
RoomOptionssetLobbyType (nByte lobbyType)
 
int getPlayerTtl (void) const
 
RoomOptionssetPlayerTtl (int playerTtl)
 
int getEmptyRoomTtl (void) const
 
RoomOptionssetEmptyRoomTtl (int emptyRoomTtl)
 
bool getSuppressRoomEvents (void) const
 
RoomOptionssetSuppressRoomEvents (bool suppressRoomEvents)
 
const Common::JVector< Common::JString > * getPlugins (void) const
 
RoomOptionssetPlugins (const Common::JVector< Common::JString > *pPlugins)
 
bool getPublishUserID (void) const
 
RoomOptionssetPublishUserID (bool publishUserID)
 
nByte getDirectMode (void) const
 
RoomOptionssetDirectMode (nByte directMode)
 
virtual Common::JStringtoString (Common::JString &retStr, bool withTypes=false) const
 
virtual JStringtoString (JString &retStr, bool withTypes=false) const=0
 
JString toString (bool withTypes=false) const
 
- Public Member Functions inherited from ToString
virtual ~ToString (void)
 
virtual JString typeToString (void) const
 
JString toString (bool withTypes=false) const
 

Detailed Description

This class aggregates the various optional parameters that can be specified on room creation.

See also
Client::opCreateRoom(), Client::opJoinOrCreateRoom()

Constructor & Destructor Documentation

◆ RoomOptions() [1/2]

RoomOptions ( bool  isVisible = true,
bool  isOpen = true,
nByte  maxPlayers = 0,
const Common::Hashtable customRoomProperties = Common::Hashtable(),
const Common::JVector< Common::JString > &  propsListedInLobby = Common::JVector<Common::JString>(),
const Common::JString lobbyName = Common::JString(),
nByte  lobbyType = LobbyType::DEFAULT,
int  playerTtl = 0,
int  emptyRoomTtl = 0,
bool  suppressRoomEvents = false,
const Common::JVector< Common::JString > *  pPlugins = NULL,
bool  publishUserID = false,
nByte  directMode = DirectMode::NONE 
)

Constructor: Creates a new instance with the specified parameters.

Parameters
isVisiblesee setIsVisible() - optional, defaults to true.
isOpensee setIsOpen() - optional, defaults to true.
maxPlayerssee setMaxPlayers() - optional, defaults to 0.
customRoomPropertiessee setCustomRoomProperties() - optional, defaults to an empty Hashtable instance.
propsListedInLobbysee setPropsListedInLobby() - optional, defaults to an empty JVector instance.
lobbyNamesee setLobbyName() - optional, defaults to an empty JString instance.
lobbyTypesee setLobbyType() - optional, defaults to LobbyType::DEFAULT.
playerTtlsee setPlayerTtl() - optional, defaults to 0.
emptyRoomTtlsee setEmptyRoomTtl() - optional, defaults to 0.
suppressRoomEventssee setSuppressRoomEvents() - optional, defaults to false.
pPluginssee setPlugins() - optional, defaults to NULL.
publishUserIDsee setPublishUserID() - optional, defaults to false.
directModesee setDirectMode() - optional, defaults to DirectMode::NONE.

◆ ~RoomOptions()

~RoomOptions ( void  )

Destructor.

◆ RoomOptions() [2/2]

RoomOptions ( const RoomOptions toCopy)

Copy-Constructor: Creates a new instance that is a deep copy of the argument instance.

Parameters
toCopyThe instance to copy.

Member Function Documentation

◆ operator=()

RoomOptions & operator= ( const RoomOptions toCopy)

operator=.

Makes a deep copy of its right operand into its left operand.

This overwrites old data in the left operand.

◆ getIsVisible()

bool getIsVisible ( void  ) const
Returns
the currently set value for the isVisible flag
See also
setIsVisible()

◆ setIsVisible()

RoomOptions & setIsVisible ( bool  isVisible)

Sets the initial state of the rooms visibility flag.

A room that is not visible is excluded from the room lists that are sent to the clients in lobbies. An invisible room can be joined by name but is excluded from random matchmaking.

Use this to "hide" a room and simulate "private rooms". Players can exchange a room name and create the room as invisible to avoid anyone else joining it.

Remarks
This function sets the initial value that is used for room creation. To change the value of the flag for an already existing room, see MutableRoom::setIsVisible().
Parameters
isVisiblethe new value to which the flag will be set
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getIsVisible()

◆ getIsOpen()

bool getIsOpen ( void  ) const
Returns
the currently set value for the isOpen flag
See also
setIsOpen()

◆ setIsOpen()

RoomOptions & setIsOpen ( bool  isOpen)

Sets the initial state of the rooms isOpen flag.

If a room is closed, then no further player can join it until the room gets reopened again. A closed room can still be listed in the lobby (use setIsVisible() to control lobby-visibility).

Remarks
This function sets the initial value that is used for room creation. To change the value of the flag for an already existing room, see MutableRoom::setIsOpen().
Parameters
isOpenthe new value to which the flag will be set
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getIsOpen()

◆ getMaxPlayers()

nByte getMaxPlayers ( void  ) const
Returns
the currently set max players
See also
setmaxPlayers()

◆ setMaxPlayers()

RoomOptions & setMaxPlayers ( nByte  maxPlayers)

Sets the initial value for the max players setting of the room.

This function sets the maximum number of players that can be inside the room at the same time, including inactive players. 0 means "no limit".

Remarks
This function sets the initial value that is used for room creation. To change the max players setting of an already existing room, see MutableRoom::setMaxPlayers().
Parameters
maxPlayersthe new maximum amount of players that can be inside the room at the same time
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getMaxPlayers()

◆ getCustomRoomProperties()

const Hashtable & getCustomRoomProperties ( void  ) const
Returns
the currently set custom room properties
See also
setCustomRoomProperties()

◆ setCustomRoomProperties()

RoomOptions & setCustomRoomProperties ( const Common::Hashtable customRoomProperties)

Sets the initial custom properties of a room.

Custom room properties are any key-value pairs that you need to define the game's setup. The shorter your key strings are, the better. Example: Map, Mode (could be L"m" when used with L"Map"), TileSet (could be L"t").

Note
JString is the only supported type for custom property keys. For custom property values you can use any type that is listed in the Table of Datatypes.
Attention: A property that only consists of a key, but does not have a value, results in a request to the server to delete this property. Although no room property can yet exist before the room has been created, this behavior still holds true when setting properties on room creation for consistency reasons. Hence you can't set a property without providing an initial value for it.
Remarks
This function sets the initial custom properties that are used for room creation. To change the custom properties of an already existing room, see MutableRoom::mergeCustomProperties(), MutableRoom::addCustomProperty(), MutableRoom::addCustomProperties(), MutableRoom::removeCustomProperty() and MutableRoom::removeCustomProperties().
Parameters
customRoomPropertiesa Hashtable of custom property key-value pairs
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getCustomRoomProperties(), setPropsListedInLobby()

◆ getPropsListedInLobby()

const JVector< JString > & getPropsListedInLobby ( void  ) const
Returns
the currently set list of properties to show in the lobby
See also
setPropsListedInLobby()

◆ setPropsListedInLobby()

RoomOptions & setPropsListedInLobby ( const Common::JVector< Common::JString > &  propsListedInLobby)

Sets the initial list of custom properties of the room that should be shown in the lobby.

List the keys of all the custom room properties that should be available to clients that are in a lobby. Use with care. Unless a custom property is essential for matchmaking or user info, it should not be sent to the lobby, which causes traffic and delays for clients in the lobby. Default: No custom properties are sent to the lobby.

Note
Properties that are intended to be shown in the lobby should be as compact as possible. Literally every single byte counts here as this info needs to be sent to every client in the lobby for every single visible room, so that with lots of users online and games running this quickly adds up to a lot of data.
Remarks
This function sets the initial list of property keys. To change which properties are shown to the lobby for an already existing room see MutableRoom::setPropsListedInLobby().
Parameters
propsListedInLobbythe keys of the custom room properties that should be shown in the lobby
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getPropsListedInLobby(), setCustomRoomProperties()

◆ getLobbyName()

const JString & getLobbyName ( void  ) const
Returns
the currently set lobby name
See also
setLobbyName()

◆ setLobbyName()

RoomOptions & setLobbyName ( const Common::JString lobbyName)

Sets the name of the lobby to which the room gets added to.

Rooms can be assigned to different lobbies on room creation. Client::opJoinRandomRoom() only uses those rooms for matchmaking that are assigned to the lobby in which it is told to be looking for rooms. A lobby can be joined by a call to Client::opJoinLobby() and inside lobbies of certain types clients can receive room lists that contain all visible rooms that are assigned to that lobby.

Remarks
If you don't set a lobby name or if you set it to an empty string, then any value that is passed for setLobbyType() gets ignored and the room gets added to the default lobby.
Lobbies are unique per lobbyName plus lobbyType, so multiple different lobbies may have the same name, as long as they are of a different type.
Parameters
lobbyNameidentifies for the lobby and needs to be unique within the scope of the lobbyType
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getLobbyName(), setLobbyType(), Matchmaking Guide

◆ getLobbyType()

nByte getLobbyType ( void  ) const
Returns
the currently set lobby type
See also
setLobbyType()

◆ setLobbyType()

RoomOptions & setLobbyType ( nByte  lobbyType)

Sets the type of the lobby to which the room gets added to. Must be one of the values in LobbyType

Please see Matchmaking Guide regarding the differences between the various lobby types.

Note
This option gets ignored and the room gets added to the default lobby, if you don't also set the lobby name to a non-empty string via a call to setLobbyName().
Parameters
lobbyTypeone of the values in LobbyType
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getLobbyType(), setLobbyName(), LobbyType, Matchmaking Guide

◆ getPlayerTtl()

int getPlayerTtl ( void  ) const
Returns
the currently set player time to live in milliseconds
See also
setPlayerTtl()

◆ setPlayerTtl()

RoomOptions & setPlayerTtl ( int  playerTtl)

Sets the player time to live in milliseconds.

If a client disconnects or if it leaves a room with the 'willComeBack' flag set to true, it's player becomes inactive first and only gets removed from the room after this timeout.

  • -1 and INT_MAX set the inactivity time to 'infinite'.
  • 0 (default) deactivates player inactivity.
  • All other positive values set the inactivity time to their value in milliseconds.
  • All other negative values get ignored and the behavior for them is as if the default value was used.
Note
A player is only able to rejoin a room in its existing player slot while it is still inactive. Once it has left for good it will be treated as a completely new player.
Parameters
playerTtla value between -1 and INT_MAX
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getPlayerTtl(), Client::opLeaveRoom(), Client::disconnect()

◆ getEmptyRoomTtl()

int getEmptyRoomTtl ( void  ) const
Returns
the currently set empty room time to live in milliseconds
See also
setEmptyRoomTtl()

◆ setEmptyRoomTtl()

RoomOptions & setEmptyRoomTtl ( int  emptyRoomTtl)

Sets the room time to live in milliseconds.

The amount of time in milliseconds that Photon servers should wait before disposing an empty room. A room is considered empty when there is no active player joined to it. So the room disposal timer starts when the last active player leaves. When a player joins or rejoins the room, then the countdown is reset.

By default, the maximum value allowed is:

  • 300000ms (5 minutes) on Photon Cloud
  • 60000ms (1minute) on Photon Server
  • 0 (default) means that an empty room gets instantly disposed.
  • All positive values set the keep-alive time to their value in milliseconds.
  • All negative values get ignored and the behavior for them is as if the default value was used.
Note
The disposal of a room means that the room gets removed from memory on the server side. Without accordingly configured Webhooks this also means that the room will be destroyed and all data related to it (like room and player properties, event caches, inactive players, etc.) gets deleted. When Webhooks for the used appID have been been set up for room persistence, then disposed rooms get stored for later retrieval. Stored rooms get reconstructed in memory when a player joins or rejoins them
Parameters
emptyRoomTtla value between 0 and INT_MAX
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getEmptyRoomTtl(), Persistence Guide, Webhooks FAQ

◆ getSuppressRoomEvents()

bool getSuppressRoomEvents ( void  ) const
Returns
the currently set value for the suppressRoomEvents flag
See also
setSuppressRoomEvents()

◆ setSuppressRoomEvents()

RoomOptions & setSuppressRoomEvents ( bool  suppressRoomEvents)

Sets the value of the suppressRoomEvents flag which determines if the server should skip room events for joining and leaving players.

Setting this flag to true makes the client unaware of the other players in a room. That can save some traffic if you have some server logic that updates players, but it can also limit the client's usability.

Parameters
suppressRoomEventsthe new value to which the flag will be set
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getSuppressRoomEvents()

◆ getPlugins()

const JVector< JString > * getPlugins ( void  ) const
Returns
the currently set list of plugins
See also
setPlugins()

◆ setPlugins()

RoomOptions & setPlugins ( const Common::JVector< Common::JString > *  pPlugins)

Informs the server of the expected plugin setup.

The operation will fail in case of a plugin mismatch returning ErrorCode::PLUGIN_MISMATCH. Setting an empty JVector means that the client expects no plugin to be setup. Note: for backwards compatibility setting NULL (the default value) omits any check.

Parameters
pPluginsthe expected plugins
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getPlugins()

◆ getPublishUserID()

bool getPublishUserID ( void  ) const
Returns
the currently set value for the publishUserID flag
See also
setPublishUserID()

◆ setPublishUserID()

RoomOptions & setPublishUserID ( bool  publishUserID)

Defines if the UserIds of players get "published" in the room. Useful for Client::opFindFriends(), if players want to play another game together.

When you set this to true, Photon will publish the UserIds of the players in that room. In that case, you can use Player::getUserID(), to access any player's userID. This is useful for Client::opFindFriends() and to set "expected users" to reserve slots in a room (see Client::opCreateRoom(), Client::opJoinOrCreateRoom() and Client::opJoinRoom()).

Parameters
publishUserIDtrue, if userIDs should be published, false otherwise
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getPublishUserID()

◆ getDirectMode()

nByte getDirectMode ( void  ) const
Returns
the currently set value for the DirectMode flag
See also
setDirectMode()

◆ setDirectMode()

RoomOptions & setDirectMode ( nByte  directMode)

Sets the DirectMode that should be used for this room.

The value of this option determines if clients establish direct peer to peer connections with other clients that can then be used to send them direct peer to peer messages with Client::sendDirect().

Parameters
directModeone of the values in DirectMode
Returns
a reference to the instance on which it was called to allow for chaining multiple setter calls
See also
getDirectMode()

◆ toString() [1/3]

JString & toString ( Common::JString retStr,
bool  withTypes = false 
) const
virtual
Remarks
The cost of this function depends a lot on implementation details of the implementing subclasses, but for container classes this function can become quite expensive, if the instance contains huge amounts of data, as its cost for many container class implementations increases disproportionately high to the size of the payload.
Parameters
retStrreference to a string, to store the return-value in; the information, which is generated by this function, will be attached at the end of any eventually existing previous content of the string
withTypesset to true, to include type information in the generated string
Returns
a JString representation of the instance and its contents for debugging purposes.

Implements ToString.

◆ toString() [2/3]

toString
Remarks
The cost of this function depends a lot on implementation details of the implementing subclasses, but for container classes this function can become quite expensive, if the instance contains huge amounts of data, as its cost for many container class implementations increases disproportionately high to the size of the payload.
Parameters
retStrreference to a string, to store the return-value in; the information, which is generated by this function, will be attached at the end of any eventually existing previous content of the string
withTypesset to true, to include type information in the generated string
Returns
a JString representation of the instance and its contents for debugging purposes.

◆ toString() [3/3]

JString toString

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
withTypesset to true, to include type information in the generated string
Returns
a JString representation of the instance and its contents for debugging purposes.
See also
JString