24U PhoneCompanion Plug-In 3.0 Syntax

Specification revision: 6, 2018-07-03.

Created by: Lukáš Liebzeit, Martin Vraný, Zdenek Hejl, ©2018 24U Software.

1. Basic technical parameters

File names:PhoneCompanion.fmx, PhoneCompanion.fmx64, PhoneCompanion.fmplugin
Plug-In ID String:24PC
Function names prefix:Phone_
Plug-In API version:FileMaker 16.0 native. FileMaker 15.0, 14.0 compatible
Windows version:Only 64bit architecture. Windows 7 - 10
MacOS version:OS X 10.10 - macOS 10.13
SN product code and versions:SNlib 4.4

2. 24U PhoneCompanion Plug-In 3.0 Syntax

Phone_Version( { versionFormat } )

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

Parameters

Name Datatype Condition Description
versionFormat string [enum] Defines 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.
"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 "?", then the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

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

Phone_Version( "platform" )
Returns "Mac OS X" , because no other platform is allowed.

Phone_Version( "autoupdate" )
Returns 03000000 for version 3.0.0 of the plug-in.

Phone_Register ( selector )

Provides special functionality to operate with plugin serial numbers.

Parameters

Name Datatype Condition Description
selector string Define the type of operation.

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
"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.

Description

Use this function to register or unregister 24U PhoneCompanion 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

Phone_Register( "address@example.com" )
This will send on email address@example.com confirmation, if you confirm than you will get trial version on this product verified by this email. Note: In case of trial version only few steps can be processed.

Phone_Register( "PHC30C050-ABCD-1234-QWER-ASDF" )
This will register this product. Registration will allow you use all features of this product.

Phone_Register( "Unregister" )
This will remove all registration of this product.

Phone_Connect( "serverIP" ; "serverPort" { ; "timeout" } )

Connect to STLI server.

Parameters

Name Datatype Condition Description
"serverIP" string The IP address of the server.
"serverPort" string The port of the server.
"timeout" string The timeout for connection. Use float number in seconds. The default value is 3s.
Note: macOS keeps its sockets open when internet is disabled after connection.

Description

Call this function establish TCP connection to STLI server. This server is needed to control the line. All phone functions will work only if the plug-in is properly connected.

Result

Function returns 0 in case of success or one of the error codes.

Examples

Phone_Connect( "10.0.0.2" ; 26535 )
The plug-in will attempt to connect to server with IP 10.0.0.2 on port 26535.

Phone_Connect( "132.65.28.17" ; 25001 ; 9.5 )
The plug-in will attempt to connect to server with IP 132.65.28.17 on port 25001 with 9.5 seconds timeout.

Phone_Disconnect

Disconnect from STLI server.

Description

This function will cause that TCP connection to STLI server will be terminated. Use this function when you no longer need phone services.

Result

Function returns 0 if the connection was terminated. It returns 0 even if there was no previous connection. Error code is returned when the connection was not terminated in the standard way (abnormal termination).

Examples

Phone_Disconnect
Function has no parameters. This will always terminate the connection and return status code.

Phone_Dial ( localDevice ; calledDirectoryNumber )

Dials a specified telephone number on the specified calling device.

Parameters

Name Datatype Condition Description
localDevice string The phone number of device from which the call originates. The device must be local.
calledDirectoryNumber string Indicates the device to which the call should be directed. The number should direct to local or external device.

Description

This function will dial the number on the local phone. The format should be FileMaker text. It can contain all numbers, "*", "#" and "+".

Result

Function returns 0 if the number was successfully dialed. It doesn't matter if the other side accepted the call or not. If some error occurred (line is not ready, server is not ready, line was forcefully disconnected or similar) the status number is returned.

Examples

Phone_Dial( "11" ; "17" )
This will dial the number 17 on the device with number 11.

Phone_Dial( "103" ; "05555925" )
You can use any number for outside calls. This will dial 05555925 number on the device with local number 103.

Phone_Answer ( localDevice )

Answers (off-hook) an incoming call.

Parameters

