correlator_plugin.h

Go to the documentation of this file.

#ifndef CORRELATOR_PLUGIN_H
#define CORRELATOR_PLUGIN_H

#ifndef  _AP_NO_DEPRECATED_PLUGINAPI_WARNING
#ifdef __GNUC__
#warning This API for writing EPL plugins is deprecated. Please use the API located in epl_plugin.hpp instead
#else
#pragma message("engine_client_c.h(0) Warning: This API for writing EPL plugins is deprecated. Please use the API located in epl_plugin.hpp instead")
#endif
#endif

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


/* Version history:
 * 1.0  First version released in Apama Engine 2.0.3
 *      Win32 support added in Apama Engine 2.0.4
 * 2.0  Add serialisation support for Apama Engine 2.1 release
 *      Unfortunately this breaks back compatibility of chunks
 * 3.0  First C-compatible version of the API, in Apama Engine 2.1.2
 *      Note that the 2.0 C++ API still exists in this release; the
 *      2.x (C++) and 3.x (C) versions will be maintained in parallel.
 * 4.0  Major version number change to force users to re-compile for VS7.1
 *      and/or check the correct free implementation is used (result of
 *      InputStream's getString must be freed with AP_Context's char8free)
 *      Also adds support for the getCorrelator() context function and the
 *      AP_PluginCorrelatorInterface type that can be used to send events
 *      back into the correlator.  This brings the C++ and C plugin APIs
 *      back into sync - future changes should be made to both APIs.
 * 5.0  Add getContextId and sendEventTo. Also added the optional
 *      GET_CAPABILITIES and THREAD_ENDED functions that the plugin may
 *      provide. Improved some function prototypes.
 * 6.0  Improved the interface's const-correctness. Increased the
 *      performance of AP_TypeList, made AP_Chunk construction and
 *      destruction cheaper, especially in a multi-threaded
 *      environment. Added AP_Type::visitSequenceElements.
 * 7.0  Remove serialisation support for Apama 5.0 release
 * 8.0  No changes here, but to keep it in sync with the .hpp
 *      9.0  Add support for modifying sequence lengths and returning sequences
 */
#define AP_CORRELATOR_PLUGIN_VERSION      0x00090000

typedef enum {
        AP_PLUGIN_EXCEPTION, 
        AP_PLUGIN_TYPE_EXCEPTION, 
        AP_PLUGIN_UNIMPLEMENTED_EXCEPTION,
        AP_PLUGIN_BOUNDS_EXCEPTION, 
        AP_PLUGIN_SERIALISATION_EXCEPTION
} AP_CorrelatorPluginExceptionType;



#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

        struct AP_PluginCorrelatorInterface_API;
        struct AP_PluginContext_API;
        struct AP_PluginType_API;
        struct AP_PluginChunk_API;
        struct AP_PluginTypeList_API;

        struct AP_PluginChunk_Callbacks;

#ifdef __cplusplus
        struct AP_PluginCorrelatorInterface_Stubs;
        struct AP_PluginContext_Stubs;
        struct AP_PluginType_Stubs;
        struct AP_PluginChunk_Stubs;
        struct AP_PluginTypeList_Stubs;

        typedef struct AP_PluginCorrelatorInterface_Stubs AP_PluginCorrelatorInterface;
        typedef struct AP_PluginContext_Stubs AP_PluginContext;
        typedef struct AP_PluginType_Stubs AP_PluginType;
        typedef struct AP_PluginChunk_Stubs AP_PluginChunk;
        typedef struct AP_PluginTypeList_Stubs AP_PluginTypeList;
#else
        typedef struct AP_PluginCorrelatorInterface_API AP_PluginCorrelatorInterface;
        typedef struct AP_PluginContext_API AP_PluginContext;
        typedef struct AP_PluginType_API AP_PluginType;
        typedef struct AP_PluginChunk_API AP_PluginChunk;
        typedef struct AP_PluginTypeList_API AP_PluginTypeList;
