This page provides an overview of PiaSession. The PiaSession module consists of various components. Understanding what each of these components does makes it easier to program with PiaSession.
In PiaSession, the term session refers both to the group's matchmaking session on the matchmaking server (or on a local communication network), and to the P2P mesh network for P2P communications between the players. When a session is created and players join that session, the corresponding matchmaking session or local network and P2P mesh network are automatically created and joined by the players. You can also manage the matchmaking session or local network and the P2P mesh network separately if necessary. In the PiaSession module, the P2P mesh network is simply referred to as the mesh.
To manage the session, use session API functions that are called through the Session class. To directly control the mesh, use mesh API functions that are called through the Mesh class.
Use of both classes at the same time is not supported. When using the Session class, use only the session API. When directly controlling the mesh, use only the mesh API.
NEX matchmaking API functions are called inside the session API functions. For more information about the proper way to use each feature, see the chapter on matchmaking in the NEX Programming Manual.
The PiaSession documentation assumes use of the session API unless clearly indicated otherwise. Only descriptions pertaining to the mesh API are clearly marked as being the mesh API.
PiaSession supports matchmaking among sessions to join together multiple sessions. Use the joint session feature to join together multiple sessions.
In a joint session, all stations participating in the various sessions are automatically joined into the newly created joint session. The original sessions continue to exist, and when the joint session is destroyed, the stations all return to their original sessions. As an example of how the joint session feature can be used, separate sessions could be created for separate teams, who could then compete against each other in a newly created joint session. Although three or more sessions can be joined together, a joint session cannot be joined with other sessions or other joint sessions.
This chapter describes the features of the network topologies available with PiaSession. It also includes illustrations of the connections in each topology. For more information about relay transmissions and relay connections, see 6.10. Advanced Features - Relay Communication Feature .
The full-mesh network topology is represented by the NetworkTopology_FullMesh enumerator. Figure 6-2. Network Topology, Full-Mesh Connection shows a connection diagram for this topology.
A full-mesh session is guaranteed to establish a direct link of communication between all pairs of stations in the session.
It has the following characteristics.
We recommend using a full-mesh network topology if the communications of your application have specifications like the following. (This is only a recommendation. You are not prohibited from using this type of topology if you have different communication specifications.)
Also use a full-mesh network topology if you are using PiaLocal and using PiaSession for local CTR communications. (There are no advantages to using a topology other than full mesh because local networking on CTR uses a full-mesh network anyway.)
The relay mesh network topology corresponds to the NetworkTopology_RelayMesh enumerator. Figure 6-3. Network Topology, Relay Mesh Connection shows a connection diagram for this topology.
In a session using relay mesh topology, stations generally establish direct communication routes with each other, but relayed communication is used with some stations.
Relay communication is used with stations for which a direct communication route could not be established when they joined the session. (Using Figure 6-3. Network Topology, Relay Mesh Connection Image as an example, the Client1-Client4, Client1-Client5, Client2-Client4, and Client2-Client5 pairs use relay connections because they have no direct communication route.)
If all stations in the session are able to establish direct communication routes to the other stations when joining, the connection state is equivalent to a full-mesh network, but network use is slightly higher due to system traffic from the relay connection and relay communication processes.
It has the following characteristics.
We recommend using the relay mesh network topology if the communications of your application have specifications like the following. (This is only a recommendation. You are not prohibited from using this type of topology if you have different communication specifications.)