Some sophisticated applications required the control of Spectrum Lab by other
programs, and vice versa (Spectrum Lab controlling other programs). This
chapter describes the two possibilities: using the tiny HTTP server which
is integrated in SpecLab, and a system using windows messages. The latter
may be a bit simpler if both programs run on the same machine.

For remotely controlled operation of Spectrum Lab, you can use the integrated
HTTP server. This has the following advantages:

the remote control client is just an ordinary web browser

you can use Javascript (in a web browser) to control SL and/or analyse data;
which is more flexible than SL's built-in 'Conditional Actions'

a custom user interface can be created in the form of HTML documents

the integrated HTTP server can be used as an audio stream server (for a limited number of clients)

other applications can retrieve data from SL via network (HTTP, JSON); for example DL2ALF's famous AirScout

Downside: Sending HTTP requests, and receiving the response (from the client's
point of view) is not as fast as exchanging WM_COPYDATA messages locally
(as explained in the next chapter). Details about the HTTP server inside
SL can be found in the server_pages
directory after the installation. There are some examples (HTML with javascript)
in the server_pages directory too. If you read this document while SpecLab
runs on the same machine, with the server enabled, try this link to check
the remote control examples:

(127.0.0.1 is a dummy IP address of the local machine, and 80 is the default
port number for HTTP = hypertext transport protocol )

To configure the built-in HTTP server, select "Options"..."Configure and
supervise HTTP Server" in SL's main menu.

Config tab

Network name of this machine : ( shows the PC's name, as
seen in the LAN (local area network) )

Local IP Address (of this PC) : ( also just a display for
convenience, can be used as browser address )

HTTP Server Port (default=80) : (enter the IP port number under
which the server shall be accessed in the LAN)

Root directory for HTTP Server :
( this is the name of the folder on your harddisk, where the web server's
HTML pages, Javascript, and other files are stored.
The HTTP server also uses this directory to store temporary files,
like JPEGs with the current spectrogram, etc)

[ ] allow remote control
("exec") (allows remotely calling the interpreter's
"exec" command )
Should only be used in a LAN (not if the server is accessable through the
internet),
because "exec" can be used to launch OS commands !

Max number of simultaneous connections, Update images only when older than
X seconds, Bandwidth limit...:
These parameters should speak for themselves. They can be used
to limit the bandwidth
when this HTTP server is used as a 'real' web server (which
can be accessed from the world wide web).

