Defines, Structures, Typedefs, Functions. More...

Files
file	clEventApi.h
	Header file of Event Manager Related APIs.
file	clEventErrors.h
	Header file of Event Manager Error Codes.
file	clEventExtApi.h
	Header file of Event Manager Related APIs.

Classes
struct	ClEventCallbacksT
	The callback structure supplied by an EO to the EM containing the callback functions that can be invoked by the EM. More...
struct	ClEventFilterArrayT
	The event filter array structure defines one or more filters. More...
struct	ClEventFilterT
	The event filter structure defines the filter type and the filter pattern to be applied on an event pattern when filtering events on an event channel. More...
struct	ClEventPatternArrayT
	The type of an event pattern array. More...
struct	ClEventPatternT
	An Event pattern may contain a name (for example: a process name, checkpoint name, service instance name, and so on). More...

Macros
#define	CL_EVENT_CHANNEL_CREATE (0x8)
	Creates an event channel if it does not exist.
#define	CL_EVENT_CHANNEL_PUBLISHER (0x4)
	Opens an event channel for publishing events.
#define	CL_EVENT_CHANNEL_SUBSCRIBER (0x2)
	Opens an event channel for subscribing events.
#define	CL_EVENT_ERR_ALREADY_INITIALIZED (0x10e) /* 0x10e */
	The Event Library has already been initialized by this EO.
#define	CL_EVENT_ERR_BAD_FLAGS (0x103) /* 0x103 */
	The flags specified are invalid - out of range or not compatible with each other.
#define	CL_EVENT_ERR_BAD_HANDLE (0x105) /* 0x105 */
	The event handle specified is invalid - has not been allocated or has been already deleted.
#define	CL_EVENT_ERR_CHANNEL_ALREADY_OPENED (0x108) /* 0x108 */
	The channel has been already openend by the EO.
#define	CL_EVENT_ERR_CHANNEL_NOT_OPENED (0x109) /* 0x109 */
	The channel specified by the channel handle has not been opened.
#define	CL_EVENT_ERR_DUPLICATE_SUBSCRIPTION (0x10a) /* 0x10a */
	The EO has already subscribed on the specified channel using the given subscription ID.
#define	CL_EVENT_ERR_EXIST (0x112) /* 0x112 */
	The specified resource such as Subscription ID, Channel, and so on already exists.
#define	CL_EVENT_ERR_INFO_WALK_STOP (0x10d) /* 0x10d */
	This return code is used to check the normal termination of the event info walk.
#define	CL_EVENT_ERR_INIT (0x114) /* 0x114 */
	The ChannelOpen Callback is NULL.
#define	CL_EVENT_ERR_INIT_NOT_DONE (0x100) /* 0x100 */
	Event Library has not been initialized.
#define	CL_EVENT_ERR_INTERNAL (0x101) /* 0x101 */
	An unexpected error has occured in the Event Library and it may not be able to process the request.
#define	CL_EVENT_ERR_INVALID_CHANNEL_HANDLE (0x104) /* 0x104 */
	The channel handle passed is invalid - the channel has not been created.
#define	CL_EVENT_ERR_INVALID_PARAM (0x102) /* 0x102 */
	The parameter passed to the API is invalid.
#define	CL_EVENT_ERR_NO_MEM (0x106) /* 0x106 */
	The Event Library is out of memory and no memory can be allocated at this point in time.
#define	CL_EVENT_ERR_NO_RESOURCE (0x113) /* 0x113 */
	The Event Library is out of some resource other than memory like file descriptors.
#define	CL_EVENT_ERR_NO_SPACE (0x110) /* 0x110 */
	The memory allocated by the user for the event data (payload) is insufficient.
#define	CL_EVENT_ERR_NOT_OPENED_FOR_PUBLISH (0x10c) /* 0x10c */
	The channel has not been opened for publish and an attempt to subscribe was made on the same.
#define	CL_EVENT_ERR_NOT_OPENED_FOR_SUBSCRIPTION (0x10b) /* 0x10b */
	The channel has not been opened for subscription and an attempt to subscribe was made on the same.
#define	CL_EVENT_ERR_NULL_PTR (0x107) /* 0x107 */
	The parameter passed to the API is NULL.
#define	CL_EVENT_ERR_STOP_WALK (0x10f) /* 0x10f */
	This return code is used to check the normal termination of a walk to remove subscribers.
#define	CL_EVENT_ERR_VERSION (0x111) /* 0x111 */
	The version specified is not supported or is incorrect.
#define	CL_EVENT_GLOBAL_CHANNEL (0x1)
	Opens a global event channel.
#define	CL_EVENT_HIGHEST_PRIORITY (0x0)
	Highest priority.
#define	CL_EVENT_LOCAL_CHANNEL (0x0)
	Opens a local event channel.
#define	CL_EVENT_LOWEST_PRIORITY (0x3)
	Lowest priority.
#define	CL_EVENT_NON_ZERO_MATCH CL_EVENT_PASS_ALL_FILTER+1
	This is extension to SAF filter ClEventFilterTypeT to provide non-zero matching.
#define	CL_EVENT_VERSION {(ClUint8T)'B', 0x1, 0x1}
	Latest Supported SAF Version for Event Service.
#define	CL_EVENTS_RC(ERR_ID) (CL_RC(CL_CID_EVENTS, ERR_ID))
	Appends the Event Component ID to the Error Code.

Typedefs
typedef ClHandleT	ClEventChannelHandleT
	The type of a handle to an open event channel.
typedef void(*	ClEventChannelOpenCallbackT )(ClInvocationT invocation, ClEventChannelHandleT channelHandle, ClRcT error)
	Open channel callback.
typedef ClUint8T	ClEventChannelOpenFlagsT
	Event Channel open flag.
typedef void(*	ClEventDeliverCallbackT )(ClEventSubscriptionIdT subscriptionId, ClEventHandleT eventHandle, ClSizeT eventDataSize)
	Event delivery callback.
typedef ClHandleT	ClEventHandleT
	The type of a handle to an event.
typedef ClUint64T	ClEventIdT
	The type of an event identifier.
