Difference between revisions of "InSim Tutorials"

From LFS Manual
Jump to: navigation, search
(Updated escape codes and added code pages.)
(rewrote insim relay page to match latest info)
Line 17: Line 17:
  
 
== InSim Relay usage information ==
 
== InSim Relay usage information ==
The InSim Relay is a service that can connect to your LFS host via InSim and relay the InSim information sent by your host, to anyone who connects to the InSim Relay. This relayed data can be used by programmers for various things, such as the LFS Spectator (remote viewing of a race) and race-tracking to store race information and statistics.
+
The InSim Relay is a service that can connect to your LFS host via InSim and relay the InSim information sent by your host, to anyone who connects to the InSim Relay. This relayed data can be used by programmers for various things, such as the LFS Remote (remote viewing / adminning of a race) and race-tracking to store race information and statistics.
  
 
To have your host connected to the Relay, see this page on LFS World:
 
To have your host connected to the Relay, see this page on LFS World:
 
http://www.lfsworld.net/?win=hosts&whichTab=insim_relay
 
http://www.lfsworld.net/?win=hosts&whichTab=insim_relay
  
The rest of this document is only for programmers who want to know how to connect with the InSim Relay, so they can make use of the available data.<br>
+
The rest of this document is only for programmers who want to know how to connect to the InSim Relay, so they can make use of the available data.<br>
 
+
NEW : you can now also connect various other insim mods via the relay, because you can 'connect' to a host with an admin password. See the bottom of this document for which packets are allowed to send.
+
  
 
=== Connecting to the InSim Relay ===
 
=== Connecting to the InSim Relay ===
The network protocol used with the Relay is UDP and it is located at isrelay.liveforspeed.net port 47474
+
The Relay code below can be seen as an extension to the regular InSim protocol, as the packets are constructed in the same manner as regular InSim packets and use their own identifiers.
  
Connecting to the Relay is done with the CCN packet. To connect, make sure bit 0 of the flags is set, which means 'connect to relay'.
+
Connect your client to isrelay.lfs.net:47474 with TCP. After you are connected you can request a list of hosts, so you can see which hosts you can connect to. Then you can send a packet to the Relay to select a host. After that the Relay will send you all insim data from that host.
The CCN packet is a multifunctional packet. It is used to connect to the Relay, request a list of available hosts and set various options.
+
<br>Here is the struct of the connection packet:
+
  
<pre>
+
Some hosts require a spectator password in order to be selectable.
struct ClientConnection
+
{
+
char Id [4]; // CCN + zero (\0)
+
byte Flags; // Bit flags for options and 'connect' flag
+
byte Spare; // spare1
+
byte Spare; // spare2
+
byte Spare; // spare2
+
}
+
  
Flags in CCN packet:
+
You do not need to specify a spectator password if you use a valid administrator password.
#define ISR_CONNECT 1 // bit 0 : 'connect' flag. Must be set to connect to Relay
+
#define ISR_HOSTLIST 2 // bit 1 : if set, you will get a list of hosts returned
+
#define ISR_NOMCI 4 // bit 2 : if set, you will not receive MCI packets
+
#define ISR_VERIFY 8 // bit 3 : if set, 'guaranteed delivery' will be on
+
</pre>
+
  
The CCN packet with bit 0 set _must_ be your first packet, otherwise your packets will be ignored. To acknowledge that the connection was successful, an ACK packet is sent, if you didn't already request a hostlist in your initial CCN packet.<br>
+
If you connect with an administrator password, you can send just about every regular InSim packet there is available in LFS, just like as if you were connected to the host directly. For a full list, see end of document.
You can additionally send a CCN packet at any time, to toggle NOMCI and/or VERIFY and to request a hostlist even while still being connected to a host.<br>
+
A note about guaranteed delivery; it works exactly like with normal InSim guaranteed delivery, so if you don't know how it works, please look in the Insim.txt that comes with LFS.
+
  
There is one official case where connecting might fail; when the Relay has reached its maximum number of users.<br>
+
=== Packet types used for the Relay ===
 
+
In that case, the Relay will send an ERR packet. The ERR packet also has some other error message purposes.
+
  
 
<pre>
 
<pre>
struct ErrorMessage
+
#define IRP_HLR 252 // Send : To request a hostlist
{
+
#define IRP_HOS 253 // Receive : Hostlist info
char Id [4]; // ERR + zero
+
#define IRP_SEL 254 // Send : To select a host
byte ErrNo; // number of the error
+
#define IRP_ERR 255 // Receive : An error number
byte Spare; // spare1
+
byte Spare; // spare2
+
byte Spare; // spare2
+
}
+
 
</pre>
 
</pre>
  
