Programming Information for WiNRADiO G31DDC HF receiver.

The G31DDC API SDK is implemented as a dynamic library (libg31ddcapi.so) for 32-bit i386 and 64-bit x86_64 platforms. It provides object-oriented and non-object-oriented interfaces to control the G31DDC device. This document describes the non-object-oriented interface. The libg31ddcapi.so library exports several functions that make it possible to control G31DDC receivers.

The API is not fully thread-safe so preferably it should be used in single-threaded applications. It can be used in multi-threaded applications as well, but with some care: One G31DDC receiver can be controlled from a single user thread only.

A C/C++ header file g31ddcapi.h is a part of the SDK.

Block diagram of G31DDC processing chain

Simplified block diagram of G31DDC processing chain
Attenuator MW filter ADC Noise blanker IF DDC1 frequency shift DDC1 DDC1 stream DDC2 frequency shift DDC2 DDC2 stream Noise blanker Demodulator filter Signal level Notch filter Gain Pre-processed DDC2 stream Demodulator Audio gain Audio stream Audio filter Filtered audio filter DDC2 frequency shift DDC2 DDC2 stream Noise blanker Demodulator filter Signal level Notch filter Gain Pre-processed DDC2 stream Demodulator Audio gain Audio stream Audio filter Filtered audio filter DDC2 frequency shift DDC2 DDC2 stream Noise blanker Demodulator filter Signal level Notch filter Gain Pre-processed DDC2 stream Demodulator Audio gain Audio stream Audio filter Filtered audio filter Simplified block diagram of G31DDC processing chain

Using WiNRADiO G31DDC API

Loading API

The lib35ddcapi.so library can be loaded to the application using the dlopen function of dynamic linking loader (link with -ldl). After the library is loaded, it is necessary to get addresses of exported functions. When the API is no longer required in the memory, the dlclose function can be used to unload the API. Before the dlclose is called, all the handles to G31DDC devices returned by the OpenDevice function must be closed by the CloseDevice function, otherwise the application can be placed into an unpredictable state.

The following source code shows how to load the API.

 
#include <stdio.h>
#include <dlfcn.h>
#include "g31ddcapi.h"

G31DDC_OPEN_DEVICE OpenDevice;
G31DDC_CLOSE_DEVICE CloseDevice;
void *API;

int main(void)
{  
    //Loading the API
    API=dlopen("libg31ddcapi.so",RTLD_LAZY);

    if(API!=NULL)
    {
        //Retrieving addresses of used API functions
        OpenDevice=(G31DDC_OPEN_DEVICE)dlsym(API,"OpenDevice");
        CloseDevice=(G31DDC_CLOSE_DEVICE)dlsym(API,"CloseDevice");

        //Here place code that uses the API

        dlclose(API);
    }
    else
    {
        //If the dlopen fails
        printf("Failed to load libg31ddcapi.so. %s\n",dlerror());
    }
    
    return 0;
}

List of available G31DDC devices

The G31DDC API provides the GetDeviceList function which returns a list of available G31DDC devices which can be opened by the OpenDevice function.

The following source code produces a list of serial numbers of available G31DDC devices.

#include <stdio.h>
#include <stdint.h>
#include <dlfcn.h>
#include <stdlib.h>
#include <errno.h>
#include "g31ddcapi.h"

G31DDC_GET_DEVICE_LIST GetDeviceList;
void *API;

int main(void)
{
 uint32_t Count,i,ItemSize;
 G31DDC_DEVICE_INFO *DeviceList;

    //Loading the API
    API=dlopen("libg31ddcapi.so",RTLD_LAZY);

    if(API!=NULL)
    {
        //Retrieving address of the GetDeviceList function
        GetDeviceList=(G31DDC_GET_DEVICE_LIST)dlsym(API,"GetDeviceList");

        //Retrieving number of available devices        
        if(GetDeviceList(NULL,0,&Count,&ItemSize))
        {
            if(Count!=0)
            {
                //Allocating memory for device information structures
                DeviceList=(G31DDC_DEVICE_INFO*)malloc(Count*sizeof(G31DDC_DEVICE_INFO));
                                               
                if(DeviceList!=NULL)
                {
                    //Retrieving information about available devices                                        
                    if(GetDeviceList(DeviceList,Count*sizeof(G31DDC_DEVICE_INFO),&Count,&ItemSize))
                    {
                        printf("Available G31DDC devices count=%d:\n",Count);
            
                        for(i=0;i<Count;i++)
                        {
                            printf("%d. SN: %s\n",i,DeviceList[i].SerialNumber);
                        }
                    }
                    else
                    {
                        printf("GetDeviceList failed with error %d.\n",errno);
                    }
        
                    free(DeviceList);
                }
                else
                {
                    printf("Out of memory\n");
                }
            }
            else
            {
                printf("No available G31DDC device found.\n");
            }
        }
        else
        {
            printf("GetDeviceList failed with error %d.\n",errno);
        }

        dlclose(API);
    }
    else
    {
        printf("Failed to load libg31ddcapi.so. %s\n",dlerror());
    }

    printf("Press enter to exit\n");
    getchar();
    
    return 0;
}

Opening G31DDC device

G31DDC device has to be open before it can be controlled. The API provides the OpenDevice function to open the device.

The following source code shows how to open the first available G31DDC device.

#include <stdio.h>
#include <dlfcn.h>
#include <errno.h>
#include "g31ddcapi.h"

G31DDC_OPEN_DEVICE OpenDevice;
G31DDC_CLOSE_DEVICE CloseDevice;
void *API;

int main(void)
{  
 int32_t hDevice;
 
    //Loading the API
    API=dlopen("libg31ddcapi.so",RTLD_LAZY);

    if(API!=NULL)
    {
        //Retrieving addresses of the OpenDevice and CloseDevice API functions
        OpenDevice=(G31DDC_OPEN_DEVICE)dlsym(API,"OpenDevice");
        CloseDevice=(G31DDC_CLOSE_DEVICE)dlsym(API,"CloseDevice");

        //Opening the first available G31DDC device using predefined G3XDDC_OPEN_FIRST constant
        hDevice=OpenDevice(G3XDDC_OPEN_FIRST);
        
        if(hDevice>=0)
        {
            //Here place code that works with the open G31DDC device            
            
            //Closing handle to opened G31DDC device
            CloseDevice(hDevice);
        }
        else
        {
            printf("OpenDevice failed with error %d.\n",errno);
        }

        dlclose(API);
    }
    else
    {
        //If the dlopen fails
        printf("Failed to load libg31ddcapi.so. %s\n",dlerror());
    }
    
    return 0;
}

GetDeviceList

The GetDeviceList function returns information about available G31DDC devices which can be opened.

C/C++ declaration

int32_t  GetDeviceList(G31DDC_DEVICE_INFO *DeviceList,uint32_t BufferSize);

Address retrieval

G31DDC_GET_DEVICE_LIST GetDeviceList=(G31DDC_GET_DEVICE_LIST)dlsym(hAPI,"GetDeviceList");

Parameters

DeviceList
[out] Pointer to array of G31DDC_DEVICE_INFO structures to be filled with information about available G31DDC devices.
This parameter can be NULL only if the BufferSize parameter is zero, otherwise the function fails.
BufferSize
[in] Specifies the size in bytes of the buffer pointed to by the DeviceList parameter. If this value is zero, function returns number of available G31DDC devices and makes no use of the DeviceList buffer.

Return value

If the function succeeds, the return value is number of available G31DDC devices.
If the function fails, the return value is negative. To get extended error information, check errno.

OpenDevice

Opens G31DDC device by its serial number.

C/C++ declaration

int32_t  OpenDevice(const char *SerialNumber);

Address retrieval

G31DDC_OPEN_DEVICE OpenDevice=(G31DDC_OPEN_DEVICE)dlsym(hAPI,"OpenDevice");

Parameters

SerialNumber
[in] Pointer to a null-terminated string that specifies the serial number of the G31DDC device to open. One of the following values can be used instead of serial number:

ValueMeaning
G3XDDC_OPEN_FIRSTThe function opens the first available G31DDC device.
G3XDDC_OPEN_DEMOThe function opens a demo G31DDC device. This allows to work with the API without a physical G31DDC device.

Return value

If the function succeeds, the returned handle to the specified G31DDC device is given. This handle can only be used with functions of G31DDC API.
If the function fails, the return value is negative. To get extended error information, check errno.

Remarks

The OpenDevice function can be called from any user thread, the returned handle can only be used in the same thread, otherwise the application can be placed into an unpredictable state.

Use the CloseDevice function to close the G31DDC device handle returned by OpenDevice.


CloseDevice

Closes G31DDC device.

C/C++ declaration

int  CloseDevice(int32_t hDevice);

Address retrieval

G31DDC_CLOSE_DEVICE CloseDevice=(G31DDC_CLOSE_DEVICE)dlsym(hAPI,"CloseDevice");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

IsDeviceConnected

Checks if the device is still connected to the computer.

C/C++ declaration

int  IsDeviceConnected(int32_t hDevice);

Address retrieval

G31DDC_IS_DEVICE_CONNECTED IsDeviceConnected=(G31DDC_IS_DEVICE_CONNECTED)dlsym(hAPI,"IsDeviceConnected");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

The function returns non-zero value if the device is still connected.
If the device is disconnected or the function fails, the return value is zero. To determine if the function failed, check errno. errno returns 0 if the device is disconnected or another error code if IsDeviceConnected failed.

Remarks

If it is determined the device is disconnected, the corresponding device handle is no longer usable and it should be closed using the CloseDevice function.

GetDeviceInfo

Retrieves information about the G31DDC device.

C/C++ declaration

int  GetDeviceInfo(int32_t hDevice,G31DDC_DEVICE_INFO *Info,uint32_t BufferLength);

Address retrieval

G31DDC_GET_DEVICE_INFO GetDeviceInfo=(G31DDC_GET_DEVICE_INFO)dlsym(hAPI,"GetDeviceInfo");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Info
[out] Pointer to a G31DDC_DEVICE_INFO structure to be filled with information about the device. This parameter cannot be NULL.
BufferLength
[in] Size in bytes of the G31DDC_DEVICE_INFO structure.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetPower

Turns the G31DDC device on or off.

C/C++ declaration

int  SetPower(int32_t hDevice,int Power);

Address retrieval

G31DDC_SET_POWER SetPower=(G31DDC_SET_POWER)dlsym(hAPI,"SetPower");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Power
[in] Specifies whether to turn on or off the device. If this parameter is non-zero the device is turned on, if it is zero the device is turned off.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If SetPower turns the device off, all the running streams are stopped.

Use the GetPower function to determine current power state of the device.


GetPower

The GetPower function determines whether the device is turned on or off.

C/C++ declaration

int  GetPower(int32_t hDevice,int *Power);

Address retrieval

G31DDC_GET_POWER GetPower=(G31DDC_GET_POWER)dlsym(hAPI,"GetPower");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Power
[out] Pointer to a variable that receives current power state of the device. If it is non-zero, the device is turned on. If it is zero the device is turned off. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetExternalReference

Enables or disables the use of external reference as the clock source.

C/C++ declaration

int  SetExternalReference(int32_t hDevice,int Enabled);

Address retrieval

G31DDC_SET_EXTERNAL_REFERENCE SetExternalReference=(G31DDC_SET_EXTERNAL_REFERENCE)dlsym(hAPI,"SetExternalReference");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[in] Specifies the desired clock source: nonzero - external reference, zero - internal.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

External reference is optional. If the receiver does not support external reference, SetExternalReference fails. The following example shows how to determine whether the receiver supports external reference:
    G31DDC_DEVICE_INFO DeviceInfo;
    int32_t hDevice;  //handle to open G31DDC device
    
    GetDeviceInfo(hDevice,&DeviceInfo,sizeof(DeviceInfo));
    
    if(DeviceInfo.Flags & G31DDC_FLAGS_EXTERNAL_REFERENCE)
    {
        //the receiver supports external reference
    }
    else
    {
        //the receiver does not support external reference
    }

GetExternalReference

Retrieves the current clock source.

