This file describes syntax of 24U SimpleTalk Plug-In's functions.
STalk_Version ( versionFormat )
Returns version string of the active 24U SimpleTalk Plug-In, formatted as requested by the parameter. Use:
"short" to get just the version number "long" to get the plug-in name followed by its version number "platform" to get the platform of the code currently running
STalk_Register ( registrationCode )
Attempts to unlock (register) your copy of 24U SimpleTalk Plug-In with the specified code. If the code is valid, 24U SimpleTalk Plug-In gets unlocked and stays in this state until you quit the FileMaker application, deactivate the plug-in, or the registration code expires. While unlocked, 24U SimpleTalk Plug-In is fully functional and does not bother the user with a shareware reminder.
Returns a non-zero result when operation is not permitted.
STalk_StartServer ( port { ; protocol } { ; datahandler { ; openhandler { ; closehandler }}} { ; encoding } { ; terminator } )
Start listening for incoming connections on the specified port. When new connection is opened, openhandler is called.
The data received through the connection are stored in a queue. When a terminator (CRLF by default) is
present in the connection queue, datahandler is called and connectionID is passed to it as parameter.
Datahandler is responsible for clearing the beginning of the queue up to the terminator(including) using the STalk_Receive
function. After the data handler completes, it is called again immediately when there is a terminator in the connection queue.
When the connection closes, closehandler is called. Neither openhandler
nor closehandler are required to call STalk_Receive.
port port number to listen on protocol "TCP" (default), additional options may be supported in future versions datahandler name of script to run (default is built-in handler) openhandler name of script to run (default is datahandler) closehandler name of script to run (default is openhandler) encoding "UTF-8" (default) or "UTF-16" or "UTF-16BE" or "UTF-16LE" or "ASCII" or "Hex" (see the note below). This value is also used as a default encoding for all further server connections. terminator string for splitting the data (default is CRLF). (see the note below) This value is also used as a default terminator for all further server connections.
Built-in handlers
If no handlers are specified in STalk_StartServer call, built-in handlers are used.
openhandler sends message "Welcome to SimpleTalk" datahandler receives data with one STalk_Receive call and performs actions if the received data match to one of the following patterns:
RUN <scriptname> schedules the specified script to run, returns "OK" if successfully scheduled, or "ERROR" if script could not be scheduled EVAL <calculation> evaluates the specified calculation in the current context (of the frontmost window) and returns result QUIT closes the connection from the server side
close handler does nothing
STalk_StartServer returns positive serverID if successful, negative error code in the case of failure.
STalk_StopServer ( serverID )
Close all open connections and shut the specified server down.
Returns 0 if successful, error code in the case of failure (i.e. invalid server ID).
STalk_Connect ( host ; port { ; protocol } { ; datahandler { ; closehandler} } { ; encoding } { ; terminator } { ; timeout { ; idle } } )
Open a TCP connection to the specified host. Datahandler and close handler are called in the same way as described in STalk_StartServer function reference.
host Domain name or IP address of the server to connect to port remote port number to connect to protocol "TCP" (default), additional options may be supported in future versions datahandler name of script to run (default datahandler does nothing) closehandler name of script to run (default is datahandler) encoding "UTF-8" (default) or "UTF-16" or "UTF-16BE" or "UTF-16LE" or "ASCII" or "Hex" (see the note below). This value is also used as a default encoding for all further connection operations. terminator string for splitting the data (default is CRLF). (see the note below) This value is also used as a default terminator for all further connection operations. timeout number of seconds to wait for a connection (default is 60). This value is also used as a default timeout for all further connection operations. idle number of seconds to wait after last send or receive operation before automatically closing the connection (default is 600)
Returns positive connectionID if successful, negative error code in the case of failure.
STalk_Disconnect ( connectionID )
Close and invalidate the specified connection.
Returns 0 if successful, error code in the case of failure (i.e. invalid connection ID).
STalk_Send ( host; port { ; protocol } { ; encoding } { ; terminator } { ; autoconvert { ; local_terminator } }{ ; timeout } ; data )
Connect to the specified host/port, send the data (and terminator), wait for reply (until the other side closes connection or the time is out), close the connection and return the reply.
If autoconvert is specified, each occurrence of local_terminator in data is replaced with terminator. Also each occurrence of terminator in the reply is replaced with local terminator.
This is useful e.g. when you want to send more lines separated with CRLF instead of line ends. (This is the default behaviour)
host Domain name or IP address of the server to connect to port remote port number to connect to protocol "TCP" (default), additional options may be supported in future versions encoding "UTF-8" (default) or "UTF-16" or "UTF-16BE" or "UTF-16LE" or "ASCII" or "Hex" (see the note below). terminator a string to be added to the end of the data being sent (CRLF by default) (see the note below) autoconvert "yes" or "no" (default is "yes") local_terminator string which will be replaced with terminator (default is line end) timeout number of seconds to wait for a connection and reply (default is 60) data data to be sent
Returns received reply if successful, negative error code in the case of failure.
STalk_Send ( connectionID { ; encoding } { ; terminator } ; data )
Send data to the other side of an open connection. Automatically append the connection's terminator to the end of the data.
connectionID numerical identification of an open connection (result of STalk_Connect or handler's script parameter) encoding "UTF-8" or "UTF-16" or "UTF-16BE" or "UTF-16LE" or "ASCII" or "Hex" (see the note below). (inherited from connection by default) terminator a string to be added to the end of the data being sent (inherited from connection by default) (see the note below) data data to be sent
Returns positive number of bytes sent (including terminator) if successful, negative error code in the case of failure.
STalk_Receive ( connectionID { ; encoding } { ; terminator } { ; timeout } )
Read data from an open connection's buffer up to the terminator. Terminator is read but not returned.
connectionID numerical identification of an open connection (result of STalk_Connect or handler's script parameter) encoding "UTF-8" or "UTF-16" or "UTF-16BE" or "UTF-16LE" or "ASCII" or "Hex" (see the note below). (inherited from connection by default) terminator string for splitting the data (inherited from connection by default). (see the note below) timeout time in seconds to wait for data before timing out (use connection's timeout by default), 0 for "don't wait" (return immediately either data or an error code)
Returns data read (without terminator) if successful, negative error code in the case of failure.
STalk_Get( selector { ; connectionOrServerID } )
Returns current value of a global variable or a connection/server option specified by selector.
STalk_Get( "local-ip" { ; connectionOrServerID } ) Local IP address STalk_Get( "local-port" ; connectionOrServerID ) Local port number associated with the specified server or connection STalk_Get( "remote-ip" ; connectionID ) IP address of the remote side of the connection STalk_Get( "remote-port" ; connectionID ) Port number of the remote side of the connection STalk_Get( "encoding" ; connectionOrServerID ) Default encoding for the connection STalk_Get( "frontmost" ) 1 if FileMaker is the frontmost application, 0 otherwise
STalk_Set( selector { ; connectionOrServerID } ; newValue )
Modifies value of a global variable or a connection/server option specified by selector.
STalk_Set( "encoding" ; connectionOrServerID ; encoding ) Modifies the default encoding of the specified server or connection STalk_Set( "frontmost" ; boolean ) Brings FileMaker to front or sends it to back
Note on data encoding
Encoding of data defines the way how the content passed to SimpleTalk is converted into binary form for sending through network and vice versa. Hence it is important that each side of the connection is synchronized with each other and uses the same encoding.
| UTF-8 | Each character of the text is encoded with one or two bytes. | |
| UTF-16BE | Each character of the text is encoded with two bytes. Big endian ordering is used. | |
| UTF-16LE | Each character of the text is encoded with two bytes. Low endian ordering is used. | |
| UTF-16 | This is synonyma for UTF-16BE | |
| ASCII | Each character of the text is encoded with one byte. Only the basic 127 ASCII characters will be send unchanged. | |
| Hex | The text is taken as a hexadecimal representation of binary data. (i.e. each pair of characters represents one byte) |
Terminator is a couple of bytes which splits the transferred data into logical blocks. Of course, both sides of the connection should use the same terminators to achieve the requested behaviour. When a terminator is specified as an optional parameter to some Plug-In's function, it is encoded into binary form with the same encoding which is given to encode/decode the data. The only exception is default terminator CRLF, which already has exact binary interpretation. When the given terminator is an empty string, its behaviour is a little bit special and depends on the calling function:
| STalk_StartServer,STalk_Connect | data handler is never called | |
| STalk_Send(connectionID,...) | normal behavior, i.e. nothing is appended to the data sent | |
| STalk_Receive | waits for timeout or the disconnection from the other side, then returns everything it received | |
| STalk_Send(host...) | partially normal behavior: nothing is appended to the data sent, occurrences of local_terminator are replaced with empty string,but the received data are not changed. |
Note on optional parameter evaluation
Majority of SimpleTalk functions can be called with optional parameters. Their syntax suggests that the plugin could not distinguish which calling form the user requested. For example the string "UTF-8" in call STalk_StartServer(2424,"UTF-8"), could describe protocol, datahandler, encoding or terminator. To be able to corectly distinguish the parameters, the name of the handlers and terminator can not be "tcp", "UTF-8", etc. Also the terminator can not be name of any existing script (potential handler). This restrictions are rather small and it rarely makes problems in practical situations. In such situation, there still is the possibility to call SimpleTalk function with all parameters given so that no ambiguity is possible.
List of the most common error codes returned by 24U SimpleTalk Plug-In's functions
-50 Invalid parameter -1000 Plug-In requires registration (expired) -3218 Invalid server ID -3247 Address/port already in use -3256 Connection error / not connected -3157 WSA internal error -3259 Connection/request timed out -3260 Connection refused