AudioScience HPI Version_4.20.16
Data Structures | Enumerations | Functions

Tuner Controls

Controls

The tuner control sets the band and frequency of a tuner, and measures the RF level. More...

Data Structures

struct  hpi_dab_service_component
 Basic component information. More...
struct  hpi_dab_service_info
 Information about a DAB service. More...
struct  hpi_dab_component_info
 Detailed DAB component information. More...
struct  hpi_service_data_packet_info
 Header for DAB data packets. More...

Enumerations

enum  HPI_TUNER_BAND {
  HPI_TUNER_BAND_AM = 1, HPI_TUNER_BAND_FM = 2, HPI_TUNER_BAND_TV_NTSC_M = 3 , HPI_TUNER_BAND_FM_STEREO = 4,
  HPI_TUNER_BAND_AUX = 5, HPI_TUNER_BAND_TV_PAL_BG = 6, HPI_TUNER_BAND_TV_PAL_I = 7, HPI_TUNER_BAND_TV_PAL_DK = 8,
  HPI_TUNER_BAND_TV_SECAM_L = 9 , HPI_TUNER_BAND_LAST = 10
}
 

Tuner bands.

More...
enum  HPI_TUNER_MODES { HPI_TUNER_MODE_RSS = 1, HPI_TUNER_MODE_RDS = 2 }
 

Tuner mode attributes.

More...
enum  HPI_TUNER_MODE_VALUES {
  HPI_TUNER_MODE_RSS_DISABLE = 0, HPI_TUNER_MODE_RSS_ENABLE = 1, HPI_TUNER_MODE_RDS_DISABLE = 0, HPI_TUNER_MODE_RDS_RDS = 1,
  HPI_TUNER_MODE_RDS_RBDS = 2
}
 

Tuner mode attribute values.

More...
enum  HPI_TUNER_STATUS_BITS {
  HPI_TUNER_VIDEO_COLOR_PRESENT = 0x0001, HPI_TUNER_VIDEO_IS_60HZ = 0x0020, HPI_TUNER_VIDEO_HORZ_SYNC_MISSING = 0x0040, HPI_TUNER_VIDEO_STATUS_VALID = 0x0100,
  HPI_TUNER_DIGITAL = 0x0200, HPI_TUNER_MULTIPROGRAM = 0x0400, HPI_TUNER_PLL_LOCKED = 0x1000, HPI_TUNER_FM_STEREO = 0x2000
}
 

Tuner Status Bits.

More...

Functions

hpi_err_t HPI_Tuner_QueryBand (const hpi_hsubsys_t *phSubSys, const hpi_handle_t hTuner, const uint32_t dwIndex, uint16_t *pwBand)
 Query tuner for supported bands.
hpi_err_t HPI_Tuner_SetBand (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wBand)
 Set the band that the tuner recieves.
hpi_err_t HPI_Tuner_GetBand (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t *pwBand)
 Get the current tuner band.
hpi_err_t HPI_Tuner_QueryFrequency (const hpi_hsubsys_t *phSubSys, const hpi_handle_t hTuner, const uint32_t dwIndex, const uint16_t band, uint32_t *pdwFreq)
 Query tuner band for supported frequency range and steps Calling with dwIndex=0,1,2 returns frequency minimum, maximum and step respectively (in kHz), for the specified band.
hpi_err_t HPI_Tuner_SetFrequency (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t wFreqInkHz)
 Set the tuner frequency.
hpi_err_t HPI_Tuner_GetFrequency (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pwFreqInkHz)
 Get the current tuner frequency.
hpi_err_t HPI_Tuner_QueryGain (const hpi_hsubsys_t *phSubSys, const hpi_handle_t hTuner, const uint32_t dwIndex, uint16_t *pwGain)
 Query possible settings of tuner gain control Iterate dwIndex until an error is returned to get the list of gains supported by this tuner.
hpi_err_t HPI_Tuner_SetGain (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short nGain)
 Set the RF attenuator gain of the tuner front end.
hpi_err_t HPI_Tuner_GetGain (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short *pnGain)
 Get the current tuner gain.