To let others remotely look at the current spectrogram through their web
browsers, it's enough to enable the HTTP server (the first option
set, the other two not set). By default, after installing Spectrum Lab, this
option (and all other HTTP-server related options) are in their safest state,
which means they are 'off' (=not enabled).
To let others remotely adjust the spectrogram's display and brightness, the
option 'allow _iproc.html' + '_ifunc.html' must be set, too. Technically,
this option allows to call interpreter functions, and interpreter procedures
through two special html pages named '_iproc.html' = remote procedure call,
and '_ifunc.htm' = remote function calls. An example for remote control
via Javascript is in the sample server pages ('server_pages/controls.htm').
A few 'potentially dangerous' interpreter commands can not be called from
the HTTP server even if this option is set - see next paragraph.
The option allow remote control ("exec") should only be used in a
LAN, because "exec" can be used to launch OS commands ! Do not set this option
if the server is accessable through the internet. This (potentially
dangerous) option is always off by default, furthermore it is only usable
along with the two other options (because from Javascript, "exec" can only
be invoked through the '_iproc.html' page mentioned above. Interpreter commands
which, from he HTTP server, can only be called with this option
are: exec,
send,
fopen/fread/fwrite .

Again, details about SL's integrated HTTP server, and the 'things you can
do with a bit of Javascript' can be found in the
server_pages (the 'readme'
is intended for developers, please read it) .

Note: If -besides the HTTP server- you also use the
Audio-via-raw-TCP/IP-Server,
take care not to use the same IP port number for these functions. Both servers
use the IP address of the machine on which they run, so you must use a different
port number for the HTTP server and the audio server. BTW, the default port
number for an HTTP server is 80.

As mentioned in the previous chapter, any of SL's interpreter functions
can also be invoked from Javascript running in a web browser
(even remotely, i.e. in a web browser which runs on a different machine, tablet PC, smartphone, etc).
Details are in the "readme"-file in Spectrum Lab's HTTP server pages directory,
which you will find on your harddisk after installing it.

For this task, a simple communication protocol which uses WM_COPYDATA messages
was implemented. Detailed information about the protocol (for fellow programmers)
can be found on the author's website, search for the file yhf_comm_info.htm,
titled

(If the link fails due to server problems, copy the title into
your favourite search engine - you may find the file on my "backup" site
too)

I didn't include it in the Spectrum Lab documentation because it is used
in other projects too (and there shall not be outdated copies of that document
all over the place.. ;-) . So follow the above link for the latest up-to-date
description of DL4YHF's "YHF_COMM" protocol if you are considering to...

All this is possible ... but, due to the unavoidable time lag in the windows
message processing system, this message system is not suitable for "tough"
real-time operation. Expect a delay of some milliseconds until the command
you sent to SL has been executed, and your program receives the result message.

All you have to know -in addition to the general message protocol- are the
MODULE-ID's and COMMAND-ID's which are used to invoke the interpreter commands
and -functions through WM_COPYDATA messages. The next chapter gives an overview
of these values.

To send a windows message to Spectrum Lab, you must know its windows handle.
This can be found with a WinAPI function called "FindWindow". For convenience,
don't search for the window's title (which may change depending on the version),
use the window's class name (lpClassName, which is the first parameter for
"FindWindow"). The class name of Spectrum Lab's main window is
TSpectrumLab. But this is not the only possibility:
To support communication between two instances of SpecLab running on the
same PC, the program now uses the following additional names (for programmers:
SL creates an extra invisible window for this purpose, which has a unique
class name) :

The first instance running on a PC receives WM_COPYDATA messages directed
to "SpecLab1"

The second instance running on a PC receives WM_COPYDATA messages directed
to "SpecLab2"

The third instance running on a PC receives WM_COPYDATA messages directed
to "SpecLab3"

The old class name "TSpectrumLab" (for the main window) remains for backward
compatibility.

Hint:

For testing purposes, open the "Command Window" in Spectrum Lab, and let
it show all received and sent traffic in the message list (in the command
window: "Options".."show Inter-Application Comm's").

The third and fourth character in the message's dwData parameter contain
the "command". They are specific to the "module ID". Here are the most important
"command IDs" for the Command Line Interpreter built inside DL4YHF's Spectrum
Lab:

Note: If possible, do not use this feature, because it is not available under
non-windows operating systems; and both sender and receiver must be running
on the same PC. Better use one of the UDP or TCP/IP-based methods mentioned
here : They allow sending
audio over a local network, and even work between PCs running different operating
systems (like Windows and Linux).

As explained in the previous chapter, the four bytes (here: four characters)
in the dwData parameter of the WM_COPYDATA message must contain the "module
identifier" (here: "AU" for audio data), followed by the "command identifier"
(here: "SD" = stream data).

Below is the sourcecode of a C function which sends a block of audio samples
through a WM_COPYDATA message (actually taken from audiomsg.c). The
T_AudioMsgBuffer structure contains the audio block, and some information
about the audio stream (like the number of channels, the sampling rate, etc).
It is defined in the file audiomsg.h which is available in the archive
"SoundUtlSources.zip".
The same data structures are used when sending audio streams via UDP or TCP/IP.
An introduction to the sound utilities is here.
Details, header files, and "C" sourcecodes of a simple test application which
uses WM_COPYDATA to send a test signal to Spectrum Lab are included in the zipped archive.