Name Datatype Condition Description
localDevice string The local device which should answer the call.

Description

The called local device should be able to accept incoming call. It should be either speakerphone or headset equipped phone. The local device should be monitored for incoming calls. Use Phone_SetScriptEvent function to monitor incoming calls.

Result

Function returns 0 if the call was successfully accepted. It the device cannot accept call or another problem occurred than the status code is returned.

Examples

Phone_Answer( "19" )
This will accept the call on the local device with number 19.

Phone_HangUp ( localDevice )

Hang up a call.

Parameters

Name Datatype Condition Description
localDevice string The local device which should hang up.

Description

This function will hang up a call on the local phone. The call should be properly established and local device should be monitored with some event. Use Phone_SetScriptEvent to start monitoring events.

Result

Function returns 0 if the phone was properly hanged up. In case of error the function returns negative error code.

Examples

Phone_HangUp( "19" )
This will hang up a call on the phone with number 19.

Phone_RawCommand ( commandString )

Sends a raw command to the server.

Parameters

Name Datatype Condition Description
commandString string The command string. In case of hosted PBX, it requires the command to be placed as a string containing serialised JSON object.

Description

This function can be used to send low level commands directly to the server.

Result

Function returns 0 if the command was successfully sent. It doesn't matter if the other side accepted the command. Note: This function does not wait for response. Use Phone_SetScriptRawEvent in conjunction with raw commands to catch server responses

Examples

TeamCall and TeamCall Express:
Phone_RawCommand( "HoldCall 199348" )
Send command "HoldCall" with number 199348 to the server. Do not wait for reply. What the server will do is undefined.

Phone Companion Server:
Phone_RawCommand( "{\"method\" : \"GET\", \"resource\" : \"/restapi?name=24u\"}" )
Send HTTP request directly to the provider. Phone Companion Server returns 24U STLI success message in case of 200 OK response family at the provider. And error message in all other scenarios.

Phone_SetScriptEvent ( localDevice ; event ; scriptName )

Tell the plug-in to launch the script when specified event is triggered from outside.

Parameters

Name Datatype Condition Description
localDevice string The phone number of the device for which the event will be triggered.
event string [enum] The type of the event which should be installed. See table below for possible types.
scriptName string The name of the script which should be triggered.

Parameter values for event

"onIncomingCall" Run the script on incoming call from outside.
"onAnswerCall" Run the script when incoming call is answered.
"onHangUp" Run the script on hang up.
"onCalling" Run the script when when the call is made from the phone.

Description

The function will call the specified script when the event of the specified type occurs. The script will receive a parameter which contains the number of controlled phone on the first line and the phone number of the second side on the second line.

To remove event for some number call Phone_SetScriptEvent( localDevice ; event ; "" ).
To remove all events for some number call Phone_SetScriptEvent( localDevice ; "" ; "" ).
To remove all events for all numbers call Phone_SetScriptEvent( "" ; "" ; "" )

Result

Function returns 0 if event is successfully installed or uninstalled. In case of error the function returns negative error code.

Note

Each triggered script from plug-in receives script parameter which can be read by Phone_Get( ScriptParameter ) script step. The parameter consists of several lines of text. See the notes below to learn what each line of script parameter means (parameters are sorted from the first line) :

Parameters passed to the "onIncomingCall" handler

localDevice The local device which registered incoming call.
callerID The number of the caller.
calledID The number of line which received the call. This parameter is optional. It is filled only on PBXs where it is supported. Hosted PBX currently does not support calledID.

Parameters passed to the "onAnswerCall" handler

localDevice The local device which registered incoming call.
callerID The number of the caller.
calledID The number of line which received the call. This parameter is optional. It is filled only on PBXs where it is supported. Hosted PBX currently does not support calledID.

Parameters passed to the "onHangUp" handler

localDevice The local device which where the event happened.

Parameters passed to the "onCalling" handler

localDevice The local device which is used right now for outgoing call.
calledID The number where the call directs.

Examples

Phone_SetScriptEvent( "19" ; "onAnswerCall" ; "Save answered call" )
This will install the script named "Save answered call" for the local device with number 19.

