clEventApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : event
 * File        : clEventApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 *          This header file contains the various API available with EM.
 *
 *
 *****************************************************************************/


#ifndef _CL_EVENT_API_H_
# define _CL_EVENT_API_H_

# ifdef __cplusplus
extern "C"
{
# endif

# include "clCommon.h"
# include "clCommonErrors.h"
# include "clOsalApi.h"
# include "clCntApi.h"
# include "clCommon.h"
# include "clEventErrors.h"


/******************************************************************************
                                EM Definitions
******************************************************************************/

# define CL_EVENT_LOCAL_CHANNEL      (0x0)

# define CL_EVENT_GLOBAL_CHANNEL     (0x1)

# define CL_EVENT_CHANNEL_SUBSCRIBER (0x2)

# define CL_EVENT_CHANNEL_PUBLISHER  (0x4)

# define CL_EVENT_CHANNEL_CREATE     (0x8)

# define CL_EVENT_HIGHEST_PRIORITY   (0x0)

# define CL_EVENT_LOWEST_PRIORITY    (0x3)

# define CL_EVENT_VERSION {(ClUint8T)'B', 0x1, 0x1}
# define CL_EVENT_VERSION_SET(version) (version).releaseCode = (ClUint8T)'B', \
                                      (version).majorVersion = 0x1,\
                                      (version).minorVersion = 0x1

/******************************************************************************
                                EM Data types
******************************************************************************/

    typedef ClUint64T ClEventIdT;

    typedef ClUint8T ClEventPriorityT;

    typedef ClUint8T ClEventChannelOpenFlagsT;



    /*
     * Various Event handles
     */

    typedef ClHandleT ClEventInitHandleT;

    typedef ClHandleT ClEventHandleT;

    typedef ClHandleT ClEventChannelHandleT;

    typedef ClUint32T ClEventSubscriptionIdT;



/******************************************************************************
                                EM Callbacks
******************************************************************************/

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

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


    typedef struct
    {

        ClEventChannelOpenCallbackT clEvtChannelOpenCallback;

        ClEventDeliverCallbackT clEvtEventDeliverCallback;

    } ClEventCallbacksT;

    typedef struct
    {
        ClUint8T version;
        ClEventCallbacksT callbacks;
    } ClEventVersionCallbacksT;

/******************************************************************************
                                EM Data structures
******************************************************************************/

    typedef struct
    {

        ClSizeT allocatedSize;

        ClSizeT patternSize;

        ClUint8T *pPattern;

    } ClEventPatternT;

    typedef struct
    {

        ClSizeT allocatedNumber;

        ClSizeT patternsNumber;

        ClEventPatternT *pPatterns;

    } ClEventPatternArrayT;


    typedef enum
    {
        CL_EVENT_PREFIX_FILTER = 1,
    CL_EVENT_SUFFIX_FILTER = 2,
    CL_EVENT_EXACT_FILTER = 3,
    CL_EVENT_PASS_ALL_FILTER = 4,

    } ClEventFilterTypeT;

    typedef struct
    {

        ClEventFilterTypeT filterType;

        ClEventPatternT filter;

    } ClEventFilterT;

    typedef struct
    {

        ClSizeT filtersNumber;

        ClEventFilterT *pFilters;

    } ClEventFilterArrayT;

/******************************************************************************
                                EM External functions
******************************************************************************/
 
    ClRcT clEventInitialize(CL_OUT ClEventInitHandleT *pEvtHandle,
                            CL_IN const ClEventCallbacksT * pEvtCallbacks,
                            CL_INOUT ClVersionT *pVersion);

    ClRcT clEventInitializeWithVersion(CL_OUT ClEventInitHandleT *pEvtHandle,
                                       CL_IN  const ClEventVersionCallbacksT *pEvtCallbackTable,
                                       CL_IN  ClUint32T numCallbacks,
                                       CL_INOUT ClVersionT *pVersion);

    ClRcT clEventSelectionObjectGet(ClEventInitHandleT evtHandle,
                                    ClSelectionObjectT * pSelectionObject);



    ClRcT clEventDispatch(ClEventInitHandleT evtHandle,
                          ClDispatchFlagsT dispatchFlags);


    ClRcT clEventFinalize(CL_IN ClEventInitHandleT evtHandle);

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


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

    ClRcT clEventChannelClose(CL_IN ClEventChannelHandleT channelHandle);


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


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

    ClRcT clEventAllocateWithVersion(CL_IN ClEventChannelHandleT channelHandle,
                                     CL_IN ClUint8T version,
                                     CL_OUT ClEventHandleT *pEventHandle);


    ClRcT clEventFree(CL_IN ClEventHandleT eventHandle);


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


    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);


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


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

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


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


    ClRcT clEventUnsubscribe(CL_IN ClEventChannelHandleT channelHandle,
                             CL_IN ClEventSubscriptionIdT subscriptionId);


/*
 ************************************
 *  \brief Clears the retention event.
 *
 *  \par Header File:
 *  clEventApi.h
 *
 *  \param channelHandle The handle of the event channel on which the event has been
 *   published. \e channelHandle must be obtained earlier by either the
 *   \e clEventChannelOpen() function or \e clEvtChannelOpenCallback() function.
 *
 *  \param eventId Identifier of the event.
 *
 *  \retval CL_OK The function completed successfully.
 *  \retval CL_EVENT_ERR_INIT_NOT_DONE Event library has not been initialized.
 *  \retval CL_EVENT_ERR_BAD_HANDLE On passing an invalid handle.
 *  \retval CL_EVENT_INTERNAL_ERROR An unexpected problem occurred within the Event Manager.
 *  \retval CL_EVENT_ERR_INVALID_PARAM On passing an invalid parameter.
 *
 *  \par Description:
 *   This function is used to clear the retention time of a published event, designated
 *   by \e eventId. It indicates that EM need not  keep the event any longer
 *   for potential new subscribers. Once the value of the retention time is reset to
 *   zero, the event is no longer available for new subscribers.
 *
 *  \par Library File:
 *  ClEventClient
 *
 *  \sa clEventPublish(), ::ClEventDeliverCallbackT
 *
 */
    ClRcT clEventRetentionTimeClear(CL_IN ClEventChannelHandleT channelHandle,
                                    CL_IN const ClEventIdT eventId);

# ifdef __cplusplus
}
# endif


#endif                          /* _CL_EVENT_API_H_ */