ErrNo meanings:<br>
+
To request a hostlist from the Relay, send this packet :
1 - Invalid Spectatorpassword given<br>
+
2 - Relay has reached maximum number of clients<br>
+
3 - Non-existent hostname given in HOS packet
+
 
+
=== Receiving the hostlist ===
+
When you have requested a list of hosts with bit 1 of the flags in the CCN packet, you will receive a list of hosts. The result packet(s) is/are identified by the CHL id. Every CHL packet contains a maximum of 8 hosts and their respective information. If there are more than 8 hosts available to select from, you will receive multiple CHL packets. You can determine how many CHL packets you should expect by reading the 'total hosts' word in every CHL packet (this number is the same in every CHL packet). You can determine the amount of hosts listed in a CHL packet, by the length of the packet.
+
 
+
  
 
<pre>
 
<pre>
struct ClientgetHostList
+
struct IR_HLR // HostList Request
 
{
 
{
char Id [4]; // CHL + zero
+
byte Size; // 4
word NrHosts; // Number of total available hosts
+
byte Type; // IRP_HLR
byte Spare; // Spare1
+
byte ReqI;
byte Spare; // Spare2
+
byte Sp0;
char Host [32]; // Hostname(s) (min: 1 / max 8 hostnames - check the length of this packet)
+
};
byte NrRacers; // Number of racers on a host
+
byte Specpass; // 1 if host requires a spectator password
+
}
+
 
</pre>
 
</pre>
  
An example of the order things in this packet:<br>
+
That will return (multiple) packets containing hostnames and some information about them
3 hosts listed in this packet:
+
  
host1[32].host2[32].host3[32].421110
+
The following struct is a sub packet of the IR_HOS packet
  
host1 has 4 racers and requires a specpass<br>
+
<pre>
host2 has 2 racers and required a specpass<br>
+
struct HInfo // Sub packet for IR_HOS. Contains host information
host3 has 1 racer and does not require a specpass
+
{
 +
char HName[32]; // Name of the host
 +
 +
char Track[6]; // Short track name
 +
byte Flags; // Info flags about the host - see NOTE 1) below
 +
byte NumConns; // Number of people on the host
 +
};
  
=== Select a host to receive InSim data from ===
+
// NOTE 1)
To start receiving InSim packets from a host, you must select the host with a HOS packet:
+
#define HOS_SPECPASS 1 // Host requires a spectator password
 +
#define HOS_LICENSED 2 // Bit is set if host is licensed
 +
#define HOS_S1         4 // Bit is set if host is S1
 +
#define HOS_S2         8 // Bit is set if host is S2
 +
</pre>
  
 
<pre>
 
<pre>
 +
struct IR_HOS // Hostlist (hosts connected to the Relay)
 +
{
 +
byte Size; // 4 + NumHosts * 40
 +
byte Type; // IRP_HOS
 +
byte ReqI; // As given in IR_HLR
 +
byte NumHosts; // Number of hosts described in this packet
  
struct SelectHost
+
HInfo Info[6]; // Host info for every host in the Relay. 1 to 6 of these in a IR_HOS
{
+
};
char Id [4]; // HOS + zero
+
char Host [32]; // hostname
+
char Specpass[24]; // spectator password
+
char Adminpass[16];  // admin password
+
}
+
 
</pre>
 
</pre>
  
Note that both the full hostname and ^-stripped/converted hostname can be used.
+
To select a host in the Relay, send this packet :
 
+
ex. "^1EXAMPLE^v^7HOST ^11" or "EXAMPLE|HOST 1"
+
 
+
=== Maintaining a connection to the Relay ===
+
If the relay has not received any data from a client in 60 seconds, the Relay will close the connection with the client. To prevent this from happening, the client can send ACK packets every 20 seconds, in case nothing else has been sent to the Relay.
+
  
 
<pre>
 
<pre>
struct Acknowledge
+
struct IR_SEL // Relay select - packet to select a host, so relay starts sending you data.
 
{
 
{
char Id [4]; // ACK + zero
+
byte Size; // 68
}
+
byte Type; // IRP_SEL
</pre>
+
byte ReqI; // If non-zero Relay will reply with an IS_VER packet
 +
byte Zero; // 0
  
If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ACK packet.
+
char HName[32]; // Hostname to receive data from - may be colourcode stripped
 +
char Admin[16]; // Admin password (to gain admin access to host)
 +
char Spec[16]; // Spectator password (if host requires it)
  
The same goes for the other way around. The Relay will send ACK packets to your client in case nothing has been sent in 20 seconds. You can make your client assume that the Relay is offline, if you didn't receive anything from the relay during 60 seconds.
+
};
 +
