Networking

From Leadwerks Developer Wiki

Jump to: navigation, search

Contents

Introduction

Networking in Leadwerks Engine is based on the enet library. The fast UDP protocol is used as a base, but packets are correctly ordered or sent with a "reliable" flag for important data. Although the UDP protocol is "connectionless", the Leadwerks networking library automatically initializes and maintains network "connections".

Commands

Host Commands

A host is the local computer.

CreateHost

  • C: THost CreateHost( int ip=0, int port=7777, int players=32)
  • C++:
    • Host::Host( const THost host = 0 )
    • Host::Host( int ip = 0, int port = 7777, int players = 32 )  ;
    • virtual bool Host::Create( int ip = 0, int port = 7777, int players = 32 )
  • BlitzMax: CreateHost:THost( ip:Int=0, port:Int=7777, players:Int=32)
Creates a network host.
[Examples]

ConnectHost

  • C: TPeer ConnectHost( THost host, int ip, int port )
  • C++: TPeer Host::Connect( const_str ip, int port )
  • BlitzMax: ConnectHost:TPeer( host:THost, ip:Int, port:Int )
Connects to a host, and returns a peer object.
[Examples]

GetHostIP

  • C: int GetHostIP( THost host )
  • C++: int Host::GetIP(void) const
  • BlitzMax: GetHostIP:Int( host:THost )
Returns the IP of a host.
[Examples]

GetHostPort

  • C: int GetHostPort( THost host )
  • C++: int Host::GetPort(void) const
  • BlitzMax: GetHostPort:Int( host:THost )
Returns the port of a host.
[Examples]

DisconnectHost

  • C: void DisconnectHost( THost host, TPeer peer, int force=false )
  • C++: void Host::Disconnet( TPeer peer, bool force = false )
  • BlitzMax: DisconnectHost( host:THost, peer:TPeer, force:Int=False )
Disconnects a peer from a host.
[Examples]

SendPacket

  • C: int SendPacket( THost host, TPeer peer, TPacket packet, int channel=0, int flags=PACKET_SEQUENCED )
  • C++: bool Host::SendPacket( const Peer& peer, const Packet& packet, int channel = 0, int flags = PACKET_SEQUENCED )
  • BlitzMax: SendPacket:Int( host:THost, peer:TPeer, packet:TPacket, channel:Int=0, flags:Int=PACKET_SEQUENCED )
Sends a packet from a peer to a host.
  • C/C++: The packet will be freed from memory and cannot be reused.
[Examples]

BroadcastPacket

  • C: void BroadcastPacket( THost host, TPacket packet, int channel=0, int flags=PACKET_SEQUENCED )
  • C++: void Host::BroadcastPacket( const Packet& packet, int channel = 0, int flags = PACKET_SEQUENCED )
  • BlitzMax: BroadcastPacket( host:THost, packet:TPacket, channel:Int=0, flags:Int=PACKET_SEQUENCED )
Broadcasts a packet to all peers of a host.
  • C/C++: The packet will be freed from memory and cannot be reused.
[Examples]

WaitNetwork

  • C: TEvent WaitNetwork( THost host, int timeout=1000 )
  • C++: void Host::WaitForEvent( Event& ev, int timeout = 1000 )
  • BlitzMax: WaitNetwork:TEvent( host:THost, timeout:Int=1000 )
Waits for the network to return an event.
[Examples]

FreeHost

  • C: void FreeHost(THost host)
  • C++:
    • void Host::Free()
    • Host::~Host(void)
Frees a host from memory.
[Examples]

Peer Commands

A peer is a remote computer.

GetPeerIP

  • C: int GetPeerIP( peer:TPeer )
  • C++: int Peer::GetIP( void ) const
  • BlitzMax: GetPeerIP:Int( peer:TPeer )
Returns the IP of a peer.
[Examples]

GetPeerPort

  • C: int GetPeerPort( peer:TPeer )
  • C++: int Peer::GetPort( void ) const
  • BlitzMax: GetPeerPort:Int( peer:TPeer )
Returns the port of a peer.
[Examples]

Packet Commands

A packet is a chunk of data one computer sends to another.

CreatePacket

  • C: TPacket CreatePacket( void )
  • C++:
    • Packet::Packet( const TPacket p = 0 )
    • Packet::Packet( const CreateMode& mode )
    • virtual bool Packet::Create( void )
  • BlitzMax: CreatePacket:TPacket()
Creates a new packet.
[Examples]

FreePacket

  • C: TPacket FreePacket( void )
  • C++:
    • void Packet::Free( void ) Note: See below: The destructor deals with this
    • Packet::~Packet( void )
Frees a packet. Only received packets need to be freed. Packets sent to other computers are freed automatically when sent or broadcast.
[Examples]

Server Commands

PublishHost

  • C: int PublishHost( THost host, str url, str name, str game="" )
  • C++: bool Host::Publish( const_str curl, const_str name, const_str game = "" )
  • BlitzMax: PublishHost:Int( host:THost, url:String, name:String, game:String="" )
Publishes a host on a public server list.
[Examples]

RequestServers

  • C: str RequestServers( str url, str game="" )
  • C++: static std::string Engine::RequestServers( const_str curl, const_str cgame = "" )
  • BlitzMax: RequestServers:String[]( url:String, game:String="" )
Retrieves the servers listed on a public server list.
[Examples]

In BlitzMax, an array of strings will be returned. In other languages, a string deliminated by end-of-line characters is returned.

The format for the string is as follows:

"integer_ip|string_ip|user_info"
456123165|83.85.65.1245|My Awesome Game Server

The user_info field may be broken up into more fields with a "|" character, depending on what the programmer enters in the name parameter of PublishHost().

The integer ip address can be used with ConnectHost() to connect to a remote server.

Stream Commands

These commands can be used to read from and write to packets.

WriteByte

  • C: void WriteByte( TPacket packet, byte data)
  • C++: void Stream::WriteByte( byte data)
  • BlitzMax: WriteByte( packet:TPacket, data:Byte )
Write a byte into a packet.
[Examples]

WriteShort

  • C: void WriteShort( TPacket packet, short data)
  • C++: void Stream::WriteShort( short data)
  • BlitzMax: WriteShort( packet:TPacket, data:Short )
Write a short (=2 byte integer) into a packet.
[Examples]

WriteInt

  • C: void WriteInt( TPacket packet, int data)
  • C++: void Stream::WriteInt( int data)
  • BlitzMax: WriteInt( packet:TPacket, data:Int )
Write a int (=4 byte integer) into a packet.
[Examples]

WriteFloat

  • C: void WriteFloat( TPacket packet, float data)
  • C++: void Stream::WriteFloat( float data)
  • BlitzMax: WriteFloat( packet:TPacket, data:Float )
Writes a float (=4 byte float) into a packet.
[Examples]

WriteLine

  • C: void WriteLine( TPacket packet, str data)
  • C++: void Stream::WriteLine( const_str data)
  • BlitzMax: WriteLine( packet:TPacket, data:String )
Writes a text line (=zero terminated string with Linefeed) into a packet.
[Examples]

ReadByte

  • C: byte ReadByte( TPacket packet )
  • C++: unsigned char Stream::ReadByte( void ) const
  • BlitzMax: ReadByte:Byte( packet:TPacket )
Reads a byte from a packet.
[Examples]

ReadShort

  • C: short ReadShort( TPacket packet )
  • C++: short int Stream::ReadShort( void ) const
  • BlitzMax: ReadShort:Short( packet:TPacket )
Reads a short (=2 byte integer) from a packet.
[Examples]

ReadInt

  • C: int ReadInt( TPacket packet )
  • C++: int Stream::ReadInt( void ) const
  • BlitzMax: ReadInt:Int( packet:TPacket )
Reads a int (=4 byte integer) from a packet.
[Examples]

ReadFloat

  • C: float ReadFloat( TPacket packet )
  • C++: float Stream::ReadFloat( void ) const
  • BlitzMax: ReadFloat:Float( packet:TPacket )
Reads a float (=4 byte float) from a packet.
[Examples]

ReadLine

  • C: str ReadLine( TPacket packet )
  • C++: str Stream::ReadLine( void ) const
  • BlitzMax: ReadLine:String( packet:TPacket )
Reads a text line from a packet.
[Examples]

Eof

  • C: int Eof( TPacket packet )
  • C++: bool Stream::IsEof( void ) const
  • BlitzMax: Eof:Int( packet:TPacket )
Returns 1 if the stream position is at the end of the stream.
[Examples]
Personal tools