PsyAPI.h

Go to the documentation of this file.

#if !defined(_PSYAPI_H_)
#define _PSYAPI_H_
 
#include "MemoryManager.h"
#include "PsyTime.h"
#include "xml_parser.h"
#include "DataMessage.h"
#include "Subscriptions.h"
#include "PsySpace.h"

#define CRANKAPI_FAILED     1 
#define CRANKAPI_INUSE      2 
#define CRANKAPI_RUNNING    3 
#define CRANKAPI_IDLE       4 

#define POST_FAILED         -1 
#define POST_NOSPEC         -2 
#define POST_OUTOFCONTEXT   -3 

#define QUERY_FAILED            1 
#define QUERY_TIMEOUT           2 
#define QUERY_NAME_UNKNOWN      3 
#define QUERY_COMPONENT_UNKNOWN 4 
#define QUERY_QUERYFAILED       5 
#define QUERY_SUCCESS           6 
#define QUERY_NOT_AVAILABLE     7 
#define QUERY_NOT_REACHABLE     8 
 
namespace cmlabs {

#define LOG_COMPONENT       8

typedef std::pair<DataMessage*, DataMessage*> TriggerAndMessage;

class PsyAPI {
    friend class PsySpace;
public:

    static struct PsyType CTRL_SYSTEM_READY;             
    static struct PsyType CTRL_PROCESS_INITIALISE;       
    static struct PsyType CTRL_PROCESS_GREETING;         
    static struct PsyType CTRL_PROCESS_SHUTDOWN;         
    static struct PsyType CTRL_CONTEXT_CHANGE;           
    static struct PsyType CTRL_SYSTEM_SHUTDOWN;          
    static struct PsyType CTRL_SYSTEM_SHUTTINGDOWN;      
    static struct PsyType CTRL_TRIGGER;                  
    static struct PsyType CTRL_TRIGGER_GROUP;            
    static struct PsyType CTRL_QUERY;                    
    static struct PsyType CTRL_QUERY_REPLY;              
    static struct PsyType CTRL_PULLCOMPONENTDATA;        
    static struct PsyType CTRL_CREATECUSTOMPAGE;         
    static struct PsyType CTRL_ADDSUBSCRIPTION;          
    static struct PsyType CTRL_RETRIEVESYSTEMIDS;        
    static struct PsyType CTRL_INTERSYSTEM_QUERY;        
    static struct PsyType CTRL_INTERSYSTEM_QUERY_REPLY;  
 
    // ***************** Constructors *****************
    // Create and destroy resources

    PsyAPI(PsySpace* space);
    ~PsyAPI();

    static PsyAPI* fromPython(unsigned long long ptr);
    static const char* fromPythonAddressOf(unsigned long long ptr);

    bool setAutoDelete(bool autodel);
 
    // ***************** System & Status *****************
    // All system calls
    // Get or set status info

    bool isRunning();

    bool shouldContinue();
    bool getModuleName(char* name, uint32 maxSize);
    std::string getCommandlineBasedir();
    bool setCommandlineBasedir(const char* cmdlineBasedir);
    std::string getModuleName();
    std::string getOtherModuleName(uint32 id);
    uint32 getInputQueueSize();
    std::string typeToText(PsyType type);
    std::string contextToText(PsyContext context);
    bool getCurrentScriptLanguage(char* language, uint32 maxSize);
    bool getCurrentScript(char* script, uint32 maxSize);
    bool getCurrentScriptFilename(char* filename, uint32 maxSize);
    std::string getCurrentScriptLanguage();
    std::string getCurrentScript();
    std::string getCurrentScriptFilename();
    std::set<std::string> getCurrentPostNames();

    bool hasCurrentSignalName(const char* name);

    bool hasCurrentQueryName(const char* name);

    bool hasCurrentRetrieveName(const char* name);

    bool hasCurrentPostName(const char* name);
 
    // ***************** Subscription *****************
    // Get or delete current subscriptions
    // Create new subscription
    // *** Not implemented yet
 
 
 
    // ***************** Tags *****************
    // Create, destroy or get info about tags
    // *** Not implemented yet
 
 
 
 
    // ***************** Messaging *****************
    DataMessage* waitForNewMessage(uint32 ms);

    std::map<std::string, DataMessage*> waitForNewMessageGroup(uint32 ms, std::string& groupName);
 

    std::string getCurrentTriggerName();

    PsyContext getCurrentTriggerContext();
 

    DataMessage* waitForNewMessage(uint32 ms, const char* &triggerName);
 
    uint64 getCurrentMessageReceiveTime();
 
    // Post output messages
    int32 postOutputMessage(const char* postName = NULL, DataMessage* msg = NULL);
 
    // Post output messages
    int32 postOutputMessage(PsyType msgType, DataMessage* msg = NULL);
 
 
    // ***************** Signals *****************
    bool emitSignal(const char* name, DataMessage* msg = NULL);
    DataMessage* waitForSignal(const char* name, uint32 timeout, uint64 lastReceivedTime = 0);
 

