The G303 receivers API is implemented as a single 32-bit library WRG303API.DLL. It provides functions for all communication with all types of G303 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.
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
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.
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 G3GetRadioList function returns information about all G303 devices that can be opened.
This function is deprecated. Please consider using the new GetRadioList function instead.
C/C++ declaration
Delphi declaration
Parameters
lpRadioInfo
The buffer for an array of OLD_RADIO_INFO structures. It will contain an OLD_RADIO_INFO structure for each unalocated G303 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.
Return Value
The count of unallocated G303 devices present in the system. This value can be greater than the real number of OLD_RADIO_INFO structures written to the buffer if the buffer is too small.
The G3GetRadioList2 function returns information about all G303 devices that can be opened. It is a more flexible implementation than in G3GetRadioList allowing future additions to the RADIO_INFO structure while the applications would not need updating.
This function is deprecated. Please consider using the new GetRadioList function instead.
C/C++ declaration
Delphi declaration
Parameters
lpRadioInfo
The buffer for an array of RADIO_INFO structures. It will contain a RADIO_INFO structure for each unalocated G303 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 G3GetRadioList2 with the size of the structure for each available receiver.
Return Value
The count of unallocated G303 devices present in the system. This value can be greater than the real number of RADIO_INFO structures written to the buffer if the buffer is too small.
The GetRadioList function returns information about all G303 devices that can be opened. It is a more flexible implementation than G3GetRadioList and G3GetRadioList2 allowing future additions to the RADIO_INFO2 structure while the applications would not need updating. The returned structure content is a lot cleaner than with the older functions and it also includes clean support for 64-bit code.
C/C++ declaration
Parameters
lpRadioInfo
The buffer for an array of RADIO_INFO2 structures. It will contain a RADIO_INFO2 structure for each unalocated G303 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 G303 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 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 tenth 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.
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.
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.
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.
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.
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 G3GetRadioList 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 G3GetRadioList 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 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
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
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
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
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 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
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
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
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
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
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
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
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
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 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.
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 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
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
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