OpenClovis Logo

clEventApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : event
21  * File : clEventApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  * This header file contains the various API available with EM.
27  *
28  *
29  *****************************************************************************/
30 
31 
44 #ifndef _CL_EVENT_API_H_
45 # define _CL_EVENT_API_H_
46 
47 # ifdef __cplusplus
48 extern "C"
49 {
50 # endif
51 
52 # include "clCommon.h"
53 # include "clCommonErrors.h"
54 # include "clOsalApi.h"
55 # include "clCntApi.h"
56 # include "clCommon.h"
57 # include "clEventErrors.h"
58 
59 
60 /******************************************************************************
61  EM Definitions
62 ******************************************************************************/
63 
67 # define CL_EVENT_LOCAL_CHANNEL (0x0)
68 
72 # define CL_EVENT_GLOBAL_CHANNEL (0x1)
73 
77 # define CL_EVENT_CHANNEL_SUBSCRIBER (0x2)
78 
82 # define CL_EVENT_CHANNEL_PUBLISHER (0x4)
83 
87 # define CL_EVENT_CHANNEL_CREATE (0x8)
88 
92 # define CL_EVENT_HIGHEST_PRIORITY (0x0)
93 
97 # define CL_EVENT_LOWEST_PRIORITY (0x3)
98 
102 # define CL_EVENT_VERSION {(ClUint8T)'B', 0x1, 0x1}
103 # define CL_EVENT_VERSION_SET(version) (version).releaseCode = (ClUint8T)'B', \
104  (version).majorVersion = 0x1,\
105  (version).minorVersion = 0x1
106 
107 /******************************************************************************
108  EM Data types
109 ******************************************************************************/
110 
115  typedef ClUint64T ClEventIdT;
116 
121  typedef ClUint8T ClEventPriorityT;
122 
140  typedef ClUint8T ClEventChannelOpenFlagsT;
141 
142 
143 
144  /*
145  * Various Event handles
146  */
147 
153  typedef ClHandleT ClEventInitHandleT;
154 
158  typedef ClHandleT ClEventHandleT;
159 
164  typedef ClHandleT ClEventChannelHandleT;
165 
171  typedef ClUint32T ClEventSubscriptionIdT;
172 
173 
174 
175 /******************************************************************************
176  EM Callbacks
177 ******************************************************************************/
178 
206  typedef void (*ClEventDeliverCallbackT)(
207  ClEventSubscriptionIdT subscriptionId,
208  ClEventHandleT eventHandle,
209  ClSizeT eventDataSize);
210 
233  typedef void (*ClEventChannelOpenCallbackT) (
234  ClInvocationT invocation,
235  ClEventChannelHandleT channelHandle,
236  ClRcT error);
237 
238 
243  typedef struct
244  {
245 
250 
255 
257 
258  typedef struct
259  {
260  ClUint8T version;
261  ClEventCallbacksT callbacks;
262  } ClEventVersionCallbacksT;
263 
264 /******************************************************************************
265  EM Data structures
266 ******************************************************************************/
267 
275  typedef struct
276  {
277 
282 
287 
291  ClUint8T *pPattern;
292 
293  } ClEventPatternT;
294 
298  typedef struct
299  {
300 
305 
310 
315 
317 
318 
323  typedef enum
324  {
341 
343 
349  typedef struct
350  {
351 
356 
361 
362  } ClEventFilterT;
363 
374  typedef struct
375  {
376 
381 
386 
388 
389 /******************************************************************************
390  EM External functions
391 ******************************************************************************/
392 
439  CL_IN const ClEventCallbacksT * pEvtCallbacks,
440  CL_INOUT ClVersionT *pVersion);
441 
442  ClRcT clEventInitializeWithVersion(CL_OUT ClEventInitHandleT *pEvtHandle,
443  CL_IN const ClEventVersionCallbacksT *pEvtCallbackTable,
444  CL_IN ClUint32T numCallbacks,
445  CL_INOUT ClVersionT *pVersion);
446 
484  ClSelectionObjectT * pSelectionObject);
485 
486 
487 
520  ClDispatchFlagsT dispatchFlags);
521 
522 
558 
615  CL_IN const ClNameT *pEvtChannelName,
616  CL_IN ClEventChannelOpenFlagsT evtChannelOpenFlag,
617  CL_IN ClTimeT timeout,
618  CL_OUT ClEventChannelHandleT *pChannelHandle);
619 
620 
677  CL_IN ClInvocationT invocation,
678  CL_IN const ClNameT *pEvtChannelName,
680  channelOpenFlags);
681 
715 
716 
761  CL_IN const ClNameT *pEvtChannelName);
762 
763 
797  CL_OUT ClEventHandleT *pEventHandle);
798 
799  ClRcT clEventAllocateWithVersion(CL_IN ClEventChannelHandleT channelHandle,
800  CL_IN ClUint8T version,
801  CL_OUT ClEventHandleT *pEventHandle);
802 
803 
830 
831 
875  CL_IN const ClEventPatternArrayT *pPatternArray,
876  CL_IN ClEventPriorityT priority,
877  CL_IN ClTimeT retentionTime,
878  CL_IN const ClNameT *pPublisherName);
879 
880 
960  CL_IN ClEventPatternArrayT *pPatternArray,
961  CL_OUT ClEventPriorityT * pPriority,
962  CL_OUT ClTimeT *pRetentionTime,
963  CL_OUT ClNameT *pPublisherName,
964  CL_OUT ClTimeT *pPublishTime,
965  CL_OUT ClEventIdT * pEventId);
966 
967 
1021  CL_INOUT void *pEventData,
1022  CL_INOUT ClSizeT *pEventDataSize);
1023 
1024 
1054  CL_OUT void **ppCookie);
1055 
1124  CL_IN const void *pEventData,
1125  CL_IN ClSizeT eventDataSize,
1126  CL_OUT ClEventIdT * pEventId);
1127 
1128 
1187  CL_IN const ClEventFilterArrayT *pFilters,
1188  CL_IN ClEventSubscriptionIdT subscriptionId,
1189  CL_IN void *pCookie);
1190 
1191 
1229  CL_IN ClEventSubscriptionIdT subscriptionId);
1230 
1231 
1232 /*
1233  ************************************
1234  * \brief Clears the retention event.
1235  *
1236  * \par Header File:
1237  * clEventApi.h
1238  *
1239  * \param channelHandle The handle of the event channel on which the event has been
1240  * published. \e channelHandle must be obtained earlier by either the
1241  * \e clEventChannelOpen() function or \e clEvtChannelOpenCallback() function.
1242  *
1243  * \param eventId Identifier of the event.
1244  *
1245  * \retval CL_OK The function completed successfully.
1246  * \retval CL_EVENT_ERR_INIT_NOT_DONE Event library has not been initialized.
1247  * \retval CL_EVENT_ERR_BAD_HANDLE On passing an invalid handle.
1248  * \retval CL_EVENT_INTERNAL_ERROR An unexpected problem occurred within the Event Manager.
1249  * \retval CL_EVENT_ERR_INVALID_PARAM On passing an invalid parameter.
1250  *
1251  * \par Description:
1252  * This function is used to clear the retention time of a published event, designated
1253  * by \e eventId. It indicates that EM need not keep the event any longer
1254  * for potential new subscribers. Once the value of the retention time is reset to
1255  * zero, the event is no longer available for new subscribers.
1256  *
1257  * \par Library File:
1258  * ClEventClient
1259  *
1260  * \sa clEventPublish(), ::ClEventDeliverCallbackT
1261  *
1262  */
1263  ClRcT clEventRetentionTimeClear(CL_IN ClEventChannelHandleT channelHandle,
1264  CL_IN const ClEventIdT eventId);
1265 
1266 # ifdef __cplusplus
1267 }
1268 # endif
1269 
1270 
1271 #endif /* _CL_EVENT_API_H_ */
1272 
Typical defines found in any software project.
Common Error Codes shared across multiple Clovis ASP Components.
Header file of Clovis Container Related APIs.
Header file of Event Manager Error Codes.
Operating System Abstraction Layer API.
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
#define CL_INOUT
CL_INOUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:108
ClInt64T ClTimeT
Time duration specified in nanoseconds.
Definition: clCommon.h:154
#define CL_OUT
CL_OUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:110
ClDispatchFlagsT
Dispatch flags.
Definition: clCommon.h:260
ClUint64T ClSizeT
Definition: clCommon.h:157
#define CL_IN
CL_IN macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:106
ClRcT clEventCookieGet(CL_IN ClEventHandleT eventHandle, CL_OUT void **ppCookie)
Returns the cookie.
ClRcT clEventFinalize(CL_IN ClEventInitHandleT evtHandle)
Finalizes EM library.
ClRcT clEventFree(CL_IN ClEventHandleT eventHandle)
Frees an event header.
ClRcT clEventSelectionObjectGet(ClEventInitHandleT evtHandle, ClSelectionObjectT *pSelectionObject)
Helps detect pending callbacks.
ClRcT clEventInitialize(CL_OUT ClEventInitHandleT *pEvtHandle, CL_IN const ClEventCallbacksT *pEvtCallbacks, CL_INOUT ClVersionT *pVersion)
Initializes EM library.
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 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.
ClUint8T ClEventPriorityT
Event priority type - it ranges from CL_EVENT_LOWEST_PRIORITY to CL_EVENT_HIGHEST_PRIORITY.
Definition: clEventApi.h:121
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 clEventPublish(CL_IN ClEventHandleT eventHandle, CL_IN const void *pEventData, CL_IN ClSizeT eventDataSize, CL_OUT ClEventIdT *pEventId)
Publishes an event.
ClHandleT ClEventChannelHandleT
The type of a handle to an open event channel.
Definition: clEventApi.h:164
ClRcT clEventUnsubscribe(CL_IN ClEventChannelHandleT channelHandle, CL_IN ClEventSubscriptionIdT subscriptionId)
Unsubscribes from an event.
ClRcT clEventDispatch(ClEventInitHandleT evtHandle, ClDispatchFlagsT dispatchFlags)
Invokes the pending callback in context of the EO.
void(* ClEventChannelOpenCallbackT)(ClInvocationT invocation, ClEventChannelHandleT channelHandle, ClRcT error)
Open channel callback.
Definition: clEventApi.h:233
ClHandleT ClEventInitHandleT
The type of the handle supplied by the EM to an EO during the initialization of the EM library.
Definition: clEventApi.h:153
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).
ClUint32T ClEventSubscriptionIdT
The type of an identifier for a particular subscription by a particular EO on a particular event chan...
Definition: clEventApi.h:171
ClRcT clEventAllocate(CL_IN ClEventChannelHandleT channelHandle, CL_OUT ClEventHandleT *pEventHandle)
Allocates an event header.
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.
void(* ClEventDeliverCallbackT)(ClEventSubscriptionIdT subscriptionId, ClEventHandleT eventHandle, ClSizeT eventDataSize)
Event delivery callback.
Definition: clEventApi.h:206
ClRcT clEventChannelClose(CL_IN ClEventChannelHandleT channelHandle)
Closes an event channel.
ClUint64T ClEventIdT
The type of an event identifier.
Definition: clEventApi.h:115
ClUint8T ClEventChannelOpenFlagsT
Event Channel open flag.
Definition: clEventApi.h:140
ClRcT clEventDataGet(CL_IN ClEventHandleT eventHandle, CL_INOUT void *pEventData, CL_INOUT ClSizeT *pEventDataSize)
Returns data associated with an earlier event.
ClHandleT ClEventHandleT
The type of a handle to an event.
Definition: clEventApi.h:158
ClEventFilterTypeT
Filter Related Information.
Definition: clEventApi.h:324
ClRcT clEventChannelUnlink(CL_IN ClEventInitHandleT evtHandle, CL_IN const ClNameT *pEvtChannelName)
Deletes an event channel.
@ CL_EVENT_EXACT_FILTER
The entire filter must exactly match the entire event pattern.
Definition: clEventApi.h:336
@ CL_EVENT_PASS_ALL_FILTER
Always matches, regardless of the filter or event pattern.
Definition: clEventApi.h:340
@ CL_EVENT_SUFFIX_FILTER
The entire filter must match the last filterSize characters of the event pattern.
Definition: clEventApi.h:332
@ CL_EVENT_PREFIX_FILTER
The entire filter must match the first filterSize characters of the event pattern.
Definition: clEventApi.h:328
A name.
Definition: clCommon.h:197
Version Information for various services.
Definition: clCommon.h:250
The callback structure supplied by an EO to the EM containing the callback functions that can be invo...
Definition: clEventApi.h:244
ClEventDeliverCallbackT clEvtEventDeliverCallback
Event delivery callback.
Definition: clEventApi.h:254
ClEventChannelOpenCallbackT clEvtChannelOpenCallback
Asynchronous Channel open callback.
Definition: clEventApi.h:249
An Event pattern may contain a name (for example: a process name, checkpoint name,...
Definition: clEventApi.h:276
ClSizeT patternSize
Actual size of the buffer allocated to receive the pattern value.
Definition: clEventApi.h:286
ClUint8T * pPattern
Pointer to a buffer where the pattern value will be copied.
Definition: clEventApi.h:291
ClSizeT allocatedSize
Size of the buffer allocated to receive the pattern value.
Definition: clEventApi.h:281
The type of an event pattern array.
Definition: clEventApi.h:299
ClEventPatternT * pPatterns
Pointer to a buffer where the array of pattern will be copied.
Definition: clEventApi.h:314
ClSizeT allocatedNumber
Number of entries allocated in the pattern buffer.
Definition: clEventApi.h:304
ClSizeT patternsNumber
Actual number of patterns in the event.
Definition: clEventApi.h:309
The event filter structure defines the filter type and the filter pattern to be applied on an event p...
Definition: clEventApi.h:350
ClEventFilterTypeT filterType
Filter type.
Definition: clEventApi.h:355
ClEventPatternT filter
Filter pattern information.
Definition: clEventApi.h:360
The event filter array structure defines one or more filters.
Definition: clEventApi.h:375
ClSizeT filtersNumber
Number of filters.
Definition: clEventApi.h:380
ClEventFilterT * pFilters
Pointer to filter pattern.
Definition: clEventApi.h:385

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen