24U SimpleTalk Plug-In 2.0 Syntax

Complete syntax and functionality of the plug-in functions

STalk_Version( { versionFormat } )

Returns version string of the active 24U SimpleTalk Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"short"To get just the version number. Default value.
"long"To get the plug-in name followed by its version number.
"platform"To get the platform of the code currently running on.
"autoupdate"To get autoupdate compatible (comparable) version number.

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?", the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Example

STalk_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleTalk Plug-In 2.0".

STalk_Register( selector )

Provides special functionality to operate with plugin serial numbers.

Parameter values for selector

SerialNumber Register given SerialNumber and return an error code.
EmailAddress Tries to activate with given email address and return an error code. Trial version is valid only after you confirm email
HashActivate a serial number with a hash received from 24U. Used for offline activation.
"Registration Window" Show the "Registration window" and return 0.
"About Window" Show the "About window" and return 0.
"Status" Return the actual registration state of the plugin: Demo, Demo expired, Trial, Trial Expired, Registered or Dead.
"Unregister" Unregister all serial numbers related to the product and return an error code. Note: after this trial version days wont come back.
"Info"Returns current plugin status and its registered serial numbers.
"ActivationChallenge"Returns generated challenge string. This string is sent to 24U.
"Purchase" ; webAddressOpens web browser with given webAddress. Given webAddress should point to 24U Store. This functionality is not implemented for FileMaker Server and Linux.

Description

Use this function to register or unregister 24U SimpleTalk Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns zero or error code depending on the selector.

Examples

STalk_Register( "STLI20C016-BXMW-VNW7-L8AJ-3KGX-VWG8" )
This function will register the plug-in with client serial number STL20C016-BXMW-VNW7-L8AJ-3KGX-VWG8 for 16 users.

STalk_Register( "user@mail.com" )
In case you do not have a serial number but you want to try the plug-in out, use the string with your email address as selector.

STalk_Register( "unregister" )
This function will unregister every serial number related to 24U SimpleTalk Plug-In.

STalk_Register( "About window" )
Similar to opening FileMaker preferences, navigating to the Plug-Ins tab and double-clicking on 24U SimpleTalk Plug-In.

Note: All serial numbers here are only for demonstration purposes. They will not work in the plug-in.

STalk_StartServer ( port { ; protocol } { ; datahandler { ; openhandler { ; closehandler }}} { ; encoding } { ; terminator } )

Parameters

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 built-in handler)
closehandler name of script to run (default is built-in handler)
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:

openhandler schedules the specified script to run, returns "OK" if successfully scheduled, or "ERROR" if script could not be scheduled
datahandler receives data with one STalk_Receive call and performs actions if the received data match to one of the following patterns:
RUN schedules the specified script to run, returns "OK" if successfully scheduled, or "ERROR" if script could not be scheduled
EVAL 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 closes the connection from the server side

Description

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.

Result

STalk_StartServer returns positive serverID if successful, negative error code in the case of failure.

Examples

STalk_StartServer( "3333" ; "TCP" ; "Some script for openhandling" ; "Some script for datahandling" ; "Some script for closehandling" )
This function will start server on port 3333 with these scripts as handlers. Note: "Some script for openhandling", "Some script for datahandling" and "Some script for closehandling" has to be valid names of scripts.

STalk_StartServer( "3333" )
This function will start server on port 3333 with default handlers.

STalk_StopServer ( serverID )

Parameters

serverID value returned by StartServer function

Description

Close all open connections and shut the specified server down.

Result

Returns 0 if successful, error code in the case of failure (i.e. invalid server ID).

Examples

STalk_StopServer( 42 )
Stops server with ID 42 - if existed.

STalk_Connect ( host ; port { ; protocol } { ; datahandler { ; closehandler} } { ; encoding } { ; terminator } { ; timeout { ; idle } } )

Parameters

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)

Description

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.

Result

Returns positive connectionID if successful, negative error code in the case of failure.