#endif /* __cplusplus */

        struct AP_PluginCorrelatorInterface_Functions
        {
                void (AP_PLUGIN_CALL* sendEvent)(AP_PluginCorrelatorInterface* _interface, const char* event);
                void (AP_PLUGIN_CALL* sendEventTo)(AP_PluginCorrelatorInterface* _interface, const char* event, AP_uint64 targetCtx, AP_uint64 sourceCtx);
        };

        struct AP_PluginCorrelatorInterface_API
        {
                void* reserved;
                const struct AP_PluginCorrelatorInterface_Functions* functions;
        };

        struct AP_PluginCorrelatorInterface_Stubs {
                struct AP_PluginCorrelatorInterface_API api;

#ifdef __cplusplus
                void sendEvent(char* event) {
                        api.functions->sendEvent(this, event);
                }

                void sendEvent(char* event, AP_uint64 targetCtx, AP_uint64 sourceCtx) {
                        api.functions->sendEventTo(this, event, targetCtx, sourceCtx);
                }
#endif /* __ cplusplus */
        };

        struct AP_PluginContext_Functions
        {
                AP_uint32 (AP_PLUGIN_CALL* version)(const AP_PluginContext* ctx);
                AP_PluginChunk* (AP_PLUGIN_CALL* createChunk)(const AP_PluginContext* ctx, const struct AP_PluginChunk_Callbacks* callbacks, void* userData);
                void (AP_PLUGIN_CALL* deleteChunk)(const AP_PluginContext* ctx, AP_PluginChunk* chunk);
                AP_bool (AP_PLUGIN_CALL* checkException)(const AP_PluginContext* ctx);
                AP_CorrelatorPluginExceptionType (AP_PLUGIN_CALL* getExceptionType)(const AP_PluginContext* ctx);
                const AP_char8* (AP_PLUGIN_CALL* getExceptionMessage)(const AP_PluginContext* ctx);
                void (AP_PLUGIN_CALL* clearException)(const AP_PluginContext* ctx);
                AP_PluginCorrelatorInterface* (AP_PLUGIN_CALL* getCorrelator)(const AP_PluginContext* ctx);
                void (AP_PLUGIN_CALL* char8free)(AP_char8* ptr);
                AP_uint64 (AP_PLUGIN_CALL* getContextId)(const AP_PluginContext* ctx);
        };

        struct AP_PluginContext_API
        {
                const void* reserved;
                const struct AP_PluginContext_Functions* functions;
        };

        struct AP_PluginContext_Stubs {
                struct AP_PluginContext_API api;

#ifdef __cplusplus
                AP_uint32 version() const {
                        return api.functions->version(this);
                }

                AP_PluginChunk* createChunk(const struct AP_PluginChunk_Callbacks* callbacks, void* userData) const {
                        return api.functions->createChunk(this, callbacks, userData);
                }

                void deleteChunk(AP_PluginChunk* chunk) const {
                        api.functions->deleteChunk(this, chunk);
                }

                AP_bool checkException() const {
                        return api.functions->checkException(this);
                }

                AP_CorrelatorPluginExceptionType getExceptionType() const {
                        return api.functions->getExceptionType(this);
                }

                const AP_char8* getExceptionMessage() const {
                        return api.functions->getExceptionMessage(this);
                }

                void clearException() const {
                        api.functions->clearException(this);
                }
                
                const AP_PluginCorrelatorInterface* getCorrelator() const{
                        return api.functions->getCorrelator(this);
                }

                void char8free(AP_char8* ptr) const{
                        api.functions->char8free(ptr);
                }

                AP_uint64 getContextId() const{
                        return api.functions->getContextId(this);
                }
#endif /* __ cplusplus */
        };


        struct AP_PluginChunk_Functions 
        {
                void* (AP_PLUGIN_CALL* getUserData)(const AP_PluginChunk* chunk);
                void (AP_PLUGIN_CALL* setUserData)(AP_PluginChunk* chunk, void* userData);
        };

        struct AP_PluginChunk_Callbacks
        {
                void (AP_PLUGIN_CALL* freeUserData)(AP_PluginChunk* chunk);
                void* (AP_PLUGIN_CALL* copyUserData)(const AP_PluginChunk* chunk);
        };

        struct AP_PluginChunk_API
        {
                void* reserved;
                const struct AP_PluginChunk_Functions *functions;
                const struct AP_PluginChunk_Callbacks *callbacks;
        };

        struct AP_PluginChunk_Stubs {
                struct AP_PluginChunk_API api;

#ifdef __cplusplus
                void* getUserData() const {
                        return api.functions->getUserData(this);
                }

                void setUserData(void* userData) {
                        api.functions->setUserData(this, userData);
                }

                void freeUserData() {
                        api.callbacks->freeUserData(this);
                }

                void* copyUserData() {
                        return api.callbacks->copyUserData(this);
                }
#endif /* __cplusplus */
        };



        struct AP_PluginType_Functions
        {
                AP_TypeDiscriminator (AP_PLUGIN_CALL* getDiscriminator)(const AP_PluginType* obj);

                AP_PluginChunk* (AP_PLUGIN_CALL* getChunkValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setChunkValue)(const AP_PluginType* obj, AP_PluginChunk* val);

                AP_int64 (AP_PLUGIN_CALL* getIntegerValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setIntegerValue)(AP_PluginType* obj, AP_int64 val);

                AP_float64 (AP_PLUGIN_CALL* getFloatValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setFloatValue)(AP_PluginType* obj, AP_float64 val);

                AP_decimal (AP_PLUGIN_CALL* getDecimalValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setDecimalValue)(AP_PluginType* obj, AP_decimal val);

                AP_bool (AP_PLUGIN_CALL* getBooleanValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setBooleanValue)(AP_PluginType* obj, AP_bool val);

                const AP_char8* (AP_PLUGIN_CALL* getStringValue)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setStringValue)(AP_PluginType* obj, const AP_char8* val);

                AP_uint32 (AP_PLUGIN_CALL* getSequenceLength)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* setSequenceLength)(const AP_PluginType* obj, AP_uint32 len);
                AP_TypeDiscriminator (AP_PLUGIN_CALL* getSequenceType)(const AP_PluginType* obj);
                void (AP_PLUGIN_CALL* createSequence)(const AP_PluginType *obj, AP_TypeDiscriminator inner);

                AP_PluginType* (AP_PLUGIN_CALL* getSequenceElement)(const AP_PluginType* obj, AP_uint32 index);

                void (AP_PLUGIN_CALL *copyFrom)(const AP_PluginType *obj, const AP_PluginType *other);

                AP_PluginType* const * (AP_PLUGIN_CALL* getSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseSequenceElements)(const AP_PluginType* obj);

                AP_PluginChunk* const * (AP_PLUGIN_CALL* getChunkSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseChunkSequenceElements)(const AP_PluginType* obj);

                AP_int64* (AP_PLUGIN_CALL* getIntegerSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseIntegerSequenceElements)(const AP_PluginType* obj);

                AP_float64* (AP_PLUGIN_CALL* getFloatSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseFloatSequenceElements)(const AP_PluginType* obj);

                AP_decimal* (AP_PLUGIN_CALL* getDecimalSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseDecimalSequenceElements)(const AP_PluginType* obj);

                AP_bool* (AP_PLUGIN_CALL* getBooleanSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseBooleanSequenceElements)(const AP_PluginType* obj);

                const AP_char8** (AP_PLUGIN_CALL* getStringSequenceElements)(const AP_PluginType* obj, AP_uint32 start, AP_uint32 length);
                void (AP_PLUGIN_CALL* releaseStringSequenceElements)(const AP_PluginType* obj);
        };

        struct AP_PluginType_API
        {
                void* reserved;
                const struct AP_PluginType_Functions* functions;
        };

        struct AP_PluginType_Stubs {
                struct AP_PluginType_API api;

#ifdef __cplusplus
                AP_TypeDiscriminator getDiscriminator() const {
                        return api.functions->getDiscriminator(this);
                }

                AP_PluginChunk* getChunkValue() const {
                        return api.functions->getChunkValue(this);
                }

                void setChunkValue(AP_PluginChunk* val) const {
                        api.functions->setChunkValue(this, val);
                }

                AP_int64 getIntegerValue() const {
                        return api.functions->getIntegerValue(this);
                }

                void setIntegerValue(AP_int64 val) {
                        api.functions->setIntegerValue(this, val);
                }

                AP_float64 getFloatValue() const {
                        return api.functions->getFloatValue(this);
                }

                void setFloatValue(AP_float64 val) {
                        api.functions->setFloatValue(this, val);
                }

                AP_decimal getDecimalValue() const {
                        return api.functions->getDecimalValue(this);
                }

                void setDecimalValue(AP_decimal val) {
                        api.functions->setDecimalValue(this, val);
                }

                AP_bool getBooleanValue() const {
                        return api.functions->getBooleanValue(this);
                }

                void setBooleanValue(AP_bool val) {
                        api.functions->setBooleanValue(this, val);
                }

                const AP_char8* getStringValue() const {
                        return api.functions->getStringValue(this);
                }

                void setStringValue(const AP_char8* val) {
                        api.functions->setStringValue(this, val);
                }

                AP_uint32 getSequenceLength() const {
                        return api.functions->getSequenceLength(this);
                }

                AP_TypeDiscriminator getSequenceType() const {
                        return api.functions->getSequenceType(this);
                }

                AP_PluginType* getSequenceElement(AP_uint32 index) const {
                        return api.functions->getSequenceElement(this, index);
                }

                void copyFrom(const AP_PluginType *other) {
                        return api.functions->copyFrom(this, other);
                }

                AP_PluginType* const *getSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getSequenceElements(this, start, length);
                }

                void releaseSequenceElements() const {
                        api.functions->releaseSequenceElements(this);
                }

                AP_PluginChunk* const * getChunkSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getChunkSequenceElements(this, start, length);
                }

                void releaseChunkSequenceElements() const {
                        api.functions->releaseChunkSequenceElements(this);
                }

                AP_int64* getIntegerSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getIntegerSequenceElements(this, start, length);
                }

                void releaseIntegerSequenceElements() const {
                        api.functions->releaseIntegerSequenceElements(this);
                }

                AP_float64* getFloatSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getFloatSequenceElements(this, start, length);
                }

                void releaseFloatSequenceElements() const {
                        api.functions->releaseFloatSequenceElements(this);
                }

                AP_decimal* getDecimalSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getDecimalSequenceElements(this, start, length);
                }

                void releaseDecimalSequenceElements() const {
                        api.functions->releaseDecimalSequenceElements(this);
                }

                AP_bool* getBooleanSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getBooleanSequenceElements(this, start, length);
                }

                void releaseBooleanSequenceElements() const {
                        api.functions->releaseBooleanSequenceElements(this);
                }

                const AP_char8** getStringSequenceElements(AP_uint32 start = 0, AP_uint32 length = ~0U) const {
                        return api.functions->getStringSequenceElements(this, start, length);
                }

                void releaseStringSequenceElements() const {
                        api.functions->releaseStringSequenceElements(this);
                }