Phone_SetScriptEvent( "105" ; "onCalling" ; "Show announcement" )
The script "Show announcement" will be called every time the user makes a call from the phone with number 105.

Phone_SetScriptRawEvent ( pattern ; scriptName )

Tell the plug-in to launch the script when it receives a message which corresponds to regular expression.

Parameters

Name Datatype Condition Description
pattern string Regular expression pattern. If incoming message matches this pattern, the script is triggered. To disable the filter set this parameter to "".
scriptName string The name of the script which should be triggered.

Description

This function is similar to Phone_SetScriptEvent. It does not recognize the meaning of events. It just filters them using regular expressions and triggers the script on match. It is recommended to always use some kind of filter. Using this function without filter can slowdown FileMaker application.

To remove triggers with some script name call Phone_SetScriptRawEvent( "" ; scriptName ).
To remove all triggers use Phone_SetScriptRawEvent( "" ; "" ).

Result

Function returns 0 if script trigger is successfully installed or uninstalled. In case of error the function returns negative error code.

Note

Each triggered script from plug-in receives script parameter which can be read by Get( ScriptParameter )script step. The parameter contains the message which triggered the script. The message is read into the FileMaker using UTF-8 encoding.

Examples

Phone_SetScriptRawEvent( "^[Ff]ailed .*" ; "Handle Failed Call" )
Call the script "Handle Failed Call" when incoming message contains word Failed or failed on the start.

Phone_SetScriptRawEvent( "^[Dd]evice[Ii]nformation 34 .*" ; "Read Phone Information" )
The script "Read Phone Information" will be called every time something happens on phone with number 34.

Phone_SetScriptRawEvent( "" ; "Read Phone Information" )
The script "Read Phone Information" will not be triggered in the future. It will be removed from all pattern queues.

Phone_SetScriptRawEvent( "^[Ff]ailed .*" ; "" )
All scripts triggered by "^[Ff]ailed .*" regular expression will be removed from the queue. No such script will be called in the future.

Phone_Get ( what )

Function to get plug-in or phone server settings and other useful data.

Parameters

Name Datatype Condition Description
what string What parameter to get.

Parameter values for what

"lastError" Returns the error code of the last error. If no error occurred 0 is returned. It does not change the value of lastError.
"lastErrorMessage" Returns the error message string of the last error. If no error occurred "" is returned. It does not change the value of lastError.
"log" Returns log.
"serverStatus" Returns either "connected" or "disconnected".
"monitoredDevices" Returns a value list of the devices which are currently monitored for events. The value list is delimited by line break.
"serverResponseTimeout" Default 3 seconds. How long Phone Companion waits for reply from the middleware.
"serverCommunicationDelay" If Phone companion sends more than one message it waits very short time between each message. Use this parameter to obtain this value in seconds.
"inlineDocumentation" Returns "on" or "off" based on status of inlineDocumentation in Plug-In.

Description

Use this function to get important parameters.

Result

Function returns data if everything is OK. In case of error, the function returns "?". Use Phone_Get with parameter "lastError" to obtain the error code.

Examples

Phone_Get( "lastError" )
Returns last function error code or 0 if last function was performed properly.

Phone_Set ( what ; newValue )

Set plug-in or phone server settings and other useful parameters.

Parameters

Name Datatype Condition Description
what string What data to set.
newValue string The new value for data.

Parameter values for what

"serverResponseTimeout" Sets how long Phone Companion waits for reply from TeamCall Server or Express. The time is in seconds and the default value is 3 s.
"serverCommunicationDelay" If Phone companion sends more than one message it waits very short time between each message. The default value is 0.1 s. Use longer delays if the middleware is not able to react to fast communication.
"inlineDocumentation" Allows to turn off or on inlineDocumentation. Possible values are "on" or "off".

Description

Use this function to set important parameters. Default communication delays and timeouts are set to work on local area networks. You can set longer values on slower networks (slow wireless networks) but the plug-in reactions will be also slower. Try to keep serverCommunicationDelay parameter as low as possible. Setting it too high (>1s) will essentially delay plug-in responses and probably will not help on broken link.

