Writing your first InSim application can be a bit daunting. This thread is designed to help you create your very first one, by providing a set of tutorials.
To those who have written InSim applications before, I hope that if you have time, and the language you use is not covered, or that you can improve or post alternative examples or tutorials, that you could pop together a tutorial for your chosen language and/or library.
What is InSim?
InSim itself is a protocol. A fixed method of talking to LFS. Think of it as a language, like French. There have been different versions (dialects) of InSim. Older versions maybe incompatible with the current version.
Take a programming language of your choice - any will do, as long as it can do some networking and there is some way for you to "pack" strings. Think of this programming language as a person.
You need to teach this "person" how to talk "french". How you do this would depend on the person. If this person natively spoke another language, like English, you'd teach them in the way they expect to be taught in an english school. Similiarly if they were spanish you'd use a spanish style of teaching.
What I'm trying to get at is that there's no correct way, in all cases, to create an InSim program. It depends on what you're using.
If you're using an interpreted language you can write the code, using whatever you want, and then run that code using the interpreter. For instance, you could write a PHP script, that understands how to talk to InSim, and then call it through the PHP command line interpreter.
If you were using a compiled language you'd write the code, using whatever you want, and then you'd need to compile that code so that you can run it.
InSim itself is not magic. All that InSim does, and can do, is inform a programmer how to get data out of LFS and how to put data back in.
Just to get slightly more complicated you can talk to InSim in 2 different ways - over TCP and UDP. TCP is "slower" but data from LFS is "guaranteed" to arrive whilst the connection is up, and will arrive at your program in a specific order. UDP is faster, but you will get no notification if LFS goes away, and the packets may arrive in any order. It is more common to use TCP than UDP these days.
However, at the end of the day every InSim application, whether or not the programmer knows it, makes the same decisions and goes through the same steps to acheive a connection to LFS using InSim and to maintain the connection. If you're using a third party library then you won't be exposed to much of the "hardcore" networking as the library will be taking care of it for you.
Vague synchronous workflow of an InSim client
In pseudocode it looks something like this:
If you have read the above and gotten a bit flustered, then do not worry as there are a few kind and clever people who have written a set of libraries which allow you to you concentrate on just writing your application and not worry too much about the above.
More information?
If you've chosen to write your own InSim connection and packet handler check out Insim.txt, included with all LFS distributions.
If you've chosen to use an existing library then the best starting point would be the documentation for that library.
To those who have written InSim applications before, I hope that if you have time, and the language you use is not covered, or that you can improve or post alternative examples or tutorials, that you could pop together a tutorial for your chosen language and/or library.
What is InSim?
InSim itself is a protocol. A fixed method of talking to LFS. Think of it as a language, like French. There have been different versions (dialects) of InSim. Older versions maybe incompatible with the current version.
Take a programming language of your choice - any will do, as long as it can do some networking and there is some way for you to "pack" strings. Think of this programming language as a person.
You need to teach this "person" how to talk "french". How you do this would depend on the person. If this person natively spoke another language, like English, you'd teach them in the way they expect to be taught in an english school. Similiarly if they were spanish you'd use a spanish style of teaching.
What I'm trying to get at is that there's no correct way, in all cases, to create an InSim program. It depends on what you're using.
If you're using an interpreted language you can write the code, using whatever you want, and then run that code using the interpreter. For instance, you could write a PHP script, that understands how to talk to InSim, and then call it through the PHP command line interpreter.
If you were using a compiled language you'd write the code, using whatever you want, and then you'd need to compile that code so that you can run it.
InSim itself is not magic. All that InSim does, and can do, is inform a programmer how to get data out of LFS and how to put data back in.
Just to get slightly more complicated you can talk to InSim in 2 different ways - over TCP and UDP. TCP is "slower" but data from LFS is "guaranteed" to arrive whilst the connection is up, and will arrive at your program in a specific order. UDP is faster, but you will get no notification if LFS goes away, and the packets may arrive in any order. It is more common to use TCP than UDP these days.
However, at the end of the day every InSim application, whether or not the programmer knows it, makes the same decisions and goes through the same steps to acheive a connection to LFS using InSim and to maintain the connection. If you're using a third party library then you won't be exposed to much of the "hardcore" networking as the library will be taking care of it for you.
Vague synchronous workflow of an InSim client
In pseudocode it looks something like this:
Get data from user - address and port of client or server running InSim - usually localhost 29999
Make a connection to the given address and port
Send the ISI (InSim Initialisation) packet
Ask for the version to get sent (so that we can check that the thing we are connecting to is talking the same version of InSim)
Create a global buffer and a way of recording the buffer size (only necessary in some languages)
Start a receive loop - wait until we get data or until we are told to quit
Create a local temporary buffer
Copy any data in the global buffer into the local temporary buffer
We receive and append any data into the local temporary buffer
Clear global buffer
Create a local counter and set it to 0
Start a loop (we'll call this packet parsing loop), using the following logic: whilst local counter + next packet size <= local buffer size
Read the first byte of the rest of the buffer
Add this number to the local counter
Read and parse that number of bytes from the local buffer - this is a packet
Do whatever you want with the packet here - usually you'd want to send it to some bit of code to deal with it
Send any data you want back to LFS
Discard this packet from the buffer
When the packet parsing loop finishes, if any bytes remain copy them into the global buffer and size the global buffer size
When the receive loop ends clear the global buffer
Close the connection to LFSIf you have read the above and gotten a bit flustered, then do not worry as there are a few kind and clever people who have written a set of libraries which allow you to you concentrate on just writing your application and not worry too much about the above.
More information?
If you've chosen to write your own InSim connection and packet handler check out Insim.txt, included with all LFS distributions.
If you've chosen to use an existing library then the best starting point would be the documentation for that library.
