ASX Version4.13.09
Functions

Adapter functions

The adapter functions are used to obtain adapter information and access the mixer. More...

Functions

ASX32_API ASX_ERROR ASX_Adapter_CheckSubSystems (ASX_HANDLE hAdapter, unsigned int *pnSubSystemMask, unsigned int *pnSubSystemOkMask)
 Returns the status of the various sub-systems that interface to the adapter.
ASX32_API ASX_ERROR ASX_Adapter_GetName (ASX_HANDLE hAdapter, char *pszName, const int nStringLength, int *RequiredLength)
 Gets the name of the adapter.
ASX32_API ASX_ERROR ASX_Adapter_GetIndex (ASX_HANDLE hAdapter, int *pnIndex)
 Gets an adapter's index.
ASX32_API ASX_ERROR ASX_Adapter_GetSerialNumber (ASX_HANDLE hAdapter, unsigned long *pdwSerialNumber)
 Gets an adapter's serial number.
ASX32_API ASX_ERROR ASX_Adapter_GetHardwareRevision (ASX_HANDLE hAdapter, char *pszRevision)
 Gets an adapter's hardware revision.
ASX32_API ASX_ERROR ASX_Adapter_GetFirmwareRevision (ASX_HANDLE hAdapter, char *pszRevision)
 Gets an adapter's firmware revision.
ASX32_API ASX_ERROR ASX_Adapter_GetMacAddress (ASX_HANDLE hAdapter, char *pszMAC)
 Gets an adapter's ethernet MAC address.
ASX32_API ASX_ERROR ASX_Adapter_GetIpAddress (ASX_HANDLE hAdapter, char *pszIP)
 Gets an adapter's network IP address.
ASX32_API ASX_ERROR ASX_Adapter_GetDspUtilization (ASX_HANDLE hAdapter, const int nDspIndex, int *pnDspUtilization)
 Gets an adapter's DSP utilization.
ASX32_API ASX_ERROR ASX_Adapter_GetMixer (ASX_HANDLE hAdapter, ASX_HANDLE *p_hMixer)
 Gets a handle to an adapter's mixer.
ASX32_API ASX_ERROR ASX_Adapter_EnumerateMode (ASX_HANDLE hAdapter, const int nIndex, enum asxADAPTERMODE *peMode, int *pnCount)
 Enumerate each adapter mode option.
ASX32_API ASX_ERROR ASX_Adapter_GetMode (ASX_HANDLE hAdapter, enum asxADAPTERMODE *peMode)
 Get the current adapter mode.
ASX32_API ASX_ERROR ASX_Adapter_SetMode (ASX_HANDLE hAdapter, const enum asxADAPTERMODE eMode)
 Set the current adapter mode.
ASX32_API ASX_ERROR ASX_Adapter_EnumerateProperty (ASX_HANDLE hAdapter, const int nIndex, const enum asxADPROPENUM_MODE eMode, const int nSubIndex, unsigned long *pdwSetting)
 Enumerates adapter properties and settings.
ASX32_API ASX_ERROR ASX_Adapter_ReadProperty (ASX_HANDLE hAdapter, const int nIndex, unsigned short *pwParm1, unsigned short *pwParm2)
 Read an adapter's property value.
ASX32_API ASX_ERROR ASX_Adapter_WriteProperty (ASX_HANDLE hAdapter, const int nIndex, const unsigned short wParm1, const unsigned short wParm2)
 Write an adapter property value.
ASX32_API ASX_ERROR ASX_Adapter_WriteNvMem (ASX_HANDLE hAdapter, const int nAddress, const unsigned char cValue)
 Write a byte to the non-volatile memory.
ASX32_API ASX_ERROR ASX_Adapter_ReadNvMem (ASX_HANDLE hAdapter, const int nAddress, unsigned char *pcValue)
 Read a byte from the non-volatile memory.
ASX32_API ASX_ERROR ASX_Adapter_GetNvMemSizeInBytes (ASX_HANDLE hAdapter, int *pnCount)
 Get the number of bytes in the adapter's non-volatile memory.

Detailed Description

The adapter functions are used to obtain adapter information and access the mixer.


Function Documentation

ASX32_API ASX_ERROR ASX_Adapter_CheckSubSystems ( ASX_HANDLE  hAdapter,
unsigned int *  pnSubSystemMask,
unsigned int *  pnSubSystemOkMask 
)

Returns the status of the various sub-systems that interface to the adapter.

This function is primarily implemented to provide feedback on whether adapters (or subsystems) that a network interface are working correctly. The bit masks used in this function consist of 1<<ASX_SYSTEM_TYPE_xxxx.

Parameters:
hAdapterA handle to an ASX adapter object.
pnSubSystemMaskA bit mapped mask of the subsystems that interface to this adapter.
pnSubSystemOkMaskA bit mapped result indicating that a particular interface is ok.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_EnumerateMode ( ASX_HANDLE  hAdapter,
const int  nIndex,
enum asxADAPTERMODE peMode,
int *  pnCount 
)

Enumerate each adapter mode option.

Parameters:
hAdapterA handle to an ASX adapter object.
nIndexThe index of the adapter mode option to fetch.
peModeThe returned adapter mode option.
pnCountThe total number of available mode options. See asxADAPTERMODE for available options.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_EnumerateProperty ( ASX_HANDLE  hAdapter,
const int  nIndex,
const enum asxADPROPENUM_MODE  eMode,
const int  nSubIndex,
unsigned long *  pdwSetting 
)

Enumerates adapter properties and settings.

Parameters:
hAdapterA handle to an ASX adapter object.
nIndexThe property number.
eModeEnumeration mode (See asxADPROPENUM_MODE).
nSubIndexSubindex.
pdwSettingReturned setting.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_GetDspUtilization ( ASX_HANDLE  hAdapter,
const int  nDspIndex,
int *  pnDspUtilization 
)

Gets an adapter's DSP utilization.

This function returns the DSP percentage utilization of the audio adapter referenced by hAdapter. The utilization can be used to check the running algorithms do not over tax the DSP.

Note:
This function is currently only supported by the ASX_SYSTEM_TYPE_HPI interface.
Parameters:
hAdapterA handle to an ASX adapter object.
nDspIndexThe DSP index. On adapters with more than one DSP, all DSPs can be accessed using this index field.
pnDspUtilizationThe returned DSP utilization in percent.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
adapter/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetFirmwareRevision ( ASX_HANDLE  hAdapter,
char *  pszRevision 
)

Gets an adapter's firmware revision.

This function returns the revision of the firmware running on an audio adapter referenced by hAdapter. An example of a revision string is "v1.25".

Note:
This function is currently only supported by the ASX_SYSTEM_TYPE_HPI interface.
Parameters:
hAdapterA handle to an ASX adapter object.
pszRevisionA pointer to a char array of length ASX_SHORT_STRING to return the revision string.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_GetHardwareRevision ( ASX_HANDLE  hAdapter,
char *  pszRevision 
)

Gets an adapter's hardware revision.

This function returns the revision of the audio adapter referenced by hAdapter. The revision indicates the hardware revision of the adapter. An example of a revision string is "A0". The first character is a letter (A-Z) inticating the major revision number and the second character is a digit (0-9) indicating the minor revision number.

Note:
This function is currently only supported by the ASX_SYSTEM_TYPE_HPI interface.
Parameters:
hAdapterA handle to an ASX adapter object.
pszRevisionA pointer to a char array of length ASX_SHORT_STRING to return the revision string.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
adapter/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetIndex ( ASX_HANDLE  hAdapter,
int *  pnIndex 
)

Gets an adapter's index.

This function returns the hardware index of the audio adapter referenced by hAdapter. All AudioScience adapters have unique indexes assigned by a hardware jumper/switch (sound cards) or programmed into non-volatile memory (network devices). Indexes in the range of 1..99 are used for sound cards or other bus based devices Indexes in the range of 100..9999 are used for network devices Indexes of 10000 and higher are used to auto-assign indexes to network devices that don't have an index programmed yet Note that the hardware index is not the same as the ASX adapter index passed to ASX_System_GetAdapter()

Parameters:
hAdapterA handle to an ASX adapter object.
pnIndexThe returned index.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
adapter/main.c, and cobranet/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetIpAddress ( ASX_HANDLE  hAdapter,
char *  pszIP 
)

Gets an adapter's network IP address.

For network devices, this function returns the IP address of the Adapter. The IP address is returned as a string with the format XXX.XXX.XXX.XXX. If the adapter does not have an IP address (i.e if it was a sound card) then an error is returned.

Parameters:
hAdapterA handle to an ASX adapter object.
pszIPA pointer to a char array of length ASX_SHORT_STRING to return the MAC address string.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
cobranet/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetMacAddress ( ASX_HANDLE  hAdapter,
char *  pszMAC 
)

Gets an adapter's ethernet MAC address.

For network devices, this function returns the ethernet MAC address of the Adapter. The MAC address is returned as a string representing the 12 hex digits, with the format XXXX.XXXX.XXXX. If the adapter does not have a MAC address (i.e if it was a sound card) then an error is returned.

Parameters:
hAdapterA handle to an ASX adapter object.
pszMACA pointer to a char array of length ASX_SHORT_STRING to return the MAC address string.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
mixer/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetMixer ( ASX_HANDLE  hAdapter,
ASX_HANDLE p_hMixer 
)

Gets a handle to an adapter's mixer.

This function returns a handle to a mixer object that can then be used to access mixer nodes andcontrols.

Parameters:
hAdapterA handle to an ASX adapter object.
p_hMixerThe retuned mixer handle.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
cobranet/main.c, dual_mono_play/main.c, dual_mono_record/main.c, mixer/main.c, mux/main.c, play/main.c, playlist/main.c, record/main.c, tuner/main.c, and volume/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetMode ( ASX_HANDLE  hAdapter,
enum asxADAPTERMODE peMode 
)

Get the current adapter mode.

Parameters:
hAdapterA handle to an ASX adapter object.
peModeThe returned adapter mode. See asxADAPTERMODE for different mode options.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_GetName ( ASX_HANDLE  hAdapter,
char *  pszName,
const int  nStringLength,
int *  RequiredLength 
)

Gets the name of the adapter.

This function returns the name of the audio adapter referenced by hAdapter. An example return string would be "ASI6114" for and AudioScience ASI6114 adapter.

Note that some adapters have plug in modules and will return addition module code characters following the adapter name. For example a ASI8920 with two modules would return "ASI8920-1100", indicating that module positions 1 and 2 are populated with modules of type "1". The device datasheet, in this case the ASI8900, should be consulted to translate the module code to a module type.

// an example of the "compact" calling method would be
char szName[ASX_SHORT_STRING];

ASX_Adapter_GetName(hAdapter,szName,ASX_SHORT_STRING,NULL);
Parameters:
hAdapterA handle to an ASX adapter object.
pszNameThe string to use to copy the returned adapter name to.
nStringLengthThe length of szString in bytes.
RequiredLengthThe minimum required length of szString in bytes. This can be set to NULL if the calling passes in a string of length ASX_SHORT_STRING.
Note:
This function can be called will szString=0 and nStringLength=0 to retrieve the required string size in bytes.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
adapter/main.c, cobranet/main.c, dual_mono_play/main.c, dual_mono_record/main.c, mixer/main.c, mux/main.c, play/main.c, playlist/main.c, tuner/main.c, and volume/main.c.
ASX32_API ASX_ERROR ASX_Adapter_GetNvMemSizeInBytes ( ASX_HANDLE  hAdapter,
int *  pnCount 
)

Get the number of bytes in the adapter's non-volatile memory.

Parameters:
hAdapterA handle to an ASX adapter object.
pnCountA pointer to the returned total number of bytes.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_GetSerialNumber ( ASX_HANDLE  hAdapter,
unsigned long *  pdwSerialNumber 
)

Gets an adapter's serial number.

This function returns the serial number of the audio adapter referenced by hAdapter. All AudioScience adapters have unique serial numbers assigned during manufacturing.

Parameters:
hAdapterA handle to an ASX adapter object.
pdwSerialNumberThe returned serial number.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
adapter/main.c.
ASX32_API ASX_ERROR ASX_Adapter_ReadNvMem ( ASX_HANDLE  hAdapter,
const int  nAddress,
unsigned char *  pcValue 
)

Read a byte from the non-volatile memory.

Parameters:
hAdapterA handle to an ASX adapter object.
nAddressThe address to read the byte from.
pcValueA pointer to the returned byte.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_ReadProperty ( ASX_HANDLE  hAdapter,
const int  nIndex,
unsigned short *  pwParm1,
unsigned short *  pwParm2 
)

Read an adapter's property value.

Current support property indexes are:

  • 1 = ERRATA_1, returns whether errata_1 workaround for 6100 cards is turned on.
  • 2 = SSX2_SETTING, returns whether SSX2 is on or off.
  • 3 = SYNC_HEADER_CONNECTIONS (read-only), returns the number of headers connected.
  • 4 = SUPPORT_SSX2 (read-only), returns true or false.
  • 5 = SUPPORTS_FW_UPDATE (read-only), device supports firmware updating
  • 6 = FIRMWARE_ID (read-only), firmware ID
    Parameters:
    hAdapterA handle to an ASX adapter object.
    nIndexThe index of the property to read.
    pwParm1Receives property specific value.
    pwParm2Receives property specific value.
    Returns:
    Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_SetMode ( ASX_HANDLE  hAdapter,
const enum asxADAPTERMODE  eMode 
)

Set the current adapter mode.

Parameters:
hAdapterA handle to an ASX adapter object.
eModeThe adapter mode to set. This must be one of the options returned by calls to ASX_Adapter_EnumerateMode().
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_WriteNvMem ( ASX_HANDLE  hAdapter,
const int  nAddress,
const unsigned char  cValue 
)

Write a byte to the non-volatile memory.

Parameters:
hAdapterA handle to an ASX adapter object.
nAddressThe address to write the byte to.
cValueThe byte to write.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
ASX32_API ASX_ERROR ASX_Adapter_WriteProperty ( ASX_HANDLE  hAdapter,
const int  nIndex,
const unsigned short  wParm1,
const unsigned short  wParm2 
)

Write an adapter property value.

Parameters:
hAdapterA handle to an ASX adapter object.
nIndexThe property number.
wParm1Property specific value.
wParm2Property specific value.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.