C/C++ declaration

int  GetExternalReference(int32_t hDevice,int *Enabled);

Address retrieval

G31DDC_GET_EXTERNAL_REFERENCE GetExternalReference=(G31DDC_GET_EXTERNAL_REFERENCE)dlsym(hAPI,"GetExternalReference");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[out] Pointer to a variable that receives information about the current clock source. If it is non-zero, external reference is used, if it is zero, internal reference is used. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAttenuator

Sets input attenuator.

C/C++ declaration

int  SetAttenuator(int32_t hDevice,uint32_t Attenuator);

Address retrieval

G31DDC_SET_ATTENUATOR SetAttenuator=(G31DDC_SET_ATTENUATOR)dlsym(hAPI,"SetAttenuator");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Attenuator
[in] Value that specifies attenuation level in dB. Possible values are: 0, 3, 6, 9, 12, 15, 18, 21. If the value is not from the list, the SetAttenuator function rounds the value to nearest lower one.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetAttenuator function to determine current setting of the attenuator.

GetAttenuator

Retrieves current setting of the attenuator.

C/C++ declaration

int  GetAttenuator(int32_t hDevice,uint32_t *Attenuator);

Address retrieval

G31DDC_GET_ATTENUATOR GetAttenuator=(G31DDC_GET_ATTENUATOR)dlsym(hAPI,"GetAttenuator");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Attenuator
[out] Pointer to a variable that receives current attenuation level. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDithering

Enables or disables ADC dithering.

C/C++ declaration

int  SetDithering(int32_t hDevice,int Enable);

Address retrieval

G31DDC_SET_DITHERING SetDithering=(G31DDC_SET_DITHERING)dlsym(hAPI,"SetDithering");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enable
[in] Specifies whether to enable or disable ADC dithering. If this parameter is non-zero, dithering is enabled. If the parameter is zero, dithering is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetDithering function to determine current setting of dithering.

GetDithering

Retrieves current setting of dithering.

C/C++ declaration

int  GetDithering(int32_t hDevice,int *Enable);

Address retrieval

G31DDC_GET_DITHERING GetDithering=(G31DDC_GET_DITHERING)dlsym(hAPI,"GetDithering");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enable
[out] Pointer to a variable that receives current dithering setting. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetMWFilter

Enables or disables MW filter (medium wave filter).

C/C++ declaration

int  SetMWFilter(int Enabled);

Address retrieval