</pre>
  
=== Closing a connection (client side) ===
+
If you specify a wrong value, like invalid packet / hostname / adminpass / specpass, the Relay returns an error packet :
When the client closes, it's nice to have it send a 'close' instruction to the Relay:
+
  
 
<pre>
 
<pre>
struct ClientClose
+
struct IR_ERR
 
{
 
{
char Id [4]; // ISC + zero
+
byte Size; // 4
}
+
byte Type; // IRP_ERR
</pre>
+
byte ReqI; // As given in RL_SEL, otherwise 0
 +
byte ErrNo; // Error number - see NOTE 2) below
 +
};
  
If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ISC packet.
+
// NOTE 2) Error numbers :
 
+
#define IR_ERR_PACKET1          1    // Invalid packet sent by client (wrong structure / length)
=== Closing a connection (relay side) ===
+
#define IR_ERR_PACKET2          2    // Invalid packet sent by client (packet was not allowed to be forwarded to host)
If the relay needs to "close" your connection for whatever reason or if the relay goes offline, it will send a packet to notify that you will need to try to connect again with the CCN packet.
+
#define IR_ERR_HOSTNAME        3    // Wrong hostname given by client
 
+
#define IR_ERR_ADMIN            4   // Wrong admin pass given by client
<pre>
+
#define IR_ERR_SPEC            5    // Wrong spec pass given by client
struct ClientTerminate
+
#define IR_ERR_NOSPEC          6    // Spectator pass required, but none given
{
+
char Id [4]; // CTM + zero
+
}
+
 
</pre>
 
</pre>
  
=== Public requests for host information ===
+
<b>Regular insim packets that a relay client can send to host :</b>
A client can request some information from a host by sending the relay one of the following InSim packets:
+
 
+
SST<br>
+
ISM<br>
+
VER<br>
+
GTH<br>
+
NPL<br>
+
RES
+
 
+
These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.
+
 
+
=== Admin-only control packets ===
+
If you have connected to a host with the adminpassword set (in the HOS packet), you are allowed to send some control packets:
+
  
VTC<br>
+
For anyone<br>
 +
TINY_VER<br>
 +
TINY_PING<br>
 +
TINY_SCP<br>
 +
TINY_SST<br>
 +
TINY_GTH<br>
 +
TINY_ISM<br>
 +
TINY_NCN<br>
 +
TINY_NPL<br>
 +
TINY_RES<br>
 +
TINY_REO<br>
 +
TINY_RST<br>
 +
TINY_AXI<br>
  
SCH<br>
+
Admin only<br>
MST<br>
+
TINY_VTC<br>
MTC
+
ISP_MST<br>
 +
ISP_MSX<br>
 +
ISP_MSL<br>
 +
ISP_MTC<br>
 +
ISP_SCH<br>
 +
ISP_BFN<br>
 +
ISP_BTN<br>
  
These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.
+
The relay will also accept, but not forward<br>
 +
TINY_NONE    // for relay-connection maintenance
  
 
=== List of escape codes ===
 
=== List of escape codes ===

Revision as of 21:39, 29 June 2009

Information

