Remote control

Detroit engine supports remote function calls. This means that every function declared in Ano script can be called over the network. Remote function call is handy in automated testing and such, or programs can be daisy chained to control each other. Remote control support must not be disabled when running configure script (do not use --disable-remote), and remote control must be initialized in Ano script in order it to work.

Somewhere at the beginning of Ano script, call remote_init() function:

	remote_init

See examples/remote_control directory for live example.

When program to be remote controlled is started, it needs at least --auth_secret command line switch to be set, or secret can be set in config file. Auth secret is the secret string that remote controller must know when it is calling functions over the net. As an example, here is minimal Ano script which can be remote controlled:

;
; @ANO_SCRIPT_NAME		remote_control
; @ANO_SCRIPT_VERSION		0.0.1
; @ANO_SCRIPT_DESCRIPTION	Example how to run functions remotely
;
; @ANO_FLAGS_VAR_NAME_SUBS	[ ]
; @ANO_FLAGS_VAR_WARN_UNUSED	[ ]
;
; Copyright (c) 2016-2023, Jani Salonen <salojan at goto10 piste co>
; All rights reserved.
;

	;
	; This is main program, just start remote thread and let it handle
	; remote connections. Program terminates when "remote_end" label is
	; called (see below).
	;

	remote_init
	end

: "remote_test" (param1, param2, param3)
	;
	; To call this function remotely (set SECRET with -na switch):
	;
	; $ telnet localhost 2109
	;   SECRET remote_test int:1 uint:2 float:3.3
	;
	; End code returned to caller is the sum of params or -1 if error
	; occurs
	;

	dump	param1
	dump	param2
	dump	param3
	end	(param1 + param2 + param3)

: "remote_end"
	;
	; To call this function remotely (set SECRET with -na switch):
	;
	; $ telnet localhost 2109
	;   SECRET remote_end
	;
	; Exit code returned to caller is 123
	;

	exit	(123)

Remote control can be done using telnet, or whatever client which is capable to send plain text to TCP socket. There is remotetool available in engine/tools directory which can be used for the job. It can be compiled by typing gmake remotetool in that directory. remotetool supports encrypted connections with GnuTLS or OpenSSL.

When not using supplied remotetool, the format of remote control string to send to program consists of at least two words separated by whitespace. First is the auth secret which must match to remote controlled program's --auth_secret string, and the second word is the function name to call. If function needs parameters, they are passed from third to n'th words. Numeral parameters needs type definition in front of them, separated by a colon. Needless to say, they must match what ever type of number function is expecting. In this example, the type of the parameters does not really matter.

To call remote_test function with three different type of numbers, pass program's remote control port something like:

SECRET remote_test int:1 uint:2 float:3.3

If remotetool is in use, just give function name and its parameters leaving out the secret, as remotetool takes care of sending the secret along with remote function call. Example:

$ remotetool -na SECRET -n6 -nh localhost -np 2109
  remote_test int:1 uint:2 float:3.3 <enter>
  remote_end <enter>

Alternatively, remote function call can be echoed to remotetool:

$ echo 'remote_end' | remotetool -na SECRET -n6 -nh localhost -np 2109

If remote function returns something, it will echo back to remote controller. List of supported number types are:

int8
int16
int32
int64
int128, might not be supported on every platform

uint8
uint16
uint32
uint64
uint128, might not be supported on every platform

char
short
int
long

uchar
ushort
uint
ulong

float
double