    DataMessage* retrieveAllSystemIDs() {
        return space->manager->retrieveAllSystemIDs();
    }
 

    bool addSubscription(const char* xml);
 
 
    // ***************** PsyProbe plugins *****************
    bool addPsyProbeCustomView(const char* name, const char* templateURL);
    bool removePsyProbeCustomView(const char* name) {
        return addPsyProbeCustomView(name, "");
    }
 
    // ***************** Own Data *****************
    // Load, save or delete own persistent data
 
    bool setPrivateData(const char* name, const char* data, uint64 size, const char* mimetype = NULL) {
        return space->manager->componentMemory->setPrivateData(currentCompID, name, data, size, mimetype);
    }

    uint64 getPrivateDataSize(const char* name) {
        return space->manager->componentMemory->getPrivateDataSize(currentCompID, name);
    }

    char* getPrivateDataCopy(const char* name, uint64 &size) {
        return space->manager->componentMemory->getPrivateDataCopy(currentCompID, name, size);
    }

    bool getPrivateData(const char* name, char* data, uint64 maxSize) {
        return space->manager->componentMemory->getPrivateData(currentCompID, name, data, maxSize);
    }

    bool deletePrivateData(const char* name) {
        return space->manager->componentMemory->deletePrivateData(currentCompID, name);
    }
 
    // ***************** Own Parameters *****************
    // Get, set, reset, create or destroy own parameters
    bool createParameter(const char* name, const char* val, const char* defaultValue = NULL) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, defaultValue);
    }

    bool createParameter(const char* name, const char* val, uint32 count, uint32 defaultIndex) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, count, defaultIndex);
    }

    bool createParameter(const char* name, std::vector<std::string> values, const char* defaultValue = NULL) {
        return space->manager->componentMemory->createParameter(currentCompID, name, values, defaultValue);
    }

    bool createParameter(const char* name, int64* val, uint32 count, uint32 defaultIndex) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, count, defaultIndex);
    }

    bool createParameter(const char* name, std::vector<std::string> values, int64 defaultValue) {
        return space->manager->componentMemory->createParameter(currentCompID, name, values, defaultValue);
    }

    bool createParameter(const char* name, std::vector<int64> values, int64 defaultValue = 0) {
        return space->manager->componentMemory->createParameter(currentCompID, name, values, defaultValue);
    }

    bool createParameter(const char* name, float64* val, uint32 count, uint32 defaultIndex) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, count, defaultIndex);
    }

    bool createParameter(const char* name, std::vector<std::string> values, float64 defaultValue) {
        return space->manager->componentMemory->createParameter(currentCompID, name, values, defaultValue);
    }

    bool createParameter(const char* name, std::vector<float64> values, float64 defaultValue = 0) {
        return space->manager->componentMemory->createParameter(currentCompID, name, values, defaultValue);
    }

    bool createParameter(const char* name, int64 val, int64 min = 0, int64 max = 0, int64 interval = 0) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, min, max, interval);
    }

    bool createParameter(const char* name, float64 val, float64 min = 0, float64 max = 0, float64 interval = 0) {
        return space->manager->componentMemory->createParameter(currentCompID, name, val, min, max, interval);
    }

    bool hasParameter(const char* name) {
        return space->manager->componentMemory->hasParameter(currentCompID, name);
    }

    bool deleteParameter(const char* name) {
        return space->manager->componentMemory->deleteParameter(currentCompID, name);
    }

    uint8 getParameterDataType(const char* name) {
        return space->manager->componentMemory->getParameterDataType(currentCompID, name);
    }

    uint32 getParameterValueSize(const char* name) {
        return space->manager->componentMemory->getParameterValueSize(currentCompID, name);
    }

    bool getParameter(const char* name, char* val, uint32 maxSize) {
        return space->manager->componentMemory->getParameter(currentCompID, name, val, maxSize);
    }

    std::string getParameterString(const char* name) {
        return space->manager->componentMemory->getParameterString(currentCompID, name);
    }

    bool getParameterAsBool(const char* name) {
        return space->manager->componentMemory->getParameterAsBool(currentCompID, name);
    }

    int64 getParameterInt(const char* name) {
        return space->manager->componentMemory->getParameterInt(currentCompID, name);
    }

    float64 getParameterFloat(const char* name) {
        return space->manager->componentMemory->getParameterFloat(currentCompID, name);
    }

    bool getParameter(const char* name, int64& val) {
        return space->manager->componentMemory->getParameter(currentCompID, name, val);
    }

    bool getParameter(const char* name, float64& val) {
        return space->manager->componentMemory->getParameter(currentCompID, name, val);
    }

    bool setParameter(const char* name, const char* val) {
        return space->manager->componentMemory->setParameter(currentCompID, name, val);
    }

    bool setParameter(const char* name, int64 val) {
        return space->manager->componentMemory->setParameter(currentCompID, name, val);
    }

    bool setParameter(const char* name, float64 val) {
        return space->manager->componentMemory->setParameter(currentCompID, name, val);
    }

    bool resetParameter(const char* name) {
        return space->manager->componentMemory->resetParameter(currentCompID, name);
    }

    bool tweakParameter(const char* name, int32 tweak) {
        return space->manager->componentMemory->tweakParameter(currentCompID, name, tweak);
    }
 
    // ***************** Other Modules' Parameters *****************
    // Get, set or reset other module's parameters
    // *** Not implemented yet
 
 
 
    // ***************** Queries *****************
    // Query a Data storage devices (Whiteboard, Stream, Catalogue) for data
    // Named queries in PsySpec may be used
    uint8 retrieve(std::list<DataMessage*> &result, const char* name, uint32 maxcount = 0, uint32 maxage = 0, uint32 timeout = 5000);
    uint8 retrieveTimeParam(std::list<DataMessage*> &result, const char* name, uint64 startTime, uint64 endTime = 0, uint32 maxcount = 0, uint32 maxage = 0, uint32 timeout = 5000);
    uint8 retrieveStringParam(std::list<DataMessage*> &result, const char* name, const char* startString, const char* endString = NULL, uint32 maxcount = 0, uint32 maxage = 0, uint32 timeout = 5000);
    uint8 retrieveIntegerParam(std::list<DataMessage*> &result, const char* name, int64 startInteger, int64 endInteger = INT64_NOVALUE, uint32 maxcount = 0, uint32 maxage = 0, uint32 timeout = 5000);
    uint8 retrieveFloatParam(std::list<DataMessage*> &result, const char* name, float64 startFloat, float64 endFloat = FLOAT64_NOVALUE, uint32 maxcount = 0, uint32 maxage = 0, uint32 timeout = 5000);
    uint8 retrieve(std::list<DataMessage*> &result, RetrieveSpec* spec, uint32 timeout = 5000);

    uint8 queryCatalog(char** result, uint32 &resultsize, const char* name, const char* query, const char* operation = NULL, const char* data = NULL, uint32 datasize = 0, uint32 timeout = 5000);

    uint8 queryCatalog(DataMessage** resultMsg, const char* name, DataMessage* msg, uint32 timeout = 5000);

    uint8 queryRemoteCatalog(DataMessage** resultMsg, const char* componentName, const char* ipAddress, uint16 port, DataMessage* msg, uint32 timeout = 5000);

    uint8 queryRemoteCatalog(DataMessage** resultMsg, const char* componentName, uint32 ipAddress, uint16 port, DataMessage* msg, uint32 timeout = 5000);

    uint8 queryRemoteCatalog(DataMessage** resultMsg, uint32& chosenAddress, const char* componentName, uint32* ipAddresses, uint32 numAddresses, uint16 port, DataMessage* msg, uint32 timeout = 5000);

    bool queryReply(uint32 id, uint8 status, char* data, uint32 size, uint32 count);
    bool queryReply(uint32 id, uint8 status, DataMessage* msg = NULL);
 
    // ***************** Performance *****************
    // For querying about performance
    // *** Not implemented yet
 
 
 
    // ***************** Monitoring *****************
    // For providing custom data to monitoring tools
    // *** Not implemented yet
 
 
 
    // ***************** Supervisor *****************
    // API for supervisor modules
    // *** Not implemented yet
 

    bool logPrint(int level, const char *formatstring, ... );
 
