Programming Information for WiNRADiO G31DDC HF receiver.

The WR-G31DDC API SDK is implemented as a 32-bit dynamic library (G31DDCAPI.dll). It provides object-oriented and non-object-oriented interface to control the WR-G31DDC device. This document describes the object-oriented interface. The G31DDCAPI.dll library provides several object types that make it possible to control G31DDC receivers.

The API is not fully thread-safe so preferrably 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. The API can be used by any 32-bit applications under Microsoft Windows 2000, XP, Vista and Windows 7 (including their 64-bit versions).

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 G31DDCAPI.dll library can be loaded to the application by two Microsoft Windows API functions. The first one is LoadLibrary and the other one is LoadLibraryEx. After the library is loaded, it is required to get addresses of exported functions. When the API is no longer required in the memory, the FreeLibrary function can be used to unload the API. Before the FreeLibrary is called, all the objects created using CreateInstance function must be freed releasing their interfaces using the Release method, otherwise the application can enter an unpredictable state.

The following source code shows how to load the API.

 

#include <stdio.h>

#include "G31DDCAPI.h"



G3XDDCAPI_CREATE_INSTANCE CreateInstance;

HMODULE hAPI;



void main(void)

{  

    //Loading the API

    hAPI=LoadLibrary("G31DDCAPI.dll");



    if(hAPI!=NULL)

    {

        //Retrieving address of the CreateInstance function

        CreateInstance=(G3XDDCAPI_CREATE_INSTANCE)GetProcAddress(hAPI,"CreateInstance");



        //Here place code that uses the API



        FreeLibrary(hAPI);

    }

    else

    {

        //If the LoadLibrary fails

        printf("Failed to load G31DDCAPI.dll.\n");

    }

}

Enumerating available G31DDC devices

To enumerate available WR-G31DDC devices the API provides an enumeration object. The object has to be created using the CreateInstance function. The following source code in C++ produces list of serial numbers of available G31DDC devices.


#include <stdio.h>

#include "G31DDCAPI.h"



void main(void)

{

 G3XDDCAPI_CREATE_INSTANCE CreateInstance;

 HMODULE hAPI;

 IG31DDCDeviceEnumerator *Enumerator=NULL;

 G31DDC_DEVICE_INFO DevInfo;

 UINT32 Index;

 UINT32 Count;



    hAPI=LoadLibrary("G31DDCAPI.dll");



    if(hAPI!=NULL)

    {

        CreateInstance=(G3XDDCAPI_CREATE_INSTANCE)GetProcAddress(hAPI,"CreateInstance");



        if(CreateInstance(G31DDC_CLASS_ID_DEVICE_ENUMERATOR,(void**)&Enumerator))

        {

            Enumerator->Enumerate();



            Count=Enumerator->GetCount();

            

            if(Count!=0)

            {

                printf("Available G31DDC devices count=%d:\n",Count);



                for(Index=0;Index<Count;Index++)

                {

                    Enumerator->GetDeviceInfo(Index,&DevInfo,sizeof(DevInfo));

                    printf("%d. SN: %s\n",Index,DevInfo.SerialNumber);

                }

            }

            else

            {

                printf("No available G31DDC device found.\n");

            }



            Enumerator->Release();

        }

        else

        {

            printf("Failed to create enumerator object. Error code=%08X\n",GetLastError());

        }



        FreeLibrary(hAPI);

    }

    else

    {

        printf("Failed to load G31DDCAPI.dll.\n");

    }



    printf("Press enter to exit\n");

    getchar();

}

Opening G31DDC device

The API provides an object to control the G31DDC device. Before the device is open, the object has to be created using the CreateInstance function.
The following source code in C++ shows how to open the first available G31DDC device.


#include <stdio.h>

#include "G31DDCAPI.h"





void main(void)

{  

 G3XDDCAPI_CREATE_INSTANCE CreateInstance;

 HMODULE hAPI;

 IG31DDCDevice *Device;

 

    //Loading the API

    hAPI=LoadLibrary("G31DDCAPI.dll");



    if(hAPI!=NULL)

    {

        //Retrieving address of the CreateInstance API functions

        CreateInstance=(G3XDDCAPI_CREATE_INSTANCE)GetProcAddress(hAPI,"CreateInstance");

        

        //Creating instance of the device object

        if(CreateInstance(G31DDC_CLASS_ID_DEVICE,(void**)&Device))

        {

            //Opening the first available G31DDC device using predefined G3XDDC_OPEN_FIRST constant            

            if(Device->Open(G3XDDC_OPEN_FIRST))

            {            

                //Here place code that works with the open G31DDC device            

                

                //Closing device

                Device->Close();

            }

            else

            {

                printf("Failed to open device. Error code=%08X\n",GetLastError());

            }

            

            //Release interface of device object

            Device->Release();

        }

        else

        {

            printf("Failed to create device object. Error code=%08X\n",GetLastError());

        }        



        FreeLibrary(hAPI);

    }

    else

    {

        //If the LoadLibrary fails

        printf("Failed to load G31DDCAPI.dll.\n");

    }

}

CreateInstance

Creates single object of the specified class and returns interface of the object.

C/C++ declaration

INT32 __stdcall CreateInstance(UINT32 ClassId,PVOID *Interface);

Address retrieval

G3XDDCAPI_CREATE_INSTANCE CreateInstance=(G3XDDCAPI_CREATE_INSTANCE)GetProcAddress(hAPI,"CreateInstance");

Parameters

ClassId
[in] Specifies class identifier of the object to be created. This parameter must be one of the following:

ValueMeaning
G31DDC_CLASS_ID_DEVICE_ENUMERATORClass identifier of the enumerator object. When the function finished successfully, IG31DDCDeviceEnumerator interface is stored to pointer variable pointed to by the Interface parameter.
G31DDC_CLASS_ID_DEVICEClass identifier of the device object. When the function finished successfully, IG31DDCDevice interface is stored to pointer variable pointed to by the Interface parameter.

Interface
[out] Pointer to a variable that receives interface to newly created object of specified class. 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, call GetLastError.

Remarks

All the objects created using CreateInstance must be freed releasing their interfaces using Release method before the API is unloaded using the FreeLibrary function.

The CreateInstance function can be called in any user-thread. Returned interface can be used only in the same thread in which its object was created, otherwise the application can become to unpredictable state.


IG31DDCDeviceEnumerator interface

IG31DDCDeviceEnumerator interface is the interface of the enumerator object that is created using the CreateInstance function and that provides enumeration mechanism of available G31DDC devices.


IG31DDCDeviceEnumerator::AddRef

Increases the reference count to the enumerator object.

C/C++ declaration

LONG __stdcall AddRef(void);

Parameters

None

Return value

The method returns resulting reference count.

Remarks

Initial reference count of an object created using CreateInstance function is 1.

IG31DDCDeviceEnumerator::Release

Decrements the reference count of the object. When the reference count reaches zero, the object and all the resources allocated by them are freed and the interface is no longer usable.

C/C++ declaration

LONG __stdcall Release(void);

Parameters

None

Return value

The method returns resulting reference count. If the return value is zero, the object was freed.

IG31DDCDeviceEnumerator::Enumerate

Performs enumeration of available G31DDC devices.

C/C++ declaration

BOOL __stdcall Enumerate(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDeviceEnumerator::GetCount

Retrieves number of available G31DDC devices enumerated using the IG31DDCDeviceEnumerator::Enumerate method.

C/C++ declaration

UINT32 __stdcall GetCount(void);

Parameters

None

Return value

The method returns number of available G31DDC devices.

IG31DDCDeviceEnumerator::GetDeviceInfo

Retrieves information about available G31DDC device.

C/C++ declaration

BOOL __stdcall GetDeviceInfo(UINT32 DeviceIndex,G31DDC_DEVICE_INFO *DeviceInfo,UINT32 BufferLength);

Parameters

DeviceIndex
[in] Specifies index of the device. It can vary from zero to one less than the value returned by the IG31DDCDeviceEnumerator::GetCount method.
DeviceInfo
[out] Pointer to a G31DDC_DEVICE_INFO structure to be filled with information about the the device.
BufferLength
[in] Size, in bytes, of the G31DDC_DEVICE_INFO structure.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice interface

IG31DDCDevice interface is an interface of the device object that is created using the CreateInstance function. This interface allows to control selected G31DDC device.


IG31DDCDevice::AddRef

Increases the reference count to the enumerator object.

C/C++ declaration

LONG __stdcall AddRef(void);

Parameters

None

Return value

The method returns resulting reference count.

Remarks

Initial reference count of an object created using CreateInstance function is 1.

IG31DDCDevice::Release

Decrements the reference count of the object. When the reference count reaches zero, the object and all the resources allocated by them are freed and the interface is no longer usable.

C/C++ declaration

LONG __stdcall Release(void);

Parameters

None

Return value

The method returns resulting reference count. If the return value is zero, the object was freed.

IG31DDCDevice::Open

Opens G31DDC device by its system path and associates the device with the device object given by its interface pointer.

C/C++ declaration

BOOL __stdcall Open(CONST CHAR *DevicePath);

Parameters

DevicePath
[in] Pointer to a null-terminated string that specifies the system path of the G31DDC device to open. The system device path of the device can be obtained from the G31DDC_DEVICE_INFO structure filled by the IG31DDCDeviceEnumerator::GetDeviceInfo method. Instead of the system path, it can be used one of the following values:

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

Return value

If the method succeeds, the return value non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::Close method to close currently open G31DDC device associated with the device object..


IG31DDCDevice::Close

Closes currently open G31DDC device associated with the device object and makes the object available for use with another G31DDC device.

C/C++ declaration

BOOL __stdcall Close(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If no open G31DDC device is associated with the object, the Close method does nothing.

IG31DDCDevice::IsConnected

Checks if the device is still connected to the computer.

C/C++ declaration

BOOL __stdcall IsConnected(void);

Parameters

None

Return value

The method returns non-zero value if the device is still connected.
If the device is disconnected or the method fails return value is zero. To determine if the method failed, call GetLastError. GetLastError returns ERROR_SUCCESS if the device is disconnected or another error code if IsConnected failed.

Remarks

If it is determined the device is disconnected, the IG31DDCDevice::Close should be used.

IG31DDCDevice::GetDeviceInfo

Retrieves information about the G31DDC device.

C/C++ declaration

BOOL __stdcall GetDeviceInfo(G31DDC_DEVICE_INFO *Info,UINT32 BufferLength);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetLED

Sets the front panel LED flashing mode.

C/C++ declaration

BOOL __stdcall SetLED(UINT32 LEDMode);

Parameters

LEDMode
[in] Specifies front panel LED flashing mode. It can be one of the following:

ValueMeaning
G3XDDC_FRONT_PANEL_LED_MODE_DIAGDiagnostic flashing.
G3XDDC_FRONT_PANEL_LED_MODE_ONAlways on.
G3XDDC_FRONT_PANEL_LED_MODE_OFFAlways off.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetLED method to determine current flashing mode of the front panel LED.

A complete list of the diagnostic flashing patterns and their meaning is as follows:

No. Pattern Description Mode
1
        
Off No power
2
        
Long flash, equal gap No connection to computer
3
        
Two short flashes USB connected, radio off
4
        
One short flash followed by a long one USB connected, radio on, ready
5
        
Two short flashes followed by a long one USB connected, driver not installed
6
        
Three short flashes USB connected, driver installed, application not running


IG31DDCDevice::GetLED

Determines current flashing mode of device's front panel LED.

C/C++ declaration

BOOL __stdcall GetLED(UINT32 *LEDMode);

Parameters

LEDMode
[out] Pointer to a variable that receives current flashing mode of device's front panel LED. For list of possible values, see SetLED. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetPower

Turns the G31DDC device on or off.

C/C++ declaration

BOOL __stdcall SetPower(BOOL Power);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetPower method to determine current power state of the device.


IG31DDCDevice::GetPower

Determines whether the device is turned on or off.

C/C++ declaration

BOOL __stdcall GetPower(BOOL *Power);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAttenuator

Sets input attenuator.

C/C++ declaration

BOOL __stdcall SetAttenuator(UINT32 Attenuator);

Parameters

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 method rounds the value to nearest lower one.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetAttenuator method to determine current setting of the attenuator.

IG31DDCDevice::GetAttenuator

Retrieves current setting of the attenuator.

C/C++ declaration

BOOL __stdcall GetAttenuator(UINT32 *Attenuator);

Parameters

Attenuator
[out] Pointer to a variable that receives current attenuation level. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetMWFilter

Enables or disables MW filter (medium wave filter).

C/C++ declaration

BOOL __stdcall SetMWFilter(BOOL Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetMWFilter method to determine current state of the MW filter.

IG31DDCDevice::GetMWFilter

Retrieves current state of the MW filter.

C/C++ declaration

BOOL __stdcall GetMWFilter(BOOL *Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDithering

Enables or disables ADC dithering.

C/C++ declaration

BOOL __stdcall SetDithering(BOOL Enabled);

Parameters

Enabled
[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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetDithering method to determine current state of ADC dithering.

IG31DDCDevice::GetDithering

Retrieves current state of ADC dithering.

C/C++ declaration

BOOL __stdcall GetDithering(BOOL *Enabled);

Parameters

Enabled
[out] Pointer to a variable that receives current state of dithering. The value is non-zero if dithering is enabled and zero if it is disabled. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetADCNoiseBlanker

Enables or disables noise blanker on ADC stream.

C/C++ declaration

BOOL __stdcall SetADCNoiseBlanker(BOOL Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetADCNoiseBlanker method to determine current state of the noise blanker.

IG31DDCDevice::GetADCNoiseBlanker

Retrieves current ADC noise blanker state.

C/C++ declaration

BOOL __stdcall GetADCNoiseBlanker(BOOL *Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetADCNoiseBlankerThreshold

Specifies ADC noise blanker threshold.

C/C++ declaration

BOOL __stdcall SetADCNoiseBlankerThreshold(WORD Threshold);

Parameters

Threshold
[in] Specifies the maximum acceptable input signal. Maximum possible value of threshold is 32767, in this case the noise blanker has no effect event it is enabled using the IG31DDCDevice::SetADCNoiseBlanker method.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetADCNoiseBlankerThreshold method to retrieve current threshold of the noise blanker.

IG31DDCDevice::GetADCNoiseBlankerThreshold

Determines ADC noise blanker threshold.

C/C++ declaration

BOOL __stdcall GetADCNoiseBlankerThreshold(WORD *Threshold);

Parameters

Threshold
[out] Pointer to a variable that receives threshold of ADC noise blanker. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::StartIF

Starts sending of IF snapshots.

C/C++ declaration

BOOL __stdcall StartIF(WORD Period);

Parameters

Period
[in] Specifies time interval in milliseconds how often the IF snapshots are sent to IG31DDCDeviceCallback::G31DDC_IFCallback callback.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Too low value of the Period parameter can dramatically increase data flow through USB wich could cause breaking of running streaming.


IG31DDCDevice::StopIF

Stops sending of IF snapshots.

C/C++ declaration

BOOL __stdcall StopIF(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The IG31DDCDeviceCallback::G31DDC_IFCallback callback is not called after StopIF returns.


IG31DDCDevice::SetInverted

Enables or disables frequency spectrum inversion.

C/C++ declaration

BOOL __stdcall SetInverted(BOOL Inverted);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetInverted

Retrieves current frequency spectrum inversion setting.

C/C++ declaration

BOOL __stdcall GetInverted(BOOL *Inverted);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetDDCInfo

Retrieves information about DDC format.

C/C++ declaration

BOOL __stdcall GetDDCInfo(UINT32 DDCTypeIndex,G3XDDC_DDC_INFO *Info);

Parameters

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 information of the DDC type.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetDDC1Count method 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 IG31DDCDevice::GetDDC1Count.

Use the IG31DDCDevice::GetDDC1 method to determine current DDC type index of DDC1 and the IG31DDCDevice::GetDDC2 method to determine current DDC type of DDC2.


IG31DDCDevice::GetDDC1Count

Retrieves number of DDC types supported by DDC1.

C/C++ declaration

BOOL __stdcall GetDDC1Count(UINT32 *Count);

Parameters

Count
[in] Specifies index of DDC type.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDDC1

Sets current DDC type of DDC1.

C/C++ declaration

BOOL __stdcall SetDDC1(UINT32 DDCTypeIndex);

Parameters

DDCTypeIndex
[in] Specifies index of DDC type to be used in DDC1.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetDDC1Count method 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 IG31DDCDevice::GetDDC1Count.

DDC1 streaming must not run when calling SetDDC1. In other words, DDC1 streaming that is started using the IG31DDCDevice::StartDDC1 method has to be stopped using the IG31DDCDevice::StopDDC1 method before calling of SetDDC1, otherwise SetDDC1 fails. The SetDDC1 method 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 demodulator filter, so it is useful to call the IG31DDCDevice::GetDDC2 and IG31DDCDevice::GetDemodulatorFilterBandwidth methods immediately after SetDDC1 to determine current DDC type of DDC2 and current bandwidth of demodulator filter.

Use the IG31DDCDevice::GetDDC1 method to determine current DDC type of the DDC1.


IG31DDCDevice::GetDDC1

Retrieves information about current DDC type of the DDC1.

C/C++ declaration

BOOL __stdcall GetDDC1(UINT32 *DDCTypeIndex,G3XDDC_DDC_INFO *DDCInfo);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Returned DDCTypeIndex can be passed to the IG31DDCDevice::GetDDCInfo method.

IG31DDCDevice::SetDDC1Frequency

Sets DDC1 center frequency.

C/C++ declaration

BOOL __stdcall SetDDC1Frequency(UINT32 Frequency);

Parameters

Frequency
[in] Specifies new center frequency of DDC1 in Hz.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetDDC1Frequency method to determine current center frequency of DDC1.


IG31DDCDevice::GetDDC1Frequency

Retrieves current center frequency of DDC1.

C/C++ declaration

BOOL __stdcall GetDDC1Frequency(UINT32 *Frequency);

Parameters

Frequency
[out] Pointer to a variable that receives current center frequency of DDC1 in Hz. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::StartDDC1

Starts DDC1 streaming.

C/C++ declaration

BOOL __stdcall StartDDC1(UINT32 SamplesPerBuffer);

Parameters

SamplesPerBuffer
[in] Specifies number of I/Q sample sets in each buffer passed to the the DDC1StreamCallback callback method. The value has to be multiple of 64 greater than zero. If it is zero, the StartDDC1 method fails. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

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

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

Use the IG31DDCDevice::StopDDC1 method to stop DDC1 streaming.

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


IG31DDCDevice::StopDDC1

Stops DDC1 streaming.

C/C++ declaration

BOOL __stdcall StopDDC1(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

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

The IG31DDCDeviceCallback::G31DDC_DDC1StreamCallback and IG31DDCDeviceCallback::G31DDC_DDC1PlaybackStreamCallback callback methods are not called after StopDDC1 returns.


IG31DDCDevice::StartDDC1Playback

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

C/C++ declaration

BOOL __stdcall StartDDC1Playback(UINT32 SamplesPerBuffer,UINT32 BitsPerSample);

Parameters

SamplesPerBuffer
[in] Specifies number of I/Q sample sets in each buffer passed to the IG31DDCDeviceCallback::G31DDC_DDC1PlaybackStreamCallback callback to fill the buffer by the application and to the IG31DDCDeviceCallback::G31DDC_DDC1StreamCallback callback. The value has to be multiple of 64 greater than zero. If it is zero, the StartDDC1Playback method fails. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.
BitsPerSample
[in] Specifies number of bits per I and Q samples. It is used for both IG31DDCDeviceCallback::G31DDC_DDC1PlaybackStreamCallback and IG31DDCDeviceCallback::G31DDC_DDC1StreamCallback callback methods. The possible value is one of the following:

ValueMeaning
0I and Q samples have default number of bits. It is given by by BitsPerSample member of the G3XDDC_DDC_INFO structure which can be retrieved using the GetDDC1 or IG31DDCDevice::GetDDCInfo method. 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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The G31DDC device has to be turned on using IG31DDCDevice::SetPower method before use of StartDDC1Playback.

The StartDDC1Playback method stops DDC1 streaming that was previously started by the IG31DDCDevice::StartDDC1 or StartDDC1Playback methods 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 IG31DDCDevice::StopDDC1 method to stop DDC1 playback.


IG31DDCDevice::PauseDDC1Playback

Pauses DDC1 playback.

C/C++ declaration

BOOL __stdcall PauseDDC1Playback(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

The IG31DDCDeviceCallback::G31DDC_DDC1PlaybackStreamCallback and IG31DDCDeviceCallback::G31DDC_DDC1StreamCallback callback methods can be called by the API once after PauseDDC1Playback returns. Then they are not called until playback is resumed using the IG31DDCDevice::ResumeDDC1Playback method.


IG31DDCDevice::ResumeDDC1Playback

Resumes paused DDC1 playback.

C/C++ declaration

BOOL __stdcall ResumeDDC1Playback(void);

Parameters

None

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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


IG31DDCDevice::GetDDC2

Retrieves information about current DDC type of the DDC2.

C/C++ declaration

BOOL __stdcall GetDDC2(UINT32 *DDCTypeIndex,G3XDDC_DDC_INFO *DDCInfo);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Each channel has its own DDC2, see the block diagram. DDC type of each DDC2 is the same and it depends 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 method to determine 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 IG31DDCDeviceCallback::G31DDC_DDC2StreamCallback and IG31DDCDeviceCallback::G31DDC_DDC2PreprocessedStreamCallback DDC2 callback methods are always in IEEE float (32 bit, little endian) format.

Returned DDCTypeIndex can be passed to the IG31DDCDevice::GetDDCInfo method.


IG31DDCDevice::SetDDC2Frequency

Sets relative center frequency of DDC2 for given channel.

C/C++ declaration

BOOL __stdcall SetDDC2Frequency(UINT32 Channel,INT32 Frequency);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

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 IG31DDCDevice::SetDDC1Frequency method) 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 IG31DDCDevice::GetDDC2Frequency method to determine current relative center frequency of the DDC2 for given channel.

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


IG31DDCDevice *Device; //Interface of the G31DDC device object, created using CreateInstance function



//1. method

Device->SetDDC1Frequency(11010000);

Device->SetDDC2Frequency(0,0);



//2. method, it can be used if bandwidth of DDC2 is less than bandwidth of DDC1

Device->SetDDC1Frequency(11000000);

Device->SetDDC2Frequency(0,10000);



//3. method, it can be used if bandwidth of DDC2 is less than bandwidth of DDC1

Device->SetDDC1Frequency(11020000);

Device->SetDDC2Frequency(0,-10000);


IG31DDCDevice::GetDDC2Frequency

Retrieves current relative center frequency of DDC2.

C/C++ declaration

BOOL __stdcall GetDDC2Frequency(UINT32 Channel,INT32 *Frequency);

Parameters

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 how to calculate absolute center frequency of DDC2. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::StartDDC2

Starts DDC2 streaming for given channel.

C/C++ declaration

BOOL __stdcall StartDDC2(UINT32 Channel,UINT32 SamplesPerBuffer);

Parameters

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 the IG31DDCDeviceCallback::G31DDC_DDC2StreamCallback and IG31DDCDeviceCallback::G31DDC_DDC2PreprocessedStreamCallback callback methods. The value has to be multiple of 64 greater than zero. If it is zero, the StartDDC2 method fails. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

If the DDC2 streaming for given channel is already running, StartDDC2 restarts it except 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 give channel. StartDDC2 does not restart audio streaming.

Use the IG31DDCDevice::StopDDC2 method to stop DDC2 streaming.

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


IG31DDCDevice::StopDDC2

Stops DDC2 streaming for given channel.

C/C++ declaration

BOOL __stdcall StopDDC2(UINT32 Channel);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

If DDC2 streaming is not active, StopDDC2 does nothing.

The IG31DDCDeviceCallback::G31DDC_DDC2StreamCallback and IG31DDCDeviceCallback::G31DDC_DDC2PreprocessedStreamCallback callback methods are not called after StopDDC2 returns.


IG31DDCDevice::SetDDC2NoiseBlanker

Enables or disables noise blanker on DDC2 stream.

C/C++ declaration

BOOL __stdcall SetDDC2NoiseBlanker(UINT32 Channel,BOOL Enabled);

Parameters

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, noise blanker is enabled. If the parameter is zero, noise blanker is disabled.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetDDC2NoiseBlanker method to determine current state of the noise blanker.

IG31DDCDevice::GetDDC2NoiseBlanker

Retrieves current DDC2 noise blanker state.

C/C++ declaration

BOOL __stdcall GetDDC2NoiseBlanker(UINT32 Channel,BOOL *Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDDC2NoiseBlankerThreshold

Specifies DDC2 noise blanker threshold.

C/C++ declaration

BOOL __stdcall SetDDC2NoiseBlankerThreshold(UINT32 Channel,double Threshold);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Threshold
[in] Specifies threshold in %.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetDDC2NoiseBlankerThreshold method to retrieve current threshold of the noise blanker.

IG31DDCDevice::GetDDC2NoiseBlankerThreshold

Retrieves DDC2 noise blanker threshold.

C/C++ declaration

BOOL __stdcall GetDDC2NoiseBlankerThreshold(UINT32 Channel,double *Threshold);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetDDC2NoiseBlankerExcessValue

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

C/C++ declaration

BOOL __stdcall GetDDC2NoiseBlankerExcessValue(UINT32 Channel,double *Value);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetSignalLevel

Determines current signal level for given channel.

C/C++ declaration

BOOL __stdcall GetSignalLevel(UINT32 Channel,FLOAT *Peak,FLOAT *RMS);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Signal level is evaluated from 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 that processed by the demoduletor filter. Buffer size (signal level evaluation rate) is given by the SamplesPerBuffer parameter of the IG31DDCDevice::StartDDC2 method.

The IG31DDCDeviceCallback::G31DDC_DDC2PreprocessedStreamCallback callback method provides signal level for each buffer passed the callback, i.e. for each buffer used in signal level evaluation. This provides way to get signal level from each processed buffer without need of pulling 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>



IG31DDCDevice *Device; //Interface of G31DDC device object, created using the CreateInstance function

float P_dBm,V_RMS;



Device->GetSignalLevel(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);


IG31DDCDevice::SetNotchFilter

Enables or disables notch filter for given channel.

C/C++ declaration

BOOL __stdcall SetNotchFilter(UINT32 Channel,BOOL Enabled);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetNotchFilter method to determine whether the filter is enabled or disabled.

IG31DDCDevice::GetNotchFilter

Retrieves current notch filter state for given channel.

C/C++ declaration

BOOL __stdcall GetNotchFilter(UINT32 Channel,BOOL *Enabled);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetNotchFilterFrequency

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

C/C++ declaration

BOOL __stdcall SetNotchFilterFrequency(UINT32 Channel,INT32 Frequency);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Frequency
[in] Specifies new center frequency of the notch filter in Hz.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetNotchFilterFrequency method to retrieve current center frequency of the notch filter.


IG31DDCDevice::GetNotchFilterFrequency

Retrieves current relative center frequency of the notch filter.

C/C++ declaration

BOOL __stdcall GetNotchFilterFrequency(UINT32 Channel,INT32 *Frequency);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetNotchFilterBandwidth

Specifies bandwidth of the notch filter for given channel.

C/C++ declaration

BOOL __stdcall SetNotchFilterBandwidth(UINT32 Channel,UINT32 Bandwidth);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Bandwidth
[in] Specifies new bandwidth of the notch filter in Hz. The bandwidth can be from range 1 - 3000 Hz.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetNotchFilterBandwidth method to retrieve current bandwidth of the notch filter.


IG31DDCDevice::GetNotchFilterBandwidth

Retrieves current bandwidth of the notch filter for given channel.

C/C++ declaration

BOOL __stdcall GetNotchFilterBandwidth(UINT32 Channel,UINT32 *Bandwidth);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Bandwidth
[out] Pointer to a variable that receives current bandwidth of the notch filter. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetNotchFilterLength

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

C/C++ declaration

BOOL __stdcall SetNotchFilterLength(UINT32 Channel,UINT32 Length);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[in] Specifies length of the notch filter. The value has to be multiple of 64, greater than or equal to 64 and less than or equal to 32768. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetNotchFilterLength method to determine current length of the notch filter.


IG31DDCDevice::GetNotchFilterLength

Retrieves current notch filter length for given channel.

C/C++ declaration

BOOL __stdcall GetNotchFilterLength(UINT32 Channel,UINT32 *Length);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Length
[out] Pointer to a variable that receives current length of the notch filter. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAGC

Enables or disables AGC for given channel.

C/C++ declaration

BOOL __stdcall SetAGC(UINT32 Channel,BOOL Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the AGC is disabled, the signal is affected by fixed gain specified using the IG31DDCDevice::SetGain method.

Use the IG31DDCDevice::GetAGC method to determine current state of the AGC.


IG31DDCDevice::GetAGC

Retrieves current state of the AGC for given channel.

C/C++ declaration

BOOL __stdcall GetAGC(UINT32 Channel,BOOL *Enabled);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAGCParams

Sets parameters of the AGC for given channel.

C/C++ declaration

BOOL __stdcall SetAGCParams(UINT32 Channel,double AttackTime,double DecayTime,double ReferenceLevel);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetAGCParams method to determine current parameters of the AGC.


IG31DDCDevice::GetAGCParams

Retrieves current parameters of the AGC for given channel.

C/C++ declaration

BOOL __stdcall GetAGCParams(UINT32 Channel,double *AttackTime,double *DecayTime,double *ReferenceLevel);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetMaxAGCGain

Sets maximum gain of the AGC for given channel.

C/C++ declaration

BOOL __stdcall SetMaxAGCGain(UINT32 Channel,double MaxGain);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetMaxAGCGain method to determine maximum gain of the AGC.


IG31DDCDevice::GetMaxAGCGain

Retrieves current maximum gain of the AGC for given channel.

C/C++ declaration

BOOL __stdcall GetMaxAGCGain(UINT32 Channel,double *MaxGain);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetGain

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

C/C++ declaration

BOOL __stdcall SetGain(UINT32 Channel,double Gain);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[in] Specifies new fixed gain in dB.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetGain method to determine current fixed gain.


IG31DDCDevice::GetGain

Retrieves current fixed gain for given channel.

C/C++ declaration

BOOL __stdcall GetGain(UINT32 Channel,double *Gain);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[out] Pointer to a variable that receives current fixed gain in dB. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetCurrentGain

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

C/C++ declaration

BOOL __stdcall GetCurrentGain(UINT32 Channel,double *CurrentGain);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
CurrentGain
[out] Pointer to a variable that receives current gain in dB. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

IG31DDCDevice::SetDemodulatorFilterBandwidth

Sets bandwidth of the demodulator filter for given channel.

C/C++ declaration

BOOL __stdcall SetDemodulatorFilterBandwidth(UINT32 Channel,UINT32 Bandwidth);

Parameters

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 current DDC2 bandwidth. Use the IG31DDCDevice::GetDDC2 method to retrieve information about current DDC type of DDC2.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

IG31DDCDevice::GetDemodulatorFilterBandwidth

Retrieves current demodulator filter bandwidth for given channel.

C/C++ declaration

BOOL __stdcall GetDemodulatorFilterBandwidth(UINT32 Channel,UINT32 *Bandwidth);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Bandwidth
[out] Pointer to a variable that receives current demodulator filter bandwidth. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDemodulatorFilterShift

Sets demodulator filter shift for given channel.

C/C++ declaration

BOOL __stdcall SetDemodulatorFilterShift(UINT32 Channel,INT32 Shift);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

This method does not change demodulator frequency just shift the filter from demodulator's centre.

Use the IG31DDCDevice::GetDemodulatorFilterShift method to determine current demodulator filter shift.


IG31DDCDevice::GetDemodulatorFilterShift

Retrieves current shift of the demodulator filter for given channel.

C/C++ declaration

BOOL __stdcall GetDemodulatorFilterShift(UINT32 Channel,INT32 *Shift);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDemodulatorFilterLength

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

C/C++ declaration

BOOL __stdcall SetDemodulatorFilterLength(UINT32 Channel,UINT32 Length);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetDemodulatorFilterLength method to determine current length of the demodulator filter.


IG31DDCDevice::SetDemodulatorMode

Sets demodulator mode for given channel.

C/C++ declaration

BOOL __stdcall SetDemodulatorMode(UINT32 Channel,UINT32 Mode);

Parameters

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_DRMDigital Radio Mondiale

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

DRM demodulation is only available if valid DRM key is loaded using the IG31DDCDevice::SetDRMKey method. More information about obtaining DRM key at http://www.winradio.com/home/drm.htm.

Use the IG31DDCDevice::GetDemodulatorMode method to retrieve current demodulator mode.


IG31DDCDevice::GetDemodulatorMode

Retrieves current demodulator mode for given channel.

C/C++ declaration

BOOL __stdcall GetDemodulatorMode(UINT32 Channel,UINT32 *Mode);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Mode
[out] Pointer to a variable that receives current demodulator mode. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDemodulatorFrequency

Sets relative center frequency of demodulator for given channel.

C/C++ declaration

BOOL __stdcall SetDemodulatorFrequency(UINT32 Channel,INT32 Frequency);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

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 IG31DDCDevice::SetDDC1Frequency method), frDDC2[i] is relative center frequency of DDC2 of i-th channel in Hz (set using the IG31DDCDevice::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 IG31DDCDevice::GetDemodulatorFrequency method to determine current relative center frequency of the demodulator for given channel.

The following example shows four methods how it is possible to set absolute demodulator center frequency of channel 0 to 11.01 MHz:


IG31DDCDevice *Device; //Interface of G31DDC device object, created using the CreateInstance function



//1. method

Device->SetDDC1Frequency(11010000);

Device->SetDDC2Frequency(0,0);

Device->SetDemodulatorFrequency(0,0);



//2. method, usable if DDC2 bandwidth is less than DDC1 bandwidth

Device->SetDDC1Frequency(11000000);

Device->SetDDC2Frequency(0,10000);

Device->SetDemodulatorFrequency(0,0);



//3. method, usable if DDC2 bandwidth is less than DDC1 bandwidth,

//and demodulator filter bandwidth is less than DDC2 bandwidth

Device->SetDDC1Frequency(11020000);

Device->SetDDC2Frequency(0,-5000);

Device->SetDemodulatorFrequency(0,-5000);



//4. method

Device->SetFrequency(0,11010000); 

//The SetFrequency method sets DDC1, DDC2 and demodulator

//center frequencies so that demodulator's absolute frequency is set to the required frequency


IG31DDCDevice::GetDemodulatorFrequency

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

C/C++ declaration

BOOL __stdcall GetDemodulatorFrequency(UINT32 Channel,INT32 *Frequency);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDemodulatorParam

Sets a parameter of the demodulation for given channel.

C/C++ declaration

BOOL __stdcall SetDemodulatorParam(UINT32 Channel,UINT32 Code,CONST VOID *Buffer,UINT32 BufferSize);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Code
[in] Specifies code of the demodulator parameter to be set by the method. 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 pointer to an UINT32 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 pointer to an UINT32 variable, and the BufferSize parameter has to be sizeof(UINT32).

Value of the variable pointed to by the Buffer parameter is capture range in Hz from range 50 to 10000 Hz. It specifies the range where the synchronous AM demodulator is able to lock to the signal. The range starts at -half of the range and ends at half of the range relatively to center of the demodulator.

G3XDDC_DEMODULATOR_PARAM_CW_FREQUENCY

CW tone frequency

The Buffer parameter has to be pointer to a INT32 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_DRM_AUDIO_SERVICE

Audio service of DRM demodulator/decoder to be listening to.

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

Value of the variable pointed to by the Buffer parameter is index of the audio service. Possible value are: 1, 2, 3, 4, where 1 is the first audio service, 2 is the second one, etc. Use the IG31DDCDevice::GetDemodulatorState method with G3XDDC_DEMODULATOR_STATE_DRM_STATUS to retrieve information about available audio services for currently received DRM station.

G3XDDC_DEMODULATOR_PARAM_DRM_MULTIMEDIA_SERVICE

Multimedia service of DRM demodulator/decoder to be decoded.

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

Value of the variable pointed to by the Buffer parameter is index of the multimedia service. Possible value are: 1, 2, 3, 4, where 1 is the first audio service, 2 is the second one, etc. Use the IG31DDCDevice::GetDemodulatorState method with G3XDDC_DEMODULATOR_STATE_DRM_STATUS to retrieve information about available multimedia services for currently received DRM station.

It is required that DRM multimedia player has to be installed to display multimedia content. It is included in G31DDC software installer as optional.

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetDemodulatorParam

Retrieves a parameter of the demodulation for given channel.

C/C++ declaration

BOOL __stdcall GetDemodulatorParam(UINT32 Channel,UINT32 Code,VOID *Buffer,UINT32 BufferSize);

Parameters

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 IG31DDCDevice::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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::GetDemodulatorState

Retrieves information about current demodulator state for given channel.

C/C++ declaration

BOOL __stdcall GetDemodulatorState(UINT32 Channel,UINT32 Code,VOID *Buffer,UINT32 BufferSize);

Parameters

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 pointer to a BOOL 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 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 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 pointer to an INT32 variable, and the BufferSize parameter has to be sizeof(INT32).

Received value is 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_DRM_STATUS

Status of DRM demodulator/decoder.

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

G3XDDC_DEMODULATOR_STATE_FM_DEVIATION

Estimated frequency deviation in Hz.

The Buffer parameter has to be pointer to an UINT32 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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::StartAudio

Starts audio streaming for given channel.

C/C++ declaration

BOOL __stdcall StartAudio(UINT32 Channel,UINT32 SamplesPerBuffer);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
SamplesPerBuffer
[in] Specifies number of samples in each buffer passed to the the IG31DDCDeviceCallback::G31DDC_AudioStreamCallback callback method. The value has to be multiple of 64 greater than zero. If it is zero, the StartAudio method fails. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

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

Use the IG31DDCDevice::StopAudio method to stop audio streaming.

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


IG31DDCDevice::StopAudio

Stops audio streaming for given channel.

C/C++ declaration

BOOL __stdcall StopAudio(UINT32 Channel);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If audio streaming is not active, StopAudio does nothing.

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

The IG31DDCDeviceCallback::G31DDC_AudioStreamCallback and IG31DDCDeviceCallback::G31DDC_AudioPlaybackStreamCallback callback methods are not called after StopAudio returns.


IG31DDCDevice::StartAudioPlayback

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

C/C++ declaration

BOOL __stdcall StartAudioPlayback(UINT32 Channel,UINT32 SamplesPerBuffer);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
SamplesPerBuffer
[in] Specifies number of samples in each buffer passed to the IG31DDCDeviceCallback::G31DDC_AudioPlaybackStreamCallback callback to fill the buffer by the application and to the IG31DDCDeviceCallback::G31DDC_AudioStreamCallback callback methods. The value has to be multiple of 64 greater than zero. If it is zero, the StartAudioPlayback method fails. If it is not multiple of 64 the method rounds it up to nearest multiple of 64.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The G31DDC device has to be turned on using IG31DDCDevice::SetPower method before use of StartDDC1Playback.

The StartDDC1Playback method stops audio streaming that was previously started by the IG31DDCDevice::StartAudio or IG31DDCDevice::StartAudioPlayback method and starts audio playback with new parameters.

Use the IG31DDCDevice::StopAudio method to stop audio playback.


IG31DDCDevice::PauseAudioPlayback

Pauses audio playback for given channel.

C/C++ declaration

BOOL __stdcall PauseAudioPlayback(UINT23 Channel);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

The IG31DDCDeviceCallback::G31DDC_AudioPlaybackStreamCallback and IG31DDCDeviceCallback::G31DDC_AudioStreamCallback callback methods can be called once after PauseAudioPlayback returns. Then they are not called until playback is resumed using the IG31DDCDevice::ResumeAudioPlayback method.


IG31DDCDevice::ResumeAudioPlayback

Resumes paused audio playback for given channel.

C/C++ declaration

BOOL __stdcall ResumeAudioPlayback(UINT32 Channel);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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


IG31DDCDevice::SetAudioGain

Sets fixed audio gain for given channel.

C/C++ declaration

BOOL __stdcall SetAudioGain(UINT32 Channel,double Gain);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[in] Specifies new fixed audio gain in dB.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetAudioGain method to retrieve current audio gain.

IG31DDCDevice::GetAudioGain

Retrieves current fixed audio gain for given channel.

C/C++ declaration

BOOL __stdcall GetAudioGain(UINT32 Channel,double *Gain);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Gain
[out] Pointer to a variable that receives current fixed gain in dB. This parameter cannot be NULL.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAudioFilter

Enabled or disables audio filter for given channel.

C/C++ declaration

BOOL __stdcall SetAudioFilter(UINT32 Channel,BOOL Enabled);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[in] Specifies whether to enable or disable 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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetAudioFiler method to retrieve current state of the audio filter.

IG31DDCDevice::GetAudioFilter

Retrieves current state of the audio filter for given channel.

C/C++ declaration

BOOL __stdcall GetAudioFilter(UINT32 Channel,BOOL *Enabled);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
Enabled
[out] Pointer to a variable that receives 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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAudioFilterParams

Sets parameters of the audio filter for given channel.

C/C++ declaration

BOOL __stdcall SetAudioFilterParams(UINT32 Channel,UINT32 CutOffLow,UINT32 CutOffHigh,double Deemphasis);

Parameters

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 filter's passband, it can be from range 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 from range 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 the filter in dB per octave. De-emphasis starts at cut-off low frequency of the filter. This value can be from range -9.9 to 0.0 dB/octave. Zero means the de-emphasis is disabled.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Use the IG31DDCDevice::GetAudioFilerParams method to retrieve current parameters of the audio filter.

IG31DDCDevice::GetAudioFilterParams

Retrieves current parameters of the audio filter for given channel.

C/C++ declaration

BOOL __stdcall GetAudioFilterParams(UINT32 Channel,UINT32 *CutOffLow,UINT32 *CutOffHigh,double *Deemphasis);

Parameters

Channel
[in] Specifies channel index. Possible values are: 0, 1, 2.
CutOffLow
[out] Pointer to a variable that receives 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 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 current de-emphasis setting of the filter. This parameter can be NULL if the application does not require this information.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetAudioFilterLength

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

C/C++ declaration

BOOL __stdcall SetAudioFilterLength(UINT32 Channel,UINT32 Length);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

Use the IG31DDCDevice::GetAudioFilterLength method to determine current length of the audio filter.


IG31DDCDevice::GetAudioFilterLength

Retrieves current audio filter length for given channel.

C/C++ declaration

BOOL __stdcall GetAudioFilterLength(UINT32 Channel,UINT32 *Length);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetFrequency

Sets absolute frequency of the demodulator for given channel.

C/C++ declaration

BOOL __stdcall SetFrequency(UINT32 Channel,UINT32 Frequency);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The method sets DDC1, DDC2 and demodulator frequencies so that 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 IG31DDCDevice::SetDDC1Frequency method), frDDC2[i] is relative center frequency of DDC2 of i-th channel in Hz (set using the IG31DDCDevice::SetDDC2Frequency) and frDEM[i] is relative center frequency of the demodulator of i-th channel in Hz (set using the IG31DDCDevice::SetDemodulatorFrequency method).

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

Use the IG31DDCDevice::GetFrequency method to retrieve current absolute frequency of the demodulator.


IG31DDCDevice::GetFrequency

Determines absolute frequency of the demodulator for given channel.

C/C++ declaration

BOOL __stdcall GetFrequency(UINT32 Channel,UINT32 *Frequency);

Parameters

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

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

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 IG31DDCDevice::SetFrequency method.

IG31DDCDevice::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

BOOL __stdcall GetSpectrumCompensation(UINT64 CenterFrequency,UINT32 Width,FLOAT *Buffer,UINT32 Count);

Parameters

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 method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The following example shows how to use the GetSpectrumCompensation method in IG31DDCDeviceCallback::G31DDC_DDC2StreamCallback callback:




//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);



IG31DDCDevice *Device; //Interface to G31DDC object device

UINT32 AbsDDC2Frequency; //Absolute frequency of the DDC2

INT32 RelDDC2Frequency; //Relative frequency of the DDC2

UINT32 DDC1Frequency; //DDC1 frequency

G3XDDC_DDC_INFO DDC2Info; //Information about current DDC type of the DDC2

FLOAT FFTBuffer[2*2048]; //Buffer for FFT result

FLOAT Compensation[2048]; //Buffer for compensation data

UINT32 FirstBin,LastBin; //the first and last bins in the FFT of useful DDC2 band

MY_CALLBACK_OBJECT MyCallbackObject; //User defined callback object implementing methods of IG31DDCDeviceCallback interface



Code before...



//Retrieve frequency of the DDC1

Device->GetDDC1Frequency(&DDC1Frequency);



//Retrieve relative frequency of the DDC2 for channel 0

Device->GetDDC2Frequency(0,&RelDDC2Frequency);



//Calculate absolute frequency of the DDC2

AbsDDC2Frequency=(INT32)DDC1Frequency+RelDDC2Frequency;



//Retrieve DDC type information of the DDC2

Device->GetDDC2(NULL,&DDC2Info);



//Retrieve compensation data

Device->GetSpectrumCompensation(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 IG31DDCDevice::SetDDC1Frequency or IG31DDCDevice::SetDDC2Frequency method.

//In this case a mutual-exclusion synchronization method (for example critical section) should be used 

//if the Compensation buffer would be modified outside the G31DDC_DDC2StreamCallback callback.



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

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



//Register callback object

Device->SetCallback(&MyCallbackObject);



//Start DDC2 streaming for channel 0

//The SamplesPerBuffer parameter is set to 2048 which is size of the FFT to simplify

//the example.

Device->StartDDC2(0,2048);



Code after...

    

void __stdcall MY_CALLBACK_OBJECT::G31DDC_DDC2StreamCallback(IG31DDCDevice *Device,UINT32 Channel,CONST FLOAT *Buffer,UINT32 NumberOfSamples)

{

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

}




IG31DDCDevice::SetCallback

Registers user-defined callback object given by its interface. The API calls methods of the object to pass samples to the application. The object has to implement methods of the IG31DDCDeviceCallback interface.

C/C++ declaration

BOOL __stdcall SetCallback(IG31DDCDeviceCallback *Callback);

Parameters

Callback
[in] Interface to user-defined object to be registered as callback object. If this parameter is NULL, current callback object is unregistered, the API will not call any callback after SetCallback returns.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDevice::SetDRMKey

Sets directory with DRM key file to unlock DRM demodulator/decoder.

C/C++ declaration

BOOL __stdcall SetDRMKey(CONST CHAR *DRMKeyFileDirectory);

Parameters

DRMKeyFileDirectory
[in] Pointer to a null-terminated string that specifies the directory which contains valid DRM key file.

Return value

If the method succeeds, the return value is non-zero.
If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the specfied directory contains valid DRM key file, the key is loaded and the DRM demodulator/decoder is unlocked and available for use, otherwise the method fails.

If the DRM demodulator/decoder is already unlocked, the method does nothing.

Use the IG31DDCDevice::IsDRMUnlocked method to determine whether DRM demodulator/decoder is unlocked or not.

Information about obtaining DRM key at http://www.winradio.com/home/drm.htm.


IG31DDCDevice::IsDRMUnlocked

Determined whether DRM demodulator/decoder is unlocked or not.

C/C++ declaration

BOOL __stdcall IsDRMUnlocked(void);

Parameters

None

Return value

If the method succeeds and the DRM demodulator/decoder is unlocked, the return value is non-zero.
If the method fails or the DRM demodulator/decoder is locked, the return value is zero. To get extended error information, call GetLastError.

IG31DDCDeviceCallback interface

IG31DDCDeviceCallback interface is an interface of application-defined object that implements methods of the interface. The object is used to receive streamed buffers from the G31DDC device object. See IG31DDCDevice::SetCallback.

Each method of the interface is called in context of thread created by the API. If some shared data are accessed inside callback methods, it is recommended to use a mutual-exclusion synchronization method. The application should not call any G31DDC API function/method from inside method of this interface, otherwise it can cause deadlock or the application can become to unpredictable state.


IG31DDCDeviceCallback::G31DDC_IFCallback

It is called by the API to pass IF snapshots to the application. Sending of IF snapshots is started using the IG31DDCDevice::StartIF method.

C/C++ declaration

VOID __stdcall G31DDC_IFCallback(IG31DDCDevice *Device,CONST SHORT *Buffer,UINT32 NumberOfSamples,WORD MaxADCAmplitude,UINT32 ADCSamplingRate);

Parameters

Device
Interface of the device object which called the method.
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 is 0 to 32767.
ADCSamplingRate
Specifies sample rate of the ADC in Hz. It can vary a little bit because of temperature instability.

IG31DDCDeviceCallback::G31DDC_DDC1StreamCallback

It is called by the API to pass I/Q samples from DDC1 to the application. The DDC1 streaming can be started using the IG31DDCDevice::StartDDC1 or IG31DDCDevice::StartDDC1Playback method.

C/C++ declaration

VOID __stdcall DDC1StreamCallback(IG31DDCDevice *Device,CONST VOID *Buffer,UINT32 NumberOfSamples,UINT32 BitsPerSample);

Parameters

Device
Interface of the device object which called the method.
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 IG31DDCDevice::SetDDC1 method. 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 IG31DDCDevice::StartDDC1 or IG31DDCDevice::StartDDC1Playback method.
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.

IG31DDCDeviceCallback::G31DDC_DDC1PlaybackStreamCallback

It is called by the API to fill the buffer with I/Q samples by the applcation. The DDC1 playback can be started using the IG31DDCDevice::StartDDC1Playback method.

C/C++ declaration

BOOL __stdcall DDC1PlaybackStreamCallback(IG31DDCDevice *Device,VOID *Buffer,UINT32 NumberOfSamples,UINT32 BitsPerSample);

Parameters

Device
Interface of the device object which called the method.
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 IG31DDCDevice::SetDDC1 method.
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 IG31DDCDevice::StartDDC1Playback method. 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.

Return value

The application should return non-zero to continue playback. The application should return zero to stop the API to call G31DDC_DDC1PlaybackStreamCallback again. This does not stop DDC1 playback, it has to be done explicitly by the application calling the IG31DDCDevice::StopDDC1 method from the thread in which the device object was created using the CreateInstance function. IG31DDCDevice::StopDDC1 must not be called from inside the callback.

IG31DDCDeviceCallback::G31DDC_DDC2StreamCallback

It is called by the API to pass I/Q samples from DDC2 to the application. The DDC2 streaming can be started using the IG31DDCDevice::StartDDC2 method.

C/C++ declaration

BOOL __stdcall DDC2StreamCallback(IG31DDCDevice *Device,UINT32 Channel,CONST FLOAT *Buffer,UINT32 NumberOfSamples);

Parameters

Device
Interface of the device object which called the method.
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 IG31DDCDevice::GetDDC2 method 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 IG31DDCDevice::StartDDC2 method.

IG31DDCDeviceCallback::G31DDC_DDC2PreprocessedStreamCallback

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 IG31DDCDevice::StartDDC2 method.

C/C++ declaration

BOOL __stdcall DDC2PreprocessedStreamCallback(IG31DDCDevice *Device,UINT32 Channel,CONST FLOAT *Buffer,

    UINT32 NumberOfSamples,FLOAT SlevelPeak,FLOAT SlevelRMS);

Parameters

Device
Interface of the device object which called the method.
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 IG31DDCDevice::GetDDC2 method 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 IG31DDCDevice::StartDDC2 method.
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 IG31DDCDevice::GetSignalLevel method.

IG31DDCDeviceCallback::G31DDC_AudioStreamCallback

It is called by the API to pass audio samples to the application. The audio streaming can be started using the IG31DDCDevice::StartAudio or IG31DDCDevice::StartAudioPlayback method.

C/C++ declaration

VOID __stdcall AudioStreamCallback(IG31DDCDevice *Device,UINT32 Channel,CONST FLOAT *Buffer,

    CONST FLOAT *BufferFiltered,UINT32 NumberOfSamples);

Parameters

Device
Interface of the device object which called the method.
Channel
Specifies channel index. It can be 0, 1, 2.
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.
BufferFiltered
Pointer to the buffer which contains samples of filtered audio signal. The signal is mono, sample rate is 48000 Hz, sample is 32bit IEEE float from range -1.0 to 1.0. If the audio filter is disabled, the samples in the buffer pointed to by the BufferFiltered are the same as the samples in the buffer pointed to by the Buffer parameter.
NumberOfSamples
Specifies number of samples to be stored in the buffer pointed to by the Buffer parameter. This value is equal to value of the SamplesPerBuffer parameter of the IG31DDCDevice::StartAudio or IG31DDCDevice::StartAudioPlayback method.

IG31DDCDeviceCallback::G31DDC_AudioPlaybackStreamCallback

It is called by the API to fill the buffer with audio samples by the application. The audio playback can be started using the IG31DDCDevice::StartAudioPlayback method.

C/C++ declaration

VOID __stdcall AudioPlaybackStreamCallback(IG31DDCDevice *Device,UINT32 Channel,FLOAT *Buffer,UINT32 NumberOfSamples);

Parameters

Device
Interface of the device object which called the method.
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 IG31DDCDevice::StartAudioPlayback method. If the application does not have requested number of samples, the application has to fill the buffer with zeros.

Return value

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

G31DDC_DEVICE_INFO

Contains information about G31DDC device.

C/C++ declaration


#pragma pack(push,1)



typedef struct

{

    CHAR        DevicePath[MAX_PATH];

    BYTE        InterfaceType;

    CHAR        SerialNumber[9];

    UINT32      ChannelCount;

    UINT32      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.
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  SampleRate;

    UINT32  Bandwidth;

    UINT32  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_DRM_STATUS

Contains information about DRM demodulator/decoder status.

C/C++ declaration


#pragma pack(push,1)



typedef struct

{

    BOOL            Valid;



    struct

    {

        BOOL        SyncFound;

        BOOL        FACDecoded;

        BOOL        SDCDecoded;

        BOOL        AudioDecoded;

        SHORT       NumberOfAudioFrames;

        SHORT       NumberOfAudioErrors;

    } DecodingState;



    INT32           Mode;

    double          RFBandwidth;

    BYTE            Interleaver;

    SHORT           SDCQam;

    SHORT           MSCQam;

    BYTE            MSCQamType;

    double          CoderateH;

    double          CoderateA;

    double          CoderateB;

    double          EstimatedSNR;

    WCHAR           TextMessage[128 + 1 + 16];

   

    struct

    {

        BYTE        Content;

        WCHAR       DynamicLabel[256];

        WCHAR       Country[256];

        WCHAR       Language[256];

        WCHAR       ProgramType[256];

        double      AudioBitrate;

        double      TextMsgBitrate;

        double      MultimediaBitrate;

        double      DataBitrate;

    } ServiceInfo[4];



    struct

    {

        BOOL        Valid;

        BYTE        AudioCoding;

        BOOL        SBR;

        INT32       AudioMode;

    } AudioDecoderInfo[4];

} G3XDDC_DRM_STATUS;



#pragma pack(pop)

Members

Valid
The value is non-zero if content of the structure is valid. It is zero, if content of the structure is not valid.
DecodingState

Structure that contains status of the decoder modules.

Members

SyncFound
Status of the sync detection. It is non-zero if sync detected.
FACDecoded
Status of the FAC decoder. It is non-zero if FAC decoded.
SDCDecoded
Status of the SDC decoder. It is non-zero if SDC decoded.
AudioDecoded
Status of the audio decoder. It is non-zero if audio decoded.
NumberOfAudioFrames
Number of audio frames in the transmission frame. It is -1 if this information is not available.
NumberOfAudioErrors
Number of audio frames that were invalid.
Mode
Used DRM robustness mode. It can be one of the following:

ValueMeaning
G3XDDC_DRM_STATE_MODE_NOT_DETERMINED_YETRobustness mode is not determined yet.
G3XDDC_DRM_STATE_MODE_ABroadcast is using DRM robustness mode A.
G3XDDC_DRM_STATE_MODE_BDRM robustness mode B.
G3XDDC_DRM_STATE_MODE_CDRM robustness mode C.
G3XDDC_DRM_STATE_MODE_DDRM robustness mode D.

RFBandwidth
Occupied RF bandwidth in kHz. It is zero if it is invalid or this information is not available (yet).
Interleaver
Interleaver length. It can be one of the following:

ValueMeaning
G3XDDC_DRM_STATE_INTERLEAVER_LONGLong interleaver used (2 sec).
G3XDDC_DRM_STATE_INTERLEAVER_SHORTShort interleaver used (400 msec).

SDCQam
Coding of the SDC (QAM). It is zero if this information is not available (yet).
MSCQam
Coding of the MSC (QAM). It is zero if this information is not available (yet).
MSCQamType
Used QAM coding for the MSC. It can be one of the following:

ValueMeaning
G3XDDC_DRM_STATE_QAM_TYPE_STDStandard
G3XDDC_DRM_STATE_QAM_TYPE_HIER_SYMHierarchical symmetrical
G3XDDC_DRM_STATE_QAM_TYPE_HIER_MIXHierarchical mixed

CoderateH
Used code-rate for hierarchical coding, values less than or equal to zero indicate not available or not used.
CoderateA
Used code-rate for protection level A, values less than or equal to zero indicate indicate not available or not used.
CoderateB
Used code-rate for protection level B, values less than or equal to zero indicate indicate not available or not used.
EstimatedSNR
Estimated SNR in dB of the decoded signal.
TextMessage
Decoded text message for the selected service in 16bit Unicode null-terminated string.
ServiceInfo

Array of four structures which contain general information on the services.

Members

Content
Type of the service. It can be combination of the following:

ValueMeaning
G3XDDC_DRM_STATE_SERVICE_CONTENT_EMPTYGiven service is not used, it contains no data, all other members of the structure are invalid.
G3XDDC_DRM_STATE_SERVICE_CONTENT_AUDIOGiven service contains audio data.
G3XDDC_DRM_STATE_SERVICE_CONTENT_TEXTMSGGiven service contains text messages.
G3XDDC_DRM_STATE_SERVICE_CONTENT_MULTIMEDIAGiven service contains multimedia data.
G3XDDC_DRM_STATE_SERVICE_CONTENT_DATAGiven service contains application specific data.

DynamicLabel
16bit Unicode null-terminated string containing dynamic label of the service.
Country
16bit Unicode null-terminated string containing the signaled country for this service.
Language
16bit Unicode null-terminated string containing the signaled language for this service.
ProgramType
16bit Unicode null-terminated string containing the signaled program type for this service.
AudioBitrate
Data rate for the audio content. It is zero if this information is not available.
TextMsgBitrate
Data rate for the text message content. It is zero if this information is not available.
MultimediaBitrate
Data rate for the multimedia content. It is zero if this information is not available.
DataBitrate
Data rate for the data content. It is zero if this information is not available.
AudioDecoderInfo

Array of four structures which contain audio decoder specific information on the services.

Members

Valid
If it is non-zero, audio decoder information are valid, if it is zero, audio decoder information are invalid and all other members of the structure contain no valid data.
AudioCoding
Used audio coding. It can be one of the following:

ValueMeaning
G3XDDC_DRM_STATE_AUDIO_CODING_AACAudio coding for given service is AAC.
G3XDDC_DRM_STATE_AUDIO_CODING_CELPAudio coding for given service is CELP.
G3XDDC_DRM_STATE_AUDIO_CODING_HVXCAudio coding for given service is HVXC.
G3XDDC_DRM_STATE_AUDIO_CODING_RFUReserved for future use.

SBR
If it is non-zero, SBR is used, if it is zero, SBR is not used.
AudioMode
The value depends on audio coding. It can be one of the following:

ValueMeaning
G3XDDC_DRM_STATE_AUDIO_MODE_AAC_MONOMono
G3XDDC_DRM_STATE_AUDIO_MODE_AAC_PARAM_STEREOParametric stereo
G3XDDC_DRM_STATE_AUDIO_MODE_AAC_STEREOStereo
G3XDDC_DRM_STATE_AUDIO_MODE_AAC_RFUReserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_CELP_NO_CRCAudio data is without CRC
G3XDDC_DRM_STATE_AUDIO_MODE_CELP_CRCCRC used
G3XDDC_DRM_STATE_AUDIO_MODE_CELP_RFU_10Reserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_CELP_RFU_11Reserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_HVXC_RFU_00Reserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_HVXC_RFU_01Reserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_HVXC_RFU_10Reserved for future use
G3XDDC_DRM_STATE_AUDIO_MODE_HVXC_RFU_11Reserved for future use