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

00001 /* SVN FILE INFO
00002  * $Revision: 316 $ : Last Committed Revision
00003  * $Date: 2009-04-29 16:40:54 -0700 (Wed, 29 Apr 2009) $ : 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 
00228                 char* priv_key_filename;
00229                 char* known_host_filename;
00230     error_code_t last_error;
00231 } agency_t;
00232 typedef agency_t* agency_p;
00233 typedef agency_p MCAgency_t;
00234 
00238 typedef struct MCAgencyOptions_s{
00239     int threads;              
00240     int default_agent_status; 
00241     int modified;             
00242     int enable_security;      
00243     unsigned char passphrase[32]; 
00245     /* Following are some thread stack size options: unix/pthreads only! */
00246     int stack_size[MC_THREAD_ALL]; 
00248                 char *known_host_filename;
00249                 char *priv_key_filename;
00250 } MCAgencyOptions_t;
00251 
00252 #ifndef AGENT_T
00253 #define AGENT_T
00254 typedef struct agent_s agent_t;
00255 typedef agent_t* MCAgent_t;
00256 typedef agent_t* agent_p;
00257 #endif
00258 
00259 enum MC_AgentType_e{ MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT };
00260 
00264 enum MC_AgentStatus_e{ 
00265         MC_NO_STATUS = -1,
00266     MC_WAIT_CH = 0,    
00267     MC_WAIT_MESSGSEND, 
00268     MC_AGENT_ACTIVE,   
00269     MC_AGENT_NEUTRAL,  
00270     MC_AGENT_SUSPENDED,
00271     MC_WAIT_FINISHED   
00272 };
00273 
00275 struct fipa_acl_message_s;
00276 #ifndef _FIPA_PERFORMATIVE_E_
00277 #define _FIPA_PERFORMATIVE_E_
00278 enum fipa_performative_e
00279 {
00280   FIPA_ERROR=-1,
00281   FIPA_ZERO,
00282   FIPA_ACCEPT_PROPOSAL,
00283   FIPA_AGREE,
00284   FIPA_CANCEL,
00285   FIPA_CALL_FOR_PROPOSAL,
00286   FIPA_CONFIRM,
00287   FIPA_DISCONFIRM,
00288   FIPA_FAILURE,
00289   FIPA_INFORM,
00290   FIPA_INFORM_IF,
00291   FIPA_INFORM_REF,
00292   FIPA_NOT_UNDERSTOOD,
00293   FIPA_PROPOGATE,
00294   FIPA_PROPOSE,
00295   FIPA_PROXY,
00296   FIPA_QUERY_IF,
00297   FIPA_QUERY_REF,
00298   FIPA_REFUSE,
00299   FIPA_REJECT_PROPOSAL,
00300   FIPA_REQUEST,
00301   FIPA_REQUEST_WHEN,
00302   FIPA_REQUEST_WHENEVER,
00303   FIPA_SUBSCRIBE
00304 };
00305 #endif
00306 
00314 EXPORTMC int 
00315 MC_AclDestroy(struct fipa_acl_message_s* message);
00316 
00322 EXPORTMC extern struct fipa_acl_message_s*
00323 MC_AclNew(void);
00324 
00333 EXPORTMC extern int MC_AclPost(MCAgent_t agent, struct fipa_acl_message_s* message);
00334 
00345 EXPORTMC extern struct fipa_acl_message_s*
00346 MC_AclReply(struct fipa_acl_message_s* acl_message);
00347 
00355 EXPORTMC extern struct fipa_acl_message_s* MC_AclRetrieve(MCAgent_t agent);
00356 
00365 EXPORTMC extern int MC_AclSend(MCAgency_t attr, struct fipa_acl_message_s* acl);
00366 
00374 EXPORTMC extern struct fipa_acl_message_s* MC_AclWaitRetrieve(MCAgent_t agent);
00375 
00376 /* ACL Helper Functions Here */
00377 enum fipa_performative_e;
00378 
00379 EXPORTMC int MC_AclSetPerformative(
00380     struct fipa_acl_message_s* acl,
00381     enum fipa_performative_e performative );
00382 
00383 EXPORTMC int MC_AclSetSender(
00384     struct fipa_acl_message_s* acl,
00385     const char* name,
00386     const char* address );
00387   
00388 EXPORTMC int MC_AclAddReceiver(
00389     struct fipa_acl_message_s* acl,
00390     const char* name,
00391     const char* address );
00392 
00393 EXPORTMC int MC_AclAddReplyTo(
00394     struct fipa_acl_message_s* acl,
00395     const char* name,
00396     const char* address);
00397 
00398 EXPORTMC int MC_AclSetContent(
00399     struct fipa_acl_message_s* acl,
00400     const char* content );
00401 
00402 /* End ACL Helper Functions */
00403 
00404 
00413 EXPORTMC extern int MC_AddAgent( 
00414     MCAgency_t attr, 
00415     MCAgent_t agent);
00416 
00432 extern const void* 
00433 MC_AgentVariableRetrieve(
00434     MCAgent_t agent,
00435     const char* var_name,
00436     int task_num);
00437 
00452 int
00453 MC_AgentVariableRetrieveInfo(
00454     MCAgent_t agent,
00455     const char* var_name,
00456     int task_num,
00457     const void** data,
00458     int* dim,
00459     const int** extent
00460     );
00461 
00479 extern int 
00480 MC_AgentVariableSave(MCAgent_t agent, const char* var_name);
00481 
00491 EXPORTMC extern int MC_BarrierDelete(MCAgency_t attr, int id);
00492 
00508 EXPORTMC extern int MC_BarrierInit(MCAgency_t attr, int id, int num_procs);
00509 
00518 EXPORTMC extern int MC_ChInitializeOptions(MCAgency_t attr, ChOptions_t *options);
00519 
00520 
00536 EXPORTMC int
00537 MC_CallAgentFunc(
00538     MCAgent_t agent,
00539     const char* funcName,
00540     void* returnVal,
00541     int numArgs,
00542     ...);
00543 
00560 EXPORTMC extern int MC_CallAgentFuncArg(
00561         MCAgent_t agent,
00562         const char* funcName,
00563         void* returnVal,
00564         void* arg
00565         );
00566 
00577 EXPORTMC extern int MC_CallAgentFuncV(
00578     MCAgent_t agent,
00579     const char* funcName,
00580     void* returnVal,
00581     va_list ap);
00582 
00583   /*
00584     \brief          Calls a function defined in an agent
00585     \param agent    A Mobile-C Agent
00586     \param funcName The name of the function to call
00587     \param returnVal (output) Return value from the agent function
00588     \param arglist  Ch Variable Argument list to pass in
00589    */
00590 EXPORTMC extern int MC_CallAgentFuncVar
00591 (
00592  MCAgent_t agent,
00593  const char* funcName,
00594  void* returnVal,
00595  ChVaList_t arglist
00596  );
00597                                          
00598 
00599 
00613 MCAgent_t
00614 MC_ComposeAgent(
00615     const char* name,
00616     const char* home,
00617     const char* owner, 
00618     const char* code,
00619     const char* return_var_name,
00620     const char* server,
00621     int persistent
00622     );
00623 
00634 EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);
00635 
00651 EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);
00652 
00663 EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);
00664 
00678 EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);
00679 
00689 int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);
00690 
00699 EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);
00700 
00711 EXPORTMC extern int MC_End(MCAgency_t attr);
00712 
00723 int MC_DestroyServiceSearchResult(
00724     char** agentName,
00725     char** serviceName,
00726     int* agentID,
00727     int numResult);
00728 
00729 
00740 EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);
00741 
00750 EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);
00751 
00760 EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);
00761 
00765 EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);
00766 
00767 /*
00768  * \brief           Retrieve an agent's name
00769  *
00770  * \return          a malloc'd character string on success, or NULL on failure
00771  */
00772 EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);
00773 
00779 EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);
00780 
00797 EXPORTMC extern int MC_GetAgentReturnData(
00798         MCAgent_t agent,
00799         int task_num,
00800         void **data,
00801         int *dim,
00802         int **extent);
00803 
00809 EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);
00810 
00816 EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);
00817 
00823 EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);
00824 
00832 EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);
00833 
00844 EXPORTMC extern MCAgency_t MC_Initialize(
00845         int port,
00846         MCAgencyOptions_t *options);
00847 
00860 EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);
00861 
00867  EXPORTMC extern int MC_MainLoop(MCAgency_t attr);
00868 
00877 EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);
00878 
00888 EXPORTMC extern int MC_MigrateAgent(MCAgent_t agent, const char* hostname, int port);
00889 
00904 EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 
00905 
00906 /*
00907  * \brief           Unlocks a MobileC synchronization variable
00908  *
00909  * \param attr      a MobileC agency handle
00910  * \param id        the synchronization variable id to unlock
00911  *
00912  * \return          0 on success, error_code_t type on failure
00913  *
00914  * \see             MC_MutexLock()
00915  */
00916 EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 
00917 
00935 EXPORTMC extern int MC_RegisterService(
00936         MCAgency_t agency,
00937         /* Optional input args: Must input 
00938          * MCAgent_t OR
00939          * agentID AND agentName */
00940         MCAgent_t agent,
00941         int agentID,
00942         const char *agentName,
00943         char **serviceNames,
00944         int numServices);
00945 
00953 EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);
00954 
00960 EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);
00961 
00973 EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);
00974 
00988 EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);
00989 
01001 EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);
01002 
01016 EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);
01017 
01026 EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);
01027 
01041 EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );
01042 
01051 EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);
01052 
01058 EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);
01059 
01065 EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);
01066 
01074 EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);
01075 
01091 EXPORTMC extern int MC_SearchForService(
01092         /* Input args */
01093         MCAgency_t attr, 
01094         const char *searchString,
01095         /* Return Args */
01096         char*** agentNames,
01097         char*** serviceNames,
01098         int** agentIDs,
01099         int* numResults);
01100 
01109 EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
01110         const char *message,
01111         const char *hostname,
01112         int port);
01113 
01122 EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
01123         const char *filename,
01124         const char *hostname,
01125         int port);
01126 
01135 EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);
01136 
01152 EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);
01153 
01162 EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);
01163 
01172 EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);
01173 
01189 EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);
01190 
01196 EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);
01197 
01203 /* EXPORTMC extern int MC_Wait(MCAgency_t attr); */
01204 
01211 EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);
01212 
01221 EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);
01222 
01236 EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);
01237 
01238 #ifdef __cplusplus
01239 }
01240 #endif
01241 
01242 #endif /* _MOBILEC_H_ */
01243