G31DDC_SET_MWFILTER SetMWFilter=(G31DDC_SET_MWFILTER)dlsym(hAPI,"SetMWFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[in] Specifies whether to enable or disable MW filter. If this parameter is non-zero, the filter is enabled. If the parameter is zero, the filter is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetMWFilter function to determine current setting of the MW Filter.


GetMWFilter

Retrieves current setting of MW Filter.

C/C++ declaration

int GetMWFilter(int *Enabled);

Address retrieval

G31DDC_GET_MWFILTER GetMWFilter=(G31DDC_GET_MWFILTER)dlsym(hAPI,"GetMWFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[out] Pointer to a variable that receives current state of the MW filter. The value is non-zero if the filter is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetPreamp

Enables or disables input preamplifier.

C/C++ declaration

int  SetPreamp(int32_t hDevice,int Preamp);

Address retrieval

G31DDC_SET_PREAMP SetPreamp=(G31DDC_SET_PREAMP)dlsym(hAPI,"SetPreamp");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Preamp
[in] Specifies whether to enable or disable preamplifier. If this parameter is non-zero, the preamplifier is enabled. If the parameter is zero, the preamplifier is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetPreamp function to determine current state of the preamplifier.


GetPreamp

Retrieves current state of input preamplifier.

C/C++ declaration

int  GetPreamp(int32_t hDevice,int *Preamp);

Address retrieval

G31DDC_GET_PREAMP GetPreamp=(G31DDC_GET_PREAMP)dlsym(hAPI,"GetPreamp");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Preamp
[out] Pointer to a variable that receives current state of the preamplifier. The value is non-zero if the preamplifier is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetADCNoiseBlanker

Enables or disables noise blanker on ADC stream.

C/C++ declaration

int  SetADCNoiseBlanker(int32_t hDevice,int Enabled);

Address retrieval

G31DDC_SET_ADC_NOISE_BLANKER SetADCNoiseBlanker=(G31DDC_SET_ADC_NOISE_BLANKER)dlsym(hAPI,"SetADCNoiseBlanker");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[in] Specifies whether to enable or disable noise blanker. If this parameter is non-zero, noise blanker is enabled. If the parameter is zero, noise blanker is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetADCNoiseBlanker function to determine current state of the noise blanker.

GetADCNoiseBlanker

Retrieves current ADC noise blanker state.

C/C++ declaration

int  GetADCNoiseBlanker(int32_t hDevice,int *Enabled);

Address retrieval

G31DDC_GET_ADC_NOISE_BLANKER GetADCNoiseBlanker=(G31DDC_GET_ADC_NOISE_BLANKER)dlsym(hAPI,"GetADCNoiseBlanker");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Enabled
[out] Pointer to a variable that receives current state of noise blanker. The value is non-zero if noise blanker is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetADCNoiseBlankerThreshold

Specifies ADC noise blanker threshold.

C/C++ declaration

int  SetADCNoiseBlankerThreshold(int32_t hDevice,uint16_t Threshold);

Address retrieval

G31DDC_SET_ADC_NOISE_BLANKER_THRESHOLD SetADCNoiseBlankerThreshold=
    (G31DDC_SET_ADC_NOISE_BLANKER_THRESHOLD)dlsym(hAPI,"SetADCNoiseBlankerThreshold");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Threshold
[in] Specifies the maximum acceptable input signal. Maximum possible value of threshold is 32767, in this case the noise blanker has no effect even if it is enabled using the SetADCNoiseBlanker function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetADCNoiseBlankerThreshold function to retrieve current threshold of the noise blanker.

GetADCNoiseBlankerThreshold

Determines ADC noise blanker threshold.

C/C++ declaration

int  GetADCNoiseBlankerThreshold(int32_t hDevice,uint16_t *Threshold);

Address retrieval

G31DDC_GET_ADC_NOISE_BLANKER_THRESHOLD GetADCNoiseBlankerThreshold=
    (G31DDC_GET_ADC_NOISE_BLANKER_THRESHOLD)dlsym(hAPI,"GetADCNoiseBlankerThreshold");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Threshold
[out] Pointer to a variable that receives threshold of ADC noise blanker. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

StartIF

Starts sending IF snapshots.

C/C++ declaration

int  StartIF(int32_t hDevice,uint16_t Period);

Address retrieval

G31DDC_START_IF StartIF=(G31DDC_START_IF)dlsym(hAPI,"StartIF");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Period
[in] Specifies time interval in milliseconds for how often the IF snapshots are sent to IFCallback callback function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The G31DDC device has to be turned on using the SetPower function before use of StartIF, otherwise the StartIF function fails.

Too low value of the Period parameter can dramatically increase data flow through USB which could cause the running stream to break.


StopIF

Stops sending IF snapshots.

C/C++ declaration

int  StopIF(int32_t hDevice);

Address retrieval

G31DDC_STOP_IF StopIF=(G31DDC_STOP_IF)dlsym(hAPI,"StopIF");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The IFCallback callback function is not called after StopIF returns.


SetInverted

Enables or disables frequency spectrum inversion.

C/C++ declaration

int  SetInverted(int32_t hDevice,int Inverted);

Address retrieval

G31DDC_SET_INVERTED SetInverted=(G31DDC_SET_INVERTED)dlsym(hAPI,"SetInverted");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Inverted
[in] Specifies whether to enable or disable frequency spectrum inversion. If this parameter is non-zero, IF spectrum is inverted.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetInverted

Retrieves current frequency spectrum inversion setting.

C/C++ declaration

int  GetInverted(int32_t hDevice,int *Inverted);

Address retrieval

G31DDC_GET_INVERTED GetInverted=(G31DDC_GET_INVERTED)dlsym(hAPI,"GetInverted");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Inverted
[out] Pointer to a variable that receives non-zero value if the frequency spectrum inversion is enabled, and zero if the inversion is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetDDCInfo

Retrieves information about DDC format.

C/C++ declaration

int  GetDDCInfo(int32_t hDevice,uint32_t DDCTypeIndex,G3XDDC_DDC_INFO *Info);

Address retrieval

G31DDC_GET_DDC_INFO GetDDCInfo=(G31DDC_GET_DDC_INFO)dlsym(hAPI,"GetDDCInfo");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
DDCTypeIndex
[in] Specifies index of DDC type. For more information, see remarks.
Info
[out] Pointer to a G3XDDC_DDC_INFO structure to be filled with information about DDC type.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetDDC1Count function to determine the number of possible DDC types of DDC1. In this case the DDCTypeIndex parameter can vary from zero to one less than the number determined by GetDDC1Count.

Use the GetDDC1 function to determine current DDC type index of DDC1 and the GetDDC2 function to determine current DDC type of DDC2.


GetDDC1Count

Retrieves number of DDC types supported by DDC1.

C/C++ declaration

int  GetDDC1Count(int32_t hDevice,uint32_t *Count);

Address retrieval

G31DDC_GET_DDC1_COUNT GetDDC1Count=(G31DDC_GET_DDC1_COUNT)dlsym(hAPI,"GetDDC1Count");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Count
[out] Pointer to a variable that receives the number of DDC types supported by the DDC1. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDDC1

Sets current DDC type of DDC1.

C/C++ declaration

int  SetDDC1(int32_t hDevice,uint32_t DDCTypeIndex);

Address retrieval

G31DDC_SET_DDC1 SetDDC1=(G31DDC_SET_DDC1)dlsym(hAPI,"SetDDC1");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
DDCTypeIndex
[in] Specifies index of DDC type to be used in DDC1. It can vary from zero to one less than the number of DDC types of the DDC1.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetDDC1Count function to determine the number of possible DDC types of DDC1. The DDCTypeIndex parameter can vary from zero to one less than the number determined by GetDDC1Count.

DDC1 streaming must not run when calling SetDDC1. In other words, DDC1 streaming which is started using the StartDDC1 function has to be stopped using the StopDDC1 function before calling of SetDDC1, otherwise SetDDC1 fails. The SetDDC1 function does not start and stop DDC1 streaming, just changes DDC type of DDC1.

Calling of SetDDC1 can change current DDC type of DDC2 and current bandwidth of the demodulator filter, so it is useful to call the GetDDC2 and GetDemodulatorFilterBandwidth functions immediately after SetDDC1 to determine current DDC type of DDC2 and current bandwidth of the demodulator filter.

Use the GetDDC1 function to determine current DDC type of the DDC1.


GetDDC1

Retrieves information about current DDC type of the DDC1.

C/C++ declaration

int  GetDDC1(int32_t hDevice,uint32_t *DDCTypeIndex,G3XDDC_DDC_INFO *DDCInfo);

Address retrieval

G31DDC_GET_DDC1 GetDDC1=(G31DDC_GET_DDC1)dlsym(hAPI,"GetDDC1");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
DDCTypeIndex
[out] Pointer to a variable that receives index of current DDC type of the DDC1. This parameter can be NULL if the application does not require this information.
DDCInfo
[out] Pointer to a G3XDDC_DDC_INFO structure to be filled with information about current DDC type of the DDC1. This parameter can be NULL if the application does not require this information.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Returned DDCTypeIndex can be passed to the GetDDCInfo function.

SetDDC1Frequency

Sets DDC1 center frequency.

C/C++ declaration

int  SetDDC1Frequency(int32_t hDevice,uint32_t Frequency);

Address retrieval

G31DDC_SET_DDC1_FREQUENCY SetDDC1Frequency=(G31DDC_SET_DDC1_FREQUENCY)dlsym(hAPI,"SetDDC1Frequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Frequency
[in] Specifies new center frequency of DDC1 in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Changing of DDC1 frequency causes change of absolute frequency of the DDC2 and demodulator in each channel.

Use the GetDDC1Frequency function to determine current center frequency of DDC1.


GetDDC1Frequency

Retrieves current center frequency of DDC1.

C/C++ declaration

int  GetDDC1Frequency(int32_t hDevice,uint32_t *Frequency);

Address retrieval

G31DDC_GET_DDC1_FREQUENCY GetDDC1Frequency=(G31DDC_GET_DDC1_FREQUENCY)dlsym(hAPI,"GetDDC1Frequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Frequency
[out] Pointer to a variable that receives current center frequency of DDC1 in Hz. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

StartDDC1

Starts DDC1 streaming.

C/C++ declaration

int  StartDDC1(int32_t hDevice,uint32_t SamplesPerBuffer);

Address retrieval

G31DDC_START_DDC1 StartDDC1=(G31DDC_START_DDC1)dlsym(hAPI,"StartDDC1");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
SamplesPerBuffer
[in] Specifies number of I/Q sample sets in each buffer passed to the DDC1StreamCallback callback function. The value has to be a multiple of 64 greater than zero. If it is zero, the StartDDC1 function fails. If it is not a multiple of 64, the function rounds it up to the nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The G31DDC device has to be turned on using the SetPower function before StartDDC1 is used. Otherwise StartDDC1 fails.

If the DDC1 streaming is already running before use of StartDDC1, StartDDC1 restarts the streaming except when it was previously started with the same SamplesPerBuffer parameter. In this case StartDDC1 does nothing. Restart of DDC1 streaming stops DDC2 and audio streaming in each channel. StartDDC1 does not restart DDC2 and audio streaming.

If DDC1 playback is running (started using StartDDC1Playback function) before use of StartDDC1, StartDDC1 stops it and starts DDC1 streaming from the device.

Use the StopDDC1 function to stop DDC1 streaming.

Decreasing the value of the SamplesPerBuffer parameter decreases latency and may increase CPU usage. Increasing the value of the SamplesPerBuffer parameter increases latency and it may decrease CPU usage.


StopDDC1

Stops DDC1 streaming.

C/C++ declaration

int  StopDDC1(int32_t hDevice);

Address retrieval

G31DDC_STOP_DDC1 StopDDC1=(G31DDC_STOP_DDC1)dlsym(hAPI,"StopDDC1");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If DDC1 playback is running (started using StartDDC1Playback) before use of StopDDC1, the StopDDC1 function stops it.

The StopDDC1 function stops all the streaming beyond the DDC1 in processing chain (DDC2 and audio streaming in all the channels).

The DDC1StreamCallback and DDC1PlaybackStreamCallback callback functions are not called after StopDDC1 returns.


StartDDC1Playback

Starts DDC1 playback. It allows passage of previously recorded DDC1 I/Q samples to the processing chain instead of the samples received from the device.

C/C++ declaration

int  StartDDC1Playback(int32_t hDevice,uint32_t SamplesPerBuffer,uint32_t BitsPerSample);

Address retrieval

G31DDC_START_DDC1_PLAYBACK StartDDC1Playback=(G31DDC_START_DDC1_PLAYBACK)dlsym(hAPI,"StartDDC1Playback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
SamplesPerBuffer
[in] Specifies number of I/Q sample sets in each buffer passed to the DDC1PlaybackStreamCallback callback to fill the buffer by the application and to the DDC1StreamCallback callback function. The value has to be a multiple of 64 greater than zero. If it is zero, the StartDDC1Playback function fails. If it is not a multiple of 64 the function rounds it up to nearest multiple of 64.
BitsPerSample
[in] Specifies number of bits per I and Q samples. It is used for both DDC1PlaybackStreamCallback and DDC1StreamCallback callback functions. The possible value is one of the following:

ValueMeaning
0I and Q samples have default number of bits. It is given by BitsPerSample member of the G3XDDC_DDC_INFO structure which can be retrieved using the GetDDC1 or GetDDCInfo function. Possible values are 16 or 32 bits per sample, signed, little endian.
16I and Q samples have 16 bit (16 bits per I, 16 bits per Q), signed, little endian.
32I and Q samples have 32 bit (32 bits per I, 32 bits per Q), signed, little endian.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The G31DDC device has to be turned on using SetPower function before use of StartDDC1Playback.

The StartDDC1Playback function stops DDC1 streaming that was previously started by the StartDDC1 or StartDDC1Playback function and starts DDC1 playback with new parameters. Stopping of DDC1 streaming stops DDC2 and audio steaming in each channel. StartDDC1Playback does not restart DDC2 and audio streaming.

Use the StopDDC1 function to stop DDC1 playback.


PauseDDC1Playback

Pauses DDC1 playback.

C/C++ declaration

int  PauseDDC1Playback(int32_t hDevice);

Address retrieval

G31DDC_PAUSE_DDC1_PLAYBACK PauseDDC1Playback=(G31DDC_PAUSE_DDC1_PLAYBACK)dlsym(hAPI,"PauseDDC1Playback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If DDC1 playback is not active or it is already paused, PauseDDC1Playback does nothing.

The DDC1PlaybackStreamCallback and DDC1StreamCallback callback functions can be called once after PauseDDC1Playback returns. Then they are not called until playback is resumed using the ResumeDDC1Playback function.


ResumeDDC1Playback

Resumes paused DDC1 playback.

C/C++ declaration

int  ResumeDDC1Playback(int32_t hDevice);

Address retrieval

G31DDC_RESUME_DDC1_PLAYBACK ResumeDDC1Playback=(G31DDC_RESUME_DDC1_PLAYBACK)dlsym(hAPI,"ResumeDDC1Playback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If DDC1 playback is not active or it is not paused, ResumeDDC1Playback does nothing.


GetDDC2

Retrieves information about current DDC type of the DDC2.

C/C++ declaration

int  GetDDC2(int32_t hDevice,uint32_t *DDCTypeIndex,G3XDDC_DDC_INFO *DDCInfo);

Address retrieval

G31DDC_GET_DDC2 GetDDC2=(G31DDC_GET_DDC2)dlsym(hAPI,"GetDDC2");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
DDCTypeIndex
[out] Pointer to a variable that receives index of current DDC type of the DDC2. This parameter can be NULL if the application does not require this information.
DDCInfo
[out] Pointer to a G3XDDC_DDC_INFO structure to be filled with information about current DDC type of the DDC2. This parameter can be NULL if the application does not require this information.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Each channel has its own DDC2, see the block diagram. DDC type of each DDC2 is the same and dependent on DDC type of DDC1, it cannot be changed by the application directly. DDC type of DDC2 is equal to DDC type of DDC1 if DDC type index of DDC1 is less than or equal to 5 (sample rate: 80 kHz, bandwidth: 64 kHz, bits per sample: 32). If DDC type index of DDC1 is above 5, DDC type index of DDC2 is always 5. Changing of DDC type of DDC1 can cause change of DDC type of DDC2, so it is useful to call GetDDC2 immediately after the SetDDC1 function to determine the current DDC type of DDC2 if the application needs to know parameters of DDC2.

The BitsPerSample member of the G3XDDC_DDC_INFO structure is not used and it can be ignored for DDC2. I and Q samples in buffers passed to the DDC2StreamCallback and DDC2PreprocessedStreamCallback DDC2 callback functions are always in IEEE float (32 bit, little endian) format.

Returned DDCTypeIndex can be passed to the GetDDCInfo function.


SetDDC2Frequency

Sets relative center frequency of DDC2 for given channel.

C/C++ declaration

int  SetDDC2Frequency(int32_t hDevice,uint32_t Channel,int32_t Frequency);

Address retrieval

G31DDC_SET_DDC2_FREQUENCY SetDDC2Frequency=(G31DDC_SET_DDC2_FREQUENCY)dlsym(hAPI,"SetDDC2Frequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[in] Specifies new center frequency of DDC2 in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Value of the Frequency parameter is center frequency of the DDC2 relative to center of the DDC1. The value can be negative.

Absolute frequency of the DDC2 is given by the following formula:

faDDC2[i] = fDDC1 + frDDC2[i]

Where faDDC2[i] is absolute center frequency of DDC2 of i-th channel in Hz, fDDC1 is center frequency of the DDC1 in Hz (set using the SetDDC1Frequency function) and frDDC2[i] is relative center frequency of DDC2 of i-th channel in Hz (set using SetDDC2Frequency).

Changing of DDC2 relative frequency changes absolute frequency of the DDC2 and demodulator in the specified channel.

Use the GetDDC2Frequency function to determine current relative center frequency of the DDC2 for given channel.

The following example shows three methods of how to set absolute DDC2 center frequency of channel 0 to 11.01 MHz:

int32_t hDevice; //Handle to G31DDC device returned by the OpenDevice function

//1. method
SetDDC1Frequency(hDevice,11010000);
SetDDC2Frequency(hDevice,0,0);

//2. method, it can be used if bandwidth of DDC2 is less than bandwidth of DDC1
SetDDC1Frequency(hDevice,11000000);
SetDDC2Frequency(hDevice,0,10000);

//3. method, it can be used if bandwidth of DDC2 is less than bandwidth of DDC1
SetDDC1Frequency(hDevice,11020000);
SetDDC2Frequency(hDevice,0,-10000);

GetDDC2Frequency

Retrieves current relative center frequency of DDC2.

C/C++ declaration

int  GetDDC2Frequency(int32_t hDevice,uint32_t Channel,int32_t *Frequency);

Address retrieval

G31DDC_GET_DDC2_FREQUENCY GetDDC2Frequency=(G31DDC_GET_DDC2_FREQUENCY)dlsym(hAPI,"GetDDC2Frequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[out] Pointer to a variable that receives current relative center frequency of DDC2 in Hz. The returned value can be negative. See remarks of the SetDDC2Frequency for information on how to calculate the absolute center frequency of DDC2. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

StartDDC2

Starts DDC2 streaming for given channel.

C/C++ declaration

int  StartDDC2(int32_t hDevice,uint32_t Channel,uint32_t SamplesPerBuffer);

Address retrieval

G31DDC_START_DDC2 StartDDC2=(G31DDC_START_DDC2)dlsym(hAPI,"StartDDC2");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
SamplesPerBuffer
[in] Specifies number of I/Q sample sets in each buffer passed to the DDC2StreamCallback and DDC2PreprocessedStreamCallback callback functions. The value has to be a multiple of 64 greater than zero. If it is zero, the StartDDC2 function fails. If it is not a multiple of 64, the function rounds it up to nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Before StartDDC2 is used, the G31DDC device has to be turned on using the SetPower function and DDC1 streaming has to be started using the StartDDC1 or StartDDC1Playback function, otherwise StartDDC2 fails.

If the DDC2 streaming for the given channel is already running, StartDDC2 restarts it except when the streaming was previously started with the same SamplesPerBuffer parameter. In this case StartDDC2 does nothing. Restart of the DDC2 streaming stops audio streaming for the given channel. StartDDC2 does not restart audio streaming.

Use the StopDDC2 function to stop DDC2 streaming.

Decreasing the value of the SamplesPerBuffer parameter decreases latency and may increase CPU usage. Increasing the value of the SamplesPerBuffer parameter increases latency and it may decrease CPU usage.


StopDDC2

Stops DDC2 streaming for given channel.

C/C++ declaration

int  StopDDC2(int32_t hDevice,uint32_t Channel);

Address retrieval

G31DDC_STOP_DDC2 StopDDC2=(G31DDC_STOP_DDC2)dlsym(hAPI,"StopDDC2");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If audio streaming for given channel is running, it is stopped too.

If DDC2 streaming is not active, StopDDC2 does nothing.

The DDC2StreamCallback and DDC2PreprocessedStreamCallback callback functions are not called after StopDDC2 returns.


SetDDC2NoiseBlanker

Enables or disables noise blanker on DDC2 stream.

C/C++ declaration

int  SetDDC2NoiseBlanker(int32_t hDevice,uint32_t Channel,int Enabled);

Address retrieval

G31DDC_SET_DDC2_NOISE_BLANKER SetDDC2NoiseBlanker=(G31DDC_SET_DDC2_NOISE_BLANKER)dlsym(hAPI,"SetDDC2NoiseBlanker");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[in] Specifies whether to enable or disable noise blanker. If this parameter is non-zero, the noise blanker is enabled. If the parameter is zero, the noise blanker is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetDDC2NoiseBlanker function to determine the current state of the noise blanker.

GetDDC2NoiseBlanker

Retrieves current DDC2 noise blanker state.

C/C++ declaration

int  GetDDC2NoiseBlanker(int32_t hDevice,uint32_t Channel,int *Enabled);

Address retrieval

G31DDC_GET_DDC2_NOISE_BLANKER GetDDC2NoiseBlanker=(G31DDC_GET_DDC2_NOISE_BLANKER)dlsym(hAPI,"GetDDC2NoiseBlanker");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[out] Pointer to a variable that receives current state of noise blanker. The value is non-zero if noise blanker is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDDC2NoiseBlankerThreshold

Specifies DDC2 noise blanker threshold.

C/C++ declaration

int  SetDDC2NoiseBlankerThreshold(int32_t hDevice,uint32_t Channel,double Threshold);

Address retrieval

G31DDC_SET_DDC2_NOISE_BLANKER_THRESHOLD SetDDC2NoiseBlankerThreshold=
    (G31DDC_SET_DDC2_NOISE_BLANKER_THRESHOLD)dlsym(hAPI,"SetDDC2NoiseBlankerThreshold");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Threshold
[in] Specifies threshold in %.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetDDC2NoiseBlankerThreshold function to retrieve current threshold of the noise blanker.

GetDDC2NoiseBlankerThreshold

Retrieves DDC2 noise blanker threshold.

C/C++ declaration

int  GetDDC2NoiseBlankerThreshold(int32_t hDevice,uint32_t Channel,double *Threshold);

Address retrieval

G31DDC_GET_DDC2_NOISE_BLANKER_THRESHOLD GetDDC2NoiseBlankerThreshold=
    (G31DDC_GET_DDC2_NOISE_BLANKER_THRESHOLD)dlsym(hAPI,"GetDDC2NoiseBlankerThreshold");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Threshold
[out] Pointer to a variable that receives threshold of the noise blanker. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetDDC2NoiseBlankerExcessValue

Determines a value which indicates the percentage ratio between the short time average signal level and maximum level.

C/C++ declaration

int  GetDDC2NoiseBlankerExcessValue(int32_t hDevice,uint32_t Channel,double *Value);

Address retrieval

G31DDC_GET_DDC2_NOISE_BLANKER_EXCESS_VALUE GetDDC2NoiseBlankerExcessValue=
    (G31DDC_GET_DDC2_NOISE_BLANKER_EXCESS_VALUE)dlsym(hAPI,"GetDDC2NoiseBlankerExcessValue");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Value
[out] Pointer to a variable that receives current excess value in %. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetSignalLevel

Determines current signal level for given channel.

C/C++ declaration

int  GetSignalLevel(int32_t hDevice,uint32_t Channel,float *Peak,float *RMS);

Address retrieval

G31DDC_GET_SIGNAL_LEVEL GetSignalLevel=(G31DDC_GET_SIGNAL_LEVEL)dlsym(hAPI,"GetSignalLevel");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Peak
[out] Pointer to a variable that receives current signal level (peak) in Volts. This parameter can be NULL if the application does not require this information.
RMS
[out] Pointer to a variable that receives current signal level (RMS) in Volts. This parameter can be NULL if the application does not require this information.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

DDC2 streaming has to be active (started using the StartDDC2 function) before calling of GetSignalLevel, otherwise the returned peak and RMS signal levels are zero.

Signal level is evaluated from the signal after the demodulator filter and before the notch filter (see block diagram), the signal is selected by the demodulator filter.

Signal level is evaluated for each buffer processed by the demodulator filter. Buffer size (signal level evaluation rate) is given by the SamplesPerBuffer parameter of the StartDDC2 function.

The DDC2PreprocessedStreamCallback callback function provides signal level for each buffer passed to the callback, i.e. for each buffer used in signal level evaluation. This provides a way to get signal level from each processed buffer without the need to poll it using GetSignalLevel.

To convert RMS signal level in Volts to power in dBm use the following formulas:

P[W] = (VRMS)2 / R = (VRMS)2 / 50

P[dBm]= 10 * log10( P[W] * 1000 )

Where VRMS is RMS signal level in Volts obtained by GetSignalLevel, R is G31DDC receiver input impedance (50 Ω), P[W] is power in Watts, P[dBm] is power in dBm and 1000 is conversion coefficient W -> mW.

The following example shows how to obtain current signal level in dBm from channel 0:

#include <stdio.h>
#include <math.h>

int32_t hDevice; //handle to G31DDC device returned by the OpenDevice function
float P_dBm,V_RMS;

GetSignalLevel(hDevice,0,NULL,&V_RMS);

P_dBm=10.0*log10(V_RMS*V_RMS*(1000.0/50.0));

printf("Current signal level [RMS]: %.1f dBm\n",P_dBm);

SetNotchFilter

Enables or disables notch filter for given channel.

C/C++ declaration

int  SetNotchFilter(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,int Enabled);

Address retrieval

G31DDC_SET_NOTCH_FILTER SetNotchFilter=(G31DDC_SET_NOTCH_FILTER)dlsym(hAPI,"SetNotchFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Must be 0.
Enabled
[in] Specifies whether to enable or disable notch filter. If this parameter is non-zero, the filter is enabled. If the parameter is zero, the filter is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetNotchFilter function to determine whether the filter is enabled or disabled.

GetNotchFilter

Retrieves current notch filter state for given channel.

C/C++ declaration

int  GetNotchFilter(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,int *Enabled);

Address retrieval

G31DDC_SET_NOTCH_FILTER SetNotchFilter=(G31DDC_SET_NOTCH_FILTER)dlsym(hAPI,"SetNotchFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Must be 0.
NotchFilterIndex
[in] Specifies notch filter index. Possible values are: 0, 1.
Enabled
[out] Pointer to a variable that receives current state of the notch filter. The value is non-zero if the filter is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetNotchFilterFrequency

Specifies relative center frequency of the notch filter for given channel.

C/C++ declaration

int  SetNotchFilterFrequency(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,int32_t Frequency);

Address retrieval

G31DDC_SET_NOTCH_FILTER_FREQUENCY SetNotchFilterFrequency=
        (G31DDC_SET_NOTCH_FILTER_FREQUENCY)dlsym(hAPI,"SetNotchFilterFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Must be 0.
Frequency
[in] Specifies new center frequency of the notch filter in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Value of the Frequency parameter is new center frequency of the notch filter relative to center of the DDC2 (see the SetDDC2Frequency function). The value can be negative.

Use the GetNotchFilterFrequency function to retrieve current center frequency of the notch filter.


GetNotchFilterFrequency

Retrieves current relative center frequency of the notch filter.

C/C++ declaration

int  GetNotchFilterFrequency(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,int32_t *Frequency);

Address retrieval

G31DDC_GET_NOTCH_FILTER_FREQUENCY GetNotchFilterFrequency=
        (G31DDC_GET_NOTCH_FILTER_FREQUENCY)dlsym(hAPI,"GetNotchFilterFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Specifies notch filter index. Possible values are: 0, 1.
Frequency
[out] Pointer to a variable that receives current center frequency of the notch filter. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetNotchFilterBandwidth

Specifies bandwidth of the notch filter for given channel.

C/C++ declaration

int  SetNotchFilterBandwidth(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,uint32_t Bandwidth);

Address retrieval

G31DDC_SET_NOTCH_FILTER_BANDWIDTH SetNotchFilterBandwidth=
        (G31DDC_SET_NOTCH_FILTER_BANDWIDTH)dlsym(hAPI,"SetNotchFilterBandwidth");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Must be 0.
Bandwidth
[in] Specifies new bandwidth of the notch filter in Hz. The bandwidth can be in the range of 1 - 3000 Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetNotchFilterBandwidth function to retrieve current bandwidth of the notch filter.


GetNotchFilterBandwidth

Retrieves current bandwidth of the notch filter for given channel.

C/C++ declaration

int  GetNotchFilterBandwidth(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,uint32_t *Bandwidth);

Address retrieval

G31DDC_GET_NOTCH_FILTER_BANDWIDTH GetNotchFilterBandwidth=
        (G31DDC_GET_NOTCH_FILTER_BANDWIDTH)dlsym(hAPI,"GetNotchFilterBandwidth");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Must be 0.
Bandwidth
[out] Pointer to a variable that receives current bandwidth of the notch filter. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetNotchFilterLength

Specifies notch filter length for given channel. The notch filter is implemented as an FIR filter. This function specifies the number of coefficients used in the filtration procedure.

C/C++ declaration

int  SetNotchFilterLength(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,uint32_t Length);

Address retrieval

G31DDC_SET_NOTCH_FILTER_LENGTH SetNotchFilterLength=
        (G31DDC_SET_NOTCH_FILTER_LENGTH)dlsym(hAPI,"SetNotchFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Must be 0.
NotchFilterIndex
[in] Specifies notch filter index. Possible values are: 0, 1.
Length
[in] Specifies length of the notch filter. The value has to be a multiple of 64, greater than or equal to 64 and less than or equal to 32768. If it is not a multiple of 64, the function rounds it up to the nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Increasing the filter length increases filter steepness and may increase CPU usage.

Use the GetNotchFilterLength function to determine the current length of the notch filter.


GetNotchFilterLength

Retrieves current notch filter length for given channel.

C/C++ declaration

int  GetNotchFilterLength(int32_t hDevice,uint32_t Channel,uint32_t NotchFilterIndex,uint32_t *Length);

Address retrieval

G31DDC_GET_NOTCH_FILTER_LENGTH GetNotchFilterLength=
        (G31DDC_GET_NOTCH_FILTER_LENGTH)dlsym(hAPI,"GetNotchFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
NotchFilterIndex
[in] Must be 0.
Length
[out] Pointer to a variable that receives current length of the notch filter. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAGC

Enables or disables AGC for given channel.

C/C++ declaration

int  SetAGC(int32_t hDevice,uint32_t Channel,int Enabled);

Address retrieval

G31DDC_SET_AGC SetAGC=(G31DDC_SET_AGC)dlsym(hAPI,"SetAGC");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[in] Specifies whether to enable or disable AGC. If this parameter is non-zero, the AGC is enabled. If the parameter is zero, the AGC is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If the AGC is disabled, the signal is affected by fixed gain specified using the SetGain function.

Use the GetAGC function to determine the current state of the AGC.


GetAGC

Retrieves current state of the AGC for given channel.

C/C++ declaration

int  GetAGC(int32_t hDevice,uint32_t Channel,int *Enabled);

Address retrieval

G31DDC_GET_AGC GetAGC=(G31DDC_GET_AGC)dlsym(hAPI,"GetAGC");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[out] Pointer to a variable that receives current state of the AGC. The value is non-zero if the AGC is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAGCParams

Sets parameters of the AGC for given channel.

C/C++ declaration

int  SetAGCParams(int32_t hDevice,uint32_t Channel,double AttackTime,double DecayTime,double ReferenceLevel);

Address retrieval

G31DDC_SET_AGC_PARAMS SetAGCParams=(G31DDC_SET_AGC_PARAMS)dlsym(hAPI,"SetAGCParams");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
AttackTime
[in] Specifies new attack time of the AGC in seconds.
DecayTime
[in] Specifies new decay time of the AGC in seconds.
ReferenceLevel
[in] Specifies new reference level of the AGC in dB.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetAGCParams function to determine the current parameters of the AGC.


GetAGCParams

Retrieves current parameters of the AGC for given channel.

C/C++ declaration

int  GetAGCParams(int32_t hDevice,uint32_t Channel,double *AttackTime,double *DecayTime,double *ReferenceLevel);

Address retrieval

G31DDC_GET_AGC_PARAMS GetAGCParams=(G31DDC_GET_AGC_PARAMS)dlsym(hAPI,"GetAGCParams");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
AttackTime
[out] Pointer to a variable that receives current attack time of the AGC in seconds. This parameter can be NULL if the application does not require this information.
DecayTime
[out] Pointer to a variable that receives current decay time of the AGC in seconds. This parameter can be NULL if the application does not require this information.
ReferenceLevel
[out] Pointer to a variable that receives current reference level of the AGC in dB. This parameter can be NULL if the application does not require this information.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetMaxAGCGain

Sets maximum gain of the AGC for given channel.

C/C++ declaration

int  SetMaxAGCGain(int32_t hDevice,uint32_t Channel,double MaxGain);

Address retrieval

G31DDC_SET_MAX_AGC_GAIN SetMaxAGCGain=(G31DDC_SET_MAX_AGC_GAIN)dlsym(hAPI,"SetMaxAGCGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
MaxGain
[in] Specifies new maximum gain of the AGC in dB.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetMaxAGCGain function to determine maximum gain of the AGC.


GetMaxAGCGain

Retrieves current maximum gain of the AGC for given channel.

C/C++ declaration

int  GetMaxAGCGain(int32_t hDevice,uint32_t Channel,double *MaxGain);

Address retrieval

G31DDC_GET_MAX_AGC_GAIN GetMaxAGCGain=(G31DDC_GET_MAX_AGC_GAIN)dlsym(hAPI,"GetMaxAGCGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
MaxGain
[out] Pointer to a variable that receives the current maximum gain of the AGC in dB. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetGain

Sets fixed gain for given channel. This gain is applied to the I/Q signal if the AGC is disabled, otherwise it is not used.

C/C++ declaration

int  SetGain(int32_t hDevice,uint32_t Channel,double Gain);

Address retrieval

G31DDC_SET_GAIN SetGain=(G31DDC_SET_GAIN)dlsym(hAPI,"SetGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[in] Specifies new fixed gain in dB.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetGain function to determine the current fixed gain.


GetGain

Retrieves the current fixed gain for given channel.

C/C++ declaration

int  GetGain(int32_t hDevice,uint32_t Channel,double *Gain);

Address retrieval

G31DDC_GET_GAIN GetGain=(G31DDC_GET_GAIN)dlsym(hAPI,"GetGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[out] Pointer to a variable that receives the current fixed gain in dB. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetCurrentGain

Retrieves current gain that is applied to I/Q signal.

C/C++ declaration

int  GetCurrentGain(int32_t hDevice,uint32_t Channel,double *CurrentGain);

Address retrieval

G31DDC_GET_CURRENT_GAIN GetCurrentGain=(G31DDC_GET_CURRENT_GAIN)dlsym(hAPI,"GetCurrentGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
CurrentGain
[out] Pointer to a variable that receives the current gain in dB. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If the AGC is enabled (using the SetAGC function), the variable pointed to by the CurrentGain parameter is filled by the current gain of the AGC. If the AGC is disabled, the variable pointed to by the CurrentGain parameter is filled by the fixed gain that is specified using the SetGain function.

SetDemodulatorFilterBandwidth

Sets bandwidth of the demodulator filter for given channel.

C/C++ declaration

int  SetDemodulatorFilterBandwidth(int32_t hDevice,uint32_t Channel,uint32_t Bandwidth);

Address retrieval

G31DDC_SET_DEMODULATOR_FILTER_BANDWIDTH SetDemodulatorFilterBandwidth=
    (G31DDC_SET_DEMODULATOR_FILTER_BANDWIDTH)dlsym(hAPI,"SetDemodulatorFilterBandwidth");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Bandwidth
[in] Specified new bandwidth of the demodulator filter in Hz. Possible values are from range 1 Hz to the current DDC2 bandwidth. Use the GetDDC2 function to retrieve information about the current DDC type of DDC2.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The demodulator filter bandwidth can be changed using the SetDDC1 function. It can change DDC type of DDC2 and if the current demodulator filter bandwidth is greater than the new bandwidth of DDC2, the demodulator filter bandwidth is reduced. So it is useful to call the GetDemodulatorFilterBandwidth function immediately after SetDDC1.

GetDemodulatorFilterBandwidth

Retrieves current demodulator filter bandwidth for given channel.

C/C++ declaration

int  GetDemodulatorFilterBandwidth(int32_t hDevice,uint32_t Channel,uint32_t *Bandwidth);

Address retrieval

G31DDC_GET_DEMODULATOR_FILTER_BANDWIDTH GetDemodulatorFilterBandwidth=
    (G31DDC_GET_DEMODULATOR_FILTER_BANDWIDTH)dlsym(hAPI,"GetDemodulatorFilterBandwidth");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Bandwidth
[out] Pointer to a variable that receives the current demodulator filter bandwidth. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDemodulatorFilterShift

Sets demodulator filter shift for given channel.

C/C++ declaration

int  SetDemodulatorFilterShift(int32_t hDevice,uint32_t Channel,int32_t Shift);

Address retrieval

G31DDC_SET_DEMODULATOR_FILTER_SHIFT SetDemodulatorFilterShift=
    (G31DDC_SET_DEMODULATOR_FILTER_SHIFT)dlsym(hAPI,"SetDemodulatorFilterShift");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Shift
[in] Specified new shift of the demodulator filter in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Value of the Shift parameter is shift in Hz relative to center of the demodulator. This value can be negative.

This function does not change the demodulator frequency, but just shifts the filter from the demodulator's centre.

Use the GetDemodulatorFilterShift function to determine the current demodulator filter shift.


GetDemodulatorFilterShift

Retrieves current shift of the demodulator filter for given channel.

C/C++ declaration

int  GetDemodulatorFilterShift(int32_t hDevice,uint32_t Channel,int32_t *Shift);

Address retrieval

G31DDC_GET_DEMODULATOR_FILTER_SHIFT GetDemodulatorFilterShift=
    (G31DDC_GET_DEMODULATOR_FILTER_SHIFT)dlsym(hAPI,"GetDemodulatorFilterShift");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Shift
[out] Pointer to a variable that receives the current shift of the demodulator. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDemodulatorFilterLength

Specifies demodulator filter length for given channel. The demodulator filter is implemented as an FIR filter. This function specifies the number of coefficients used in the filtration procedure.

C/C++ declaration

int  SetDemodulatorFilterLength(int32_t hDevice,uint32_t Channel,uint32_t Length);

Address retrieval

G31DDC_SET_DEMODULATOR_FILTER_LENGTH SetDemodulatorFilterLength=
    (G31DDC_SET_DEMODULATOR_FILTER_LENGTH)dlsym(hAPI,"SetDemodulatorFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[in] Specifies the length of the demodulator filter. The value has to be a multiple of 64, greater than or equal to 64 and less than or equal to 32768. If it is not a multiple of 64, the function rounds it up to the nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Increasing the filter length increases filter steepness and it may increase CPU usage.

Use the GetDemodulatorFilterLength function to determine the current length of the demodulator filter.


GetDemodulatorFilterLength

Retrieves current length of the demodulator filter for given channel.

C/C++ declaration

int  GetDemodulatorFilterLength(int32_t hDevice,uint32_t Channel,uint32_t *Length);

Address retrieval

G31DDC_GET_DEMODULATOR_FILTER_LENGTH GetDemodulatorFilterLength=
    (G31DDC_GET_DEMODULATOR_FILTER_LENGTH)dlsym(hAPI,"GetDemodulatorFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[out] Pointer to a variable that receives the current demodulator filter length. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDemodulatorMode

Sets demodulator mode for given channel.

C/C++ declaration

int  SetDemodulatorMode(int32_t hDevice,uint32_t Channel,uint32_t Mode);

Address retrieval

G31DDC_SET_DEMODULATOR_MODE SetDemodulatorMode=(G31DDC_SET_DEMODULATOR_MODE)dlsym(hAPI,"SetDemodulatorMode");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Mode
[in] Specifies new demodulator mode. This value can be one of the following:

ValueMeaning
G3XDDC_MODE_CWContinuous wave
G3XDDC_MODE_AMAmplitude modulation
G3XDDC_MODE_FMFrequency modulation
G3XDDC_MODE_LSBLower sideband modulation
G3XDDC_MODE_USBUpper sideband modulation
G3XDDC_MODE_AMSAmplitude modulation
G3XDDC_MODE_DSBDouble sideband modulation
G3XDDC_MODE_ISBIndependent sideband modulation

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetDemodulatorMode

Retrieves current demodulator mode for given channel.

C/C++ declaration

int  GetDemodulatorMode(int32_t hDevice,uint32_t Channel,uint32_t *Mode);

Address retrieval

G31DDC_GET_DEMODULATOR_MODE GetDemodulatorMode=(G31DDC_GET_DEMODULATOR_MODE)dlsym(hAPI,"GetDemodulatorMode");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Mode
[out] Pointer to a variable that receives the current demodulator mode. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDemodulatorFrequency

Sets relative center frequency of demodulator for given channel.

C/C++ declaration

int  SetDemodulatorFrequency(int32_t hDevice,uint32_t Channel,int32_t Frequency);

Address retrieval

G31DDC_SET_DEMODULATOR_FREQUENCY SetDemodulatorFrequency=
    (G31DDC_SET_DEMODULATOR_FREQUENCY)dlsym(hAPI,"SetDemodulatorFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[in] Specified new center frequency of the demodulator in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Value of the Frequency parameter is center frequency of the demodulator relative to center of the DDC2. The value can be negative.

Absolute frequency of the demodulator is given by the following formula:

faDEM[i] = fDDC1 + frDDC2[i] + frDEM[i]

Where faDEM[i] is absolute center frequency of the demodulator of i-th channel in Hz, fDDC1 is center frequency of the DDC1 in Hz (set using the SetDDC1Frequency function), frDDC2[i] is relative center frequency of DDC2 of i-th channel in Hz (set using the SetDDC2Frequency) and frDEM[i] is relative center frequency of the demodulator of i-th channel in Hz (set using SetDemodulatorFrequency).

Absolute center frequency of the demodulator is the real-world frequency that you are listening to.

Use the GetDemodulatorFrequency function to determine the current relative center frequency of the demodulator for the given channel.

The following example shows four methods to set the absolute demodulator center frequency of channel 0 to 11.01 MHz:

int32_t hDevice; //Handle to G31DDC device returned by the OpenDevice function

//1. method
SetDDC1Frequency(hDevice,11010000);
SetDDC2Frequency(hDevice,0,0);
SetDemodulatorFrequency(hDevice,0,0);

//2. method
SetDDC1Frequency(hDevice,11000000);
SetDDC2Frequency(hDevice,0,10000);
SetDemodulatorFrequency(hDevice,0,0);

//3. method
SetDDC1Frequency(hDevice,11020000);
SetDDC2Frequency(hDevice,0,-5000);
SetDemodulatorFrequency(hDevice,0,-5000);

//4. method
SetFrequency(hDevice,0,11010000); 
//The SetFrequency function sets DDC1, DDC2 and demodulator
//center frequencies so that demodulator's absolute frequency is set to the required frequency

GetDemodulatorFrequency

Retrieves current relative center frequency of the demodulator for given channel.

C/C++ declaration

int  GetDemodulatorFrequency(int32_t hDevice,uint32_t Channel,int32_t *Frequency);

Address retrieval

G31DDC_GET_DEMODULATOR_FREQUENCY GetDemodulatorFrequency=
    (G31DDC_GET_DEMODULATOR_FREQUENCY)dlsym(hAPI,"GetDemodulatorFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[out] Pointer to a variable that receives the current center frequency of the demodulator. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetDemodulatorParam

Sets a parameter of the demodulation for given channel.

C/C++ declaration

int  SetDemodulatorParam(int32_t hDevice,uint32_t Channel,uint32_t Code,const VOID *Buffer,uint32_t BufferSize);

Address retrieval

G31DDC_SET_DEMODULATOR_PARAM SetDemodulatorParam=
    (G31DDC_SET_DEMODULATOR_PARAM)dlsym(hAPI,"SetDemodulatorParam");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Code
[in] Specifies code of the demodulator parameter to be set by the function. The code can be one of the following:

ValueMeaning
G3XDDC_DEMODULATOR_PARAM_AMS_SIDE_BAND

Side band for synchronous AM demodulation.

The Buffer parameter has to be a pointer to an uint32_t variable, and the BufferSize parameter has to be sizeof(UINT32).

Value of the variable pointed to by the Buffer parameter can be one of the following:

G3XDDC_SIDE_BAND_LOWER
AMS demodulator will use lower sideband

G3XDDC_SIDE_BAND_UPPER
AMS demodulator will use upper sideband

G3XDDC_SIDE_BAND_BOTH
AMS demodulator will use both side bands.

G3XDDC_DEMODULATOR_PARAM_AMS_CAPTURE_RANGE

Capture range of synchronous AM demodulator.

The Buffer parameter has to be a pointer to a G3XDDC_AMS_CAPTURE_RANGE structure, and the BufferSize parameter has to be sizeof(G3XDDC_AMS_CAPTURE_RANGE).

G3XDDC_DEMODULATOR_PARAM_CW_FREQUENCY

CW tone frequency

The Buffer parameter has to be a pointer to a int32_t variable, and the BufferSize parameter has to be sizeof(INT32).

Value of the variable pointed to by the Buffer parameter is CW tone frequency in Hz.

G3XDDC_DEMODULATOR_PARAM_DSB_SIDE_BAND

Side band for DSB demodulation.

The Buffer parameter has to be a pointer to an uint32_t variable, and the BufferSize parameter has to be sizeof(UINT32).

Value of the variable pointed to by the Buffer parameter can be one of the following:

G3XDDC_SIDE_BAND_LOWER
DSB demodulator will use lower sideband

G3XDDC_SIDE_BAND_UPPER
DSB demodulator will use upper sideband

G3XDDC_SIDE_BAND_BOTH
DSB demodulator will use both side bands.

G3XDDC_DEMODULATOR_PARAM_ISB_SIDE_BAND

Side band for ISB demodulation.

The Buffer parameter has to be a pointer to an uint32_t variable, and the BufferSize parameter has to be sizeof(UINT32).

Value of the variable pointed to by the Buffer parameter can be one of the following:

G3XDDC_SIDE_BAND_LOWER
ISB demodulator will use lower sideband

G3XDDC_SIDE_BAND_UPPER
ISB demodulator will use upper sideband

G3XDDC_SIDE_BAND_BOTH
ISB demodulator will use both side bands.

Buffer
[in] Pointer to a buffer containing the value of the demodulator parameter which the function will set. This parameter cannot be NULL.
BufferSize
[in] Specifies the size of the buffer.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetDemodulatorParam

Retrieves a parameter of the demodulation for given channel.

C/C++ declaration

int  GetDemodulatorParam(int32_t hDevice,uint32_t Channel,uint32_t Code,VOID *Buffer,uint32_t BufferSize);

Address retrieval

G31DDC_GET_DEMODULATOR_PARAM GetDemodulatorParam=
    (G31DDC_GET_DEMODULATOR_PARAM)dlsym(hAPI,"GetDemodulatorParam");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Code
[in] Specifies code of the demodulator parameter to be retrieved. For detailed information about available codes see SetDemodulatorParam.
Buffer
[out] Pointer to a buffer that receives requested parameter. This parameter cannot be NULL.
BufferSize
[in] Specifies the size of the buffer.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

GetDemodulatorState

Retrieves information about current demodulator state for given channel.

C/C++ declaration

int  GetDemodulatorState(int32_t hDevice,uint32_t Channel,uint32_t Code,VOID *Buffer,uint32_t BufferSize);

Address retrieval

G31DDC_GET_DEMODULATOR_STATE GetDemodulatorState=
    (G31DDC_GET_DEMODULATOR_STATE)dlsym(hAPI,"GetDemodulatorState");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Code
[in] Specifies code of the demodulator state to be retrieved. It can be one of the following:

ValueMeaning
G3XDDC_DEMODULATOR_STATE_AMS_LOCK

Lock state of synchronous AM demodulation.

The Buffer parameter has to be a pointer to an int variable, and the BufferSize parameter has to be sizeof(BOOL).

Received value is non-zero if synchronous AM demodulator is locked to signal, and zero if it is not locked.

G3XDDC_DEMODULATOR_STATE_AMS_FREQUENCY

Frequency in Hz which synchronous AM demodulator is locked to. It is relative to center of the demodulator. It can be negative.

The Buffer parameter has to be a pointer to a double variable, and the BufferSize parameter has to be sizeof(double).

G3XDDC_DEMODULATOR_STATE_AM_DEPTH

Depth of AM modulation in %.

The Buffer parameter has to be a pointer to a double variable, and the BufferSize parameter has to be sizeof(double).

G3XDDC_DEMODULATOR_STATE_DSB_LOCK

Lock state of DSB demodulation.

The Buffer parameter has to be a pointer to an int variable, and the BufferSize parameter has to be sizeof(BOOL).

Received value is non-zero if DSB demodulator is locked to signal, and zero if it is not locked.

G3XDDC_DEMODULATOR_STATE_DSB_FREQUENCY

Frequency in Hz which DSB demodulator is locked to. It is relative to center of the demodulator. It can be negative.

The Buffer parameter has to be a pointer to a double variable, and the BufferSize parameter has to be sizeof(double).

G3XDDC_DEMODULATOR_STATE_TUNE_ERROR

Estimated tune error in Hz.

The Buffer parameter has to be a pointer to an int32_t variable, and the BufferSize parameter has to be sizeof(INT32).

Received value is a difference between demodulator frequency and frequency of received signal. Subtract the returned tune error from demodulator frequency to get frequency of the received signal. Tune error is relative to center of the demodulator and it can be negative.

G3XDDC_DEMODULATOR_STATE_FM_DEVIATION

Estimated frequency deviation in Hz.

The Buffer parameter has to be a pointer to an uint32_t variable, and the BufferSize parameter has to be sizeof(UINT32).

Buffer
[out] Pointer to a buffer that receives requested information. This parameter cannot be NULL.
BufferSize
[in] Specifies the size of the buffer.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

StartAudio

Starts audio streaming for given channel.

C/C++ declaration

int  StartAudio(int32_t hDevice,uint32_t Channel,uint32_t SamplesPerBuffer);

Address retrieval

G31DDC_START_AUDIO StartAudio=(G31DDC_START_AUDIO)dlsym(hAPI,"StartAudio");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
SamplesPerBuffer
[in] Specifies number of samples in each buffer passed to the AudioStreamCallback callback function. The value has to be a multiple of 64 greater than zero. If it is zero, the StartAudio function fails. If it is not a multiple of 64 the function rounds it up to nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Before StartAudio is used, the G31DDC device has to be turned on using the SetPower function and DDC1 streaming has to be started using the StartDDC1 or StartDDC1Playback function and DDC2 streaming has to be started using the StartDDC2 function, otherwise StartAudio fails.

If the audio streaming for given channel is already running, StartAudio restarts it except when the streaming was previously started with the same SamplesPerBuffer parameter. In this case StartAudio does nothing.

Use the StopAudio function to stop audio streaming.

Decreasing the value of the SamplesPerBuffer parameter decreases latency and it may increase CPU usage. Increasing the value of the SamplesPerBuffer parameter increases latency and may decrease CPU usage.


StopAudio

Stops audio streaming for given channel.

C/C++ declaration

int  StopAudio(int32_t hDevice,uint32_t Channel);

Address retrieval

G31DDC_STOP_AUDIO StopAudio=(G31DDC_STOP_AUDIO)dlsym(hAPI,"StopAudio");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If audio streaming is not active, StopAudio does nothing.

If audio playback (started using the StartAudioPlayback function) is active, StopAudio stops it.

The AudioStreamCallback and AudioPlaybackStreamCallback callback functions are not called after StopAudio returns.


StartAudioPlayback

Starts audio playback for given channel. It allows passing of previously recorded audio samples to the processing chain instead of the samples from the demodulator.

C/C++ declaration

int  StartAudioPlayback(int32_t hDevice,uint32_t Channel,uint32_t SamplesPerBuffer);

Address retrieval

G31DDC_START_AUDIO_PLAYBACK StartAudioPlayback=(G31DDC_START_AUDIO_PLAYBACK)dlsym(hAPI,"StartAudioPlayback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
SamplesPerBuffer
[in] Specifies number of samples in each buffer passed to the AudioPlaybackStreamCallback callback to fill the buffer by the application and to the AudioStreamCallback callback function. The value has to be a multiple of 64 greater than zero. If it is zero, the StartAudioPlayback function fails. If it is not a multiple of 64 the function rounds it up to nearest a multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The G31DDC device has to be turned on using SetPower function before use of StartAudioPlayback.

The StartAudioPlayback function stops audio streaming which was previously started by the StartAudio or StartAudioPlayback function and starts audio playback with new parameters.

Use the StopAudio function to stop audio playback.


PauseAudioPlayback

Pauses audio playback for given channel.

C/C++ declaration

int  PauseAudioPlayback(int32_t hDevice,uint32_t Channel);

Address retrieval

G31DDC_PAUSE_AUDIO_PLAYBACK PauseAudioPlayback=(G31DDC_PAUSE_AUDIO_PLAYBACK)dlsym(hAPI,"PauseAudioPlayback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If audio playback is not active or it is already paused, PauseAudioPlayback does nothing.

The AudioPlaybackStreamCallback and AudioStreamCallback callback functions can be called once after PauseAudioPlayback returns. Then they are not called until playback is resumed using the ResumeAudioPlayback function.


ResumeAudioPlayback

Resumes paused audio playback for given channel.

C/C++ declaration

int  ResumeAudioPlayback(int32_t hDevice,uint32_t Channel);

Address retrieval

G31DDC_RESUME_AUDIO_PLAYBACK ResumeAudioPlayback=(G31DDC_RESUME_AUDIO_PLAYBACK)dlsym(hAPI,"ResumeAudioPlayback");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If audio playback is not active or it is not paused, ResumeAudioPlayback does nothing.


SetAudioGain

Sets fixed audio gain for given channel.

C/C++ declaration

int  SetAudioGain(int32_t hDevice,uint32_t Channel,double Gain);

Address retrieval

G31DDC_SET_AUDIO_GAIN SetAudioGain=(G31DDC_SET_AUDIO_GAIN)dlsym(hAPI,"SetAudioGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[in] Specifies new fixed audio gain in dB.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetAudioGain function to retrieve the current audio gain.

GetAudioGain

Retrieves current fixed audio gain for given channel.

C/C++ declaration

int  GetAudioGain(int32_t hDevice,uint32_t Channel,double *Gain);

Address retrieval

G31DDC_GET_AUDIO_GAIN GetAudioGain=(G31DDC_GET_AUDIO_GAIN)dlsym(hAPI,"GetAudioGain");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[out] Pointer to a variable that receives the current fixed gain in dB. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAudioFilter

Enables or disables audio filter for given channel.

C/C++ declaration

int  SetAudioFilter(int32_t hDevice,uint32_t Channel,int Enabled);

Address retrieval

G31DDC_SET_AUDIO_FILTER SetAudioFilter=(G31DDC_SET_AUDIO_FILTER)dlsym(hAPI,"SetAudioFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[in] Specifies whether to enable or disable the audio filter. If this parameter is non-zero, the filter is enabled. If the parameter is zero, the filter is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetAudioFiler function to retrieve the current state of the audio filter.

GetAudioFilter

Retrieves current state of the audio filter for given channel.

C/C++ declaration

int  GetAudioFilter(int32_t hDevice,uint32_t Channel,int *Enabled);

Address retrieval

G31DDC_GET_AUDIO_FILTER GetAudioFilter=(G31DDC_GET_AUDIO_FILTER)dlsym(hAPI,"GetAudioFilter");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[out] Pointer to a variable that receives the current state of the audio filter. The value is non-zero if the filter is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAudioFilterParams

Sets parameters of the audio filter for given channel.

C/C++ declaration

int  SetAudioFilterParams(int32_t hDevice,uint32_t Channel,uint32_t CutOffLow,uint32_t CutOffHigh,double Deemphasis);

Address retrieval

G31DDC_SET_AUDIO_FILTER_PARAMS SetAudioFilterParams=
    (G31DDC_SET_AUDIO_FILTER_PARAMS)dlsym(hAPI,"SetAudioFilterParams");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
CutOffLow
[in] Specifies cut-off low frequency of the filter in Hz. This is the start frequency of the filter's passband, it can be in the range of 0 to 23999 Hz. The value has to be less then the cut-off high frequency specified by the CutOffHigh parameter.
CutOffHigh
[in] Specifies cut-off high frequency of the filter in Hz. This is the end frequency of filter's passband it can be in the range of 1 - 24000 Hz. The value has to be greater than the cut-off low frequency specified by the CutOffLow parameter.
Deemphasis
[in] Specifies de-emphasis for the filter in dB per octave. De-emphasis starts at the cut-off low frequency of the filter. This value can be in the range of -9.9 to 0.0 dB/octave. Zero means that de-emphasis is disabled.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetAudioFilerParams function to retrieve the current parameters of the audio filter.

GetAudioFilterParams

Retrieves current parameters of the audio filter for given channel.

C/C++ declaration

int  GetAudioFilterParams(int32_t hDevice,uint32_t Channel,uint32_t *CutOffLow,uint32_t *CutOffHigh,double *Deemphasis);

Address retrieval

G31DDC_GET_AUDIO_FILTER_PARAMS GetAudioFilterParams=
    (G31DDC_GET_AUDIO_FILTER_PARAMS)dlsym(hAPI,"GetAudioFilterParams");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
CutOffLow
[out] Pointer to a variable that receives the current cut-off low frequency of the filter. This parameter can be NULL if the application does not require this information.
CutOffHigh
[out] Pointer to a variable that receives the current cut-off high frequency of the filter. This parameter can be NULL if the application does not require this information.
Deemphasis
[out] Pointer to a variable that receives the current de-emphasis setting of the filter. This parameter can be NULL if the application does not require this information.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetAudioFilterLength

Specifies audio filter length for given channel. The audio filter is implemented as an FIR filter. This function specifies number of coefficients used in filtration procedure.

C/C++ declaration

int  SetAudioFilterLength(int32_t hDevice,uint32_t Channel,uint32_t Length);

Address retrieval

G31DDC_SET_AUDIO_FILTER_LENGTH SetAudioFilterLength=
        (G31DDC_SET_AUDIO_FILTER_LENGTH)dlsym(hAPI,"SetAudioFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[in] Specifies length of the audio filter. The value has to be a multiple of 64, greater than or equal to 64 and less than or equal to 32768. If it is not a multiple of 64 the function rounds it up to a nearest multiple of 64.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Increasing the filter length increases filter steepness and may increase CPU usage.

Use the GetAudioFilterLength function to determine the current length of the audio filter.


GetAudioFilterLength

Retrieves current audio filter length for given channel.

C/C++ declaration

int  GetAudioFilterLength(int32_t hDevice,uint32_t Channel,uint32_t *Length);

Address retrieval

G31DDC_GET_AUDIO_FILTER_LENGTH GetAudioFilterLength=
        (G31DDC_GET_AUDIO_FILTER_LENGTH)dlsym(hAPI,"GetAudioFilterLength");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[out] Pointer to a variable that receives the current length of the audio filter. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetVolume

Sets audio volume for given channel.

C/C++ declaration

int  SetVolume(int32_t hDevice,uint32_t Channel,uint8_t Volume);

Address retrieval

G31DDC_SET_VOLUME SetVolume=(G31DDC_SET_VOLUME)dlsym(hAPI,"SetVolume");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Volume
[in] Specifies new volume. The value can vary from 0 to 31, where 31 means maximum volume.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetVolume function to retrieve the current volume.


GetVolume

Retrieve current volume for given channel.

C/C++ declaration

int  GetVolume(int32_t hDevice,uint32_t Channel,uint8_t *Volume);

Address retrieval

G31DDC_GET_VOLUME GetVolume=(G31DDC_GET_VOLUME)dlsym(hAPI,"GetVolume");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Volume
[out] Pointer to a variable that receives the current volume. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetMute

Mutes or unmutes audio.

C/C++ declaration

int  SetMute(int32_t hDevice,uint32_t Channel,int Mute);

Address retrieval

G31DDC_SET_MUTE SetMute=(G31DDC_SET_MUTE)dlsym(hAPI,"SetMute");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Mute
[in] Specifies whether to mute or unmute audio. If this parameter is non-zero, the audio is muted. If the parameter is zero, the audio is unmuted.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Use the GetMute function to retrieve the current mute state.


GetMute

Retrieves current mute state for given channel.

C/C++ declaration

int  GetMute(int32_t hDevice,uint32_t Channel,int *Mute);

Address retrieval

G31DDC_GET_MUTE GetMute=(G31DDC_GET_MUTE)dlsym(hAPI,"GetMute");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Mute
[out] Pointer to a variable that receives the current mute state. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

SetFrequency

Sets absolute frequency of the demodulator for given channel.

C/C++ declaration

int  SetFrequency(int32_t hDevice,uint32_t Channel,uint32_t Frequency);

Address retrieval

G31DDC_SET_FREQUENCY SetFrequency=(G31DDC_SET_FREQUENCY)dlsym(hAPI,"SetFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[in] Specifies new absolute frequency of the demodulator in Hz.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The function sets DDC1, DDC2 and demodulator frequencies so that the new absolute frequency of the demodulator is the required one.

Absolute frequency of the demodulator is given by the following formula:

faDEM[i] = fDDC1 + frDDC2[i] + frDEM[i]

Where faDEM[i] is absolute center frequency of the demodulator of i-th channel in Hz, fDDC1 is center frequency of the DDC1 in Hz (set using the SetDDC1Frequency function), frDDC2[i] is relative center frequency of DDC2 of i-th channel in Hz (set using the SetDDC2Frequency) and frDEM[i] is relative center frequency of the demodulator of i-th channel in Hz (set using the SetDemodulatorFrequency function).

Absolute center frequency of the demodulator is the real-world frequency that you are listening to.

Use the GetFrequency function to retrieve the current absolute frequency of the demodulator.


GetFrequency

Determines absolute frequency of the demodulator for the given channel.

C/C++ declaration

int  GetFrequency(int32_t hDevice,uint32_t Channel,uint32_t *Frequency);

Address retrieval

G31DDC_GET_FREQUENCY GetFrequency=(G31DDC_GET_FREQUENCY)dlsym(hAPI,"GetFrequency");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[out] Pointer to a variable that receives the current absolute frequency of the demodulator. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

Returned value of the variable pointed to by the Frequency parameter is sum of DDC1, DDC2 and demodulator relative frequency. For more information, see remarks of the SetFrequency function.

GetSpectrumCompensation

Determines compensation data for frequency spectrum computed from DDC1 or DDC2 signal. It is used to convert relative amplitudes in dB to absolutes ones in dBm.

C/C++ declaration

int  GetSpectrumCompensation(int32_t hDevice,UINT64 CenterFrequency,uint32_t Width,float *Buffer,uint32_t Count);

Address retrieval

G31DDC_GET_SPECTRUM_COMPENSATION GetSpectrumCompensation=
    (G31DDC_GET_SPECTRUM_COMPENSATION)dlsym(hAPI,"GetSpectrumCompensation");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
CenterFrequency
[in] Specifies absolute center frequency of requested compensation data in Hz.
Width
[in] Specifies width of requested compensation data in Hz.
Buffer
[out] Pointer to a buffer to be filled with compensation data. This parameter cannot be NULL.
Count
[in] Specifies number of float items in the buffer pointed to by the Buffer parameter.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

The following example shows how to use the GetSpectrumCompensation function in DDC2StreamCallback callback function:

//Let the following is prototype of a function which computes FFT from I/Q signal stored in
//the buffer pointed to be the Input parameter. Result is stored in complex form in the buffer
//pointed to by the Output parameter. Size of the FFT is given be the Size parameter.
//The example uses 2048 bins FFT.
void FFT(float *Output,const float *Input,int Size);

int32_t hDevice; //handle to G31DDC device
uint32_t AbsDDC2Frequency; //Absolute frequency of the DDC2
int32_t RelDDC2Frequency; //Relative frequency of the DDC2
uint32_t DDC1Frequency; //DDC1 frequency
G3XDDC_DDC_INFO DDC2Info; //Information about the current DDC type of the DDC2
float FFTBuffer[2*2048]; //Buffer for FFT result
float Compensation[2048]; //Buffer for compensation data
uint32_t FirstBin,LastBin; //the first and last bins in the FFT of useful DDC2 band
G31DDC_CALLBACKS Callbacks; //Structure which contains pointer to callback functions

Code before...

//Retrieve frequency of the DDC1
GetDDC1Frequency(hDevice,&DDC1Frequency);

//Retrieve relative frequency of the DDC2 for channel 0
GetDDC2Frequency(hDevice,0,&RelDDC2Frequency);

//Calculate absolute frequency of the DDC2
AbsDDC2Frequency=(INT32)DDC1Frequency+RelDDC2Frequency;

//Retrieve DDC type information of the DDC2
GetDDC2(hDevice,NULL,&DDC2Info);

//Retrieve compensation data
GetSpectrumCompensation(hDevice,AbsDDC2Frequency,DDC2Info.SampleRate,Compensation,2048);
//In this case the Width parameter is equal to sample rate, because we need compensation data
//for whole DDC2 band.
//Compensation data have to be updated after change of absolute DDC2 frequency using
//the SetDDC1Frequency or SetDDC2Frequency function.
//In this case a mutual-exclusion synchronization method (for example critical section) should be used 
//if the Compensation buffer would be modified outside the MyDDC2StreamCallback callback.

FirstBin=2048*(DDC2Info.SampleRate-DDC2Info.Bandwidth)/2/DDC2Info.SampleRate;
LastBin=2048*(DDC2Info.SampleRate+DDC2Info.Bandwidth)/2/DDC2Info.SampleRate;

//Set callback function for DDC2 streaming
//Pointers to callback function which should not be called by the API have to be set to NULL.
Callbacks.DDC2StreamCallback=MyDDC2StreamCallback;

//Start DDC2 streaming for channel 0
//The SamplesPerBuffer parameter is set to 2048 which is size of the FFT to simplify
//the example.
StartDDC2(hDevice,0,2048);

Code after...
    
void  MyDDC2StreamCallback(uint32_t Channel,const float *Buffer,uint32_t NumberOfSamples,uintptr_t UserData)
{
 uint32_t i;
 
    //Compute FFT
    FFT(FFTBuffer,Buffer,2048);
    
    //Converts complex FFT result to dB
    for(i=0;i<2048;i++)
    {
        FFTBuffer[i]=(float)(10.0*log10(FFTBuffer[i*2]*FFTBuffer[i*2]+FFTBuffer[i*2+1]*FFTBuffer[i*2+1]));
    }
    
    //Apply compensation data to get amplitudes in frequency spectrum in dBm
    for(i=0;i<2048;i++)
    {
        FFTBuffer[i]+=Compensation[i];
    }
    
    //now the FFTBuffer contains amplitudes in dBm
    //Useful band starts at the bin given by the FirstBin variable
    //and ends at the bin given by the LastBin variable.
}


SetCallbacks

Registers user-defined functions as callback functions called by the API.

C/C++ declaration

int  SetCallbacks(int32_t hDevice,const G31DDC_CALLBACKS *Callbacks,uintptr_t UserData);

Address retrieval

G31DDC_SET_CALLBACKS SetCallbacks=(G31DDC_SET_CALLBACKS)dlsym(hAPI,"SetCallbacks");

Parameters

hDevice
[in] Handle to G31DDC device returned by the OpenDevice function.
Callbacks
[in] Pointer to a G31DDC_CALLBACKS structure which contains pointers to the user-defined function to be registered as callback functions.
UserData
[in] Specifies a user-defined value which is passed to callback functions.

Return value

If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, check errno.

Remarks

If the application does not require that the API calls some callback function, set related member of the G31DDC_CALLBACKS structure to NULL.

If value of the Callbacks parameter is NULL, all the callback functions are unregistered, the API will not call any callback function.


Structures

G31DDC_DEVICE_INFO

Contains information about G31DDC device.

C/C++ declaration

#pragma pack(push,1)

typedef struct
{
    char        DevicePath[MAX_PATH];
    uint8_t        InterfaceType;
    char        SerialNumber[9];
    uint16_t        HWVersion;
    uint16_t        FWVersion;
    uint8_t        EEPROMVersion;    
    uint32_t      Flags;
    uint32_t      ChannelCount;
    uint32_t      DDCTypeCount;   
} G31DDC_DEVICE_INFO;

#pragma pack(pop

Members

DevicePath
Device system path in a null-terminated string. It is used to open the device using object interface.
InterfaceType

Device interface type. The value can be one of the following:

G3XDDC_INTERFACE_TYPE_PCIE
The device is connected to the computer via PCI express.

G3XDDC_INTERFACE_TYPE_USB
The device is connected to the computer via USB.

SerialNumber
Serial number in null-terminated string.
HWVersion
Version of the hardware.
FWVersion
Version of the firmware.
EEPROMVersion
EEPROM structure version.
Flags
Reserved.
ChannelCount
Number of channels.
DDCTypeCount
Number of DDC types supported by the DDC1.

G3XDDC_DDC_INFO

Contains information about DDC type.

C/C++ declaration

#pragma pack(push,1)

typedef struct
{
    uint32_t  SampleRate;
    uint32_t  Bandwidth;
    uint32_t  BitsPerSample;
} G3XDDC_DDC_INFO;

#pragma pack(pop

Members

SampleRate
Sample rate of I/Q signal in Hz.
Bandwidth
Useful bandwidth in Hz.
BitsPerSample
Number of bits per sample. It can be 16 or 32. It is used to determine bits per sample for DDC1.

G3XDDC_AMS_CAPTURE_RANGE

Contains information about DDC type.

C/C++ declaration

#pragma pack(push,1)

typedef struct
{
    uint32_t  Tune;
    uint32_t  Lock;
} G3XDDC_AMS_CAPTURE_RANGE;

#pragma pack(pop

Members

Tune
Initial capture range in Hz.
Lock
Capture range (in Hz) used when AMS demodulator is locked.

G31DDC_CALLBACKS

Contains pointers to user-defined functions to be registered as callback functions.

Each callback function is called in context of the thread created by the API. If shared data is accessed inside callback functions, it is recommended use a mutual-exclusion synchronization method. The application should not call any G31DDC API functions from inside callback functions, otherwise it can cause deadlock or the application may be placed into an unpredictable state.

C/C++ declaration

#pragma pack(push,1)

typedef struct
{
    G31DDC_IF_CALLBACK                          IFCallback;
    G31DDC_DDC1_STREAM_CALLBACK                 DDC1StreamCallback;
    G31DDC_DDC1_PLAYBACK_STREAM_CALLBACK        DDC1PlaybackStreamCallback;
    G31DDC_DDC2_STREAM_CALLBACK                 DDC2StreamCallback;
    G31DDC_DDC2_PREPROCESSED_STREAM_CALLBACK    DDC2PreprocessedStreamCallback;
    G31DDC_AUDIO_STREAM_CALLBACK                AudioStreamCallback;
    G31DDC_AUDIO_PLAYBACK_STREAM_CALLBACK       AudioPlaybackStreamCallback;
} G31DDC_CALLBACKS;

#pragma pack(pop)

Members

IFCallback

Pointer to a user-defined function to be registered as IF callback. It is called by the API to pass IF snapshots to the application. Sending of IF snapshots is started using the StartIF function.

C/C++ declaration

VOID  IFCallback(const SHORT *Buffer,uint32_t NumberOfSamples,uint16_t MaxADCAmplitude,uint32_t ADCSamplingRate,uintptr_t UserData);

Parameters

Buffer
Pointer to the buffer which contains samples directly received from ADC. Sample rate is 100 MHz, sample is 16bit signed little endian.
NumberOfSamples
Specifies number of samples in the buffer pointed to be the Buffer parameter. This is usually 65536.
MaxADCAmplitude
Specifies maximum amplitude. Measurement of the maximum is started at the end of the previous snapshot to the current one. The possible value range is 0 to 32767.
ADCSamplingRate
Specifies sample rate of the ADC in Hz. It can vary a little bit because of temperature instability.
UserData
User-defined data. It is a value passed to the SetCallbacks function as the UserData parameter.
DDC1StreamCallback

Pointer to a user-defined function to be registered as DDC1 stream callback. It is called by the API to pass I/Q samples from DDC1 to the application. The DDC1 streaming can be started using the StartDDC1 or StartDDC1Playback function.

C/C++ declaration

VOID  DDC1StreamCallback(const VOID *Buffer,uint32_t NumberOfSamples,uint32_t BitsPerSample,uintptr_t UserData);

Parameters

Buffer
Pointer to the buffer which contains I/Q sample sets from DDC1. Sample rate and bits per sample is given by used DDC type, see the SetDDC1 function. One I/Q sample set consists of two samples.
NumberOfSamples
Specifies number of I/Q sample sets in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartDDC1 or StartDDC1Playback function.
BitsPerSample
Specifies number of bits per sample. It is given by DDC type used for DDC1 and it can be 16 or 32. If it is 16, sample is 16bit integer (32bits per I/Q sample set), signed, little endian, from range -32768 to 32767. If it is 32, sample is 32bit integer (64bits per I/Q sample set), signed, little endian, from range -2147483648 to 2147483647.
UserData
User-defined data. It is value passed to the SetCallbacks function as the UserData parameter.
DDC1PlaybackStreamCallback

Pointer to a user-defined function to be registered as DDC1 playback stream callback. It is called by the API to fill the buffer with I/Q samples by the application. The DDC1 playback can be started using the StartDDC1Playback function.

C/C++ declaration

int  DDC1PlaybackStreamCallback(VOID *Buffer,uint32_t NumberOfSamples,uint32_t BitsPerSample,uintptr_t UserData);

Parameters

Buffer
Pointer to the buffer to be filled with I/Q sample sets. Sample rate and bits per sample is given by used DDC type, see the SetDDC1 function.
NumberOfSamples
Specifies number of I/Q sample sets to be stored to the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartDDC1Playback function. If the application does not have requested number of sample sets, it has to fill the buffer with zeros. One I/Q sample set consists of two samples.
BitsPerSample
Specifies number of bits per sample. It is given by DDC type used for DDC1 and it can be 16 or 32. If it is 16, sample is 16bit integer (32bits per I/Q sample set), signed, little endian, from range -32768 to 32767. If it is 32, sample is 32bit integer (64bits per I/Q sample set), signed, little endian, from range -2147483648 to 2147483647.
UserData
User-defined data. It is value passed to the SetCallbacks function as the UserData parameter.

Return value

The application should return non-zero to continue playback. The application should return zero to stop the API to call DDC1PlaybackStreamCallback again. This does not stop DDC1 playback, it has to be done explicitly by the application calling the StopDDC1 function from the thread in which the device was open using the OpenDevice function. StopDDC1 must not be called from inside the callback function.
DDC2StreamCallback

Pointer to a user-defined function to be registered as DDC2 stream callback. It is called by the API to pass I/Q samples from DDC2 to the application. The DDC2 streaming can be started using the StartDDC2 function.

C/C++ declaration

VOID  DDC2StreamCallback(uint32_t Channel,const float *Buffer,uint32_t NumberOfSamples,uintptr_t UserData);

Parameters

Channel
Specifies channel index. It can be 0, 1, 2.
Buffer
Pointer to the buffer which contains I/Q sample sets from DDC2. Sample rate is given by the DDC type of the DDC2. Use the GetDDC2 function to determine current DDC type of the DDC2. Sample is 32bit IEEE float from range -1.0 to 1.0. One I/Q sample set consists of two samples.
NumberOfSamples
Specifies number of I/Q sample sets in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartDDC2 function.
UserData
User-defined data. It is value passed to the SetCallbacks function as the UserData parameter.
DDC2PreprocessedStreamCallback

Pointer to a user-defined function to be registered as preprocessed DDC2 stream callback. It is called by the API to pass preprocessed I/Q samples from DDC2 to the application. The samples are filtered by the demodulator filter, notch filter and affected by AGC or fixed gain. The DDC2 streaming can be started using the StartDDC2 function.

C/C++ declaration

VOID  DDC2PreprocessedStreamCallback(uint32_t Channel,const float *Buffer,uint32_t NumberOfSamples,
            float SlevelPeak,float SlevelRMS,uintptr_t UserData);

Parameters

Channel
Specifies channel index. It can be 0, 1, 2.
Buffer
Pointer to the buffer which contains preprocessed I/Q sample sets from DDC2. Sample rate is given by the DDC type of the DDC2. Use the GetDDC2 function to determine the current DDC type of the DDC2. Sample is 32bit IEEE float from range -1.0 to 1.0. One I/Q sample set consists of two samples.
NumberOfSamples
Specifies number of I/Q sample sets in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartDDC2 function.
SlevelPeak
Specifies peak signal level in Volts evaluated from samples stored in the buffer pointed to by the Buffer parameter.
SlevelRMS
Specifies RMS signal level in Volts evaluated from samples stored in the buffer pointed to by the Buffer parameter. For detailed information how to convert RMS signal level to dBm, see remarks of the GetSignalLevel function.
UserData
User-defined data. It is a value passed to the SetCallbacks function as the UserData parameter.
AudioStreamCallback

Pointer to a user-defined function to be registered as an audio stream callback. It is called by the API to pass audio samples to the application. The audio streaming can be started using the StartAudio or StartAudioPlayback functions. The callback is invoked three times for each audio buffer (see description of the Type parameter).

C/C++ declaration

VOID  AudioStreamCallback(uint32_t Channel,uint32_t Type,const float *Buffer,uint32_t NumberOfSamples,uintptr_t UserData);

Parameters

Channel
Specifies channel index. It can be 0, 1.
Type
Specifies type (stage) of audio samples stored in the buffer pointed to by the Buffer parameter. Value of this parameter can be one of the following:

ValueMeaning
0The buffer contains audio samples affected by audio gain (see SetAudioGain).
1The buffer contains audio samples affected by audio gain and audio filter (see SetAudioGain and SetAudioFilter).
2The buffer contains audio samples affected by audio gain, audio filter and volume (see SetAudioGain, SetAudioFilter, SetVolume and SetMute).
Buffer
Pointer to the buffer which contains samples of audio signal. The signal is mono, sample rate is 48000 Hz, sample is 32bit IEEE float from range -1.0 to 1.0.
NumberOfSamples
Specifies number of samples stored in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartAudio or StartAudioPlayback function.
UserData
User-defined data. It is value passed to the SetCallbacks function as the UserData parameter.
AudioPlaybackStreamCallback

Pointer to a user-defined function to be registered as an audio playback stream callback. It is called by the API to fill the buffer with audio samples by the application. The audio playback can be started using the StartAudioPlayback function.

C/C++ declaration

int  AudioPlaybackStreamCallback(uint32_t Channel,float *Buffer,uint32_t NumberOfSamples,uintptr_t UserData);

Parameters

Channel
Specifies channel index. It can be 0, 1, 2.
Buffer
Pointer to the buffer to by filled with audio samples. The audio signal is mono, sample rate is 48000 Hz, sample is 32bit IEEE float from range -1.0 to 1.0.
NumberOfSamples
Specifies number of samples in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the StartAudioPlayback function. If the application does not have requested number of samples, the application has to fill the buffer with zeros.
UserData
User-defined data. It is value passed to the SetCallbacks function as the UserData parameter.

Return value

The application should return non-zero to continue playback. The application should return zero to stop the API to call AudioPlaybackStreamCallback again. This does not stop audio playback, it has to be done explicitly by the application calling the StopAudio function from the thread in which the device was open using the OpenDevice function. StopAudio must not be called from inside the callback function.