private:
    PsySpace* space;
    utils::Mutex apiMutex;
    uint64 startedRunning;
    bool shouldContinueRunning;
    uint32 currentCrankID;
    uint32 currentCompID;
    uint32 msgReceivedCount;
    uint32 msgInputCount;
    uint32 msgSentCount;
    uint32 msgPostedCount;
    uint64 lastCPUTicks;
    uint64 lastWallTime;
    uint32 chainCPUTicks;
    uint32 chainWallTime;
    uint32 chainCount;
 
    std::queue<TriggerAndMessage> inputQueue;
    utils::Semaphore inputQueueSemaphore;
 
    bool autoDelete;
    DataMessage* currentTriggerMsg;
    DataMessage* currentMsg;
    std::map<std::string, DataMessage*> currentGroupMap;    // T1.6: member messages of the current joined set (owned; freed on next wait)
    DataMessage* currentSignalMsg;
    TriggerSpec* currentTriggerSpec;
    char currentTriggerName[MAXKEYNAMELEN+1];
    char commandlineBasedir[MAXCOMMANDLINELEN + 1];
 
    // Only called by PsySpace
    uint64 checkLastWaitForMessage();
    uint8 addInputTrigger(uint32 crankID, uint32 compID, DataMessage* trigger, DataMessage* msg);
    bool begin();
    bool finish();
    bool stop();
};
 
} // namespace cmlabs
 
#endif //_PSYAPI_H_