/home/dko/projects/mobilec/trunk/src/include/libmc.h

Go to the documentation of this file.

/*[
 * Copyright (c) 2007 Integration Engineering Laboratory
                      University of California, Davis
 *
 * Permission to use, copy, and distribute this software and its
 * documentation for any purpose with or without fee is hereby granted,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.
 *
 * Permission to modify the software is granted, but not the right to
 * distribute the complete modified source code.  Modifications are to
 * be distributed as patches to the released version.  Permission to
 * distribute binaries produced by compiling modified sources is granted,
 * provided you
 *   1. distribute the corresponding source modifications from the
 *    released version in the form of a patch file along with the binaries,
 *   2. add special version identification to distinguish your version
 *    in addition to the base release version number,
 *   3. provide your name and address as the primary contact for the
 *    support of your modified version, and
 *   4. retain our contact information in regard to use of the base
 *    software.
 * Permission to distribute the released version of the source code along
 * with corresponding source modifications in the form of a patch file is
 * granted with same provisions 2 through 4 for binary distributions.
 *
 * This software is provided "as is" without express or implied warranty
 * to the extent permitted by applicable law.
]*/

/* Filename: libmc.h */
/* Current functions implemented 
MC_AclDestroy
MC_AclNew
MC_AclPost
MC_AclReply
MC_AclRetrieve
MC_AclSend
MC_AclWaitRetrieve
MC_AddAgent 
MC_Barrier 
MC_BarrierInit 
MC_BarrierDelete 
MC_CallAgentFunc
MC_ChInitializeOptions 
MC_ComposeAgent
MC_CondBroadcast 
MC_CondSignal 
MC_CondWait  
MC_CondReset 
MC_CopyAgent 
MC_DeleteAgent 
MC_DeregisterService
MC_End 
MC_FindAgentByName
MC_FindAgentByID
MC_GetAgentArrivalTime 
MC_GetAgentStatus 
MC_GetAgentXMLString 
MC_GetAgentExecEngine 
MC_GetAgentID
MC_GetAgentName
MC_GetAgentReturnData
MC_GetAgentNumTasks 
MC_GetAgentType 
MC_GetAllAgents 
MC_HaltAgency 
MC_Initialize
MC_InitializeAgencyOptions 
MC_MutexLock 
MC_MutexUnlock 
MC_PrintAgentCode 
MC_RegisterService
MC_ResumeAgency 
MC_RetrieveAgent 
MC_RetrieveAgentCode 
MC_ResetSignal 
MC_SearchForService
MC_SemaphorePost 
MC_SemaphoreWait 
MC_SendCh
MC_SendAgentMigrationMessage
MC_SendAgentMigrationMessageFile
MC_SendSteerCommand 
MC_SetAgentStatus 
MC_SetDefaultAgentStatus
MC_SetThreadOn 
MC_SetThreadsAllOn
MC_SetThreadOff 
MC_SetThreadsAllOff
MC_Steer
MC_SteerControl 
MC_SyncDelete 
MC_SyncInit 
MC_TerminateAgent 
MC_MainLoop 
MC_MainLoop
MC_WaitAgent 
MC_WaitRetrieveAgent 
MC_WaitSignal 

   *** */

#ifndef _MOBILEC_H_
#define _MOBILEC_H_

#ifdef WIN32
        #ifdef _MC_DLL
                // Building a .dll - export functions as marked
                #define EXPORTMC _declspec(dllexport)
        #else
                // Not building a .dll - building .lib assumed - no export required
                #define EXPORTMC
        #endif
#else
        // Not windows
        #define EXPORTMC
#endif

/* The MC_Wait() function is deprecated as of version 1.9.4.
 * All calls to MC_Wait() should now be changed to MC_MainLoop() */
#define MC_Wait(arg1) \
  MC_MainLoop(arg1)