Result

Function returns the real value of parameter if everything is OK. In case of error the function returns "?". Use Phone_Get with parameter "lastError" to obtain the error code.

Examples

Phone_Set( "serverResponseTimeout" ; 4.5 )
he plug-in will wait for each answer from TeamCall up to 4.5 seconds. This also means that FileMaker will frozen for 4.5 seconds if TeamCall does not respond - do not set it too high.

3. Script Steps

Since version 16 of FileMaker Pro and FileMaker Pro Advanced new feature called "External script steps" has been added. This feature allows plug-in to offer its functionality as FileMaker script steps.
In PhoneCompanion 3.0 external script steps for some of our plug-in functions were added. Following table shows, which functions of plug-in can be also called as script step.

Plug-In function Script Step
Phone_Version Phone Version
Phone_Register Phone Register
Phone_Connect Phone Connect
Phone_Disconnect Phone Disconnect
Phone_Dial Phone Dial
Phone_Answer Phone Answer
Phone_HangUp Phone HangUp
Phone_SetScriptEvent Phone Set Script Event
Phone_SetScriptRawEvent Phone Set Script Raw Event
Phone_Set Phone Set Option
Phone_RawCommand Phone Send Raw Command

4. Error Codes Table

Here is the list of all error codes which can be returned by the plug-in. The error codes are derived from MacErrors.h header file from Mac OS. Plug-in's custom error codes are positive numbers in the range between 2400 and 9999. If function fails it either returns "?" signaling an error or it returns the error code directly. If it returns "?" you can use Phone_Get( "lastError" ) to obtain the code.

Code Description
0 Success The given action succeeded and/or there is no problem with proceeding with another.
-4 Not implemented If you see this error please report the error and steps to reproduce it to 24U Support. This error should never be invoked in the released version of the plug-in.
-50 Wrong parameter If you see this error please check documentation for correct usage of the plug-in.
2400 Unknown error An unknown error occurred. If you see this error please report the error and steps to reproduce it to 24U Support. We will try to identify error conditions and add the error to this list with a new error code assigned.
2420 Wrong script name Unknown script name was passed to plug-in.
2421 Wrong event name Unknown event name was passed to plug-in.
2430 STLI: Already monitored The extension is already monitored from another session.
2431 STLI: No device There is no such device.
2432 STLI: No monitor The extension is not monitored in this session.
2433 STLI: Unavailable request Request not supported, disabled or invalid.
2434 STLI: Pending request Another session is currently waiting for the same request with the same parameters.
2435 STLI: No connection Request not executed, there's no connection at the device.
2436 STLI: No call Request not executed, there's no call at the device.
2437 STLI: Link out of service The request cannot be executed because there is no connection to PBX.
2438 STLI: Invalid parameter Wrong parameter value was passed in raw command.
2439 STLI: Invalid number of parameters Wrong number of parameters was passed in raw command.
2440 STLI: Invalid forwarding feature Unknown parameter for request SetForwarding.
2441 STLI: Invalid device feature Unknown parameter for request SetDeviceFeature.
2442 STLI: Invalid agent state Unknown parameter for request SetAgentState.
2443 STLI: Invalid command Invalid command could not be processed.
2444 STLI: Internal demoversion Only one device can be monitored with this demo version.
2445 STLI: No multiple instance Extension is already monitored in this session.
2446 STLI: Unknown error An unrecognized error occurred.
2450 Middleware Error Error on middleware communication occurred. Read "lastErrorMessage" to get exact error string.
-3256 Socket is not connected The plugin is not connected to the server.
-3259 Time out The server didn't reply within the timeout period.
24001 Demo mode expired If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002 Product expired Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003 SN limit was met The serial number is already registered on too many computers.
24004 Product is dead The product expired and cannot be used any more. Please download the new version from 24U Software.
24005 Invalid serial number Serial number you entered is not valid.
24006 Activation failed Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007 Deactivation failed Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008 Unknown 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.
24009 Blacklisted serial number The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010 eSellerate 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.