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

00001 /* SVN FILE INFO
00002  * $Revision: 427 $ : Last Committed Revision
00003  * $Date: 2009-09-18 12:48:01 -0700 (Fri, 18 Sep 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 #ifndef THREAD_T
00129 #ifdef _WIN32
00130 #include <windows.h>
00131 #define THREAD_T HANDLE
00132 #else
00133 #define THREAD_T pthread_t
00134 #endif
00135 #endif
00136 
00137 #ifdef WIN32
00138         #ifdef _MC_DLL
00139                 // Building a .dll - export functions as marked
00140                 #define EXPORTMC _declspec(dllexport)
00141         #else
00142                 // Not building a .dll - building .lib assumed - no export required
00143                 #define EXPORTMC
00144         #endif
00145 #else
00146         // Not windows
00147         #define EXPORTMC
00148 #endif
00149 
00150 /* The MC_Wait() function is deprecated as of version 1.9.4.
00151  * All calls to MC_Wait() should now be changed to MC_MainLoop() */
00152 #define MC_Wait(arg1) \
00153   MC_MainLoop(arg1)
00154 
00155 #include <embedch.h>
00156 #ifdef __cplusplus
00157 extern "C" {
00158 #endif
00159 
00160 #ifndef _ERROR_CODE_E_
00161 #define _ERROR_CODE_E_
00162 /*
00163  * Error Codes
00164  * NOTE: There is a copy of this enum in mc_error.h
00165  * */
00166 typedef enum error_code_e {
00167     MC_SUCCESS = 0,
00168     MC_ERR,
00169     MC_ERR_CONNECT,
00170     MC_ERR_PARSE,
00171     MC_ERR_EMPTY,
00172     MC_ERR_INVALID,
00173     MC_ERR_INVALID_ARGS,
00174     MC_ERR_NOT_FOUND,
00175     MC_ERR_MEMORY,
00176     MC_ERR_SEND,
00177     MC_WARN_DUPLICATE
00178 } error_code_t;
00179 #endif
00180 
00184 enum MC_ThreadIndex_e{ 
00185     MC_THREAD_DF=0,   
00186     MC_THREAD_AMS,    
00187     MC_THREAD_ACC,    
00188     MC_THREAD_CP,     
00189     MC_THREAD_AGENT,  
00190     MC_THREAD_ALL };
00191 
00192 
00196 typedef enum MC_SteerCommand_e {
00197   MC_RUN = 0,     
00198   MC_SUSPEND,     
00199   MC_RESTART,     
00200   MC_STOP         
00201 } MC_SteerCommand_t;
00202 
00211 enum MC_Signal_e{
00212     MC_NO_SIGNAL      =0x00, 
00213     MC_RECV_CONNECTION=0x01, 
00214     MC_RECV_MESSAGE   =0x02, 
00215     MC_RECV_AGENT     =0x04, 
00216     MC_RECV_RETURN    =0x08, 
00217     MC_EXEC_AGENT     =0x10, 
00218     MC_ALL_SIGNALS    =0x20  
00219 };
00220 
00224 typedef struct agency_s {
00225     int client;
00226     int server;
00227     char *hostName;                     
00228     char *filename;
00229     int portno;                         
00230     int portnoc;
00231     int initInterps;
00232     struct mc_platform_s* mc_platform;  
00233     int default_agentstatus;            
00234     int threads;                        
00235     int enable_security;                
00236     int stack_size[MC_THREAD_ALL];
00237 
00238                 char* priv_key_filename;
00239                 char* known_host_filename;
00240     error_code_t last_error;
00241 } agency_t;
00242 typedef agency_t* agency_p;
00243 typedef agency_p MCAgency_t;
00244 
00248 typedef struct MCAgencyOptions_s{
00249     int threads;              
00250     int default_agent_status; 
00251     int modified;             
00252     int enable_security;      
00253     unsigned char passphrase[32]; 
00255     /* Following are some thread stack size options: unix/pthreads only! */
00256     int stack_size[MC_THREAD_ALL]; 
00258     char *known_host_filename;
00259     char *priv_key_filename;
00260     int initInterps;
00261     ChOptions_t* ch_options;
00262 } MCAgencyOptions_t;
00263 
00264 typedef struct agent_thread_arg_s {
00265         void* args;
00266         struct agent_s* agent;
00267         MCAgency_t attr;
00268         THREAD_T thread;
00269 } agent_thread_arg_t;
00270 
00271 #ifndef AGENT_T
00272 #define AGENT_T
00273 typedef struct agent_s agent_t;
00274 typedef agent_t* MCAgent_t;
00275 typedef agent_t* agent_p;
00276 #endif
00277 
00278 enum MC_AgentType_e{ MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT };
00279 
00283 enum MC_AgentStatus_e{ 
00284         MC_NO_STATUS = -1,
00285     MC_WAIT_CH = 0,    
00286     MC_WAIT_MESSGSEND, 
00287     MC_AGENT_ACTIVE,   
00288     MC_AGENT_NEUTRAL,  
00289     MC_AGENT_SUSPENDED,
00290     MC_WAIT_FINISHED   
00291 };
00292 
00294 struct fipa_acl_message_s;
00295 #ifndef _FIPA_PERFORMATIVE_E_
00296 #define _FIPA_PERFORMATIVE_E_
00297 enum fipa_performative_e
00298 {
00299   FIPA_ERROR=-1,
00300   FIPA_ZERO,
00301   FIPA_ACCEPT_PROPOSAL,
00302   FIPA_AGREE,
00303   FIPA_CANCEL,
00304   FIPA_CALL_FOR_PROPOSAL,
00305   FIPA_CONFIRM,
00306   FIPA_DISCONFIRM,
00307   FIPA_FAILURE,
00308   FIPA_INFORM,
00309   FIPA_INFORM_IF,
00310   FIPA_INFORM_REF,
00311   FIPA_NOT_UNDERSTOOD,
00312   FIPA_PROPOGATE,
00313   FIPA_PROPOSE,
00314   FIPA_PROXY,
00315   FIPA_QUERY_IF,
00316   FIPA_QUERY_REF,
00317   FIPA_REFUSE,
00318   FIPA_REJECT_PROPOSAL,
00319   FIPA_REQUEST,
00320   FIPA_REQUEST_WHEN,
00321   FIPA_REQUEST_WHENEVER,
00322   FIPA_SUBSCRIBE
00323 };
00324 #endif
00325 
00333 EXPORTMC int 
00334 MC_AclDestroy(struct fipa_acl_message_s* message);
00335 
00341 EXPORTMC extern struct fipa_acl_message_s*
00342 MC_AclNew(void);
00343 
00352 EXPORTMC extern int MC_AclPost(MCAgent_t agent, struct fipa_acl_message_s* message);
00353 
00364 EXPORTMC extern struct fipa_acl_message_s*
00365 MC_AclReply(struct fipa_acl_message_s* acl_message);
00366 
00374 EXPORTMC extern struct fipa_acl_message_s* MC_AclRetrieve(MCAgent_t agent);
00375 
00384 EXPORTMC extern int MC_AclSend(MCAgency_t attr, struct fipa_acl_message_s* acl);
00385 
00393 EXPORTMC extern struct fipa_acl_message_s* MC_AclWaitRetrieve(MCAgent_t agent);
00394 
00395 /* ACL Helper Functions Here */
00396 enum fipa_performative_e;
00397 enum fipa_protocol_e;
00398 
00399 EXPORTMC int MC_AclSetProtocol(
00400     struct fipa_acl_message_s* acl,
00401     enum fipa_protocol_e performative );
00402 
00403 EXPORTMC int MC_AclSetConversationID(
00404     struct fipa_acl_message_s* acl,
00405     char* id);
00406 
00407 EXPORTMC int MC_AclSetPerformative(
00408     struct fipa_acl_message_s* acl,
00409     enum fipa_performative_e performative );
00410 
00411 EXPORTMC int MC_AclSetSender(
00412     struct fipa_acl_message_s* acl,
00413     const char* name,
00414     const char* address );
00415   
00416 EXPORTMC int MC_AclAddReceiver(
00417     struct fipa_acl_message_s* acl,
00418     const char* name,
00419     const char* address );
00420 
00421 EXPORTMC int MC_AclAddReplyTo(
00422     struct fipa_acl_message_s* acl,
00423     const char* name,
00424     const char* address);
00425 
00426 EXPORTMC int MC_AclSetContent(
00427     struct fipa_acl_message_s* acl,
00428     const char* content );
00429 
00430 /* End ACL Helper Functions */
00431 
00432 
00441 EXPORTMC extern int MC_AddAgent( 
00442     MCAgency_t attr, 
00443     MCAgent_t agent);
00444 
00445 
00446 #ifndef _WIN32
00447 int MC_AddStationaryAgent(MCAgency_t agency, void* (*agent_thread)(struct agent_thread_arg_s*), const char* name, void* agent_args);
00448 #else
00449 int MC_AddStationaryAgent(MCAgency_t agency, LPTHREAD_START_ROUTINE agent_thread, const char* name, void* agent_args);
00450 #endif
00451 
00467 extern const void* 
00468 MC_AgentVariableRetrieve(
00469     MCAgent_t agent,
00470     const char* var_name,
00471     int task_num);
00472 
00487 int
00488 MC_AgentVariableRetrieveInfo(
00489     MCAgent_t agent,
00490     const char* var_name,
00491     int task_num,
00492     const void** data,
00493     int* dim,
00494     const int** extent
00495     );
00496 
00514 extern int 
00515 MC_AgentVariableSave(MCAgent_t agent, const char* var_name);
00516 
00526 EXPORTMC extern int MC_BarrierDelete(MCAgency_t attr, int id);
00527 
00543 EXPORTMC extern int MC_BarrierInit(MCAgency_t attr, int id, int num_procs);
00544 
00553 #ifdef OBS
00554 EXPORTMC extern int MC_ChInitializeOptions(MCAgency_t attr, ChOptions_t *options);
00555 #endif
00556 
00557 
00573 EXPORTMC int
00574 MC_CallAgentFunc(
00575     MCAgent_t agent,
00576     const char* funcName,
00577     void* returnVal,
00578     int numArgs,
00579     ...);
00580 
00597 EXPORTMC extern int MC_CallAgentFuncArg(
00598         MCAgent_t agent,
00599         const char* funcName,
00600         void* returnVal,
00601         void* arg
00602         );
00603 
00614 EXPORTMC extern int MC_CallAgentFuncV(
00615     MCAgent_t agent,
00616     const char* funcName,
00617     void* returnVal,
00618     va_list ap);
00619 
00620   /*
00621     \brief          Calls a function defined in an agent
00622     \param agent    A Mobile-C Agent
00623     \param funcName The name of the function to call
00624     \param returnVal (output) Return value from the agent function
00625     \param arglist  Ch Variable Argument list to pass in
00626    */
00627 EXPORTMC extern int MC_CallAgentFuncVar
00628 (
00629  MCAgent_t agent,
00630  const char* funcName,
00631  void* returnVal,
00632  ChVaList_t arglist
00633  );
00634                                          
00635 
00636 
00651 EXPORTMC extern MCAgent_t
00652 MC_ComposeAgent(
00653     const char* name,
00654     const char* home,
00655     const char* owner, 
00656     const char* code,
00657     const char* return_var_name,
00658     const char* server,
00659                 const char* workgroup_code,
00660     int persistent
00661     );
00662 
00678 EXPORTMC extern MCAgent_t
00679 MC_ComposeAgentFromFile(
00680     const char* name,
00681     const char* home,
00682     const char* owner, 
00683     const char* filename,
00684     const char* return_var_name,
00685     const char* server,
00686                 const char* workgroup_code,
00687     int persistent
00688     );
00689 
00700 EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);
00701 
00717 EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);
00718 
00729 EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);
00730 
00744 EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);
00745 
00755 int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);
00756 
00765 EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);
00766 
00778 EXPORTMC extern int MC_DeleteAgentWG(MCAgent_t calling_agent, MCAgent_t agent);
00779 
00790 EXPORTMC extern int MC_End(MCAgency_t attr);
00791 
00802 int MC_DestroyServiceSearchResult(
00803     char** agentName,
00804     char** serviceName,
00805     int* agentID,
00806     int numResult);
00807 
00808 
00819 EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);
00820 
00829 EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);
00830 
00839 EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);
00840 
00844 EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);
00845 
00846 /*
00847  * \brief           Retrieve an agent's name
00848  *
00849  * \return          a malloc'd character string on success, or NULL on failure
00850  */
00851 EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);
00852 
00858 EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);
00859 
00876 EXPORTMC extern int MC_GetAgentReturnData(
00877         MCAgent_t agent,
00878         int task_num,
00879         void **data,
00880         int *dim,
00881         int **extent);
00882 
00888 EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);
00889 
00895 EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);
00896 
00902 EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);
00903 
00911 EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);
00912 
00923 EXPORTMC extern MCAgency_t MC_Initialize(
00924         int port,
00925         MCAgencyOptions_t *options);
00926 
00939 EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);
00940 
00946  EXPORTMC extern int MC_MainLoop(MCAgency_t attr);
00947 
00956 EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);
00957 
00967 EXPORTMC extern int MC_MigrateAgent(MCAgent_t agent, const char* hostname, int port);
00968 
00983 EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 
00984 
00985 /*
00986  * \brief           Unlocks a MobileC synchronization variable
00987  *
00988  * \param attr      a MobileC agency handle
00989  * \param id        the synchronization variable id to unlock
00990  *
00991  * \return          0 on success, error_code_t type on failure
00992  *
00993  * \see             MC_MutexLock()
00994  */
00995 EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 
00996 
01014 EXPORTMC extern int MC_RegisterService(
01015         MCAgency_t agency,
01016         /* Optional input args: Must input 
01017          * MCAgent_t OR
01018          * agentID AND agentName */
01019         MCAgent_t agent,
01020         int agentID,
01021         const char *agentName,
01022         char **serviceNames,
01023         int numServices);
01024 
01032 EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);
01033 
01039 EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);
01040 
01052 EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);
01053 
01067 EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);
01068 
01080 EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);
01081 
01095 EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);
01096 
01105 EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);
01106 
01120 EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );
01121 
01130 EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);
01131 
01137 EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);
01138 
01144 EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);
01145 
01153 EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);
01154 
01170 EXPORTMC extern int MC_SearchForService(
01171         /* Input args */
01172         MCAgency_t attr, 
01173         const char *searchString,
01174         /* Return Args */
01175         char*** agentNames,
01176         char*** serviceNames,
01177         int** agentIDs,
01178         int* numResults);
01179 
01188 EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
01189         const char *message,
01190         const char *hostname,
01191         int port);
01192 
01201 EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
01202         const char *filename,
01203         const char *hostname,
01204         int port);
01205 
01214 EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);
01215 
01231 EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);
01232 
01241 EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);
01242 
01251 EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);
01252 
01268 EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);
01269 
01275 EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);
01276 
01277 
01278 EXPORTMC extern int 
01279 MC_TerminateAgentWG(MCAgent_t calling_agent, MCAgent_t agent);
01285 /* EXPORTMC extern int MC_Wait(MCAgency_t attr); */
01286 
01293 EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);
01294 
01303 EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);
01304 
01318 EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);
01319 
01320 #ifdef __cplusplus
01321 }
01322 #endif
01323 
01324 #endif /* _MOBILEC_H_ */
01325