typedef ClHandleT	ClEventInitHandleT
	The type of the handle supplied by the EM to an EO during the initialization of the EM library.
typedef ClUint8T	ClEventPriorityT
	Event priority type - it ranges from `CL_EVENT_LOWEST_PRIORITY` to `CL_EVENT_HIGHEST_PRIORITY`.
typedef ClUint32T	ClEventSubscriptionIdT
	The type of an identifier for a particular subscription by a particular EO on a particular event channel.

Enumerations
enum	ClEventFilterTypeT { CL_EVENT_PREFIX_FILTER = 1, CL_EVENT_SUFFIX_FILTER = 2, CL_EVENT_EXACT_FILTER = 3, CL_EVENT_PASS_ALL_FILTER = 4 }
	Filter Related Information. More...

Functions
ClRcT	clEventAllocate (CL_IN ClEventChannelHandleT channelHandle, CL_OUT ClEventHandleT *pEventHandle)
	Allocates an event header.
ClRcT	clEventAttributesGet (CL_IN ClEventHandleT eventHandle, CL_IN ClEventPatternArrayT pPatternArray, CL_OUT ClEventPriorityT pPriority, CL_OUT ClTimeT pRetentionTime, CL_OUT ClNameT pPublisherName, CL_OUT ClTimeT pPublishTime, CL_OUT ClEventIdT pEventId)
	Returns the event attributes.
ClRcT	clEventAttributesSet (CL_IN ClEventHandleT eventHandle, CL_IN const ClEventPatternArrayT pPatternArray, CL_IN ClEventPriorityT priority, CL_IN ClTimeT retentionTime, CL_IN const ClNameT pPublisherName)
	Sets the event attributes.
ClRcT	clEventChannelClose (CL_IN ClEventChannelHandleT channelHandle)
	Closes an event channel.
ClRcT	clEventChannelOpen (CL_IN ClEventInitHandleT evtHandle, CL_IN const ClNameT pEvtChannelName, CL_IN ClEventChannelOpenFlagsT evtChannelOpenFlag, CL_IN ClTimeT timeout, CL_OUT ClEventChannelHandleT pChannelHandle)
	Opens an event channel.
ClRcT	clEventChannelOpenAsync (CL_IN ClEventInitHandleT evtHandle, CL_IN ClInvocationT invocation, CL_IN const ClNameT *pEvtChannelName, CL_IN ClEventChannelOpenFlagsT channelOpenFlags)
	Opens an event channel asynchronously.
ClRcT	clEventChannelUnlink (CL_IN ClEventInitHandleT evtHandle, CL_IN const ClNameT *pEvtChannelName)
	Deletes an event channel.
ClRcT	clEventCookieGet (CL_IN ClEventHandleT eventHandle, CL_OUT void **ppCookie)
	Returns the cookie.
ClRcT	clEventDataGet (CL_IN ClEventHandleT eventHandle, CL_INOUT void pEventData, CL_INOUT ClSizeT pEventDataSize)
	Returns data associated with an earlier event.
ClRcT	clEventDispatch (ClEventInitHandleT evtHandle, ClDispatchFlagsT dispatchFlags)
	Invokes the pending callback in context of the EO.
ClRcT	clEventExtAttributesGet (CL_IN ClEventHandleT eventHandle, CL_OUT ClUint32T pEventType, CL_OUT ClEventPriorityT pPriority, CL_OUT ClTimeT pRetentionTime, CL_OUT ClNameT pPublisherName, CL_OUT ClTimeT pPublishTime, CL_OUT ClEventIdT pEventId)
	Returns event attributes designated by eventHandle.
ClRcT	clEventExtAttributesSet (CL_IN ClEventHandleT eventHandle, CL_IN ClUint32T eventType, CL_IN ClEventPriorityT priority, CL_IN ClTimeT retentionTime, CL_IN const ClNameT *pPublisherName)
	Sets event attributes.
ClRcT	clEventExtSubscribe (CL_IN ClEventChannelHandleT channelHandle, CL_IN ClUint32T eventType, CL_IN ClEventSubscriptionIdT subscriptionId, CL_IN void *pCookie)
	Subscribes to an event identified by event type (constant integer instead of filter).
ClRcT	clEventExtWithRbeSubscribe (CL_IN const ClEventChannelHandleT channelHandle, CL_IN ClRuleExprT pRbeExpr, CL_IN ClEventSubscriptionIdT subscriptionID, CL_IN void pCookie)
	Subscribes to an event identified by an RBE.
ClRcT	clEventFinalize (CL_IN ClEventInitHandleT evtHandle)
	Finalizes EM library.
ClRcT	clEventFree (CL_IN ClEventHandleT eventHandle)
	Frees an event header.
ClRcT	clEventInitialize (CL_OUT ClEventInitHandleT pEvtHandle, CL_IN const ClEventCallbacksT pEvtCallbacks, CL_INOUT ClVersionT *pVersion)
	Initializes EM library.
ClRcT	clEventPublish (CL_IN ClEventHandleT eventHandle, CL_IN const void pEventData, CL_IN ClSizeT eventDataSize, CL_OUT ClEventIdT pEventId)
	Publishes an event.
ClRcT	clEventSelectionObjectGet (ClEventInitHandleT evtHandle, ClSelectionObjectT *pSelectionObject)
	Helps detect pending callbacks.
ClRcT	clEventSubscribe (CL_IN ClEventChannelHandleT channelHandle, CL_IN const ClEventFilterArrayT pFilters, CL_IN ClEventSubscriptionIdT subscriptionId, CL_IN void pCookie)
	Subscribes to an event identified by an event type (filter).
ClRcT	clEventUnsubscribe (CL_IN ClEventChannelHandleT channelHandle, CL_IN ClEventSubscriptionIdT subscriptionId)
	Unsubscribes from an event.

Detailed Description

Defines, Structures, Typedefs, Functions.

Macro Definition Documentation

#define CL_EVENT_ERR_INVALID_CHANNEL_HANDLE (0x104) /* 0x104 */

The channel handle passed is invalid - the channel has not been created.

