This is the header file for the Apama Engine C SDK. More...

#include <AP_Types.h>
#include <AP_Platform.h>

Classes
struct	AP_Event_Functions
	Event functions API. More...

struct	AP_Event_API
	Event. More...

struct	AP_EventSupplier_Functions
	EventSupplier function API. More...

struct	AP_EventSupplier_API
	Event supplier. More...

struct	AP_EventConsumer_Functions
	EventConsumer function API. More...

struct	AP_EventConsumer_API
	EventConsumer. More...

struct	AP_DisconnectableEventConsumer_Functions
	DisconnectableEventConsumer function API. More...

struct	AP_DisconnectableEventConsumer_API
	DisconnectableEventConsumer. More...

struct	AP_MonitorScript_Functions
	MonitorScript function API. More...

struct	AP_MonitorScript_API
	Monitorscript. More...

struct	AP_EngineStatus_Functions
	EngineStatus function API. More...

struct	AP_EngineStatus_API
	EngineStatus. More...

struct	AP_NameInfo_Functions
	NameInfo function API. More...

struct	AP_NameInfo_API
	NameInfo. More...

struct	AP_NamedMonitorInfo_Functions
	NamedMonitorInfo function API. More...

struct	AP_NamedMonitorInfo_API
	NamedMonitorInfo facade for NamedInfo object. More...

struct	AP_NamedJavaApplicationInfo_Functions
	NamedJavaApplicationInfo function API. More...

struct	AP_NamedJavaApplicationInfo_API
	NamedJavaApplicationInfo facade for NamedInfo object. More...

struct	AP_NamedEventTypeInfo_Functions
	NamedEventTypeInfo function API. More...

struct	AP_NamedEventTypeInfo_API
	NamedEventTypeInfo facade for NamedInfo object. More...

struct	AP_NamedTimerInfo_Functions
	NamedTimerInfoInfo function API. More...

struct	AP_NamedTimerInfo_API
	NamedTimerInfoInfo facade for NamedInfo object. More...

struct	AP_NamedContextInfo_Functions
	NamedContextInfo function API. More...

struct	AP_NamedContextInfo_API
	NamedContextInfo facade for NamedInfo object. More...

struct	AP_NamedAggregateInfo_Functions
	NamedAggregateInfo function API. More...

struct	AP_NamedAggregateInfo_API
	NamedAggregateInfo facade for NamedInfo object. More...

struct	AP_NamedReceiverInfo_Functions
	NamedReceiverInfo function API. More...

struct	AP_NamedReceiverInfo_API
	NamedReceiverInfo facade for NamedInfo object. More...

struct	AP_NamedPluginReceiverInfo_Functions
	NamedPluginReceiverInfo function API. More...

struct	AP_NamedPluginReceiverInfo_API
	NamedPluginReceiverInfo facade for NamedInfo object. More...

struct	AP_EngineInfo_Functions
	EngineInfo function API. More...

struct	AP_EngineInfo_API
	EngineInfo. More...

struct	AP_EngineManagement_Functions
	EngineManagement function API. More...

struct	AP_EngineManagement_API
	EngineManagement. More...

Enumerations
enum	AP_EngineManagement_ConnectMode { CONNECT_LEGACY, CONNECT_PARALLEL }
	The mode that attachAsEventConsumerTo and detachAsEventConsumerFrom operate in. More...

enum	AP_EngineClientLogLevel { OFF_LEVEL, FORCE_LEVEL, CRIT_LEVEL, FATAL_LEVEL, ERROR_LEVEL, WARN_LEVEL, INFO_LEVEL, DEBUG_LEVEL, TRACE_LEVEL }
	Available logging levels. More...

enum	AP_EngineClientExceptionType { AP_ENGINE_EXCEPTION }

Functions
AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_EngineInit (const char *processName)
	This function must be called once per process first before any other Engine operations are carried out. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_EngineInitNoMessaging (const char *processName)
	This function (or engineInit) must be called once per process first before any other Engine operations are carried out. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_EngineShutdown ()
	This function must be called once per process before the application closes down. More...

