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_GetAVDECCController (ASX_HANDLE hAdapter, void **controller_obj)
	Gets an adapter's AVDECC Controller object.
ASX32_API ASX_ERROR	ASX_Adapter_GetAVDECCSystem (ASX_HANDLE hAdapter, void **sys)
	This function returns the system object used by adapters of subsystem type 1722.1.
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:

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_GetAVDECCController	(	ASX_HANDLE	hAdapter,
		void **	controller_obj
	)

Gets an adapter's AVDECC Controller object.

This function returns the controller object used by adapters of subsystem type 1722.1

Parameters:

hAdapter	A handle to an ASX adapter object.
controller_obj	The returned controller object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Adapter_GetAVDECCSystem	(	ASX_HANDLE	hAdapter,
		void **	sys
	)

This function returns the system object used by adapters of subsystem type 1722.1.

Parameters:

hAdapter	A handle to an ASX adapter object.
sys	The returned system object.

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

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

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.

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:

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.

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:

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

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:

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

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

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

  hAdapter	A handle to an ASX adapter object.
  nIndex	The index of the property to read.
  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.