It may be closed/deleted/unlinked.

Typedef Documentation

typedef void(* ClEventChannelOpenCallbackT)(ClInvocationT invocation, ClEventChannelHandleT channelHandle, ClRcT error)

Open channel callback.

Parameters

invocation	This parameter was supplied by an EO in the corresponding invocation of the clEventChannelOpenAsync() function and is used by the EM in this callback. It allows the EO to match the invocation of the function with the invocation of this callback.
channelHandle	The handle that designates the event channel.
error	This parameter indicates whether the clEventChannelOpenAsync function executed successfully.

Description:: The EM invokes this callback function when the operation requested by the clEventChannelOpenAsync() function completes. This callback is invoked in the context of EO that initialized the EM.

: On successful execution, the handle to the opened or created event channel is returned in channelHandle, else, an error is returned in the error parameter.

typedef ClUint8T ClEventChannelOpenFlagsT

Event Channel open flag.

It can have one of the following values:

CL_EVENT_LOCAL_CHANNEL
CL_EVENT_GLOBAL_CHANNEL
CL_EVENT_CHANNEL_PUBLISHER
CL_EVENT_CHANNEL_SUBSCRIBER
CL_EVENT_CHANNEL_CREATE
Parameters

evtChannelOpenFlags (in) The requested access modes and scope of the event channel. The value of this flag is obtained by a bitwise or can be set as one of the following:
CL_EVENT_CHANNEL_PUBLISHER: to enable the EO to use the event channel handle returned by the clEventPublish function.
CL_EVENT_CHANNEL_SUBSCRIBER: to enable the EO to use the event channel handle returned by the clEventSubscribe function.
CL_EVENT_CHANNEL_CREATE: to open and create an event channel that does not exist.
CL_EVENT_GLOBAL_CHANNEL and CL_EVENT_LOCAL_CHANNEL flags specify the scope of the event channel.

typedef void(* ClEventDeliverCallbackT)(ClEventSubscriptionIdT subscriptionId, ClEventHandleT eventHandle, ClSizeT eventDataSize)

Event delivery callback.

Parameters

subscriptionId	An identifier that an EO supplied to an invocation of clEventSubscribe() to determine which subscription resulted in the delivery of the event.
eventHandle	The handle to the event delivered by this callback.
ClSizeT	The size of the data associated with the event.

Description:: The EM invokes this callback function to notify the subscriber EO that an event has been received. This callback is invoked in the subscriber EO context. A published event is received when it has an event pattern matching the filter of a subscription of this EO, established by the clEventSubscribe() call.

: After successful completion of this call, the EO may invoke the clEventAttributesGet() function to obtain the attributes and the clEventDataGet() function to obtain the data associated with the event.

: It is the responsibility of the EO to free the event by invoking the clEventFree() function.

: The validity of the eventHandle parameter is not limited to the scope of this callback function.

typedef ClUint64T ClEventIdT

The type of an event identifier.

Values ranging from 0 to 1000 have special meanings and cannot be used by the event service to identify regular events.

typedef ClHandleT ClEventInitHandleT

The type of the handle supplied by the EM to an EO during the initialization of the EM library.

The EO uses this to whenever it invokes an EM function so that the EM can recognize the EO.

typedef ClUint32T ClEventSubscriptionIdT

The type of an identifier for a particular subscription by a particular EO on a particular event channel.

This identifier is used to associate the delivery of events for that subscription to the EO.

Enumeration Type Documentation

enum ClEventFilterTypeT

Filter Related Information.

Enumerator:

CL_EVENT_PREFIX_FILTER	The entire filter must match the first filterSize characters of the event pattern.
CL_EVENT_SUFFIX_FILTER	The entire filter must match the last filterSize characters of the event pattern.
CL_EVENT_EXACT_FILTER	The entire filter must exactly match the entire event pattern.
CL_EVENT_PASS_ALL_FILTER	Always matches, regardless of the filter or event pattern.

Function Documentation

ClRcT clEventAllocate	(	CL_IN ClEventChannelHandleT	channelHandle,
		CL_OUT ClEventHandleT *	pEventHandle
	)

Allocates an event header.

Header File:: clEventApi.h

Parameters

channelHandle	Handle of the event channel on which the event is to be published. It must be obtained earlier either by clEventChannelOpen() function or clEvtChannelOpenCallback() function.
pEventHandle	(out) Pointer to the handle for the newly allocated event. The invoking EO is responsible to allocate memory for the eventHandle before calling this function. The EM will assign the value of the eventHandle when this function is invoked.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function is used to allocate memory for the event header. The event allocated by this function must be freed by the clEventFree() function.

Library File:: ClEventClient

See Also: clEventFree(), clEventPublish()

ClRcT clEventAttributesGet	(	CL_IN ClEventHandleT	eventHandle,
		CL_IN ClEventPatternArrayT *	pPatternArray,
		CL_OUT ClEventPriorityT *	pPriority,
		CL_OUT ClTimeT *	pRetentionTime,
		CL_OUT ClNameT *	pPublisherName,
		CL_OUT ClTimeT *	pPublishTime,
		CL_OUT ClEventIdT *	pEventId
	)

Returns the event attributes.

Header File:: clEventApi.h

Parameters

eventHandle	Handle of the event for which attributes are to be retrieved.
pPatternArray	(in/out) Pointer to a structure that describes the event pattern array and the number of patterns to be retrieved. If the caller sets pPatternArray->patterns to NULL, the EM ignores the pPatternArray->allocatedNumber field, and it will allocate memory for the pattern array and the individual patterns and will set the fields pPatternArray->patternsNumber, pPatternArray->patterns, pPatternArray->patterns[i].pattern, and pPatternArray->patterns[i].patternSize accordingly. The invoking EO is then responsible for de-allocating the corresponding memory, that is, pPatternArray->patterns and each pPatternArray->patterns[i].pattern. Alternatively, the invoking EO can allocate the memory to retrieve all event patterns and set the fields pPatternArray->allocatedNumber, pPatternArray->patterns, pPatternArray->patterns[i].allocatedSize, and pPatternArray->patterns[i].pattern accordingly. Here, these fields are in parameters and will not be modified by the EM. The EM copies the patterns into the successive entries of pPatternArray->patterns, starting with the first entry and continuing until all event patterns are copied. If pPatternArray->allocatedNumber is smaller than the number of event patterns or if the size of the buffer allocated for one of the patterns is then the actual size of the pattern, the invocation fails and the `CL_EVENT_ERR_NO_SPACE` error is returned. If such an error happens, it is not specified whether some buffers pointed to by pPatternArray->patterns[i].pattern were changed by the EM. Regardless of whether such an error occurs, the EM sets the pPatternArray->patternsNumber and pPatternArray->patterns[i].patternSize fields for all pPatternArray->allocatedNumber individual patterns, to indicate the number of event patterns and the size of each pattern.
pPriority	(out) Pointer to the priority of the event.
pRetentionTime	(out) Pointer to the duration for which the publisher will retain the event.
pPublisherName	(out) Pointer to the name of the event publisher.
pPublishTime	(out) Pointer to the time when the publisher published the event. NOTE: The nodes may required to synched wrt time to use this parameter effectively.
pEventId	(out) Pointer to the event identifier.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_SPACE	The buffer provided by the process is too small to hold the data associated with the delivered event.

Description:: This function is used to retrieve the value of the attributes of the event designated by eventHandle.

: For each of the out or in/out parameters, if the invoking EO provides a NULL reference, the EM does not return the out value.

This function can be called on any event allocated by the clEventAllocate() function or received via the clEvtEventDeliverCallback() function. This can also be modified by the clEventAttributesSet() function.

If this function is invoked on a received event, the attributes "publish time" and "event id" have the values set by the EM at event publishing time.
Else, the attributes will either have the initial values set by the EM while allocating the event or the attributes set by a call to clEventAttributesSet function.

Library File:: ClEventClient

See Also: clEventAllocate(), clEventFree(), clEventChannelOpen(), clEventChannelOpenAsync(), clEventAttributesSet()

ClRcT clEventAttributesSet	(	CL_IN ClEventHandleT	eventHandle,
		CL_IN const ClEventPatternArrayT *	pPatternArray,
		CL_IN ClEventPriorityT	priority,
		CL_IN ClTimeT	retentionTime,
		CL_IN const ClNameT *	pPublisherName
	)

Sets the event attributes.

Header File:: clEventApi.h

Parameters

eventHandle	Handle of the event for which attributes are to be set.
pPatternArray	Pointer to a structure that contains the array of pattern to be copied into the event pattern array and the number of such pattern.
priority	Priority of the event.
retentionTime	Duration for which the event will be retained. NOTE: Event Retention is not currently supported and this arguments has no effect.
pPublisherName	Pointer to the name of the event publisher.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NOT_OPENED_FOR_PUBLISH	`CL_EVENT_CHANNEL_PUBLISHER` flag was not set for the event channel on which the event to be published was allocated, i.e, the event channel was not opened for publisher access.

Description:: This function is used to set all the write-able event attributes, such as - pPatternArray, priority, retentionTime, and pPublisherName, in the header of the event, designated by eventHandle. If pPatternArray or pPublisherName is NULL, the corresponding attributes are not changed.

Library File:: ClEventClient

See Also: clEventAllocate(), clEventFree(), ClEventDeliverCallbackT, clEventAttributesGet(), clEventChannelOpen(), clEventChannelOpenAsync()

ClRcT clEventChannelClose ( CL_IN ClEventChannelHandleT channelHandle )

Closes an event channel.

Header File:: clEventApi.h

Parameters

channelHandle Handle of the event channel to close. It must have been obtained by an earlier invocation of either clEventChannelOpen() function or clEvtChannelOpenCallback() function.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.

Description:: This function is used to close the event channel, designated by channelHandle, which was opened by an earlier invocation of clEventChannelOpen() or clEventChannelOpenAsync() functions. After the invocation of this function, the channelHandle is no longer valid.

: On successful execution of this function, if no EO has the event channel open, the event channel is deleted immediately if its deletion was pending as a result of a clEventChannelUnlink() function.

Library File:: ClEventClient

See Also: clEventChannelOpen(), clEventChannelOpenAsync(), clEvtChannelOpenCallbackT, clEventChannelUnlink()

ClRcT clEventChannelOpen	(	CL_IN ClEventInitHandleT	evtHandle,
		CL_IN const ClNameT *	pEvtChannelName,
		CL_IN ClEventChannelOpenFlagsT	evtChannelOpenFlag,
		CL_IN ClTimeT	timeout,
		CL_OUT ClEventChannelHandleT *	pChannelHandle
	)

Opens an event channel.

Header File:: clEventApi.h

Note: An event channel cannot be opened multiple times by the same EO. It can be opened only for subscribing and/or publishing an event or a group of events.

Parameters

evtHandle	The handle obtained by the clEventInitialize() function designating this particular initialization of the EM.
pEvtChannelName	Pointer to the name of the event channel to identify the channel.
evtChannelOpenFlags	The requested access modes and scope of the event channel. The value of this flag is obtained by a bitwise or can be set as one of the following: `CL_EVENT_CHANNEL_PUBLISHER:` To enable the EO to use the event channel handle returned by the clEventPublish() function. `CL_EVENT_CHANNEL_SUBSCRIBER:` To enable the EO to use the event channel handle returned by the clEventSubscribe() function. `CL_EVENT_CHANNEL_CREATE:` To open and create an event channel that does not exist. `CL_EVENT_GLOBAL_CHANNEL` and `CL_EVENT_LOCAL_CHANNEL` flags specify the scope of the event channel.
timeout	Time-out for calling this function. Note: An event channel can be created even after the time-out has expired.
pChannelHandle	(out) Pointer to the handle of the event channel, provided by the invoking EO in the address space of the EO. If the event channel is opened successfully, the EM stores the handle in pChannelHandle. This handle is used by the EO to access the channel in subsequent invocations of the Event Service functions.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_BAD_FLAGS	On passing an invalid flag.
CL_EVENT_ERR_NULL_PTR	On passing a NULL pointer.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_CHANNEL_ALREADY_OPENED	If a channel is already opened by an EO with the same name and scope.

Description:: This function is used to open an event channel. If the event channel does not exist and the CL_EVENT_CHANNEL_CREATE flag is set in channelOpenFlags, the event channel is created. This function is a blocking operation and returns a new event channel handle.

Library File:: ClEventClient

See Also: clEventInitialize(), clEventChannelClose()

ClRcT clEventChannelOpenAsync	(	CL_IN ClEventInitHandleT	evtHandle,
		CL_IN ClInvocationT	invocation,
		CL_IN const ClNameT *	pEvtChannelName,
		CL_IN ClEventChannelOpenFlagsT	channelOpenFlags
	)

Opens an event channel asynchronously.

Header File:: clEventApi.h

Parameters

evtHandle	Handle obtained by the clEventInitialize() function designating this particular initialization of the EM.
invocation	It allows the invoking component to match the invocation of clEventChannelOpenAsync() function with the corresponding callback.
pEvtChannelName	Pointer to the name of the event channel that identifies the event channel.
evtChannelOpenFlags	The requested access modes and scope of the event channel. The value of this flag is obtained bitwise or can be set as one of the following: `CL_EVENT_CHANNEL_PUBLISHER:` To enable the EO to use the event channel handle returned by the clEventPublish() function. `CL_EVENT_CHANNEL_SUBSCRIBER:` To enable the EO to use the event channel handle returned by the clEventSubscribe() function. `CL_EVENT_CHANNEL_CREATE:` To open and create an event channel that does not exist. `CL_EVENT_GLOBAL_CHANNEL` and `CL_EVENT_LOCAL_CHANNEL` flags are the scope of the event channel.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_BAD_FLAGS	On passing an invalid flag.
CL_EVENT_ERR_NULL_PTR	On passing a NULL pointer.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_CHANNEL_ALREADY_OPENED	If a channel is already opened by an EO with the same name and scope.

Description:: This function is used to open an event channel asynchronously. If the event channel does not exist and the CL_EVENT_CHANNEL_CREATE flag is set in the channelOpenFlags parameter, the event channel is created.

: The successful execution of this function is signaled by an invocation of the associated clEvtChannelOpenCallback() callback function supplied while the EO calls the clEventInitialize() function.

: The EO supplies the value of invocation while calling the clEventChannelOpenAsync() function. This value is supplied back to the application by the EM while calling the clEvtChannelOpenCallback() function.

Note: The invocation parameter is a mechanism that enables the EO to determine which callback is triggered by which call.

Library File:: ClEventClient

See Also: clEvtChannelOpenCallbackT(), clEventInitialize(), clEventChannelClose()

ClRcT clEventChannelUnlink	(	CL_IN ClEventInitHandleT	evtHandle,
		CL_IN const ClNameT *	pEvtChannelName
	)

Deletes an event channel.

Header File:: clEventApi.h

Parameters

evtHandle	Handle obtained by the invocation of clEventInitialize() designating this particular initialization of the EM.
pEvtChannelName	Pointer to the name of the event channel to be unlinked.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.

Description:: This function is used to delete an existing event channel, identified by pEvtChannelName, from the cluster.

After the successful execution of this function:

The name pEvtChannelName is no longer valid, that is, any invocation of a function of the EM function that uses the event channel name returns an error, unless an event channel is re-created with this name. The event channel can be re-created by specifying the same name of the event channel to be unlinked in an open call with the CL_EVENT_CHANNEL_CREATE flag set. This way, a new instance of the event channel is created while the old instance of the event channel has been still not deleted.
If none of the EOs has an event channel open any longer, the event channel is deleted immediately.
Any EO that has the event channel open can still continue to access it. Deletion of the event channel will occur when the last clEventChannelClose() is executed.

The deletion of an event channel frees all resources allocated by the EM, such as - published events with non-zero retention time.

Library File:: ClEventClient

Note: An event channel is only deleted from the cluster namespace when clEventChannelUnlink() is invoked on it.

See Also: clEventInitialize(), clEventChannelClose()

ClRcT clEventCookieGet	(	CL_IN ClEventHandleT	eventHandle,
		CL_OUT void **	ppCookie
	)

Returns the cookie.

Header File:: clEventApi.h

Parameters

eventHandle	Handle to the event delivered by clEvtEventDeliverCallback().
ppCookie	(out) Cookie information while subscribing for event.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function is used to return the cookie passed by the EO on subscription to an event. It can be invoked from the registered callback function.

Library File:: ClEventClient

See Also: clEventSubscribe()

ClRcT clEventDataGet	(	CL_IN ClEventHandleT	eventHandle,
		CL_INOUT void *	pEventData,
		CL_INOUT ClSizeT *	pEventDataSize
	)

Returns data associated with an earlier event.

Header File:: clEventApi.h

Parameters

eventHandle	Handle to the event delivered by clEvtEventDeliverCallback().
pEventData	(in/out) Pointer to a buffer provided by the EO in which the EM stores the data associated with the delivered event. If pEventData is NULL, the value of pEventDataSize provided by the invoking EO is ignored, and the buffer is provided by the EM library. The buffer must be deallocated by the calling EO after returning from the clEventDataGet call. NOTE: This argument cannot be NULL as the API needs a pointer to pointer to return allocated memory to the callee. This is a bug in the SAF sepcification B.01.01 and has been fixed in the newer version of the specification. The user is always required allocate and also free the memory.
pEventDataSize	(in/out) If pEventData is not NULL, the in value of this parameter is same as the pEventData buffer provided by the invoking EO. If this buffer is not large enough to hold all of the data associated with this event, then no data will be copied into the buffer, and the error code `CL_EVENT_ERR_NO_SPACE` is returned. If pEventData is NULL, the in value of pEventDataSize is ignored. The out value of pEventDataSize is set when the function returns either `CL_AIS_OK` or `CL_EVENT_ERR_NO_SPACE`, and its size is same as that of the data associated with this event, which may be less than, equal to, or greater than the in value of pEventDataSize.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_SPACE	The buffer provided by the process is too small to hold the data associated with the delivered event.