#endif /* __cplusplus */
        };



        struct AP_PluginTypeList_Functions 
        {
                AP_uint32 (AP_PLUGIN_CALL* getSize)(const AP_PluginTypeList* list);
                AP_bool (AP_PLUGIN_CALL* isEmpty)(const AP_PluginTypeList* list);
                const AP_PluginType* (AP_PLUGIN_CALL* getElement)(const AP_PluginTypeList* list, AP_uint32 index);
        };

        struct AP_PluginTypeList_API 
        {
                void* reserved;
                const struct AP_PluginTypeList_Functions* functions;
        };

        struct AP_PluginTypeList_Stubs {
                struct AP_PluginTypeList_API api;

#ifdef __cplusplus
                AP_uint32 getSize() const {
                        return api.functions->getSize(this);
                }

                AP_bool isEmpty() const {
                        return api.functions->isEmpty(this);
                }

                const AP_PluginType* getElement(AP_uint32 index) const {
                        return api.functions->getElement(this, index);
                }
#endif /* __cplusplus */
        };


        typedef void (AP_PLUGIN_CALL* AP_PluginFunctionPtr)(const AP_PluginContext* ctx, const AP_PluginTypeList* args, AP_PluginType* rval, AP_TypeDiscriminator rtype);

        typedef struct
        {
                const AP_char8* name;

                AP_PluginFunctionPtr fptr;

                AP_uint32 nParams;

                const AP_char8** paramTypes;

                const AP_char8* returnType;

        } AP_PluginFunction;
        
        typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_PluginInitFunctionPtr)(const AP_PluginContext* ctx, AP_uint32* version, AP_uint32* nFunctions, AP_PluginFunction** functions);

        typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_PluginShutdownFunctionPtr)(const AP_PluginContext* ctx);

        typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_PluginVersionFunctionPtr)(const AP_PluginContext* ctx, AP_uint32* version);

        typedef AP_PLUGIN_DLL_SYM AP_Capabilities (AP_PLUGIN_CALL* AP_PluginGetCapabilitiesFunctionPtr)(const AP_PluginContext* ctx);

        typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_PluginThreadEndedFunctionPtr) (const AP_PluginContext* ctx);

#ifdef __cplusplus
}  /* extern "C" */
#endif /* __cplusplus */

#endif /* CORRELATOR_PLUGIN_H */