#include <embedch.h>
#ifdef __cplusplus
extern "C" {
#endif

#ifndef _ERROR_CODE_E_
#define _ERROR_CODE_E_
/*
 * Error Codes
 * NOTE: There is a copy of this enum in mc_error.h
 * */
typedef enum error_code_e {
    MC_SUCCESS = 0,
    MC_ERR,
    MC_ERR_CONNECT,
    MC_ERR_PARSE,
    MC_ERR_EMPTY,
    MC_ERR_INVALID,
    MC_ERR_INVALID_ARGS,
    MC_ERR_NOT_FOUND,
    MC_ERR_MEMORY,
    MC_ERR_SEND,
    MC_WARN_DUPLICATE
} error_code_t;
#endif

enum MC_ThreadIndex_e{ 
    MC_THREAD_DF=0,   
    MC_THREAD_AMS,    
    MC_THREAD_ACC,    
    MC_THREAD_CP,     
    MC_THREAD_AGENT,  
    MC_THREAD_ALL };


typedef enum MC_SteerCommand_e {
  MC_RUN = 0,     
  MC_SUSPEND,     
  MC_RESTART,     
  MC_STOP         
} MC_SteerCommand_t;

enum MC_Signal_e{
    MC_NO_SIGNAL      =0x00, 
    MC_RECV_CONNECTION=0x01, 
    MC_RECV_MESSAGE   =0x02, 
    MC_RECV_AGENT     =0x04, 
    MC_RECV_RETURN    =0x08, 
    MC_EXEC_AGENT     =0x0F, 
    MC_ALL_SIGNALS    =0x10  
};

typedef struct agency_s {
    int client;
    int server;
    char *hostName;                     
    char *filename;
    int portno;                         
    int portnoc;
    struct mc_platform_s* mc_platform;  
    int default_agentstatus;            
    int threads;                        
    int enable_security;                
    int stack_size[MC_THREAD_ALL];
    error_code_t last_error;
} agency_t;
typedef agency_t* agency_p;
typedef agency_p MCAgency_t;

typedef struct MCAgencyOptions_s{
    int threads;              
    int default_agent_status; 
    int modified;             
    int enable_security;      
    /* Following are some thread stack size options: unix/pthreads only! */
    int stack_size[MC_THREAD_ALL]; 
} MCAgencyOptions_t;

#ifndef AGENT_T
#define AGENT_T
typedef struct agent_s agent_t;
typedef agent_t* MCAgent_t;
typedef agent_t* agent_p;
#endif

enum MC_AgentType_e{ MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT };

enum MC_AgentStatus_e{ 
        MC_NO_STATUS = -1,
    MC_WAIT_CH = 0,    
    MC_WAIT_MESSGSEND, 
    MC_AGENT_ACTIVE,   
    MC_AGENT_NEUTRAL,  
    MC_AGENT_SUSPENDED,
    MC_WAIT_FINISHED   
};

struct fipa_acl_message_s;

EXPORTMC int 
MC_AclDestroy(struct fipa_acl_message_s* message);

EXPORTMC extern struct fipa_acl_message_s*
MC_AclNew(void);

EXPORTMC extern int MC_AclPost(MCAgent_t agent, struct fipa_acl_message_s* message);

EXPORTMC extern struct fipa_acl_message_s*
MC_AclReply(struct fipa_acl_message_s* acl_message);

EXPORTMC extern struct fipa_acl_message_s* MC_AclRetrieve(MCAgent_t agent);

EXPORTMC extern int MC_AclSend(MCAgency_t attr, struct fipa_acl_message_s* acl);

EXPORTMC extern struct fipa_acl_message_s* MC_AclWaitRetrieve(MCAgent_t agent);

/* ACL Helper Functions Here */
enum fipa_performative_e;

EXPORTMC int MC_AclSetPerformative(
    struct fipa_acl_message_s* acl,
    enum fipa_performative_e performative );

EXPORTMC int MC_AclSetSender(
    struct fipa_acl_message_s* acl,
    const char* name,
    const char* address );
  
EXPORTMC int MC_AclAddReceiver(
    struct fipa_acl_message_s* acl,
    const char* name,
    const char* address );

EXPORTMC int MC_AclAddReplyTo(
    struct fipa_acl_message_s* acl,
    const char* name,
    const char* address);

EXPORTMC int MC_AclSetContent(
    struct fipa_acl_message_s* acl,
    const char* content );

/* End ACL Helper Functions */


EXPORTMC extern int MC_AddAgent( 
    MCAgency_t attr, 
    MCAgent_t agent);

extern const void* 
MC_AgentVariableRetrieve(
    MCAgent_t agent,
    const char* var_name,
    int task_num);

extern int 
MC_AgentVariableSave(MCAgent_t agent, const char* var_name);

EXPORTMC extern int MC_BarrierDelete(MCAgency_t attr, int id);

EXPORTMC extern int MC_BarrierInit(MCAgency_t attr, int id, int num_procs);

EXPORTMC extern int MC_ChInitializeOptions(MCAgency_t attr, ChOptions_t *options);

EXPORTMC extern int MC_CallAgentFunc(
        MCAgent_t agent,
        const char* funcName,
        void* returnVal,
        void* varg
        );


MCAgent_t
MC_ComposeAgent(
    const char* name,
    const char* home,
    const char* owner, 
    const char* code,
    const char* return_var_name,
    const char* server,
    int persistent
    );

EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);

EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);

EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);

EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);

int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);

EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);

EXPORTMC extern int MC_End(MCAgency_t attr);

int MC_DestroyServiceSearchResult(
    char** agentName,
    char** serviceName,
    int* agentID,
    int numResult);


EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);

EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);

EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);

EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);

/*
 * \brief           Retrieve an agent's name
 *
 * \return          a malloc'd character string on success, or NULL on failure
 */
EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);

EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);

EXPORTMC extern int MC_GetAgentReturnData(
        MCAgent_t agent,
        int task_num,
        void **data,
        int *dim,
        int **extent);

EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);

EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);

EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);

EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);

EXPORTMC extern MCAgency_t MC_Initialize(
        int port,
        MCAgencyOptions_t *options);

EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);

 EXPORTMC extern int MC_MainLoop(MCAgency_t attr);

EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);

EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 

/*
 * \brief           Unlocks a MobileC synchronization variable
 *
 * \param attr      a MobileC agency handle
 * \param id        the synchronization variable id to unlock
 *
 * \return          0 on success, error_code_t type on failure
 *
 * \see             MC_MutexLock()
 */
EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 

EXPORTMC extern int MC_RegisterService(
        MCAgency_t agency,
        /* Optional input args: Must input 
         * MCAgent_t OR
         * agentID AND agentName */
        MCAgent_t agent,
        int agentID,
        const char *agentName,
        char **serviceNames,
        int numServices);

EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);

EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);

EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);

EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);

EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);

EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);

EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);

EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );

EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);

EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);

EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);

EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);

EXPORTMC extern int MC_SearchForService(
        /* Input args */
        MCAgency_t attr, 
        const char *searchString,
        /* Return Args */
        char*** agentNames,
        char*** serviceNames,
        int** agentIDs,
        int* numResults);

EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
        const char *message,
        const char *hostname,
        int port);

EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
        const char *filename,
        const char *hostname,
        int port);

EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);

EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);

EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);

EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);

EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);

EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);

/* EXPORTMC extern int MC_Wait(MCAgency_t attr); */

EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);

EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);

EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);

#ifdef __cplusplus
}
#endif

#endif /* _MOBILEC_H_ */

---