The G39WSB receivers API is implemented as a single 32-bit library WRG39WSBAPI.DLL. It provides interfacing functions for all types of G39WSB receivers. It can be used by any 32-bit application under Windows 2000, XP, Vista, 7, 8 and 10 and by 64-bit applications under 64-bit Windows XP, Vista, 7, 8 and 10. In 64-bit Windows versions there is also support for 32-bit applications but restrictions may be required in multi-threaded applications due to possible race conditions between threads.
The API consists of two independent sets of functions. The first, a low-level set of functions, covers all hardware related functionality, including basic on-board DSP accessing. The second set of functions offer full demodulating features. In order to be able to use these higher-level functions the InitializeDemodulator function must be called first.
Opens a radio device by its serial number to be able to control the device using the other API functions.
C/C++ declaration
Delphi declaration
Parameters
ID
Radio device serial number that you would like to open. If NULL is specified, a demo receiver will be opened. The serial number is a null-terminated string.
Return Value
Returns a handle to the device that has to be used to call all the other API functions (hRadio). If zero is returned, the specified device does not exist or could not be opened.
Remarks
If you would like to have more than one application use the same device, you will have to close the device when you have finished using it, to allow other applications to access the device. For Win32 applications, multiple threads can access the same device at any time.
See Also
Opens a radio device by its index to allow you to control the device using the other API functions.
C/C++ declaration
Delphi declaration
Parameters
iDeviceNum
Radio device number that you would like to open from 1 to 255. If zero is specified, it will open the next available device.
Return Value
Returns a handle to a device that has to be used to call all the other API functions (hRadio). If zero is returned, no devices were available to open or the specified device does not exist.
Remarks
If you would like to have more than one application use the same device, you will have to close the device when you have finished using it to allow other applications to access the device. For Win32 applications, multiple threads can access the same device at any time.
Closes a radio device that was previously opened, and allows another program to access the radio device.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to the radio device to close, returned by OpenRadioDevice or Open.
Return Value
If the function succeeds, the return value is TRUE, otherwise the return value is FALSE (invalid handle, or has already been closed).
The GetRadioList function returns information about all G39WSB devices that can be opened.
C/C++ declaration
Parameters
lpRadioInfo
The buffer for an array of RADIO_INFO2 structures. It will contain a RADIO_INFO2 structure for each unallocated G39WSB device present in the system.
BufferSize
The size of the lpRadioInfo buffer. The function does not write all structures if the buffer is too small.
Infosize
Pointer to an integer value that will be written by GetRadioList with the size of the structure for each available receiver.
Return Value
The count of unallocated G39WSB devices present in the system. This value can be greater than the real number of RADIO_INFO2 structures written to the buffer if the buffer is too small.
See Also
The DSP must be initialized before any signal processing, including signal strength measurement, can commence. When initializing the demodulator, the full path to a valid calibration table data file may be provided if the signal strength measurement should be calibrated. If calibrated measurement is not required, the passed pointer should be NULL.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
CalFilePath
Pointer to the file containing the calibration data for the receiver in use
Return Value
The returned value is TRUE if the demodulator could be initialized and FALSE if not.
Remarks
Once the demodulator is initialized, all handles to the receiver must be closed in order to allow a full re-initialization.
See Also
Demodulator initializing and using example
The GetSignalStrengthdBm function returns the strength of the radio signal in dBm received by the radio device.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The aproximate value of the signal strength in dBm. If the demodulator is properly initialized and a calibration file is provided, the resulting signal strength is calibrated.
See Also
The GetRawSignalStrength function returns the "raw" signal strength value. This is made available for compatibility with legacy applications which expect the signal strength value to be from 0 (min signal level) to 255 (max signal level). The formula for this is:
SignalStrength_RAW = 255*(SignalStrength_dBm + 1300)/1000
This means that -130dBm corresponds to 0 and -30dBm corresponds to 255 of "raw" value.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
RAW signal strength in the interval <0,255>.
The GetLastSSdBm function returns the last measured strength of the radio signal in dBm. This is useful for block scanning.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The aproximate value of the signal strength in dBm.
The GetLastRawSS function returns last measured RAW signal strength value. Useful for block scanning.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
RAW signal strength <0,255>.
The GetInternalRSSI function returns a combination of the RSSI and AGC values read from the receiver hardware.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
AGC value in the upper 16 bits of the result and RSSI value in the lower 16 bits of the result.
The SetFrequency function sets the frequency the device is to be tuned to.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
dwFreq
Specifies the frequency to tune to receiver to.
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
Remarks
The lower and upper limits are specified in the dwMinFreq and dwMaxFreq fields respectively in the RADIO_INFO structure that can be retrieved with the GetInfo or GetRadioList function.
See Also
The SetFreqAsync function starts the sequence of hardware commands that sets the frequency the device is to be tuned to. In order to insure the sequence has been executed and that the hardware is properly tuned, WaitFreqAsync function must be called.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
dwFreq
Specifies the frequency to tune to receiver to.
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
Remarks
The lower and upper limits are specified in the dwMinFreq and dwMaxFreq fields respectively in the RADIO_INFO structure that can be retrieved with the GetInfo or GetRadioList function.
See Also
The WaitFreqAsync function waits for the end of a receiver tunning started by a SetFreqAsync call.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
See Also
The SetAtten function activates or deactivates the RF input attenuator. It is used to prevent overloading of the receiver with strong signals.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
fAtten
If TRUE, the RF attenuator is on, otherwise if FALSE, the RF attenuator is off (more sensitive).
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
See Also
The SetRFAmp function activates or deactivates the RF preamplifier. It is used to improve reception of weak signals.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
fRFAmp
If TRUE, the RF preamplifier is on (more sensitive), otherwise if FALSE, the RF preamplifier is off.
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.
See Also
The SetPower function switches the device power on or off. This function can be used to power down the receiver in portable applications to conserve battery power.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
fPower
If TRUE, the radio power is on, otherwise if FALSE, the power is off.
Return Value
If this function succeeds, the return value is TRUE. If it fails, the return value is FALSE.
See Also
Specifies the reference clock frequency and allows switching between internal and external clock references.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
RefClock
The frequency of the external reference clock. If 0 is specified, internal reference clock is used.
Return Value
If the function succeeds, the return value is TRUE, else the return value is FALSE.
See Also
The GetFrequency function retrieves the frequency the receiver is tuned to.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The current receiver frequency in Hz. If the handle is invalid, 0 is returned instead.
See Also
The GetAtten function returns the RF input attenuator setting.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
GetAtten returns TRUE if the RF attenuator is on, otherwise it returns FALSE if it is off.
See Also
The GetAtten function returns the RF input preamplifier setting.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
GetRFAmp returns TRUE if the RF preamplifier is on, otherwise it returns FALSE if it is off.
See Also
The GetPower function returns whether the receiver power is on or off.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
Returns TRUE if the receiver power is on, otherwise it returns FALSE if it is off.
See Also
Retrieves the PLLs lock status.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
GetType
This argument is reserved for future extensions.
Return Value
If the function succeeds, the return value is a combination of the PLLs lock bits. Otherwise 0 is returned.
Retrieves the current reference clock frequency.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
If the function succeeds, the return value is current reference clock frequency, else the return value is 0xFFFFFFFF.
See Also
Retrieves the RADIO_INFO2 structure of the receiver.
C/C++ declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
info
The pointer to an empty RADIO_INFO2 structure. It must have bLength member initialized to sizeof(RADIO_INFO2).
Return Value
If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.
Remarks
For backward compatibility, depending on the value of the bLength field in the passed structure, also OLD_RADIO_INFO and RADIO_INFO structures are supported.
Checks the receiver whether it is ready to accept commands.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
If the receiver is currently busy TRUE is returned. Otherwise the function returns FALSE.
Retrieves the system pathname of the receiver.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Pathname
Pointer to the buffer that will be filled by the function with the device pathname.
size
The size of the destination buffer that must not be exceeded by the function.
Return Value
If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.
See Also
Retrieves the system pathname of the receiver.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
If the function succeeds, the return value is a pointer to the receiver pathname. Otherwise NULL is returned.
See Also
Checks if the receiver is still connected to the computer. It is used only for external receivers (WR-G39WSBe); internal models (WR-G39WSBi) will always be reported as connected.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.
Sets the LED flashing pattern for the external receivers to the specified value.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Pattern
The pattern value as an 8-bit mask for 8 time slots; for each of those slots, a bit value of 1 corresponds to LED turned on and a bit value of 0 corresponds to LED turned off.
Return Value
If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.
Function for queueing a frequency for pipelined scanning sequence.
C/C++ declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
dwFreq
The frequency to be queued
IsFirst
Flag to be set to TRUE when the first frequency of the pipelined scanning sequence and FALSE for all other frequencies
Settling
AGC settling time in ms to be used when measuring the signal strength
Return Value
If the function succeeds, the return value is 0.
Remarks
A pipelined scanning sequence consists of calls of SetFreqPipelined and GetSSPipelined functions. The first function queues the frequencies to be scanned and the second one waits for ending the current step and returns the signal strength related readings. A pipelined sequence starts with two SetFreqPipelined calls, with the first and the second frequencies to be measured, and continues with alternating calls of GetSSPipelined and SetFreqPipelined. The signal strength reading corresponds to the frequency pipelined one steps before as the reading is immeditely followed, into the driver, by starting the tuning to the last pipelined frequency. This approach allows the application to use for other purposes the time normally spent waiting for the tuning and signal strength reading processes to end.
Sea Also
Function for reading the signal strength during pipelined scanning sequences.
C/C++ declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
SS
Pointer to the signal strength variable to be written on success; if NULL the value is discarded
RawSS
Pointer to the raw signal strength variable to be written on success; if NULL the value is discarded
RSSI
Pointer to the RSSI variable to be written on success; if NULL the value is discarded
AGC
Pointer to the AGC loop gain variable to be written on success; if NULL the value is discarded
Return Value
If the function succeeds, the return value is 0.
Sea Also
Function for setting the final audio bandwidth. This is intended for audio monitoring only (for the convenience of the operator, to assist in locating signals, etc., not for the actual sonobuoy output intended for analysis).
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
BW
The audio bandwidth in Hz
Return Value
The return value is TRUE if the audio bandwidth can be set and FALSE if not.
See Also
GetAudioBandwidth
Demodulator initializing and
using example
Function for setting the fixed audio gain. This value is used to provide a fixed audio amplification when the software AGC is disabled.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Gain
The fixed audio gain
Return Value
The return value is TRUE if the fixed audio gain can be set and FALSE if not.
See Also
GetAudioGain
Demodulator initializing and
using example
Function for setting the audition volume. It can be any value between 0 and 31.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Volume
The audition volume
Return Value
The return value is TRUE if the audition volume can be set and FALSE if not.
See Also
GetVolume
Demodulator initializing and
using example
Function for getting the current audio bandwidth.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The return value is the current audio bandwidth in Hz.
See Also
SetAudioBandwidth
Demodulator initializing and
using example
Function for getting the current fixed audio gain (for monitoring only).
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The return value is the current fixed audio gain.
See Also
SetAudioGain
Demodulator initializing and
using example
Function for getting the current audition volume.
C/C++ declaration
Delphi declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
Return Value
The return value is the current audition volume.
See Also
SetVolume
Demodulator initializing and
using example
Function for activating the IF and/or audio streams callback functions while the demodulator is active.
C/C++ declaration
Parameters
hRadio
Handle to a radio device that was returned by OpenRadioDevice or Open.
IFH
Application provided function to be called by the API when there is new data received through the IF stream from the receiver; if NULL IF streaming is no longer sent to the application. G39WSB does not provide IF stream so this parameter should be set to NULL.
IFT
Argument to be passed to the IFH application defined callback function. G39WSB does not provide IF stream so this parameter should be set to NULL.
AudioH
Application provided function to be called by the API when there is new data received through the audio stream from the receiver; if NULL, audio streaming is nolonger sent to the application
AudioT
Argument to be passed to the AudioH application defined callback function
Return Value
The return value is TRUE if the streams callback functions could be properly set, or FALSE if not.
Remarks
For demodulators that provide more channels (such as ISB), the channels are provided in the audio stream with alternating samples.
Both callback functions should be like this:
The arguments are the following:
Target - application specified value when the callback functions are registered;
Buf - buffer with the 16-bit signed integer samples read from the DSP memory;
Size - size of the buffer holding the samples in bytes;
SamplingRate - samples sampling rate.
The buffers sent to the application-defined callback functions will always have the same size and will always contain the same number of samples or sample sets. They will never contain only fractions of samples or sample sets.
SeeAlso
Demodulator initialization and usage example
This function gets the sonobuoy channel frequency. The channel number can be any value between 1 and 99.
C/C++ declaration
Delphi declaration
Parameters
Channel
The sonobouy channel number.
Return Value
The return frequency is the frequency associated with the required channel.