Documentation of Etna functions
| ETNA_Initialise() |
| Description: Initialise the Etna library. Call this function once before any use of the library. |
| Return value: True if the initialisation was successful. |
| ETNA_SetServer(server$) |
| Description: Specify to Etna the server address where are located the script files (like php files). You can also specify a directory on the server. This function should be called at least once, but could be called at any moment to use different servers. |
| Parameters: server$ = Server address. |
| Return value: None |
| Example: ; The address of the script file is: http://www.aSite.com/myScript.php ETNA_SetServer("http://www.aSite.com") ; The address of the script file is: http://www.server.net/folder/file/request.php ETNA_SetServer("http://www.server.net/folder/file/") |
| ETNA_SetDelimiter(delimiter$) |
| Description: Specify the delimiter when the result of the request contains more than one line. By default, this is a carriage return - chr(13). The delimiter may be more than one character long. |
| Parameters: delimiter$ = The new delimiter to use. |
| Return value: None |
| ETNA_SetKey(key$) |
| Description: When you use encryption, use this function to set the encryption key. This sets the key to and from the server (see the two next functions if you want different keys). This key should be the same on the program side and the script side. You may call this function several times to set different keys for different scripts. Advice for improved security: do not use simple keys, or keys belonging to the dictionnary. "sG4%fh*$^k" is better than "secret"! |
| Parameters: key$ = the key (string) for the encryption/decryption. |
| Return value: None |
| ETNA_SetKeySend(key$) |
| Description: When you use encryption, use this function to set the encryption key when you send information to the server (with ETNA_Send()). The information going to the server (to the script) will be encrypted with this key. This key should be the same on the program side and the script side. You may call this function several times to set different keys for different scripts. |
| Parameters: key$ = the key (string) for the encryption. |
| Return value: None |
| ETNA_SetKeyReceive(key$) |
| Description: When you use encryption, use this function to set the encryption key when you receive the information from the server (with ETNA_GetResult()). The information coming from the server (from the script) will be decrypted with this key. This key should be the same on the program side and the script side. You may call this function several times to set different keys for different scripts. |
| Parameters: key$ = the key (string) for the decryption. |
| Return value: None |
| ETNA_Send(ID%, command$, [encrypted%=False], [highPriority%=False]) |
| Description: Send a request to the server. You can send a threaded or non-threaded request depending on the ID argument. For a threaded request, this function returns immediately and the program can continue. You can also encrypt the information you send. This is very easy, you just have to set the parameter encrypted to True. Of course, your script should decrypt the information, but ETNA is providing the function to do that: refer to the tutorial or the library section for more details. Note that all requests are garanteed to arrive in the same order they were sent. |
| Parameters: ID% = The identification of the command. This allows the programmer to distinguish between different commands. If ID = ETNA_NO_THREAD, the request will be executed immediately, but will stop the flow of the program for a short instant. In that case, get the result of the request using the functions ETNA_GetState() and ETNA_GetResult(). If ID is user-defined (<> ETNA_NO_THREAD), the request will be sent using a thread, and will be queued after the previous requests. To check if the result was received, use the function ETNA_Receive() with the same ID. command$ = The command you are sending on the server. Usually, this is a call to a script (for example php script). encrypted% = Optional parameter to specify if you want to encrypt the information you are sending. [Default value = False] highPriority% = In the case of a threaded request, you can ask to put this particular request at the top of the queue. By default, the request is put at the end of the queue. [Default value = False] |
| Return value: None |
| Example: ; A threaded request: Const GET_VALUE = 1 ETNA_Send(GET_VALUE, "myScript.php?opt=getValue") ; A non threaded request: ETNA_Send(ETNA_NO_THREAD, "myScript.php?opt=setValue&value=1") ; A threaded request with encryption: ETNA_Send(GET_VALUE, "myScript.php?opt=getValue", True) |
| ETNA_Cancel(ID%) |
| Description: Function to cancel a certain type of ID in the queue (for threaded requests). It is not possible to cancel a command already running! |
| Parameters: ID% = the ID of the command(s) you want to cancel. If ID = -1, then cancel all commands in the queue. |
| Return value: None |
| ETNA_GetNumberOfCommandsInQueue() |
| Description: Function returning the number of commands in the queue (for threaded requests). Make sure that the queue is not growing exponentially! |
| Return value: The number of commands in the queue. |
| ETNA_Update() |
| Description: Handle the threaded requests. Put this function in your main loop if you use requests with thread (see ETNA_Send()). This function is not needed for a non-threaded request. WARNING: this is the central function for the threaded requests: do not forget to call this function regularly (ideally in the main loop)!! |
| Return value: None |
| ETNA_Receive(ID%) |
| Description: Function to check if the result of a command was received. If the result is True, use the functions ETNA_GetState() and ETNA_GetResult() to get the results. This function is for the threaded requests only. A call to ETNA_Update() needs to be done before a call to this function (ideally in the main loop). Note that all requests are garanteed to arrive in the same order they were sent. |
| Parameters: ID% = The ID of the command you want to check. |
| Return value: True if the result for this particular ID was received. |
| Example: If ETNA_Receive(GET_VALUE) Then Print "State of the command = " + ETNA_GetState() Print "Result of the command = " + ETNA_GetResult() EndIf |
| ETNA_GetState() |
| Description: Function returning the state (OK or error) of the last request received. Use this right after ETNA_Receive() for a threaded request and right after ETNA_Send() for a non-threaded request. If there is no error, use ETNA_GetResult() to get the result. |
| Return value: Several states are possible:
|
| Example: If ETNA_Receive(GET_VALUE) Then If ETNA_GetState() = ETNA_OK Then Print "Request successful" EndIf |
| ETNA_GetResult([lineNb%=-1]) |
| Description: Function returning the result of the last request received. ETNA_GetState() should have returned ETNA_OK to get a non empty result. Use this right after ETNA_Receive() for a threaded request and right after ETNA_Send() for a non-threaded request. ETNA will detect automatically if the string result is encrypted, and will decrypt it in that case. See the tutorial for more details on encryption. line has the index 1, not 0! |
| Parameters: lineNb% = If nothing is specified for this argument (or if = -1), the function will return the whole result, with several lines when it applies (separated by the default delimiter). If this parameter is entered, it returns the specified line from the result of the script. You can get the number of lines returned by the script using the function ETNA_GetNbOfLines(). Warning: the first [Default value = -1] |
| Return value: The whole result of the request or the specific line of the result if the lineNb argument is entered. |
| Example: If ETNA_Receive(GET_VALUE) Then If ETNA_GetState() = ETNA_OK Then Print ETNA_GetResult() For i% = 1 To ETNA_GetNbOfLines() Print ETNA_GetResult(i) Next EndIf EndIf |
| ETNA_GetNbOfLines() |
| Description: Function returning the number of lines in the output of the script on the server. |
| Return value: the number of lines in the result. |
on 27 Nov 2006.