Mobile-C: /home/dko/projects/mobilec/trunk/src/include/libmc.h Source File

00001 /* SVN FILE INFO
00002  * $Revision: 229 $ : Last Committed Revision
00003  * $Date: 2008-10-02 16:27:19 -0700 (Thu, 02 Oct 2008) $ : Last Committed Date */
00004 /*[
00005  * Copyright (c) 2007 Integration Engineering Laboratory
00006                       University of California, Davis
00007  *
00008  * Permission to use, copy, and distribute this software and its
00009  * documentation for any purpose with or without fee is hereby granted,
00010  * provided that the above copyright notice appear in all copies and
00011  * that both that copyright notice and this permission notice appear
00012  * in supporting documentation.
00013  *
00014  * Permission to modify the software is granted, but not the right to
00015  * distribute the complete modified source code.  Modifications are to
00016  * be distributed as patches to the released version.  Permission to
00017  * distribute binaries produced by compiling modified sources is granted,
00018  * provided you
00019  *   1. distribute the corresponding source modifications from the
00020  *    released version in the form of a patch file along with the binaries,
00021  *   2. add special version identification to distinguish your version
00022  *    in addition to the base release version number,
00023  *   3. provide your name and address as the primary contact for the
00024  *    support of your modified version, and
00025  *   4. retain our contact information in regard to use of the base
00026  *    software.
00027  * Permission to distribute the released version of the source code along
00028  * with corresponding source modifications in the form of a patch file is
00029  * granted with same provisions 2 through 4 for binary distributions.
00030  *
00031  * This software is provided "as is" without express or implied warranty
00032  * to the extent permitted by applicable law.
00033 ]*/
00034 
00052 /* Filename: libmc.h */
00053 /* Current functions implemented 
00054 MC_AclDestroy
00055 MC_AclNew
00056 MC_AclPost
00057 MC_AclReply
00058 MC_AclRetrieve
00059 MC_AclSend
00060 MC_AclWaitRetrieve
00061 MC_AddAgent 
00062 MC_Barrier 
00063 MC_BarrierInit 
00064 MC_BarrierDelete 
00065 MC_CallAgentFunc
00066 MC_ChInitializeOptions 
00067 MC_ComposeAgent
00068 MC_CondBroadcast 
00069 MC_CondSignal 
00070 MC_CondWait  
00071 MC_CondReset 
00072 MC_CopyAgent 
00073 MC_DeleteAgent 
00074 MC_DeregisterService
00075 MC_End 
00076 MC_FindAgentByName
00077 MC_FindAgentByID
00078 MC_GetAgentArrivalTime 
00079 MC_GetAgentStatus 
00080 MC_GetAgentXMLString 
00081 MC_GetAgentExecEngine 
00082 MC_GetAgentID
00083 MC_GetAgentName
00084 MC_GetAgentReturnData
00085 MC_GetAgentNumTasks 
00086 MC_GetAgentType 
00087 MC_GetAllAgents 
00088 MC_HaltAgency 
00089 MC_Initialize
00090 MC_InitializeAgencyOptions 
00091 MC_MutexLock 
00092 MC_MutexUnlock 
00093 MC_PrintAgentCode 
00094 MC_RegisterService
00095 MC_ResumeAgency 
00096 MC_RetrieveAgent 
00097 MC_RetrieveAgentCode 
00098 MC_ResetSignal 
00099 MC_SearchForService
00100 MC_SemaphorePost 
00101 MC_SemaphoreWait 
00102 MC_SendCh
00103 MC_SendAgentMigrationMessage
00104 MC_SendAgentMigrationMessageFile
00105 MC_SendSteerCommand 
00106 MC_SetAgentStatus 
00107 MC_SetDefaultAgentStatus
00108 MC_SetThreadOn 
00109 MC_SetThreadsAllOn
00110 MC_SetThreadOff 
00111 MC_SetThreadsAllOff
00112 MC_Steer
00113 MC_SteerControl 
00114 MC_SyncDelete 
00115 MC_SyncInit 
00116 MC_TerminateAgent 
00117 MC_MainLoop 
00118 MC_MainLoop
00119 MC_WaitAgent 
00120 MC_WaitRetrieveAgent 
00121 MC_WaitSignal 
00122 
00123    *** */
00124 
00125 #ifndef _MOBILEC_H_
00126 #define _MOBILEC_H_
00127 
00128 #ifdef WIN32
00129         #ifdef _MC_DLL
00130                 // Building a .dll - export functions as marked
00131                 #define EXPORTMC _declspec(dllexport)
00132         #else
00133                 // Not building a .dll - building .lib assumed - no export required
00134                 #define EXPORTMC
00135         #endif
00136 #else
00137         // Not windows
00138         #define EXPORTMC
00139 #endif
00140 
00141 /* The MC_Wait() function is deprecated as of version 1.9.4.
00142  * All calls to MC_Wait() should now be changed to MC_MainLoop() */
00143 #define MC_Wait(arg1) \
00144   MC_MainLoop(arg1)
00145 
00146 #include <embedch.h>
00147 #ifdef __cplusplus
00148 extern "C" {
00149 #endif
00150 
00151 #ifndef _ERROR_CODE_E_
00152 #define _ERROR_CODE_E_
00153 /*
00154  * Error Codes
00155  * NOTE: There is a copy of this enum in mc_error.h
00156  * */
00157 typedef enum error_code_e {
00158     MC_SUCCESS = 0,
00159     MC_ERR,
00160     MC_ERR_CONNECT,
00161     MC_ERR_PARSE,
00162     MC_ERR_EMPTY,
00163     MC_ERR_INVALID,
00164     MC_ERR_INVALID_ARGS,
00165     MC_ERR_NOT_FOUND,
00166     MC_ERR_MEMORY,
00167     MC_ERR_SEND,
00168     MC_WARN_DUPLICATE
00169 } error_code_t;
00170 #endif
00171 
00175 enum MC_ThreadIndex_e{ 
00176     MC_THREAD_DF=0,   
00177     MC_THREAD_AMS,    
00178     MC_THREAD_ACC,    
00179     MC_THREAD_CP,     
00180     MC_THREAD_AGENT,  
00181     MC_THREAD_ALL };
00182 
00183 
00187 typedef enum MC_SteerCommand_e {
00188   MC_RUN = 0,     
00189   MC_SUSPEND,     
00190   MC_RESTART,     
00191   MC_STOP         
00192 } MC_SteerCommand_t;
00193 
00202 enum MC_Signal_e{
00203     MC_NO_SIGNAL      =0x00, 
00204     MC_RECV_CONNECTION=0x01, 
00205     MC_RECV_MESSAGE   =0x02, 
00206     MC_RECV_AGENT     =0x04, 
00207     MC_RECV_RETURN    =0x08, 
00208     MC_EXEC_AGENT     =0x10, 
00209     MC_ALL_SIGNALS    =0x20  
00210 };
00211 
00215 typedef struct agency_s {
00216     int client;
00217     int server;
00218     char *hostName;                     
00219     char *filename;
00220     int portno;                         
00221     int portnoc;
00222     struct mc_platform_s* mc_platform;  
00223     int default_agentstatus;            
00224     int threads;                        
00225     int enable_security;                
00226     int stack_size[MC_THREAD_ALL];
00227     error_code_t last_error;
00228 } agency_t;
00229 typedef agency_t* agency_p;
00230 typedef agency_p MCAgency_t;
00231 
00235 typedef struct MCAgencyOptions_s{
00236     int threads;              
00237     int default_agent_status; 
00238     int modified;             
00239     int enable_security;      
00241     /* Following are some thread stack size options: unix/pthreads only! */
00242     int stack_size[MC_THREAD_ALL]; 
00243 } MCAgencyOptions_t;
00244 
00245 #ifndef AGENT_T
00246 #define AGENT_T
00247 typedef struct agent_s agent_t;
00248 typedef agent_t* MCAgent_t;
00249 typedef agent_t* agent_p;
00250 #endif
00251 
00252 enum MC_AgentType_e{ MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT };
00253 
00257 enum MC_AgentStatus_e{ 
00258         MC_NO_STATUS = -1,
00259     MC_WAIT_CH = 0,    
00260     MC_WAIT_MESSGSEND, 
00261     MC_AGENT_ACTIVE,   
00262     MC_AGENT_NEUTRAL,  
00263     MC_AGENT_SUSPENDED,
00264     MC_WAIT_FINISHED   
00265 };
00266 
00268 struct fipa_acl_message_s;
00269 #ifndef _FIPA_PERFORMATIVE_E_
00270 #define _FIPA_PERFORMATIVE_E_
00271 enum fipa_performative_e
00272 {
00273   FIPA_ERROR=-1,
00274   FIPA_ZERO,
00275   FIPA_ACCEPT_PROPOSAL,
00276   FIPA_AGREE,
00277   FIPA_CANCEL,
00278   FIPA_CALL_FOR_PROPOSAL,
00279   FIPA_CONFIRM,
00280   FIPA_DISCONFIRM,
00281   FIPA_FAILURE,
00282   FIPA_INFORM,
00283   FIPA_INFORM_IF,
00284   FIPA_INFORM_REF,
00285   FIPA_NOT_UNDERSTOOD,
00286   FIPA_PROPOGATE,
00287   FIPA_PROPOSE,
00288   FIPA_PROXY,
00289   FIPA_QUERY_IF,
00290   FIPA_QUERY_REF,
00291   FIPA_REFUSE,
00292   FIPA_REJECT_PROPOSAL,
00293   FIPA_REQUEST,
00294   FIPA_REQUEST_WHEN,
00295   FIPA_REQUEST_WHENEVER,
00296   FIPA_SUBSCRIBE
00297 };
00298 #endif
00299 
00307 EXPORTMC int 
00308 MC_AclDestroy(struct fipa_acl_message_s* message);
00309 
00315 EXPORTMC extern struct fipa_acl_message_s*
00316 MC_AclNew(void);
00317 
00326 EXPORTMC extern int MC_AclPost(MCAgent_t agent, struct fipa_acl_message_s* message);
00327 
00338 EXPORTMC extern struct fipa_acl_message_s*
00339 MC_AclReply(struct fipa_acl_message_s* acl_message);
00340 
00348 EXPORTMC extern struct fipa_acl_message_s* MC_AclRetrieve(MCAgent_t agent);
00349 
00358 EXPORTMC extern int MC_AclSend(MCAgency_t attr, struct fipa_acl_message_s* acl);
00359 
00367 EXPORTMC extern struct fipa_acl_message_s* MC_AclWaitRetrieve(MCAgent_t agent);
00368 
00369 /* ACL Helper Functions Here */
00370 enum fipa_performative_e;
00371 
00372 EXPORTMC int MC_AclSetPerformative(
00373     struct fipa_acl_message_s* acl,
00374     enum fipa_performative_e performative );
00375 
00376 EXPORTMC int MC_AclSetSender(
00377     struct fipa_acl_message_s* acl,
00378     const char* name,
00379     const char* address );
00380   
00381 EXPORTMC int MC_AclAddReceiver(
00382     struct fipa_acl_message_s* acl,
00383     const char* name,
00384     const char* address );
00385 
00386 EXPORTMC int MC_AclAddReplyTo(
00387     struct fipa_acl_message_s* acl,
00388     const char* name,
00389     const char* address);
00390 
00391 EXPORTMC int MC_AclSetContent(
00392     struct fipa_acl_message_s* acl,
00393     const char* content );
00394 
00395 /* End ACL Helper Functions */
00396 
00397 
00406 EXPORTMC extern int MC_AddAgent( 
00407     MCAgency_t attr, 
00408     MCAgent_t agent);
00409 
00425 extern const void* 
00426 MC_AgentVariableRetrieve(
00427     MCAgent_t agent,
00428     const char* var_name,
00429     int task_num);
00430 
00448 extern int 
00449 MC_AgentVariableSave(MCAgent_t agent, const char* var_name);
00450 
00460 EXPORTMC extern int MC_BarrierDelete(MCAgency_t attr, int id);
00461 
00477 EXPORTMC extern int MC_BarrierInit(MCAgency_t attr, int id, int num_procs);
00478 
00487 EXPORTMC extern int MC_ChInitializeOptions(MCAgency_t attr, ChOptions_t *options);
00488 
00489 
00505 EXPORTMC int
00506 MC_CallAgentFunc(
00507     MCAgent_t agent,
00508     const char* funcName,
00509     void* returnVal,
00510     int numArgs,
00511     ...);
00512 
00529 EXPORTMC extern int MC_CallAgentFuncArg(
00530         MCAgent_t agent,
00531         const char* funcName,
00532         void* returnVal,
00533         void* arg
00534         );
00535 
00546 EXPORTMC extern int MC_CallAgentFuncV(
00547     MCAgent_t agent,
00548     const char* funcName,
00549     void* returnVal,
00550     va_list ap);
00551 
00552   /*
00553     \brief          Calls a function defined in an agent
00554     \param agent    A Mobile-C Agent
00555     \param funcName The name of the function to call
00556     \param returnVal (output) Return value from the agent function
00557     \param arglist  Ch Variable Argument list to pass in
00558    */
00559 EXPORTMC extern int MC_CallAgentFuncVar
00560 (
00561  MCAgent_t agent,
00562  const char* funcName,
00563  void* returnVal,
00564  ChVaList_t arglist
00565  );
00566                                          
00567 
00568 
00582 MCAgent_t
00583 MC_ComposeAgent(
00584     const char* name,
00585     const char* home,
00586     const char* owner, 
00587     const char* code,
00588     const char* return_var_name,
00589     const char* server,
00590     int persistent
00591     );
00592 
00603 EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);
00604 
00620 EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);
00621 
00632 EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);
00633 
00647 EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);
00648 
00658 int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);
00659 
00668 EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);
00669 
00680 EXPORTMC extern int MC_End(MCAgency_t attr);
00681 
00692 int MC_DestroyServiceSearchResult(
00693     char** agentName,
00694     char** serviceName,
00695     int* agentID,
00696     int numResult);
00697 
00698 
00709 EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);
00710 
00719 EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);
00720 
00729 EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);
00730 
00734 EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);
00735 
00736 /*
00737  * \brief           Retrieve an agent's name
00738  *
00739  * \return          a malloc'd character string on success, or NULL on failure
00740  */
00741 EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);
00742 
00748 EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);
00749 
00766 EXPORTMC extern int MC_GetAgentReturnData(
00767         MCAgent_t agent,
00768         int task_num,
00769         void **data,
00770         int *dim,
00771         int **extent);
00772 
00778 EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);
00779 
00785 EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);
00786 
00792 EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);
00793 
00801 EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);
00802 
00813 EXPORTMC extern MCAgency_t MC_Initialize(
00814         int port,
00815         MCAgencyOptions_t *options);
00816 
00829 EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);
00830 
00836  EXPORTMC extern int MC_MainLoop(MCAgency_t attr);
00837 
00846 EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);
00847 
00862 EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 
00863 
00864 /*
00865  * \brief           Unlocks a MobileC synchronization variable
00866  *
00867  * \param attr      a MobileC agency handle
00868  * \param id        the synchronization variable id to unlock
00869  *
00870  * \return          0 on success, error_code_t type on failure
00871  *
00872  * \see             MC_MutexLock()
00873  */
00874 EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 
00875 
00893 EXPORTMC extern int MC_RegisterService(
00894         MCAgency_t agency,
00895         /* Optional input args: Must input 
00896          * MCAgent_t OR
00897          * agentID AND agentName */
00898         MCAgent_t agent,
00899         int agentID,
00900         const char *agentName,
00901         char **serviceNames,
00902         int numServices);
00903 
00911 EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);
00912 
00918 EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);
00919 
00931 EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);
00932 
00946 EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);
00947 
00959 EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);
00960 
00974 EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);
00975 
00984 EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);
00985 
00999 EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );
01000 
01009 EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);
01010 
01016 EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);
01017 
01023 EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);
01024 
01032 EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);
01033 
01049 EXPORTMC extern int MC_SearchForService(
01050         /* Input args */
01051         MCAgency_t attr, 
01052         const char *searchString,
01053         /* Return Args */
01054         char*** agentNames,
01055         char*** serviceNames,
01056         int** agentIDs,
01057         int* numResults);
01058 
01067 EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
01068         const char *message,
01069         const char *hostname,
01070         int port);
01071 
01080 EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
01081         const char *filename,
01082         const char *hostname,
01083         int port);
01084 
01093 EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);
01094 
01110 EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);
01111 
01120 EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);
01121 
01130 EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);
01131 
01147 EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);
01148 
01154 EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);
01155 
01161 /* EXPORTMC extern int MC_Wait(MCAgency_t attr); */
01162 
01169 EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);
01170 
01179 EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);
01180 
01194 EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);
01195 
01196 #ifdef __cplusplus
01197 }
01198 #endif
01199 
01200 #endif /* _MOBILEC_H_ */
01201