hpi_err_t HPI_Tuner_GetRFLevel (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short *pwLevel)
 Get the RF level of a tuner input in millibel microvolts.
hpi_err_t HPI_Tuner_GetRawRFLevel (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short *pwLevel)
 Get the RF raw level of a tuner.
hpi_err_t HPI_Tuner_QueryDeemphasis (const hpi_hsubsys_t *phSubSys, const hpi_handle_t hTuner, const uint32_t dwIndex, const uint16_t band, uint32_t *pdwDeemphasis)
 Query tuner band for supported deemphasis settings.
hpi_err_t HPI_Tuner_SetDeemphasis (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t dwDeemphasis)
 Set the audio de-emphasis.
hpi_err_t HPI_Tuner_GetDeemphasis (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pdwDeemphasis)
 Get the audio de-emphasis setting.
hpi_err_t HPI_Tuner_QueryProgram (const hpi_hsubsys_t *phSubSys, const hpi_handle_t hTuner, uint32_t *pbitmapProgram)
 Get list of the HD Radio programs supported by this tuner as a bitfield.
hpi_err_t HPI_Tuner_SetProgram (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t dwProgram)
 Sets the tuner HD Radio program.
hpi_err_t HPI_Tuner_GetProgram (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pdwProgram)
 Gets the tuner HD Radio program.
hpi_err_t HPI_Tuner_GetHdRadioDspVersion (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszDspVersion, const uint32_t dwStringSize)
 Gets the DSP firmware verison of an HD Radio tuner.
hpi_err_t HPI_Tuner_GetHdRadioSdkVersion (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszSdkVersion, const uint32_t dwStringSize)
 Gets the SDK firmware verison of an HD Radio tuner.
hpi_err_t HPI_Tuner_GetFirmwareVersion (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszFWVersion, const uint32_t dwStringSize)
 Gets the Firmware firmware verison of a HD or DAB Radio tuner.
hpi_err_t HPI_Tuner_GetStatus (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t *pwStatusMask, uint16_t *pwStatus)
 Get the status of various Boolean attributes of a tuner control.
hpi_err_t HPI_Tuner_SetMode (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t nMode, uint32_t nValue)
 This function turns off the RSS (FM FR level reading) capability for the specified tuner.
hpi_err_t HPI_Tuner_GetMode (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t nMode, uint32_t *pnValue)
 Get the current tuner mode.
hpi_err_t HPI_Tuner_GetHdRadioSignalQuality (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pdwQuality)
 Get the digital signal quality from an HDRadio tuner.
hpi_err_t HPI_Tuner_GetHdRadioSignalBlend (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pdwBlend)
 Get the signal blend from an HDRadio tuner.
hpi_err_t HPI_Tuner_SetHdRadioSignalBlend (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, const uint32_t dwBlend)
 Set the signal blend from an HDRadio tuner.
hpi_err_t HPI_Tuner_SetDabAudioService (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, const uint32_t dwIndex)
 Sets the DAB audio service.
hpi_err_t HPI_Tuner_GetDabAudioServiceName (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszAudioServiceName, const uint32_t dwStringSize, const uint32_t nIndex)
 Gets the DAB audio service name.
hpi_err_t HPI_Tuner_GetDabAudioServiceCount (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t *pdwIndex, uint32_t *pdwCount)
 Gets the number of DAB audio services.
hpi_err_t HPI_Tuner_GetDabMultiplexName (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszMultiplexName, const uint32_t dwStringSize)
 Gets the DAB Multiplex name.
hpi_err_t HPI_Tuner_GetDabAudioInfo (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pszInfo, const uint32_t dwStringSize)
 Gets the current DAB audio service information - bitrate, mode etc.
hpi_err_t HPI_Tuner_GetDabServiceInfo (hpi_handle_t hControl, unsigned int index, struct hpi_dab_service_info *service_info)
 Get DAB service info.
hpi_err_t HPI_Tuner_GetDabComponentInfo (hpi_handle_t hControl, uint32_t service_id, uint16_t component_id, struct hpi_dab_component_info *component_info)
 Get DAB component info.
hpi_err_t HPI_Tuner_GetDabDataPacket (hpi_handle_t hControl, char *buffer, const size_t buf_len, size_t *data_len, int *next_poll_interval_ms)
 Get DAB data packet.
hpi_err_t HPI_Tuner_SetDabService (hpi_handle_t hControl, uint32_t service_id, uint16_t component_id, int start)
 Start or stop a DAB data service.
hpi_err_t HPI_Tuner_GetDabService (hpi_handle_t hControl, uint32_t *service_id, uint16_t *component_id)
 Get the currently selected Audio service.
hpi_err_t HPI_Tuner_GetRDS (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, char *pData)
 Get tuner RDS data.

Detailed Description

The tuner control sets the band and frequency of a tuner, and measures the RF level.

tuner.png

Enumeration Type Documentation

Tuner bands.

Used for HPI_Tuner_SetBand(),HPI_Tuner_GetBand()

Enumerator:
HPI_TUNER_BAND_AM 

AM band.

HPI_TUNER_BAND_FM 

FM band (mono)

HPI_TUNER_BAND_TV_NTSC_M 

NTSC-M TV band.

HPI_TUNER_BAND_FM_STEREO 

FM band (stereo)

HPI_TUNER_BAND_AUX 

Auxiliary input.

HPI_TUNER_BAND_TV_PAL_BG 

PAL-B/G TV band.

HPI_TUNER_BAND_TV_PAL_I 

PAL-I TV band.

HPI_TUNER_BAND_TV_PAL_DK 

PAL-D/K TV band.

HPI_TUNER_BAND_TV_SECAM_L 

SECAM-L TV band.

HPI_TUNER_BAND_LAST 

The index of the last tuner band.

Tuner mode attributes.

Used by HPI_Tuner_SetMode(), HPI_Tuner_GetMode()

Enumerator:
HPI_TUNER_MODE_RSS 

Control RSS.

HPI_TUNER_MODE_RDS 

Control RBDS/RDS.

Tuner mode attribute values.

Used by HPI_Tuner_SetMode(), HPI_Tuner_GetMode()

Enumerator:
HPI_TUNER_MODE_RSS_DISABLE 

RSS disable.

HPI_TUNER_MODE_RSS_ENABLE 

RSS enable.

HPI_TUNER_MODE_RDS_DISABLE 

RDS - disabled.

HPI_TUNER_MODE_RDS_RDS 

RDS - RDS mode.

HPI_TUNER_MODE_RDS_RBDS 

RDS - RBDS mode.

Tuner Status Bits.

These bitfield values are returned by a call to HPI_Tuner_GetStatus(). Multiple fields are returned from a single call.

Enumerator:
HPI_TUNER_VIDEO_COLOR_PRESENT 

Video color is present.

HPI_TUNER_VIDEO_IS_60HZ 

60 Hz video detected.

HPI_TUNER_VIDEO_HORZ_SYNC_MISSING 

Video HSYNC is missing.

HPI_TUNER_VIDEO_STATUS_VALID 

Video status is valid.

HPI_TUNER_DIGITAL 

Tuner reports digital programming.

HPI_TUNER_MULTIPROGRAM 

Tuner reports multiple programs.

HPI_TUNER_PLL_LOCKED 

The tuner's PLL is locked.

HPI_TUNER_FM_STEREO 

Tuner reports back FM stereo.


Function Documentation

hpi_err_t HPI_Tuner_QueryBand ( const hpi_hsubsys_t *  phSubSys,
const hpi_handle_t  hTuner,
const uint32_t  dwIndex,
uint16_t *  pwBand 
)

Query tuner for supported bands.

Iterate dwIndex until an error is returned to get the list of bands supported by this tuner

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hTunerControl to query
dwIndexIndex for possible attribute values
pwBandband

References HPI_ControlQuery().

hpi_err_t HPI_Tuner_SetBand ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t  wBand 
)

Set the band that the tuner recieves.

Not all tuners support all bands, e.g. AM+FM or TV+FM.

Note:
That with the exception of HPI_TUNER_BAND_AUX, the tuner frequency must subsequently be set using HPI_Tuner_SetFrequency().
The tuner band may not change immediately. It may take up to 300ms to change. To determine when the band has changed, call HPI_Tuner_GetBand() until it returns the new band.
See also:
HPI_ControlQuery() for details on determining the bands supported by a particular Tuner Controls.
Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
wBandOne of the supported bands HPI_TUNER_BAND.
hpi_err_t HPI_Tuner_GetBand ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t *  pwBand 
)

Get the current tuner band.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pwBandCurrent tuner band - one of HPI_TUNER_BAND bands.
hpi_err_t HPI_Tuner_QueryFrequency ( const hpi_hsubsys_t *  phSubSys,
const hpi_handle_t  hTuner,
const uint32_t  dwIndex,
const uint16_t  band,
uint32_t *  pdwFreq 
)

Query tuner band for supported frequency range and steps Calling with dwIndex=0,1,2 returns frequency minimum, maximum and step respectively (in kHz), for the specified band.

For example, to determine the frequency range of the AM band, do the following:

wErr= HPI_Tuner_QueryFrequency(phSS,hC, HPI_TUNER_FREQ, 0, HPI_TUNER_BAND_AM , pdwMinFreq);
wErr= HPI_Tuner_QueryFrequency(phSS,hC, HPI_TUNER_FREQ, 1, HPI_TUNER_BAND_AM , pdwMaxFreq);
wErr= HPI_Tuner_QueryFrequency(phSS,hC, HPI_TUNER_FREQ, 2, HPI_TUNER_BAND_AM , pdwFreqStep);
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hTunerControl to query
dwIndexIndex for possible attribute values
bandBand for which to query frequency range
pdwFreqfrequency min,max, step for given band

References HPI_ControlQuery().

hpi_err_t HPI_Tuner_SetFrequency ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t  wFreqInkHz 
)

Set the tuner frequency.

Note:
See HPI_ControlQuery() to determine how to find the frequency supported by a particular tuner band.
The tuner frequency may not change immediately. It may take up to 300ms to change. To determine when the frequency has changed, call HPI_Tuner_GetFrequency() until it returns the new frequency.
Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlVestigial subsys handle (unused), may be set to NULL
wFreqInkHzTuner frequncy in kHz. Valid values depend on the tuner band setting.
hpi_err_t HPI_Tuner_GetFrequency ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pwFreqInkHz 
)

Get the current tuner frequency.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pwFreqInkHzReturned tuner frequency in kHz.
hpi_err_t HPI_Tuner_QueryGain ( const hpi_hsubsys_t *  phSubSys,
const hpi_handle_t  hTuner,
const uint32_t  dwIndex,
uint16_t *  pwGain 
)

Query possible settings of tuner gain control Iterate dwIndex until an error is returned to get the list of gains supported by this tuner.

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hTunerControl to query
dwIndexIndex for possible attribute values
pwGainTuner gain in millibels

References HPI_ControlQuery().

hpi_err_t HPI_Tuner_SetGain ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
short  nGain 
)

Set the RF attenuator gain of the tuner front end.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
nGainValid values depend on the adapter type. For the ASI8700: 0dB or -20 x HPI_UNITS_PER_dB.
hpi_err_t HPI_Tuner_GetGain ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
short *  pnGain 
)

Get the current tuner gain.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pnGainCurrent tuner gain in milliBels
hpi_err_t HPI_Tuner_GetRFLevel ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
short *  pwLevel 
)

Get the RF level of a tuner input in millibel microvolts.

Divide the return value by HPI_UNITS_PER_dB to get the level in dBuV.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pwLevelReturn level. The units are mBuV (mB micro volts). Range is +/- 100 dBuV
hpi_err_t HPI_Tuner_GetRawRFLevel ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
short *  pwLevel 
)

Get the RF raw level of a tuner.

This is a "raw" value and it will depend on the type of tuner being accessed. This function only applies to certain bands on certain tuners. ASI87xx - Supports this function.
ASI89xx with ASI1711 tuner - Does not support this function. It will return HPI_ERROR_INVALID_CONTROL_ATTRIBUTE.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pwLevelThe units of this depend on the tuner type. This is the raw level reading that the tuner returns.
hpi_err_t HPI_Tuner_QueryDeemphasis ( const hpi_hsubsys_t *  phSubSys,
const hpi_handle_t  hTuner,
const uint32_t  dwIndex,
const uint16_t  band,
uint32_t *  pdwDeemphasis 
)

Query tuner band for supported deemphasis settings.

Some tuner bands don't support deemphasis, and will return an empty list. Iterate dwIndex until an error is returned to get the list of deemphasis supported by this tuner band.

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hTunerControl to query
dwIndexIndex for possible deemphasis values
bandBand for which to query deemphasis
pdwDeemphasisdeemphasis in us

References HPI_ControlQuery().

hpi_err_t HPI_Tuner_SetDeemphasis ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t  dwDeemphasis 
)

Set the audio de-emphasis.

Not all tuners support de-emphasis. USA FM channels require de-emphasis of 75 usec, while Europe requires 50 usec. Some AM tuners may also have a deemphasis setting.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
dwDeemphasisPre-emphasis - 0, 50 or 75 (usec)
hpi_err_t HPI_Tuner_GetDeemphasis ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pdwDeemphasis 
)

Get the audio de-emphasis setting.

Not all tuners support de-emphasis.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pdwDeemphasisReturns pre-emphasis value of, 0, 50 or 75 (usec)
hpi_err_t HPI_Tuner_QueryProgram ( const hpi_hsubsys_t *  phSubSys,
const hpi_handle_t  hTuner,
uint32_t *  pbitmapProgram 
)

Get list of the HD Radio programs supported by this tuner as a bitfield.

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hTunerControl to query
pbitmapProgramTuner program bitfield. Each bit position, when set indicates an available HD Radio program. Bits 0..7 are valid

References HPI_ControlQuery().

hpi_err_t HPI_Tuner_SetProgram ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t  dwProgram 
)

Sets the tuner HD Radio program.

HD Radio tuners and transmitting stations support multiple programs on a single tuner frequency. This API allows the user to set the program number on the currently tuned channel. See HPI_ControlQuery() documentation for how to find the list of supported programs.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
dwProgramProgram number to set. Range is 0-7.
hpi_err_t HPI_Tuner_GetProgram ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pdwProgram 
)

Gets the tuner HD Radio program.

HD Radio tuners and transmitting stations support multiple programs on a single tuner frequency. This API allows the user to get the current program number on the currently tuned channel.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pdwProgramReturns current program. Range is 0-7.
hpi_err_t HPI_Tuner_GetHdRadioDspVersion ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszDspVersion,
const uint32_t  dwStringSize 
)

Gets the DSP firmware verison of an HD Radio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszDspVersionReturns current version of DSP software running on the tuner.
dwStringSizeLength on the string in bytes.
hpi_err_t HPI_Tuner_GetHdRadioSdkVersion ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszSdkVersion,
const uint32_t  dwStringSize 
)

Gets the SDK firmware verison of an HD Radio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszSdkVersionReturns current version of SDK software running on the tuner.
dwStringSizeLength on the string in bytes.
hpi_err_t HPI_Tuner_GetFirmwareVersion ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszFWVersion,
const uint32_t  dwStringSize 
)

Gets the Firmware firmware verison of a HD or DAB Radio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszFWVersionReturns current version of SDK software running on the tuner.
dwStringSizeLength of the string buffer in bytes.
hpi_err_t HPI_Tuner_GetStatus ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint16_t *  pwStatusMask,
uint16_t *  pwStatus 
)

Get the status of various Boolean attributes of a tuner control.

The pwStatusMask returns which bits in wStatus are valid, as not all tuners support all the status attributes.

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
*pwStatusMaskA returned bitfield indicating which of the bits in pwStatus contain valid status information. See HPI_TUNER_STATUS_BITS for valid bit settings.
*pwStatusA returned bitfield containing current status flags. See HPI_TUNER_STATUS_BITS for bit meanings.
Returns:
0 on success, or one of the HPI_ERROR_CODES.
hpi_err_t HPI_Tuner_SetMode ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t  nMode,
uint32_t  nValue 
)

This function turns off the RSS (FM FR level reading) capability for the specified tuner.

This only applies to certain bands on certain tuners.
ASI87xx - Supports nMode = HPI_TUNER_MODE_RSS
ASI89xx with ASI1721 tuner - Supports nMode = HPI_TUNER_MODE_RDS
Otherwise will return HPI_ERROR_INVALID_CONTROL_ATTRIBUTE.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
nModeOne of the HPI_TUNER_MODES
nValueOne of the HPI_TUNER_MODE_VALUES, according to the mode
hpi_err_t HPI_Tuner_GetMode ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t  nMode,
uint32_t *  pnValue 
)

Get the current tuner mode.

Currently supports checking whether RSS is enabled or disabled. There are some dependancies across adapters for this function.
ASI87xx - Supports nMode = HPI_TUNER_MODE_RSS.
ASI89xx with ASI1711 tuner - RSS is always enabled. Supports nMode = HPI_TUNER_MODE_RDS
Otherwise will return HPI_ERROR_INVALID_CONTROL_ATTRIBUTE.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
nModeCurrently only supports HPI_TUNER_MODE_RSS.
pnValueReturned value is either HPI_TUNER_MODE_RSS_DISABLE or HPI_TUNER_MODE_RSS_ENABLE.
hpi_err_t HPI_Tuner_GetHdRadioSignalQuality ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pdwQuality 
)

Get the digital signal quality from an HDRadio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pdwQualityPointer to returned HDRadio signal quality.
hpi_err_t HPI_Tuner_GetHdRadioSignalBlend ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pdwBlend 
)

Get the signal blend from an HDRadio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pdwBlendPointer to returned HDRadio blend (0 = automatic, 1 = force analog only).
hpi_err_t HPI_Tuner_SetHdRadioSignalBlend ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
const uint32_t  dwBlend 
)

Set the signal blend from an HDRadio tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
dwBlendHDRadio blend (0 = automatic, 1 = force analog only).
hpi_err_t HPI_Tuner_SetDabAudioService ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
const uint32_t  dwIndex 
)

Sets the DAB audio service.

Deprecated:
This function is no longer supported. Use HPI_Tuner_SetDabService() instead.

DAB/DAB+ supports multiple services on a single tuner frequency (multiplex/ensemble). This API allows the user to set the service number on the currently tuned multiplex/ensemble.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
dwIndexService number to set
hpi_err_t HPI_Tuner_GetDabAudioServiceName ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszAudioServiceName,
const uint32_t  dwStringSize,
const uint32_t  nIndex 
)

Gets the DAB audio service name.

Deprecated:
This function is no longer supported. Use HPI_Tuner_GetDabServiceInfo() instead.

DAB/DAB+ supports multiple services on a single tuner frequency (multiplex/ensemble) This API allows the user to get the service name of the specified service index.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszAudioServiceNameReturns name of indexed programme (max length 16 chars) pointer to name of queried service
dwStringSizeLength of the string buffer in bytes.
nIndexindex of service
hpi_err_t HPI_Tuner_GetDabAudioServiceCount ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
uint32_t *  pdwIndex,
uint32_t *  pdwCount 
)

Gets the number of DAB audio services.

Certain tuners and transmitting stations support multiple services on a single tuner frequency. This API allows the user to get the number of services on the currently tuned channel.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pdwIndexUse of this argument is deprecated and its value should be ignored.
pdwCount# of services on ensemble
hpi_err_t HPI_Tuner_GetDabMultiplexName ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszMultiplexName,
const uint32_t  dwStringSize 
)

Gets the DAB Multiplex name.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszMultiplexNamepointer to string to return the multiplex/ensemble name
dwStringSizeLength of the string buffer in bytes.
hpi_err_t HPI_Tuner_GetDabAudioInfo ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pszInfo,
const uint32_t  dwStringSize 
)

Gets the current DAB audio service information - bitrate, mode etc.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to tuner control.
pszInfopointer to string to return the DAB audio information
dwStringSizeLength of the string buffer in bytes.
hpi_err_t HPI_Tuner_GetDabServiceInfo ( hpi_handle_t  hControl,
unsigned int  index,
struct hpi_dab_service_info service_info 
)

Get DAB service info.

This API is called with a particular service index and returns a structure, dab_service_info, that contains information about the service, including id, name, number of components and their ids.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
hControlTuner handle
indexEnumeration index, 0 .. num_services-1
service_infodab_service_info structure
hpi_err_t HPI_Tuner_GetDabComponentInfo ( hpi_handle_t  hControl,
uint32_t  service_id,
uint16_t  component_id,
struct hpi_dab_component_info component_info 
)

Get DAB component info.

This API used to find out information about each component. It returns this in the dab_component_info structure including its id, name and its User Application (UA) types of Program Associated Data (PAD) contained in the component. For example a UA type of 7 is EPG and UA type of 2 is a MOT slideshow.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Note:
This function uses deferred HPI processing. This means that it must be repeatedly called with the same parameters until it returns something other than HPI_ERROR_CONTROL_NOT_READY. One deferred call per tuner can be in progress simultaneously.
Parameters:
hControlTuner handle
service_idService ID from service list
component_idComponent ID from service list
component_infoPointer to struct dab_component_info for result
hpi_err_t HPI_Tuner_GetDabDataPacket ( hpi_handle_t  hControl,
char *  buffer,
const size_t  buf_len,
size_t *  data_len,
int *  next_poll_interval_ms 
)

Get DAB data packet.

This returns data into a user-supplied buffer (A buffer of 8KiB will accomodate the maximum size packet). This function should be polled at least every 50ms.

The beginning of the buffer is a struct hpi_service_data_packet_info, containing information about how to interpret the rest of the buffer data.

hpi_service_data_packet_info.data_type indicates the kind of data packet; For example, a .data_type of 128, means that the rest of the buffer contains DLS text. hpi_service_data_packet_info.buff_count is number of remaining packets on the tuner.

Returns:
0 on success, or one of the HPI_ERROR_CODES. The function will return HPI_ERROR_CONTROL_NOT_READY if there is no packet available.
Parameters:
hControl- tuner handle
buffer- buffer for component info structure, recommend 8KiB
buf_len- size of buffer
data_len- actual number of bytes returned into buffer OR if retval==HPI_ERROR_RESPONSE_BUFFER_TOO_SMALL, the minimum buffer size needed
next_poll_interval_ms- recommended delay before calling this function again, typically 50ms.

References hpi_service_data_packet_info::buff_count, and hpi_service_data_packet_info::flags.

hpi_err_t HPI_Tuner_SetDabService ( hpi_handle_t  hControl,
uint32_t  service_id,
uint16_t  component_id,
int  start 
)

Start or stop a DAB data service.

A particular service/component is then started (or stopped) using this API. If the component contains audio, then it will start being rendered (and any previous audio component will be stopped). If the component contains PAD or is a data-only component, data packets will start accumulating in a buffer. If the component is non-audio, it can be enabled concurrently to other components.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Note:
This function uses deferred HPI processing. This means that it must be repeatedly called with the same parameters until it returns something other than HPI_ERROR_CONTROL_NOT_READY. One deferred call per tuner can be in progress simultaneously.
Parameters:
hControl- tuner handle
service_id- from service list
component_id- from service list
start- 1=start service, 0=stop service
hpi_err_t HPI_Tuner_GetDabService ( hpi_handle_t  hControl,
uint32_t *  service_id,
uint16_t *  component_id 
)

Get the currently selected Audio service.

Returns:
0 on success, or one of the HPI_ERROR_CODES.

This returns the ID of the last audio service that was set. It will have a zero MSB, indicating that it is an audio service.

Parameters:
hControl- tuner handle
service_id- 32 bit service ID
component_id- 16 bit component ID
hpi_err_t HPI_Tuner_GetRDS ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hControl,
char *  pData 
)

Get tuner RDS data.

Returns RDS data if there is any. ASI87xx - Does not support this function.
ASI8821/8921 with ASI172x tuner - Does support this function.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Return values:
HPI_ERROR_INVALID_DATASIZEif the RDS buffer is now empty.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL.
hControlHandle to tuner control.
pDatapointer to 12 element array for returned RDS data (i.e. an array of 12 chars).