Entire Class Index | Main Class Index | Cross Index | Global Index

# Class CL_NetSession

CL_NetSession is the interface to communcation with a network session/game.
Contained in: global
Derived from: none
Derived by: none
Group: Network (NetSessions)

#include <ClanLib/network.h>

### public function member index:
### Construction:
`` | `CL_NetSession` | `(`const` `std::string`& `app_id`, `int` `port`)`;
`` | `CL_NetSession` | `(`const` `std::string`& `app_id`, `const` `std::string`& `hostname`, `int` `port`)`;
`` | `CL_NetSession` | `(`const` `CL_ServerInfo`& `server`)`;
`` | `CL_NetSession` | `(`const` `CL_NetSession`& `copy`)`;
``virtual`` | `~CL_NetSession` | `()`;
### Attributes:
``CL_EventTrigger`*` | `get_trigger` | `()`;
``CL_NetComputer`&` | `get_server` | `()`;
``CL_NetGroup`&` | `get_all` | `()`;
``bool`` | `peek` | `(`int` `channel`) `const``;
``int`` | `access_status` | `(`int` `channel`) `const``;
``bool`` | `is_writable` | `(`int` `channel`) `const``;
``bool`` | `is_readable` | `(`int` `channel`) `const``;
### Operations:
``void`` | `operator``=` | `(`const` `CL_NetSession`& `session`)`;
``CL_NetMessage`` | `receive` | `(`int` `channel`, `int` `timeout` = -1)`;
``void`` | `send` | `(`const` `int` `dest_channel`, `const` `CL_NetGroup`& `dest`, `const` `CL_NetMessage`& `message`, `bool` `reliable` = true)`;
``CL_NetComputer`` | `receive_computer_leave` | `()`;
``CL_NetComputer`` | `receive_computer_join` | `()`;
``CL_NetComputer`` | `receive_computer_rejoin` | `()`;
``bool`` | `receive_session_closed` | `()`;
``int`` | `receive_access_changed` | `()`;
``void`` | `set_access` | `(`int` `channel`, `const` `CL_NetGroup`& `group`, `int` `access_rights` = ACCESS_CHANNEL_READ | ACCESS_CHANNEL_WRITE)`;
### Signals:
``CL_Signal_v2`<`CL_NetMessage`& , `int`>&` | `sig_receive_message_default` | `()`;
``CL_Signal_v1`<`CL_NetComputer`>&` | `sig_computer_leave` | `()`;
``CL_Signal_v1`<`CL_NetComputer`>&` | `sig_computer_join` | `()`;
``CL_Signal_v1`<`CL_NetComputer`>&` | `sig_computer_rejoin` | `()`;
``CL_Signal_v1`<`int`>&` | `sig_access_changed` | `()`;
``CL_Signal_v0`&` | `sig_session_closed` | `()`;
### Implementation:
`` | `CL_NetSession` | `(`class` `CL_NetSession_Generic`* `impl`)`;

## Description:

## Function Member Descriptions:

CL_NetSession::CL_NetSession - Create a netsession server on the specified port. Only netsession clients with same application ID will be able to connect to the server.
`` `CL_NetSession``(`const` `std::string`& `app_id`, `int` `port`)`;

CL_NetSession::CL_NetSession - Create a netsession client and connect to a server.
`` `CL_NetSession``(`const` `std::string`& `app_id`, `const` `std::string`& `hostname`, `int` `port`)`;

CL_NetSession::CL_NetSession - Connect to a server coming from a server info structure. Usually used together with master browse servers and LAN broadcast browsing.
`` `CL_NetSession``(`const` `CL_ServerInfo`& `server`)`;

CL_NetSession::CL_NetSession - Copy constructor.
`` `CL_NetSession``(`const` `CL_NetSession`& `copy`)`;

CL_NetSession::access_status - Returns the access status flags on the channel.
``int`` `access_status``(`int` `channel`) `const``;

CL_NetSession::get_all - A group of all the computers in the netsession.
``CL_NetGroup`&` `get_all``()`;

CL_NetSession::get_server - The server of the network game.
``CL_NetComputer`&` `get_server``()`;

CL_NetSession::get_trigger - Event trigger that triggers when the netsession object changes (on incoming data).
``CL_EventTrigger`*` `get_trigger``()`;

CL_NetSession::is_readable - Returns true if the ACCESS_CHANNEL_READ flag is set on channel.
``bool`` `is_readable``(`int` `channel`) `const``;

CL_NetSession::is_writable - Returns true if the ACCESS_CHANNEL_WRITE flag is set on channel.
``bool`` `is_writable``(`int` `channel`) `const``;

CL_NetSession::operator = - Makes a copy of the current session. Since sessions are reference counted, this just means you will have two handles for the same session.
``void`` `operator``=``(`const` `CL_NetSession`& `session`)`;

CL_NetSession::peek - Returns true if a message is available on the specified channel.
``bool`` `peek``(`int` `channel`) `const``;

CL_NetSession::receive - Receives a message from the specified channel. The call is blocking, so don't call it if you aren't completly sure it will arrive (unless you set a timeout).
Note, if you don't want to poll, use the signals below.
``CL_NetMessage`` `receive``(`int` `channel`, `int` `timeout` = -1)`;

> channel - Channel to look for a message.
> timeout - Timeout, -1 means block forever.
> Returns - The message received from the specified channel.

CL_NetSession::receive_access_changed - Returns the first netchannel that has had its access changed. Returns -1 when no more channels have had their access changed.
This function only works on a client netsession.
Note, if you don't want to poll, use the signals below.
``int`` `receive_access_changed``()`;

CL_NetSession::receive_computer_join - Returns the first (if more) computer that is joining the game, or throws an exception if none joined. The next time the function is called, it returns the next computer, etc.
Note, if you don't want to poll, use the signals below.
``CL_NetComputer`` `receive_computer_join``()`;

CL_NetSession::receive_computer_leave - Returns the first (if more) computer that has left the game, or NULL if none. The next time the function is called, it returns the next computer, etc.
CL_NetComputer instances are reference counted. A computer wont be forgotten until all instances of it has been destroyed. If a computer rejoins the server while there still exist a netcomputer instance, it will be recognized and cause a 'rejoin' event instead of a normal join event.
Note, if you don't want to poll, use the signals below.
``CL_NetComputer`` `receive_computer_leave``()`;

CL_NetSession::receive_computer_rejoin - Returns the first (if more) computer that is re-joining the game, or throws an exception if none joined. The next time the function is called, it returns the next computer, etc.
A re-joining computer is simply a computer joining the game, that still havn't had its CL_NetComputer reference deleted. This provides a way to recognize a computer that was in the game.
Note, if you don't want to poll, use the signals below.
``CL_NetComputer`` `receive_computer_rejoin``()`;

CL_NetSession::receive_session_closed - Returns true if the session was closed.
Note, if you don't want to poll, use the signals below.
``bool`` `receive_session_closed``()`;

CL_NetSession::send - Sends a message to a group of computers at netchannel 'dest_channel'.
``void`` `send``(`const` `int` `dest_channel`, `const` `CL_NetGroup`& `dest`, `const` `CL_NetMessage`& `message`, `bool` `reliable` = true)`;

> dest - The group of computers to receive the message.
> dest_channel - Netchannel the message is sent to.
> message - Data in the message sent. All the data from 'message' is duplicated before this function returns.
> reliable - Arrival reliability. True guarantees arrival (use TCP/Pony express), false doesn't (use UDP/US Mail).

CL_NetSession::set_access - Sets the channel access flags on the channel for the computers specified.
This function only has effect on a server netsession.
``void`` `set_access``(`int` `channel`, `const` `CL_NetGroup`& `group`, `int` `access_rights` = ACCESS_CHANNEL_READ | ACCESS_CHANNEL_WRITE)`;

CL_NetSession::sig_access_changed - This signal is emitted when a netchannel had its access changed.
This function only works on a client netsession.
``CL_Signal_v1`<`int`>&` `sig_access_changed``()`;

CL_NetSession::sig_computer_join - This signal is emitted when a computer is joining the game.
``CL_Signal_v1`<`CL_NetComputer`>&` `sig_computer_join``()`;

CL_NetSession::sig_computer_leave - This signal is emitted when a computer has left the game.
CL_NetComputer instances are reference counted. A computer wont be forgotten until all instances of it has been destroyed. If a computer rejoins the server while there still exist a netcomputer instance, it will be recognized and cause a 'rejoin' event instead of a normal join event.
``CL_Signal_v1`<`CL_NetComputer`>&` `sig_computer_leave``()`;

CL_NetSession::sig_computer_rejoin - This signal is emitted when a computer is re-joining the game.
A re-joining computer is simply a computer joining the game, that still havn't had its CL_NetComputer reference deleted. This provides a way to recognize a computer that was in the game.
``CL_Signal_v1`<`CL_NetComputer`>&` `sig_computer_rejoin``()`;

CL_NetSession::sig_receive_message_default - This signal is emitted when a message is received, and which wasn't routed to the sig_receive_message signal.
``CL_Signal_v2`<`CL_NetMessage`& , `int`>&` `sig_receive_message_default``()`;

> Returns - CL_NetMessage - The message received from the specified channel.
> Returns - int - The channel the message was received in.

CL_NetSession::sig_session_closed - This signal is emitted when the session was closed.
``CL_Signal_v0`&` `sig_session_closed``()`;

CL_NetSession::~CL_NetSession - Net Session destructor
``virtual`` `~CL_NetSession``()`;

## Variable Member Descriptions: