Programming Information for WiNRADiO G305 Series Receivers

The G305 receivers API is implemented as a single 32-bit or 64-bit library WRG305API.DLL, depending on the operating system. It provides functions for all communication with all types of G305 receivers. It can be used by any 32-bit application under Windows 98, ME, 2000, XP and Vista and by 64-bit applications under 64-bit Windows XP and Vista. On 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.

Open

Opens a radio device by its serial number to allow you 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 doesn't exist or couldn't 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. Multiple threads of the same application can access the same device at any time.

See Also

GetRadioList

OpenRadioDevice

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 doesn't 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. Multiple threads of the same application can access the same device at any time.

CloseRadioDevice

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

GetRadioList

The GetRadioList function returns information about all G305 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 unalocated G305 device present in the system.

BufferSize

The size of the lpRadioInfo buffer. The function doesn't 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 G305 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

Opening the device example

GetSignalStrengthdBm

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 aproximated value of the signal strength in dBm * 10 (i.e. the value is given in tenths of dBm).

Remarks

In order to have valid signal strength values for external receivers connected through USB, the CodecStart function must be called. The signal strength readings are sent to the PC only while the IF input stream is active.

GetRawSignalStrength

The GetRawSignalStrength function returns the "raw" signal strength value. This is made available for compatibility with 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>.

Remarks

In order to have valid signal strength values for external receivers connected through USB, the CodecStart function must be called. The signal strength readings are sent to the PC only while the IF input stream is active.

GetLastSSdBm

The GetLastSSdBm function returns the last measured strength of the radio signal in dBm. Useful during block scanning.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The aproximated value of the signal strength in dBm * 10 (i.e. the value is given in tenths of dBm).

Remarks

In order to have valid signal strength values for external receivers connected through USB, the CodecStart function must be called. The signal strength readings are sent to the PC only while the IF input stream is active.

GetLastRawSS

The GetLastRawSS function returns last measured RAW signal strength value. Useful during 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>.

Remarks

In order to have valid signal strength values for external receivers connected through USB, the CodecStart function must be called. The signal strength readings are sent to the PC only while the IF input stream is active.

GetInternalRSSI

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.

Remarks

In order to have valid signal strength values for external receivers connected through USB, the CodecStart function must be called. The signal strength readings are sent to the PC only while the IF input stream is active.

SetFrequency

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_INFO2 structure that can be retrieved with the GetInfo or GetRadioList function.

See Also

GetFrequency

SetFreqAsync

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_INFO2 structure that can be retrieved with the GetInfo or GetRadioList function.

See Also

WaitFreqAsync

WaitFreqAsync

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

SetFreqAsync

SetIF2Frequency

The SetIF2Frequency function sets the center frequency of the last IF signal.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iFreq

Specifies the IF2 frequency. It can be either positive or negative, negative values causing an IF2 spectrum inversion

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetIF2Frequency

SetAtten

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

GetAtten

SetRFAmp

The SetRFAmp function activates or deactivates the RF preamplifier. It is used to improve receiving 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

GetRFAmp

SetPower

The SetPower function switches the device's 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's power is on, otherwise if FALSE, the radio's power is off.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetPower

SetAGC

The SetAGC function sets the AGC value for given receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iAGC

AGC value <0,3> - off, slow, medium or fast.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetAGC

SetIFGain

Sets IFGain value for the specified receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iIFGain

IFGain value <0,100> to be set.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetIFGain

SetFMW

The SetFMW function switches the demodulator software input (either sound card or internal codec depending on the model) between narrow band IF output and the optional FMW module audio output.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

FMW

If TRUE the FMW module audio output is selected.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetFMW

SetRefClock

Specifies the reference clock frequency and allows switching between internal and external 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 the internal reference clock is used.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetRefClock

GetFrequency

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

SetFrequency

IsSpectrumInverted

Checks if the receiver IF spectrum for narrow band demodulation is inverted.

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 narrow band IF spectrum is inverted for the currently tuned frequency. Otherwise FALSE is returned.

GetIF2Frequency

The GetIF2Frequency function retrieves the current last IF frequency.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The current last IF frequency in Hz. If the handle is invalid, 0 is returned instead.

See Also

SetIF2Frequency

GetAtten

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

SetAtten

GetRFAmp

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

SetRFAmp

GetPower

The GetPower function returns whether the receiver's 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's power is on, otherwise it returns FALSE if it is off.

See Also

SetPower

GetAGC

The GetAGC function returns current AGC value of radio device.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The current AGC value if successful, otherwise -1 is returned.

See Also

SetAGC

GetIFGain

Retrieves the IFGain value 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 the IFGain value. Otherwise -1 is returned.

See Also

SetIFGain

GetFMW

The GetFMW function returns information about the demodulator software input source.

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 FMW audio output is the currently selected source.

See Also

SetFMW

GetLock

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.

GetRefClock

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

SetRefClock

BlockScan

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Freqs

The array of frequencies to be scanned.

Count

The count of frequencies to be scanned.

StopSquelchRaw

The value of the RAW signal strength at which the scanning should stop.

FeedbackTime

The time interval in ms after which G3 API sends you scanned data.

WinHandle

The window handle to which the scanned data will arrive.

Msg

The constant for window mesage that will bring the scanned data.

Return Value

If the scan started, the return value is TRUE. Otherwise FALSE is returned.

Remarks

Scanned RAW signal strength values are written back to the Freqs buffer. Each frequency in the Freqs buffer is replaced by appropriate RAW value. Parts of this buffer are sent to the appplication after Feedback time interval expires. The block scanning automatically ends when scanned RAW signal strength value rises StopSquelchRaw parameter. The scanned RAW values are sent using window message Msg to the window procedure of the window handle WinHandle with buffer pointer as WParam and buffer length as LParam.

For USB connected receivers the codec streaming must be active for block scanning to be used, otherwise no signal strength information is available and block scanning will always return 255 as raw level and will do just 1 step per second. For more information see CodecStart.

See Also

Block scanning example

StopBlockScan

Stops block scanning if it has been started.

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.

See Also

Block scanning example

PauseBlockScan

Pauses block scanning, if it has been started.

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.

See Also

Block scanning example

ResumeBlockScan

Resumes block scanning if it has been paused.

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.

See Also

Block scanning example

GetInfo

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.

IsBusy

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.

GetPath

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

GetPath2

GetPath2

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

GetPath

IsDeviceConnected

Checks if the receiver is still connected to the computer. It is significant only for external receivers while the internal ones 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.

IsUSVersion

Checks if the receiver is a special US version one.

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 receiver is a special US version one. Otherwise FALSE is returned.

SetLEDFlashPattern

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.

InvertSpectrum

Function for applying spectrum inversion to a buffer of IF samples. The spectrum inversion is applied according to the other receiver setting that might affect it. The resulting samples are written over the samples in the input buffer.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Samples

Pointer to the buffer of input/output samples.

SamplesNum

The number of samples in the input/output buffer.

SamplingRate

The sampling rate of the samples to be processed.

BitsPerSample

The size of the input and output samples in bits.

Force

Flag to force having the final spectrum inverted.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

Remarks

The final spectrum may be inverted or not when compared to the spectrum of the input samples. By evaluating the possible factors that affect spectrum inverting in RF hardware the function decides what kind of processing is required. The input samples are always passed through the processing code in order to insure when tuning with just 1Hz around spectrum inverting frequencies there is no undesired glitch in the resulting IF stream.

Sea Also

IF codec streaming example

SetFreqPipelined

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 is built from 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 streangth reading to end.

Sea Also

Pipelined scanning example

GetSSPipelined

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

SetFreqPipelined

CodecStart

Function for starting the IF streaming input from a USB connected external receiver.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

CallbackFunction

Application provided function to be called by the API when there is new data received through the IF stream from the receiver

CallbackTarget

Argument to be passed to the application defined callback function

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

Remarks

The provided callback function is called from a separate thread that waits for codec samples sent by the receiver and code to prevent resources accessing must be included in the application if necessary. If no callback function is provided (NULL is passed for the argument value), the codec streaming is still functional and CodecRead can be periodically called to check for new IF data. The internal IF data queue is large enough for 2 seconds buffering before unread data is overwritten.

Sea Also

IF codec streaming example

CodecStop

Function for stopping the IF streaming input from a USB connected external 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 TRUE. Otherwise FALSE is returned.

Sea Also

IF codec streaming example

CodecRead

Function for reading IF data received from the receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Buf

Destination buffer into which the IF data should be written by the API

Size

The size of the destination buffer

Return Value

The function returns the number of bytes written into the destination buffer. If no data was available it returns 0.

Remarks

There is no guarantee that the data received from the receiver is aligned at sample level and, thus, the application should be able to handle fragmented samples (one byte of the 16-bit samples can be read through a first CodecRead call and the other when new data is received from the receiver).

Sea Also

IF codec streaming example