Codec Engine Runtime

Data Structures
struct	Engine_Attrs
	Attributes of an Engine. More...
struct	Engine_AlgInfo
	Properties of an Engine algorithm. More...
Defines
#define	Engine_GTNAME "CE"
	Trace name for the Engine module.
#define	Engine_EOK 0
#define	Engine_EEXIST 1
#define	Engine_ENOMEM 2
#define	Engine_EDSPLOAD 3
#define	Engine_ENOCOMM 4
#define	Engine_ENOSERVER 5
#define	Engine_ECOMALLOC 6
#define	Engine_ERUNTIME 7
#define	Engine_ECODECCREATE 8
#define	Engine_ECODECSTART 9
#define	Engine_EINVAL 10
#define	Engine_EBADSERVER 11
#define	Engine_ENOTAVAIL 12
#define	Engine_EWRONGSTATE 13
#define	Engine_EINUSE 14
#define	Engine_ENOTFOUND 15
#define	Engine_ETIMEOUT 16
Typedefs
typedef struct Engine_Obj *	Engine_Handle
	Opaque handle to an engine.
typedef Int	Engine_Error
	Engine error code.
Functions
Void	CERuntime_exit (Void)
	Exit the Codec Engine Runtime.
Void	CERuntime_init (Void)
	Initialize the Codec Engine Runtime.
Void	Engine_close (Engine_Handle engine)
	Close an Engine.
Engine_Handle	Engine_open (String name, Engine_Attrs attrs, Engine_Error ec)
	Open an Engine.
Int	Engine_fwriteTrace (Engine_Handle engine, String prefix, FILE *out)
	Write Server's trace buffer to specifed file stream.
Engine_Error	Engine_getAlgInfo (String name, Engine_AlgInfo *algInfo, Int index)
	Get details of an algorithm configured into an engine.
Int	Engine_getCpuLoad (Engine_Handle engine)
	Get Server's cpu usage in percent.
Engine_Error	Engine_getLastError (Engine_Handle engine)
	Get error code of the last failed operation.
String	Engine_getName (Engine_Handle engine)
	Get the name of an opened engine.
Engine_Error	Engine_getNumAlgs (String name, Int *numAlgs)
	Get the number of algorithms configured into an engine.
Server_Handle	Engine_getServer (Engine_Handle engine)
	Get handle to an Engine's server.
UInt32	Engine_getUsedMem (Engine_Handle engine)
	Get Server's total memory usage.
Int	Engine_setTrace (Engine_Handle engine, String mask)
	Set Server's trace mask.
Variables
Engine_Attrs	Engine_ATTRS
	Default engine attributes.

Define Documentation

#define Engine_GTNAME "CE"

Trace name for the Engine module.

#define Engine_EOK 0

Success.

#define Engine_EEXIST 1

Name does not exist.

#define Engine_ENOMEM 2

Unable to allocate memory.

#define Engine_EDSPLOAD 3

Unable to load the DSP.

#define Engine_ENOCOMM 4

Unable to create a comm connection to the DSP.

#define Engine_ENOSERVER 5

Unable to locate the server on the DSP.

#define Engine_ECOMALLOC 6

Unable to allocate communication buffer.

#define Engine_ERUNTIME 7

Internal engine runtime failure.

#define Engine_ECODECCREATE 8

Creation of the Codec failed.

#define Engine_ECODECSTART 9

Start of the Codec failed. For codecs which are implemented as a thread, this implies that the codec thread of execution failed to start.

#define Engine_EINVAL 10

Bad paramater passed to method.

#define Engine_EBADSERVER 11

Incompatible server specified.

#define Engine_ENOTAVAIL 12

Service not available.

#define Engine_EWRONGSTATE 13

Call can not be made at this time.

#define Engine_EINUSE 14

Call can't be made at this time because a required name/resource is in use.

#define Engine_ENOTFOUND 15

Entity was not found.

#define Engine_ETIMEOUT 16

Timeout-based operation timed out.

Typedef Documentation

typedef struct Engine_Obj* Engine_Handle

Opaque handle to an engine.

typedef Int Engine_Error

Engine error code.

Function Documentation

Void CERuntime_exit ( Void )

Exit the Codec Engine Runtime.

Remarks:: This function finalizes the Codec Engine modules used in the current configuration.

Void CERuntime_init ( Void )

Initialize the Codec Engine Runtime.

Remarks:: This function must be called prior to using any Codec Engine APIs; it initializes all Codec Engine modules used in the the current configuration.

Void Engine_close ( Engine_Handle engine )

Close an Engine.

Parameters:

[in] engine The handle to an engine, previously acquired by a call to Engine_open().

Precondition:: engine must not be referenced by any codec instance object; i.e., you must first delete all codec instances associated with engine before closing it.; engine is a valid (non-NULL) engine handle which is in the open state.

Engine_Handle Engine_open	(	String	name,
		Engine_Attrs *	attrs,
		Engine_Error *	ec
	)

Open an Engine.

The handle returned may be used to create one or more instances of a codec "contained" in the specified engine.

An engine may be opened more than once; each open returns a unique handle that can be used to create codec instances or get status of any underlying server.

Engine handles must not be concurrently accessed by multiple threads; each thread must either obtain its own handle (via Engine_open()) or explicitly serialize access to a shared handle.

Parameters:

`[in]`	name	The name of the engine to open. `name` is specified in the engine configuration.
`[in]`	attrs	Attributes for the open engine.
`[out]`	ec	Optional output error code

Return values:

	NULL	An error has occurred.
	non-NULL	The handle to the opened engine.

Precondition:: name is a non-NULL string.; name is a valid, pre-configured name of an engine.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:

If the return handle is NULL and ec is non-NULL, *ec is set to a non-zero value indicating the cause of the failure.

If ec is non-NULL, the Engine_Error value is set to one of the following values:

Engine_EOK success
Engine_EEXIST name does not exist
Engine_ENOMEM can't allocate memory
Engine_EDSPLOAD can't load the DSP
Engine_ENOCOMM can't create a comm connection to DSP
Engine_ENOSERVER can't locate the server on the DSP
Engine_ECOMALLOC can't allocate communication buffer

Int Engine_fwriteTrace	(	Engine_Handle	engine,
		String	prefix,
		FILE *	out
	)

Write Server's trace buffer to specifed file stream.

Parameters:

`[in]`	engine	The handle to the opened engine.
`[in]`	prefix	A string to prepend to each line output; this allows one to easily identify trace from the server from the application's trace, for example.
`[in]`	out	A open FILE stream used to output the Server's trace characters.

Return values:

Integer

number of characters copied to the specified FILE stream.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

Postcondition:

In the event a negative value is returned, Engine_getLastError() will return one of the following values:

Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Engine_EINUSE Server trace resource is already in use.

Engine_Error Engine_getAlgInfo	(	String	name,
		Engine_AlgInfo *	algInfo,
		Int	index
	)

Get details of an algorithm configured into an engine.

Parameters:

`[in]`	name	The name of the engine. `name` is specified in the engine configuration.
`[out]`	algInfo	Structure to store algorithm details. The `algInfoSize` field of this structure must be set to `sizeof(Engine_AlgInfo)` by the application.
`[out]`	index	The index of the algorithm to get the information.

Return values:

	Engine_EOK	Success.
	Engine_EEXIST	There is no engine with the given name.
	Engine_ENOTFOUND	`index` is greater than or equal to the total number of algorithms configured for the engine, or `index` < 0.
	Engine_EINVAL	The value of `algInfoSize` passed to this function does not match the CE library's `sizeof(Engine_AlgInfo)`.

Precondition:: name is a non-NULL string.; algInfo is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name and 0 <= index < the total number of algorithms configured for the engine, then algInfo will contain the information for the engine's ith (i = index) algorithm.

See also:: Engine_getNumAlgs().

Int Engine_getCpuLoad ( Engine_Handle engine )

Get Server's cpu usage in percent.

Deprecated:: This service has been replaced by Server_getCpuLoad() to better indicate that this API is not intended for obtaining the current processor's CPU load, rather it obtains the CPU load of a remote Server.

Parameters:

[in] engine The handle to the opened engine.

Return values:

integer

between 0-100 indicating percentage of time the Server is processing measured over a period of approximately 1 second. If the load is unavailable, a negative value is returned.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

Postcondition:

In the event a negative value is returned, Engine_getLastError() will return one of the following values:

Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Engine_ENOTAVAIL The CPU load can not be computed.

See also:: Server_getCpuLoad()

Engine_Error Engine_getLastError ( Engine_Handle engine )

Get error code of the last failed operation.

Parameters:

[in] engine The handle to the opened engine.

Return values:

error

code (Engine_Error) of the last failed engine operation.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

String Engine_getName ( Engine_Handle engine )

Get the name of an opened engine.

Parameters:

[in] engine The handle to the opened engine.

Return values:

	NULL	An error has occurred.
	non-NULL	The name of the opened engine.

Engine_Error Engine_getNumAlgs	(	String	name,
		Int *	numAlgs
	)

Get the number of algorithms configured into an engine.

Parameters:

`[in]`	name	The name of the engine. `name` is specified in the engine configuration.
`[out]`	numAlgs	The number of algorithms that are configured in the given engine.

Return values:

	Engine_EOK	Success.
	Engine_EEXIST	There is no engine with the given name.

Precondition:: name is a non-NULL string.; numAlgs is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name, then numAlgs will contain the number of algorithms configured for the given engine.

See also:: Engine_getAlgs().

Server_Handle Engine_getServer ( Engine_Handle engine )

Get handle to an Engine's server.

This function returns the handle to an Engines server, that can be used with Server APIs to obtain information from and control the remote DSP server.

Parameters:

[in] engine The handle to the opened engine.

Return values:

Handle

to engine's server.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

UInt32 Engine_getUsedMem ( Engine_Handle engine )

Get Server's total memory usage.

Deprecated:: This service has been replaced by Server_getMemStat() to better indicate that this API is not intended for obtaining the current processor's memory statistics, rather it obtains the memory statistics of a remote Server. Also, Server_getMemStat() provides more granularity than Engine_getUsedMem().

Parameters:

[in] engine The handle to the opened engine.

Return values:

Total

amount of used memory (in MAUs). If the amount is not available, 0 is returned and the reason can be retrieved via Engine_getLastError().

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

Postcondition:

in the event that 0 is returned, Engine_getLastError() will return one of the following values:

Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Engine_ENOTAVAIL The memory usage can not be computed.

Int Engine_setTrace	(	Engine_Handle	engine,
		String	mask
	)

Set Server's trace mask.

Parameters:

`[in]`	engine	The handle to the opened engine.
`[in]`	mask	Trace mask, e.g. "*=01234567"

Return values:

	Engine_ENOSERVER	No server for this engine.
	Engine_EINUSE	Trace resource is already in use.
	Engine_ERUNTIME	Internal runtime error has occurred.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

Remarks:: This only sets the trace for a remote server. To change the trace mask for the application-side of the framework, use GT_set().

See also:: GT_set()

Variable Documentation

Engine_Attrs Engine_ATTRS

Default engine attributes.

Default attrs.

Codec Engine Runtime

Data Structures

Defines

Typedefs

Functions

Variables

Define Documentation

Typedef Documentation

Function Documentation

Variable Documentation