Description:: This function is used to retrieve the data associated with an event earlier delivered by clEvtEventDeliverCallback().

Library File:: ClEventClient

See Also: ClEventDeliverCallbackT, clEventFree(), clEventChannelOpen(), clEventChannelOpenAsync()

ClRcT clEventDispatch	(	ClEventInitHandleT	evtHandle,
		ClDispatchFlagsT	dispatchFlags
	)

Invokes the pending callback in context of the EO.

Header File:: clEventApi.h

Parameters

evtHandle	The handle, obtained through the clEventInitialize() function, designating this particular initialization of the Event Service.
dispatchFlags	Flags that specify the callback execution behavior clEventDispatch() function, which have the values `CL_DISPATCH_ONE`, `CL_DISPATCH_ALL` or `CL_DISPATCH_BLOCKING`, as defined in clCommon.h.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function invokes, in the context of the calling EO, pending callbacks for handle evtHandle in a way that is specified by the dispatchFlags parameter.

Library File:: ClEventClient

See Also: clEventInitialize(), clEventSelectionObjectGet()

ClRcT clEventExtAttributesGet	(	CL_IN ClEventHandleT	eventHandle,
		CL_OUT ClUint32T *	pEventType,
		CL_OUT ClEventPriorityT *	pPriority,
		CL_OUT ClTimeT *	pRetentionTime,
		CL_OUT ClNameT *	pPublisherName,
		CL_OUT ClTimeT *	pPublishTime,
		CL_OUT ClEventIdT *	pEventId
	)

Returns event attributes designated by eventHandle.

Header File:: clEventExtApi.h

Parameters

eventHandle	Handle of the event for which attributes are to be retrieved.
pEventType	(out) Pointer to an event type.
pPriority	(out) Pointer to the priority of the event.
pRetentionTime	(out) Pointer to the duration for which the publisher will retain the event.
pPublisherName	(out) Pointer to the name of the publisher of the event.
pPublishTime	(out) Pointer to the time at which the publisher published the event.
pEventId	(out) Pointer to the event identifier.

Return values

CL_OK	The API completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	On initialization failure.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function servers as a wrapper around clEventAttributesGet() taking a fixed length event type instead of a filter. It retrieves the value of the attributes of the event designated by eventHandle.

: For each of the out or in/out parameters, if the invoking EO provides a NULL reference, the EM does not return the out value.

This function can be called on any event allocated by the clEventAllocate function or received via the clEvtEventDeliverCallback() function. It can also be modified by the clEventExtAttributesSet() API.

If this function is invoked on a received event, the attributes "publish time" and "event id" have the values set by the EM at event publishing time.
Else, the attributes will either have the initial values set by the EM when allocating the event or the attributes set by a prior invocation of the clEventExtAttributesSet() function.

Library File:: ClEventClient

See Also: clEventAttributesSet(), clEventExtAttributesGet()

ClRcT clEventExtAttributesSet	(	CL_IN ClEventHandleT	eventHandle,
		CL_IN ClUint32T	eventType,
		CL_IN ClEventPriorityT	priority,
		CL_IN ClTimeT	retentionTime,
		CL_IN const ClNameT *	pPublisherName
	)

Sets event attributes.

Header File:: clEventExtApi.h

Parameters

eventHandle	Handle of the event for which attributes are to be set.
eventType	Event type that wants to publish on given channel.
priority	Priority of the event.
retentionTime	The duration till when the event will be retained.
pPublisherName	Pointer to the name of the event publisher.

Return values

CL_OK	The API completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	On initialization failure.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function serves as a wrapper around clEventAttributesSet() taking a fixed length event type instead of a filter. It is used to set all the write-able event attributes, like - fixed length event type, priority, retentionTime, and pPublisherName, in the header of the event, designated by the eventHandle. If pPatternArray or pPublisherName are NULL, the corresponding attributes are not changed.

Library File:: ClEventClient

See Also: clEventAttributesSet(), clEventExtAttributesGet()

ClRcT clEventExtSubscribe	(	CL_IN ClEventChannelHandleT	channelHandle,
		CL_IN ClUint32T	eventType,
		CL_IN ClEventSubscriptionIdT	subscriptionId,
		CL_IN void *	pCookie
	)

Subscribes to an event identified by event type (constant integer instead of filter).

Header File:: clEventExtApi.h

Parameters

channelHandle	Handle of the event channel on which the EO is subscribing to receive events. This parameter must be obtained earlier by clEventChannelOpen API or clEvtChannelOpenCallback() function.
eventType	Event type within event channel.
pSubscriptionId	Identifies a specific subscription on this instance of the opened event channel corresponding to the channelHandle and that is used as a parameter of clEvtEventDeliverCallback().
pCookie	Cookie passed by you, which can be sent back by the clEvtEventUtilsCookiGet() function.

Return values

CL_OK	The API completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	On initialization failure.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_NOT_OPENED_FOR_SUBSCRIPTION	The channel, identified by channelHandle, was not opened with the `CL_EVENT_CHANNEL_SUBSCRIBER` flag set, i.e, the event channel was not opened for subscriber access.

Description:: This function serves as a wrapper around clEventSubscribe() and enables an EO to subscribe for events on an event channel * by registering a fixed length event type on that event channel instead of filters.

: Events are delivered via the invocation of the clEvtEventDeliverCallback() callback function supplied when the EO called the clEventInitialize() function.

: The EO must open the event channel, designated by channelHandle, with the CL_EVENT_CHANNEL_SUBSCRIBER flag set for successful execution of this function. The memory associated with the filters is not deallocated by the clEventExtSubscribe function. It is the responsibility of the invoking EO to deallocate the memory when the clEventExtSubscribe function returns.

: For a given subscription, the filters parameter cannot be modified. To change the filters parameter without losing events, an EO must establish a new subscription with the new filters parameter. Once a new subscription is established, the old subscription can be removed by invoking the clEventUnsubscribe() function.