AP_ENGINE_CLIENT_API AP_EngineManagement *AP_ENGINE_CLIENT_CALL	AP_ConnectToEngine (const AP_char8 *hostname, AP_uint16 port)
	This function attempts to establish a connection to an Engine. More...

AP_ENGINE_CLIENT_API AP_EngineManagement *AP_ENGINE_CLIENT_CALL	AP_connectToEngineReceiveOnly (const AP_char8 *hostname, AP_uint16 port)
	Attempt to establish a receive-only connection to an Engine listening on the named host and port. More...

AP_ENGINE_CLIENT_API AP_EngineManagement *AP_ENGINE_CLIENT_CALL	AP_connectToEngineMonitorOnly (const AP_char8 *hostname, AP_uint16 port)
	Attempt to establish a monitor-only connection to an Engine listening on the named host and port. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DisconnectFromEngine (AP_EngineManagement *engine)
	This function allows disconnection from an Engine. More...

AP_ENGINE_CLIENT_API AP_MonitorScript *AP_ENGINE_CLIENT_CALL	AP_CreateMonitorScript (const AP_char8 *text)
	This function allows creation of AP_MonitorScript instances. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteMonitorScript (AP_MonitorScript *script)
	This function allows deletion of AP_MonitorScript instances. More...

AP_ENGINE_CLIENT_API AP_Event *AP_ENGINE_CLIENT_CALL	AP_CreateEvent (const AP_char8 text, const AP_char8 channel)
	This function allows creation of an AP_Event instance. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteEvent (AP_Event *event)
	This function allows deletion of an AP_Event instance. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteEventSupplier (AP_EventSupplier *supplier)
	This function disconnects and deletes an AP_EventSupplier instance. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteEngineStatus (AP_EngineStatus *status)
	This function allows deletion of an AP_EngineStatus instance. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteEngineInfo (AP_EngineInfo *info)
	This function allows deletion of an AP_EngineInfo instance. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_DeleteWarnings (const AP_char8 const warnings)
	This function allows deletion of warnings. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetLogLevel (AP_EngineClientLogLevel level)
	Sets the level at which the client library will log information. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetLogFile (const AP_char8 *filename, int truncate)
	Sets the file to which the client library should log information. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetLogFileUTF8 (const AP_char8 *filename, int truncate)
	Sets the file to which the client library should log information. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetLogFD (int fd)
	Sets the file descriptor to which the client library should log information. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetLogMutex (void *)
	Sets the mutex which the client library logger should use. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_ReOpenLog ()
	Re-opens the log file. More...

AP_ENGINE_CLIENT_API AP_bool AP_ENGINE_CLIENT_CALL	AP_CheckException ()
	Checks if an exeption was thrown and saved by the library. More...

AP_ENGINE_CLIENT_API AP_EngineClientExceptionType AP_ENGINE_CLIENT_CALL	AP_GetExceptionType ()
	Returns the type of the pending exception. More...

AP_ENGINE_CLIENT_API const AP_char8 *AP_ENGINE_CLIENT_CALL	AP_GetExceptionMessage ()
	Retrieve the message enclosed within the exception. More...

AP_ENGINE_CLIENT_API const AP_char8 const AP_ENGINE_CLIENT_CALL	AP_GetExceptionWarnings ()
	Retrieve the set of warnings associated with the exception. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_ClearException ()
	Clears the pending exception. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_SetEngineParams (const AP_char8 *params)
	Set custom parameters for this instance of the client library. More...

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL	AP_char8free (char *string)
	Free any char* string returned from the client API. More...

Detailed Description

This is the header file for the Apama Engine C SDK.

NOTE: This is based on the C++ API which should be used in preference if possible

Enumeration Type Documentation

enum AP_EngineClientExceptionType

Enumerator
AP_ENGINE_EXCEPTION	An exception in the client library.

enum AP_EngineClientLogLevel

Available logging levels.