Examples

STalk_Connect ( "1.1.1.1" ; "80" )
Connects to server with IP 1.1.1.1 using port 80.

STalk_Connect ( "192.168.0.1"; "33" ; "TCP" ; "UTF-8" ; ">" )
Connects to server with IP 192.168.0.1 using port 33. Encoding for communication UTF-8, as terminator is used character >.

STalk_Disconnect ( serverID )

Parameters

serverID value returned by StartServer function

Description

Close and invalidate the specified connection.

Result

Returns 0 if successful, error code in the case of failure (i.e. invalid server ID).

Examples

STalk_Disconnect ( 4 )
Disconnects from with given serverID.

STalk_Send ( host; port { ; protocol } { ; encoding } { ; terminator } { ; autoconvert { ; local_terminator } }{ ; timeout } ; data )

Parameters

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

Description

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)

Result

Returns received reply if successful, negative error code in the case of failure.

Examples

STalk_Send ( "192.168.0.1"; "33" ; "Hello my new friend\r\n" )
Sends string to address 192.168.0.1 using port 33. Terminator is used default "\r\n".

STalk_Send ( connectionID { ; encoding } { ; terminator } ; data )

Parameters

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)
data data to be send.

Description

Send data to the other side of an open connection. Automatically append the connection's terminator to the end of the data.

Result

Returns positive number of bytes sent (including terminator) if successful, negative error code in the case of failure.

Examples

STalk_Send ( 5 ; "SimpleTalk says hi!\r\n" )
Sends message to connection with ID 5. Terminator is used default "\r\n".

STalk_Receive ( connectionID { ; encoding } { ; terminator } { ; timeout } )

Parameters

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)

Description

Read data from an open connection's buffer up to the terminator. Terminator is read but not returned.

Result

Returns data read (without terminator) if successful, negative error code in the case of failure.

Examples

STalk_Receive ( 42 )
Tries to receive data from connection with ID 42.

STalk_Get( selector { ; connectionOrServerID } )

Parameters

selector specifies operation
connectionOrServerID value returned by StartServer or Connect functions

Possible values for selector

"local-ip" Local IP address
"local-port" Local port number associated with the specified server or connection
"remote-ip" IP address of the remote side of the connection
"remote-port" Port number of the remote side of the connection
"encoding" Default encoding for the connection
"frontmost" 1 if FileMaker is the frontmost application, 0 otherwise

Description

Returns current value of a global variable or a connection/server option specified by selector.

Result

Returns requested value or "?" in case of an error

Examples

STalk_Get( "local-ip" )
Returns IP adress of local pc.

STalk_Set( selector { ; connectionOrServerID } ; newValue )

Parameters

selector specifies operation
connectionOrServerID value returned by StartServer or Connect functions

Possible values for selector

"encoding" Modifies the default encoding of the specified server or connection
"frontmost" Brings FileMaker to front or sends it to back.

Description

Modifies value of a global variable or a connection/server option specified by selector.

Result

Returns 0 or "?" in case of an error

Examples

STalk_Set( "encoding" ; "UTF-16" )
Sets default encoding "UTF-16".

STalk_Set( "frontmost" ; True )
Brings FileMaker to front.

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)

Note on terminators

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 behaviour, 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 behaviour: 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.

24U SimpleTalk Plug-In status codes

-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
24001Demo mode expired: If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002Product expired: Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003SN limit was met: The serial number is already registered on too many computers.
24004Product is dead: The product expired and cannot be used any more. Please download the new version from 24U Software.
24005Invalid serial number: Serial number you entered is not valid.
24006Activation failed: Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007Deactivation failed: Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008Unknown serial number: The given serial number cannot be used for the current product. It has been stored so that other product can try to use it.
24009Blacklisted serial number: The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010eSellerate engine not installed: This product uses eSellerate to validate user registration and purchases, but its installation failed. Please, reboot the computer or try again later.