The Tutorials section is meant to become a collection of tutorials on how to connect to InSim using various programming languages. I know that of course there are lots of precompiled software packages (like JInSim for Java, FullMotion.LiveForSpeed for C# and so on) on the LfSForum and lots of them are also very good, but you do not really learn how to use InSim if you use precompiled packages. So each section of this page should be for one programming language and should contain the following subsections:

  1. Datatypes
  2. How to build/parse packets
  3. Connecting to InSim
  4. Disconnecting from InSim
  5. Easy example


Tutorials

Tutorials are available for the following programming languages:

PHP5


InSim Relay usage information

The InSim Relay is a service that can connect to your LFS host via InSim and relay the InSim information sent by your host, to anyone who connects to the InSim Relay. This relayed data can be used by programmers for various things, such as the LFS Remote (remote viewing / adminning of a race) and race-tracking to store race information and statistics.

To have your host connected to the Relay, see this page on LFS World: http://www.lfsworld.net/?win=hosts&whichTab=insim_relay

The rest of this document is only for programmers who want to know how to connect to the InSim Relay, so they can make use of the available data.

Connecting to the InSim Relay

The Relay code below can be seen as an extension to the regular InSim protocol, as the packets are constructed in the same manner as regular InSim packets and use their own identifiers.

Connect your client to isrelay.lfs.net:47474 with TCP. After you are connected you can request a list of hosts, so you can see which hosts you can connect to. Then you can send a packet to the Relay to select a host. After that the Relay will send you all insim data from that host.

Some hosts require a spectator password in order to be selectable.

You do not need to specify a spectator password if you use a valid administrator password.

If you connect with an administrator password, you can send just about every regular InSim packet there is available in LFS, just like as if you were connected to the host directly. For a full list, see end of document.

Packet types used for the Relay

#define IRP_HLR		252	// Send : To request a hostlist
#define IRP_HOS		253	// Receive : Hostlist info
#define IRP_SEL		254	// Send : To select a host
#define IRP_ERR		255	// Receive : An error number

To request a hostlist from the Relay, send this packet :

struct IR_HLR // HostList Request
{
	byte	Size;		// 4
	byte	Type;		// IRP_HLR
	byte	ReqI;
	byte	Sp0;
};

That will return (multiple) packets containing hostnames and some information about them

The following struct is a sub packet of the IR_HOS packet

struct HInfo // Sub packet for IR_HOS. Contains host information
{
	char	HName[32];	// Name of the host
	
	char	Track[6];	// Short track name
	byte	Flags;		// Info flags about the host - see NOTE 1) below
	byte	NumConns;	// Number of people on the host
};

// NOTE 1)
#define HOS_SPECPASS		1	// Host requires a spectator password
#define HOS_LICENSED		2	// Bit is set if host is licensed
#define HOS_S1		        4	// Bit is set if host is S1
#define HOS_S2		        8	// Bit is set if host is S2
struct IR_HOS // Hostlist (hosts connected to the Relay)
{
	byte	Size;		// 4 + NumHosts * 40
	byte	Type;		// IRP_HOS
	byte	ReqI;		// As given in IR_HLR
	byte	NumHosts;	// Number of hosts described in this packet

	HInfo	Info[6];	// Host info for every host in the Relay. 1 to 6 of these in a IR_HOS
};

To select a host in the Relay, send this packet :

struct IR_SEL // Relay select - packet to select a host, so relay starts sending you data.
{
	byte	Size;		// 68
	byte	Type;		// IRP_SEL
	byte	ReqI;		// If non-zero Relay will reply with an IS_VER packet
	byte	Zero;		// 0

	char	HName[32];	// Hostname to receive data from - may be colourcode stripped
	char	Admin[16];	// Admin password (to gain admin access to host)
	char	Spec[16];	// Spectator password (if host requires it)

};

If you specify a wrong value, like invalid packet / hostname / adminpass / specpass, the Relay returns an error packet :

struct IR_ERR
{
	byte	Size;		// 4
	byte	Type;		// IRP_ERR
	byte	ReqI;		// As given in RL_SEL, otherwise 0
	byte	ErrNo;		// Error number - see NOTE 2) below
};

// NOTE 2) Error numbers :
#define IR_ERR_PACKET1          1    // Invalid packet sent by client (wrong structure / length)
#define IR_ERR_PACKET2          2    // Invalid packet sent by client (packet was not allowed to be forwarded to host)
#define IR_ERR_HOSTNAME         3    // Wrong hostname given by client
#define IR_ERR_ADMIN            4    // Wrong admin pass given by client
#define IR_ERR_SPEC             5    // Wrong spec pass given by client
#define IR_ERR_NOSPEC           6    // Spectator pass required, but none given

Regular insim packets that a relay client can send to host :

For anyone
TINY_VER
TINY_PING
TINY_SCP
TINY_SST
TINY_GTH
TINY_ISM
TINY_NCN
TINY_NPL
TINY_RES
TINY_REO
TINY_RST
TINY_AXI

Admin only
TINY_VTC
ISP_MST
ISP_MSX
ISP_MSL
ISP_MTC
ISP_SCH
ISP_BFN
ISP_BTN

The relay will also accept, but not forward
TINY_NONE // for relay-connection maintenance

List of escape codes

^v - |
^a - *
^c - :
^d - \
^s - /
^q - ?
^t - "
^l - <
^r - >

^L = Latin 1 (CP1252)
^G = Greek (ISO-8859-7)
^C = Cyrillic (CP1251)
^J = Japanese (Shift-JIS)
^E = Central Europe (ISO-8859-2)
^T = Turkish (ISO-8859-9)
^B = Baltic (ISO-8859-13)
^H = Traditional Chinese (CP936)
^S = Simpified Chinese (CP949)
^K = Korean (CP950)

^0 - Black
^1 - Red
^2 - Light green
^3 - Yellow
^4 - Blue
^5 - Purple
^6 - Light blue
^7 - White
^8 - Dark green (default)
^9 - Original text colour and codepage.


Basic Setup Guide | Advanced Setup Guide | Technical Reference | League Racing Guide | Skin Tutorial | Autocross Editor | Hosting | File Formats | LFS Programming | Movie Tutorial | Scripting