Enumerator
OFF_LEVEL	Nothing logged.
FORCE_LEVEL	Startup and other important messages.
CRIT_LEVEL	Critical messages.
FATAL_LEVEL	Fatal messages.
ERROR_LEVEL	Error messages.
WARN_LEVEL	Warning messages.
INFO_LEVEL	Information messages (default)
DEBUG_LEVEL	Debugging messages.
TRACE_LEVEL	More-verbose debug messages.

enum AP_EngineManagement_ConnectMode

The mode that attachAsEventConsumerTo and detachAsEventConsumerFrom operate in.

Enumerator
CONNECT_LEGACY	For backwards compatibility, single serial connection.
CONNECT_PARALLEL	Allow parallel connections on multiple channels.

Function Documentation

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_char8free ( char * string )

Free any char* string returned from the client API.

AP_ENGINE_CLIENT_API AP_bool AP_ENGINE_CLIENT_CALL AP_CheckException ( )

Checks if an exeption was thrown and saved by the library.

Returns: true if an exception was thrown, false otherwise

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_ClearException ( )

Clears the pending exception.

AP_ENGINE_CLIENT_API AP_EngineManagement* AP_ENGINE_CLIENT_CALL AP_ConnectToEngine	(	const AP_char8 *	hostname,
		AP_uint16	port
	)

This function attempts to establish a connection to an Engine.

It returns an AP_EngineManagement instance that can be used to access the Engine.

Parameters

hostname	The machine name where an Engine can be located.
port	The port that the Engine is listening on for transport negotiations with the client.

Returns: A pointer to AP_EngineManagement if an Engine is located and a connection established.

Exceptions

EngineException

AP_ENGINE_CLIENT_API AP_EngineManagement* AP_ENGINE_CLIENT_CALL AP_connectToEngineMonitorOnly	(	const AP_char8 *	hostname,
		AP_uint16	port
	)

Attempt to establish a monitor-only connection to an Engine listening on the named host and port.

If successful, the returned pointer to AP_EngineManagement can be used for the getStatus(), inspectEngine() and ping() operations. All other operations will fail.

Parameters

hostname	The hostname of the machine the Engine is running on.
port	The port that the Engine is listening on.

Returns: An EngineManagement object operating in monitor-only mode.

Exceptions

EngineException If the connection cannot be established.

AP_ENGINE_CLIENT_API AP_EngineManagement* AP_ENGINE_CLIENT_CALL AP_connectToEngineReceiveOnly	(	const AP_char8 *	hostname,
		AP_uint16	port
	)

Attempt to establish a receive-only connection to an Engine listening on the named host and port.

If successful, the returned AP_EngineManagement can be used for the connectEventConsumer(), getStatus(), inspectEngine() and ping() operations. All other operations will fail.

Parameters

hostname	The hostname of the machine the Engine is running on.
port	The port that the Engine is listening on.

Returns: An EngineManagement object operating in receive-only mode.

Exceptions

EngineException If the connection cannot be established.

AP_ENGINE_CLIENT_API AP_Event* AP_ENGINE_CLIENT_CALL AP_CreateEvent	(	const AP_char8 *	text,
		const AP_char8 *	channel
	)

This function allows creation of an AP_Event instance.

Parameters

eventString C style string representing the event instance in MonitorScript. Note that this string should be encoded in UTF-8.

Returns: A pointer to an AP_Event instance.

AP_ENGINE_CLIENT_API AP_MonitorScript* AP_ENGINE_CLIENT_CALL AP_CreateMonitorScript ( const AP_char8 * text )

This function allows creation of AP_MonitorScript instances.

Parameters

monitorString MonitorScript monitor/event definitions

Returns: A pointer to AP_MonitorScript instance.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteEngineInfo ( AP_EngineInfo * info )

This function allows deletion of an AP_EngineInfo instance.

All instances returned by any calls to the methods of the EngineInfo object are also deleted, so after calling inspectEngine, AP_DeleteEngineInfo is the only method which needs to be called to clean up.

Parameters

info	A pointer to an AP_EngineInfo instance.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteEngineStatus ( AP_EngineStatus * status )

