Communication between Spectrum Lab and other programs

Introduction

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.

The integrated HTTP server

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 (running in your browser) to do whatever you want
• a custom user interface can be created in the form of HTML documents

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 some examples (in 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:

http://127.0.0.1:80

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

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-TCP/IP-Server, take care not to use the same IP port number for these function. 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.

Communication using WM_COPYDATA messages

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

Communication between windows programs using WM_COPYDATA messages

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

• write your own application which shall receive "something" from Spectrum Lab
• write your own application which shall "control" Spectrum Lab (because there is something you cannot achieve with SL alone).

No idea what such an application could be ? You can send any interpreter command which is mentioned in the SL manual in a WM_COPYDATA message, so you could..

• send a command to SL to produce a screenshot instantly, because only your program knows that "something interesting" has just happened,
• send a command to SL to start logging, stop logging, start/stop the spectrum analyzer, etc etc,
• ask SL for the current amplitude in a given frequency range, tell you the current noise level, and calculate a lot of other values.

The other way around, you can also

• send commands from SL to other programs (if they are designed for it), using the interpreter's "send"-command.
• exchange audio streams via WM_COPYDATA messages (not recommended, though... better use internet protocols)

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

Module- and Command Identifiers in Spectrum Lab

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:

A practical example: To stop the spectrum analyser, send the following message..

 COPYDATASTRUCT cds;
 // Set module ID "CL"  + command ID "EC" :
 cds.dwData = ('C')+((DWORD)'L'>>8)+((DWORD)'E'>>16)+((DWORD)'C'>>24);
 cds.lpData = "spectrum.pause=1";        // command sent to SpecLab's interpreter
 cds.cbData = strlen((char*)cds.lpData); // count of bytes in data block
 SendMessage(hDestWindow,WM_COPYDATA,(WPARAM)MyWindowHandle,(LPARAM)&cds);

How to send audio streams per WM_COPYDATA is explained in the next chapter.

See also: Spectrum Lab's main index, Spectrum Lab's interpreter commands, interpreter functions (in separate documents).

Sending uncompressed Audio via WM_COPYDATA

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

The first use for this principle was the "winamp-to-SpecLab" plugin; the WM_COPYDATA method was chosen for simplicity.

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.

See also: Spectrum Lab's main index, Spectrum Lab's interpreter commands, interpreter functions (in separate documents).