Codec Engine Runtime


Data Structures

struct  Engine_Attrs
 Attributes of an Engine. 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

Typedefs

typedef Engine_Obj * Engine_Handle
 Opaque handle to an engine.
typedef Int Engine_Error
 Engine error code.
typedef Engine_Attrs Engine_Attrs
 Attributes of an Engine.

Functions

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

Typedef Documentation

typedef struct Engine_Obj* Engine_Handle
 

Opaque handle to an engine.

typedef Int Engine_Error
 

Engine error code.

typedef struct Engine_Attrs Engine_Attrs
 

Attributes of an Engine.

See also:
Engine_open() and Engine_ATTRS.

Function Documentation

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:

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.

Int Engine_getCpuLoad (  Engine_Handle  engine  ) 
 

Get Server's cpu usage in percent.

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

UInt32 Engine_getUsedMem (  Engine_Handle  engine  ) 
 

Get Server's total memory usage.

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:

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:
success/error code
Precondition:
engine is a valid (non-NULL) engine handle and the engine is in the open state.

Variable Documentation

Engine_Attrs Engine_ATTRS
 

Default engine attributes.

Default attrs.

Copyright 2006, Texas Instruments Incorporated