Tutorials on Etna
You have 3 tutorials available. They will help you get used to ETNA very quickly. Tutorials available:
- requests using no thread,
- requests using thread,
- requests using encryption,
- setting the php script on your own server.
Basic tutorial - requests using no thread
This example will show you how to set a score on a web database (score of two teams for example).
This example uses no thread, which means that the program will be interrupted for a fraction of a second during the request. This is not a problem if it's outside the main loop of the game: after the game finished, or during the loading, etc.
The files relative to this tutorial are in "Examples/Simple Example (no encryption)/score_no_thread.**". They are available in BlitzBasic, BlitzMax and PureBasic. For illustration purpose, we will use the BlitzBasic code, but the commands are in fact identical for the other languages.
OK, let's begin lines after lines:
|
Include "../Include/Etna_inc.bb" |
Of course, you have to include the library (actually the interface to the library). This could be in the Include/ directory, or whatever directory you chose. Also, don't forget to put the Etna.dll file in the same directory as your source code.
|
ETNA_Initialise() |
Use this command before starting using the Etna library. This command is not mandatory for BlitzBasic.
|
ETNA_SetServer("http://repeatuntil.online.fr/Etna") |
Use this command to set the server and the directory where you can find the php scripts. You can call this function more than once in your program if you want to use several servers or directories. The server in example here has been set by the authors.
|
ETNA_Send(ETNA_NO_THREAD, "score.php?opt=getScore") |
This will send a request to the php script. The request won't use thread since the first argument is ETNA_NO_THREAD. The second argument will call the script "score.php" located at "http://repeatuntil.online.fr/Etna". There is some arguments given to the php script ("opt=getScore"), which request to take the score from the database. See the php/mySql scripts to have more detail...
|
If ETNA_GetState() = ETNA_OK Then Print "Result = " + ETNA_GetResult() For i% = 1 To ETNA_GetNbOfLines() Print "Result line by line = " + ETNA_GetResult(i) Next Else Print "The request failed with the error message = " + ETNA_GetState() EndIf |
When we use no thread, the result is immediately available after the call to Etna_Send(). First it is advised to check the state of the request (is it OK, or was there some errors?): see the documentation to see a list of flags returned by Etna_GetState().
Then, if the state is OK, we can retrieve the result from the php script. The php script (with "echo") may return some strings: you can get it with Etna_GetResult(). Note that this function will give you all the lines returned by the script. To get the result line by line, use the first parameter in ETNA_GetResult() in combination with ETNA_GetNbOfLines(). In this example, this is particularly useful since we can retrieve the 2 scores separately. Looking at the php script, we see that the first line is the first score and the second line is the second score. So we could do:
cesll
score1 = ETNA_GetResult(1)
score2 = ETNA_GetResult(2)
And that's it! That is as simple as that to use Etna for non-threaded requests!
Notice that you have some other available commands, as well as some optional parameters in the functions described previously. See the documentation for more details.
Basic tutorial - requests using thread
This example will show you how to set a score on a web database (score of two teams for example).
This example uses thread, which means that the program will NOT be interrupted by the request: this is the main feature of the Etna library. This means that you can do some requests during the main loop of your game. This could be very practical if you want to update information like number of people connected to your game, refreshing a master server, updating scores in real time, etc. All this information can for example be available on a web site in real time.
The files relative to this tutorial are in "Examples/Simple Example (no encryption)/score_thread.**". They are available in BlitzBasic, BlitzMax, PureBasic and DELPHI. For illustration purpose, we will use the BlitzBasic code, but the commands are in fact identical for the other languages.
OK, let's begin lines after lines, skipping the lines already described in the previous tutorial:
|
Const SET_SCORE% = 1 Const GET_SCORE% = 2 |
These constants will be used when you will send the request. Each request of the same type should have its own identification (although it is not mandatory). You will use these ID in Etna_Send() and Etna_Receive().
|
ETNA_Send(GET_SCORE, "score.php?opt=getScore") |
This command will send the request. This request will have the ID "GET_SCORE" which will be useful later on. The nice thing here, compared to non threaded request, is that this function will return immediately, and won't interrupt the program. Of course, you will have to wait a bit to get the result!
|
While KeyHit <> KEY_ESCAPE |
This is now the beginning of your main loop of your game, or the loop of the menu, etc.
|
ETNA_Update() |
This function should be called at every loop. This is the main function of Etna which is doing the hard work. If you forget to call this function, nothing will happen!
|
If ETNA_Receive(GET_SCORE) Then If ETNA_GetState() = ETNA_OK Then Print "Result for the request getting the score:" Print "Result = " + ETNA_GetResult() For i% = 1 To ETNA_GetNbOfLines() Print "Result line by line = " + ETNA_GetResult(i) Next Else Print "The request failed with the error message = " + ETNA_GetState() EndIf EndIf |
Then, in the loop, you check if you received a particular request, specified by its identification ("GET_SCORE"). If ETNA_Receive() returns true, then we just received the response of the request. You can then get the result associated to this request, using ETNA_GetState() and ETNA_GetResult() (see previous tutorial).
|
Delay 1 |
In this example, we have to include a delay which simulates some calculation/drawing in the main loop. Warning, if there is no delay (or no calculation or drawing), the cpu will go crazy, and the lib won't work correctly!
And that's it! This is as simple as that to do threaded requests in Etna!
Basic tutorial - requests using encryption
This example will show you how to set a score on a web database (score of two teams for example) using encryption.
This example uses no thread, but this is as easy with thread and encryption.
The files relative to this tutorial are in "Examples/Simple Example (encryption)/score_encrypted_no_thread.**". They are available in BlitzBasic, BlitzMax, PureBasic and DELPHI. For illustration purpose, we will use the BlitzBasic code, but the commands are in fact identical for the other languages.
OK, let's see how easy it is to have encryption with ETNA. We will skip the parts already explained in the the first tutorial.
|
ETNA_SetServer("http://repeatuntil.online.fr/Etna") ETNA_SetKey("mySecretKey") |
Use the second command (ETNA_SetKey) to set the key for the encryption. Don't use a key easy guess! "FDG$T@(4&DG" is better than "secret"!!
You can call this function more than once in your program if you want to use several keys (for several scripts you are calling for example).
|
ETNA_Send(ETNA_NO_THREAD, "score_encrypted.php?opt=getScore", true) |
This will send a request to the php script. The third argument of this function is set to True, which means that encryption is used. ETNA will encrypt the argument of the script (here "opt=getScore").
In the php script on the server (see score_encrypted.php in the SimpleExample directory), the decryption is as simple as that:
|
in the php: $listArg = ETNA_GetArg("mySecretKey"); |
Of course, you have to specify the same key as the one used in your program. The variable $listArg will contain the decrypted list of arguments given to the php.
In ETNA, you have also the option to receive encrypted string (in fact, you could use encryption in only one direction, or both, this is completely up to you). If you want that the php script sends an encrypted string, just do:
|
in the php: $answer = "I am the result \n"; in the php: $answer .= "of the script \n"; in the php: echo ETNA_Encrypt($answer,"mySecretKey"); |
Very IMPORTANT: ETNA_Encrypt() is called only once, when the string of the php is complete. The encryption here is done with the same key than the one we used to send the command. This is not mandatory, a different key could be used in the php (in that case use ETNA_SetKeySend() and ETNA_SetKeyReceive() instead of ETNA_SetKey()).
|
If ETNA_GetState() = ETNA_OK Then Print "Result = " + ETNA_GetResult() EndIf |
ETNA detects automatically that the string sended by the php script was encrypted, and will decrypt automatically the result. No action have to be taken from your part. The function will return the decrypted string.
And that's it! That is as simple as that to use Etna for encryption!
Setting the php script on your own server
The php scripts for these 3 tutorials are available in "Tutorials/Simple Example (*)/" (score.php and score_encrypted.php). You can first try to run with the server that the authors set up. But you can then try to install the php scripts on your own server, and, why not, try to customize it.
To install this on your own server, you should first create the database table using score.mysql (with phpMyAdmin for example). Then you modify the score.php script, changing the server, user, password and database information. You upload this file to your server. In the source file (.bb, .bmx or .pb), change the server name in ETNA_SetServer(). And it should work!!
For encryption, you have also to follow the steps described in the installation (php paragraph).