Library File:: ClEventClient

See Also: clEventSubscribe(), clEventExtWithRbeSubscribe()

ClRcT clEventExtWithRbeSubscribe	(	CL_IN const ClEventChannelHandleT	channelHandle,
		CL_IN ClRuleExprT *	pRbeExpr,
		CL_IN ClEventSubscriptionIdT	subscriptionID,
		CL_IN void *	pCookie
	)

Subscribes to an event identified by an RBE.

Header File:: clEventExtApi.h

Parameters

channelHandle	Handle of the event channel on which the EO is subscribing to receive events. This parameter must be obtained earlier by clEventChannelOpen() API or clEvtChannelOpenCallback() function.
pRbeExpr	Pointer to RBE expression, allocated by the EO, that defines filter patterns using RBE expression. The EO may deallocate the memory for the filters when clEventExtWithRbeSubscribe returns.
pSubscriptionId	Identifies a specific subscription on this instance of the opened event channel corresponding to the channelHandle and that is used as a parameter of clEvtEventDeliverCallback() function.
pCookie	Cookie passed by you, which can be given back by the clEvtEventUtilsCookiGet() function.

Return values

CL_OK	The API completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	On initialization failure.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_NOT_OPENED_FOR_SUBSCRIPTION	The channel, identified by channelHandle, was not opened with the `CL_EVENT_CHANNEL_SUBSCRIBER` flag set, i.e, the event channel was not opened for subscriber access.

Description:: This function is an extension to clEventSubscribe function. This function enables an EO to subscribe for events on an event channel by registering RBE expression on that event channel.

: Events are delivered via the invocation of the clEvtEventDeliverCallback() callback function, which must have been supplied when the EO called the clEventInitialize() function.

: The EO must have opened the event channel, designated by channelHandle, with the CL_EVENT_CHANNEL_SUBSCRIBER flag set for an invocation of this function to be successful.

: The memory associated with the RBE is not deallocated by the clEventExtWithRbeSubscribe function. It is the responsibility of the invoking EO to deallocate the memory when the clEventExtWithRbeSubscribe API returns.

: For a given subscription, the filters parameter cannot be modified. To change the filters parameter without losing events, an EO must establish a new subscription with the new filters parameter. After the new subscription is established, the old subscription can be removed by invoking the clEventUnsubscribe function.

Library File:: ClEventClient

See Also: clEventSubscribe(), clEventExtSubscribe()

ClRcT clEventFinalize ( CL_IN ClEventInitHandleT evtHandle )

Finalizes EM library.

Header File:: clEventApi.h

Parameters

evtHandle Handle obtained through clEventInitialize() function designating this particular initialization of the EM.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.

Description:: This function is used to close the association, represented by evtHandle, between the invoking EO and EM. The EO must call the clEventInitialize() function before it calling this function.

: If the clEventFinalize() function executed successfully, all resources are released which were acquired by the clEventInitialize() function. Moreover, it also removes all the open event channels for the particular handle and cancels all pending callbacks related to the particular handle.

Library File:: ClEventClient

Note: As the callback invocation is asynchronous, some callback calls can still be processed even after calling this function.

See Also: clEventInitialize()

ClRcT clEventFree ( CL_IN ClEventHandleT eventHandle )

Frees an event header.

Header File:: clEventApi.h

Parameters

eventHandle Handle of the event for which memory is to be freed by the EM.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.

Description:: This function is used to give permission to the EM to deallocate the memory that contains the attributes and the event data, if present, of the event that is associated with eventHandle. It frees the events allocated by clEventAllocate() function or clEvtEventDeliverCallback() function.

Library File:: ClEventClient

See Also: clEventAllocate(), clEventChannelOpen(), clEventChannelOpenAsync()

ClRcT clEventInitialize	(	CL_OUT ClEventInitHandleT *	pEvtHandle,
		CL_IN const ClEventCallbacksT *	pEvtCallbacks,
		CL_INOUT ClVersionT *	pVersion
	)

Initializes EM library.

Header File:: clEventApi.h

Warning:: This function can be called by an EO only once.

Parameters

pEvtHandle (out) Pointer to the handle designating this particular initialization of the EM to be returned.

pEvtCallbacks If evtCallbacks is set to NULL, no callback is registered; else, it is a pointer to ClEventCallbacksT structure, containing the callback functions of the EO that the EM may invoke. Only non-NULL callback functions in this structure will be registered.

pVersion

(in/out) This can be either an input or an output parameter.

As an input parameter, version is a pointer to the required EM version. Here, minorVersion is ignored and should be set to 0x00.

As an output parameter, the version actually supported by the EM is delivered.

Return values

CL_OK	The function completed successfully.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function is used to initialize the EM for the invoking EO and registers the various callback functions. It must be invoked prior to the invocation of any other EM functionality. The handle pEvtHandle is returned as the reference to this association between the EO and the EM. The EO uses this handle in subsequent communication with the EM.

: If the implementation supports the required releaseCode, and a majorVersion greater than or equal to the required majorVersion, CL_AIS_OK is returned.

Library File:: ClEventClient

See Also: clEventSelectionObjectGet(), clEventDispatch(), clEventFinalize()

ClRcT clEventPublish	(	CL_IN ClEventHandleT	eventHandle,
		CL_IN const void *	pEventData,
		CL_IN ClSizeT	eventDataSize,
		CL_OUT ClEventIdT *	pEventId
	)

Publishes an event.

Header File:: clEventApi.h

Parameters

eventHandle	Handle of the event to be published. The event must be allocated by the clEventAllocate() function or obtained vthrough the clEvtEventDeliverCallback() function. The patterns must be set by clEventAttributesSet() function, if changes are required.
pEventData	Pointer to a buffer that contains additional event information for the event being published. This parameter is set to NULL if no additional information is associated with the event. The EO may deallocate the memory for pEventData when clEventPublish() function returns.
eventDataSize	The number of bytes in the buffer pointed to by pEventData. This parameter is ignored if pEventData is NULL.
pEventId	(out) Pointer to the identifier of the event.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NOT_OPENED_FOR_PUBLISH	`CL_EVENT_CHANNEL_PUBLISHER` flag was not set for the event channel on which the event to be published was allocated, i.e, the event channel was not opened for publisher access.

Description:: This function is used to publish an event on the channel for which the event specified by eventHandle has been allocated or obtained through the clEvtEventDeliverCallback() function. It returns the event identifier in eventId. The event to be published consists of a standard set of attributes, such as - the event header, and an optional data part.

: The event channel must be opened by the EO, on which this event is published with the CL_EVENT_CHANNEL_PUBLISHER flag set for successful execution of this function.

: Before an event can be published, the publisher EO can call the clEventAttributesSet() function to set the write-able event attributes. The published event is delivered to the subscribers whose subscription filters match the event patterns.

When the EM publishes an event, it automatically sets the following read-only event attributes into the published event:

Event publish time
Event identifier NOTE: The Event identifier is not being set as Event Retention is not supported yet and this parameter does't come into picture. However, the Event publish time would give the time of publish of the event.

In addition to the event attributes, an EO also supply values for the pEventData and eventDataSize parameters for publication as part of the event. The event attributes and the event data of the event identified by eventHandle are not affected by this function.

: This function copies the event attributes and the event data into internal memory of the EM. The invoking EO can free the event using clEventFree() after clEventPublish() returns successfully.

Library File:: ClEventClient

See Also: clEventAllocate(), clEventFree(), ClEventDeliverCallbackT, clEventAttributesSet(), clEventSubscribe()

ClRcT clEventSelectionObjectGet	(	ClEventInitHandleT	evtHandle,
		ClSelectionObjectT *	pSelectionObject
	)

Helps detect pending callbacks.

Header File:: clEventApi.h

Parameters

evtHandle	The handle, obtained through the clEventInitialize() function, designating this particular initialization of the Event Service.
pSelectionObject	(out) A pointer to the operating system handle that the invoking EO can use to detect pending callbacks.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.

Description:: This function returns the operating system handle, pSelectionObject, associated with the handle evtHandle. The invoking EO can use this handle to detect pending callbacks, instead of repeatedly invoking clEventDispatch() for this purpose. The pSelectionObject returned by this function, is a file descriptor that can be used with poll() or select() systems call detect incoming callbacks. The selectionObject returned by this function is valid until clEventFinalize() is invoked on the same handle evtHandle.

Library File:: ClEventClient

See Also: clEventInitialize(), clEventDispatch(), clEventFinalize()

ClRcT clEventSubscribe	(	CL_IN ClEventChannelHandleT	channelHandle,
		CL_IN const ClEventFilterArrayT *	pFilters,
		CL_IN ClEventSubscriptionIdT	subscriptionId,
		CL_IN void *	pCookie
	)

Subscribes to an event identified by an event type (filter).

Header File:: clEventApi.h

Parameters

channelHandle	Handle of the event channel on which the EO is subscribing to receive events. The parameter channelHandle must have been obtained previously by either clEventChannelOpen() or clEvtChannelOpenCallback() functions.
pFilters	Pointer to a ClEventFilterArrayT structure, allocated by the EO, that defines filter patterns to use to filter events received on the event channel. The EO may deallocate the memory for the filters when clEventSubscribe() returns.
pSubscriptionId	Identifies a specific subscription on this instance of the opened event channel corresponding to the channelHandle and that is used as a parameter of clEvtEventDeliverCallback().
pCookie	Cookie passed by you, which can be given back by the clEvtEventUtilsCookiGet() function.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.
CL_EVENT_ERR_NOT_OPENED_FOR_SUBSCRIPTION	The channel, identified by channelHandle, was not opened with the `CL_EVENT_CHANNEL_SUBSCRIBER` flag set, i.e, the event channel was not opened for subscriber access.

Description:: This function enables an EO to subscribe for events on an event channel by registering one or more filters on that event channel. Events are delivered using clEvtEventDeliverCallback() function supplied when the EO called the clEventInitialize() function.

: The EO must open the event channel, designated by channelHandle, with the CL_EVENT_CHANNEL_SUBSCRIBER flag set for successful execution of this function.

: The memory associated with the filters is not deallocated by the clEventSubscribe() function. It is the responsibility of the invoking EO to deallocate the memory when the clEventSubscribe() function returns.

: For a given subscription, the filters parameter cannot be modified. To change the filters parameter without losing events, an EO must establish a new subscription with the new filters parameter. Once the new subscription is established, the old subscription can be removed using the clEventUnsubscribe() function.

Library File:: ClEventClient

See Also: clEventUnsubscribe(), clEventDataGet(), ClEventDeliverCallbackT, clEventAttributesGet()

ClRcT clEventUnsubscribe	(	CL_IN ClEventChannelHandleT	channelHandle,
		CL_IN ClEventSubscriptionIdT	subscriptionId
	)

Unsubscribes from an event.

Header File:: clEventApi.h

Parameters

channelHandle	The event channel for which the subscriber is requesting the EM to delete the subscription. This parameter must be obtained earlier by either clEventChannelOpen() function or clEvtChannelOpenCallback() function.
subscriptionId	Identifier of the subscription.

Return values

CL_OK	The function completed successfully.
CL_EVENT_ERR_INIT_NOT_DONE	Event library has not been initialized.
CL_EVENT_ERR_BAD_HANDLE	On passing an invalid handle.
CL_EVENT_INTERNAL_ERROR	An unexpected problem occurred within the Event Manager.
CL_EVENT_ERR_INVALID_PARAM	On passing an invalid parameter.
CL_EVENT_ERR_NO_MEM	On memory allocation failure.

Description:: This function allows an EO to stop receiving events for a particular subscription on an event channel by removing the subscription.

: The execution of this function is successful if the subscriptionId matches with an earlier registered subscription. Events queued to be delivered to the EO, and ones that no longer match any subscription if the clEventUnsubscribe() function are purged. An EO that wants to modify a subscription without losing any events must establish the new subscription before removing the existing subscription.

Library File:: ClEventClient

See Also: clEventSubscribe()

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation