Adapter functions

Detailed Description

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


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 *pp_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 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.

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:
hAdapter A handle to an ASX adapter object.
pnSubSystemMask A bit mapped mask of the subsystems that interface to this adapter.
pnSubSystemOkMask A 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:
hAdapter A handle to an ASX adapter object.
nIndex The index of the adapter mode option to fetch.
peMode The returned adapter mode option.
pnCount The 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:
hAdapter A handle to an ASX adapter object.
nIndex The property number.
eMode Enumeration mode (See asxADPROPENUM_MODE).
nSubIndex Subindex.
pdwSetting Returned 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:
hAdapter A handle to an ASX adapter object.
nDspIndex The DSP index. On adapters with more than one DSP, all DSPs can be accessed using this index field.
pnDspUtilization The 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:
hAdapter A handle to an ASX adapter object.
pszRevision A pointer to a char array of length ASX_STRING_SHORT 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:
hAdapter A handle to an ASX adapter object.
pszRevision A pointer to a char array of length ASX_STRING_SHORT 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:
hAdapter A handle to an ASX adapter object.
pnIndex The returned index.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.

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:
hAdapter A handle to an ASX adapter object.
pszIP A 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.

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:
hAdapter A handle to an ASX adapter object.
pszMAC A pointer to a char array of length ASX_STRING_SHORT to return the MAC address string.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Adapter_GetMixer (  ASX_HANDLE  hAdapter,
ASX_HANDLE *  pp_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:
hAdapter A handle to an ASX adapter object.
pp_hMixer The retuned mixer handle.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.
Examples:
dual_mono_play/main.c, dual_mono_record/main.c, mixer/main.c, mux/main.c, play/main.c, record/main.c, and tuner/main.c.

ASX32_API ASX_ERROR ASX_Adapter_GetMode (  ASX_HANDLE  hAdapter,
enum asxADAPTERMODE *  peMode
) 
 

Get the current adapter mode.

Parameters:
hAdapter A handle to an ASX adapter object.
peMode The 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:
hAdapter A handle to an ASX adapter object.
pszName The string to use to copy the returned adapter name to.
nStringLength The length of szString in bytes.
RequiredLength The 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, dual_mono_play/main.c, dual_mono_record/main.c, mixer/main.c, mux/main.c, play/main.c, and tuner/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:
hAdapter A handle to an ASX adapter object.
pnCount A 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:
hAdapter A handle to an ASX adapter object.
pdwSerialNumber The 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:
hAdapter A handle to an ASX adapter object.
nAddress The address to read the byte from.
pcValue A 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 property value.

Parameters:
hAdapter A handle to an ASX adapter object.
nIndex The property number.
pwParm1 Receives property specific value.
pwParm2 Receives 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:
hAdapter A handle to an ASX adapter object.
eMode The 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:
hAdapter A handle to an ASX adapter object.
nAddress The address to write the byte to.
cValue The 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:
hAdapter A handle to an ASX adapter object.
nIndex The property number.
wParm1 Property specific value.
wParm2 Property specific value.
Returns:
Returns 0 if there is no error, otherwise one of asxERROR is returned.

Generated on Fri Aug 1 13:40:06 2008 for ASX by  doxygen 1.4.6-NO