This function allows deletion of an AP_EngineStatus instance.

Parameters

status A pointer to an AP_EngineStatus instance.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteEvent ( AP_Event * event )

This function allows deletion of an AP_Event instance.

Parameters

event A pointer to an AP_Event instance.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteEventSupplier ( AP_EventSupplier * supplier )

This function disconnects and deletes an AP_EventSupplier instance.

It also stops the associated AP_EventConsumer from receiving events.

Parameters

supplier A pointer to an AP_EventSupplier instance.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteMonitorScript ( AP_MonitorScript * script )

This function allows deletion of AP_MonitorScript instances.

Parameters

mon	The pointer to the AP_MonitorScript instance to delete.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DeleteWarnings ( const AP_char8 *const * warnings )

This function allows deletion of warnings.

Parameters

warnings A pointer to a NULL terminated list of warnings

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_DisconnectFromEngine ( AP_EngineManagement * engine )

This function allows disconnection from an Engine.

Any EventSuppliers created from the AP_EngineManagement must be deleted explicitly using AP_DeleteEventSupplier in addition to disconnecting the AP_EngineManagement object.

Parameters

corr	The Engine to disconnect from.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_EngineInit ( const char * processName )

This function must be called once per process first before any other Engine operations are carried out.

Exceptions

EngineException

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_EngineInitNoMessaging ( const char * processName )

This function (or engineInit) must be called once per process first before any other Engine operations are carried out.

Exceptions

EngineException

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_EngineShutdown ( )

This function must be called once per process before the application closes down.

It ensures that communications are shutdown properly and state cleaned up.

AP_ENGINE_CLIENT_API const AP_char8* AP_ENGINE_CLIENT_CALL AP_GetExceptionMessage ( )

Retrieve the message enclosed within the exception.

Returns: C style string with details of the error that caused the operation to fail.

AP_ENGINE_CLIENT_API AP_EngineClientExceptionType AP_ENGINE_CLIENT_CALL AP_GetExceptionType ( )

Returns the type of the pending exception.

Returns: type of the pending exception

AP_ENGINE_CLIENT_API const AP_char8* const* AP_ENGINE_CLIENT_CALL AP_GetExceptionWarnings ( )

Retrieve the set of warnings associated with the exception.

Returns: A pointer to a NULL terminated list of warnings, possibly NULL if there are none. This list is owned by the exception object. It should not be deleted.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_ReOpenLog ( )

Re-opens the log file.

Also called if SIGHUP is received.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetEngineParams ( const AP_char8 * params )

Set custom parameters for this instance of the client library.

Must be called before AP_EngineInit. The parameters are passed as a set of name, value pairs formatted as <name1>=<value1>;<name2=value2>; (i.e. equals sign between name and value, and semicolon separating the name value pairs).

The following parameters are defined so far.

ConfigFile - A filename from which to read a configuration file LogicalID - The logical id with which this component should be identified (a 64-bit integer)

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetLogFD ( int fd )

Sets the file descriptor to which the client library should log information.

Parameters

fd	The file descriptor to log to

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetLogFile	(	const AP_char8 *	filename,
		int	truncate
	)

Sets the file to which the client library should log information.

Parameters

filename	The filename to which the library should log. Will log to stderr if the filename cannot be opened.
truncate	If non-zero the log file will be truncated when it is opened. If zero then it will simply be appended to. set.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetLogFileUTF8	(	const AP_char8 *	filename,
		int	truncate
	)

Sets the file to which the client library should log information.

Parameters

filename	The filename, specified using UTF-8 characters, to which the library should log. Will log to stderr if the filename cannot be opened.
truncate	If non-zero the log file will be truncated when it is opened. If zero then it will simply be appended to. set.

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetLogLevel ( AP_EngineClientLogLevel level )

Sets the level at which the client library will log information.

Parameters

level The level to log at

AP_ENGINE_CLIENT_API void AP_ENGINE_CLIENT_CALL AP_SetLogMutex ( void * )

Sets the mutex which the client library logger should use.

For internal use only.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation