Mobile-C: /home/dko/Projects/mobilec/tags/MobileC-v1.10.10/src/include/libmc.h Source File

00001 /* SVN FILE INFO
00002  * $Revision: 446 $ : Last Committed Revision
00003  * $Date: 2010-03-16 15:12:24 -0700 (Tue, 16 Mar 2010) $ : 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 
00649 EXPORTMC extern MCAgent_t
00650 MC_ComposeAgent(
00651     const char* name,
00652     const char* home,
00653     const char* owner, 
00654     const char* code,
00655     const char* return_var_name,
00656     const char* server,
00657     int persistent
00658     );
00659 
00674 EXPORTMC extern MCAgent_t
00675 MC_ComposeAgentS(
00676     const char* name,
00677     const char* home,
00678     const char* owner, 
00679     const char* code,
00680     const char* return_var_name,
00681     const char* server,
00682                 const char* workgroup_code,
00683     int persistent
00684     );
00685 
00700 EXPORTMC extern MCAgent_t
00701 MC_ComposeAgentFromFile(
00702     const char* name,
00703     const char* home,
00704     const char* owner, 
00705     const char* filename,
00706     const char* return_var_name,
00707     const char* server,
00708     int persistent
00709     );
00710 
00726 EXPORTMC extern MCAgent_t
00727 MC_ComposeAgentFromFileS(
00728     const char* name,
00729     const char* home,
00730     const char* owner, 
00731     const char* filename,
00732     const char* return_var_name,
00733     const char* server,
00734                 const char* workgroup_code,
00735     int persistent
00736     );
00737 
00748 EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);
00749 
00765 EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);
00766 
00777 EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);
00778 
00792 EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);
00793 
00803 int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);
00804 
00813 EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);
00814 
00826 EXPORTMC extern int MC_DeleteAgentWG(MCAgent_t calling_agent, MCAgent_t agent);
00827 
00838 EXPORTMC extern int MC_End(MCAgency_t attr);
00839 
00850 int MC_DestroyServiceSearchResult(
00851     char** agentName,
00852     char** serviceName,
00853     int* agentID,
00854     int numResult);
00855 
00856 
00867 EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);
00868 
00877 EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);
00878 
00887 EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);
00888 
00892 EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);
00893 
00894 /*
00895  * \brief           Retrieve an agent's name
00896  *
00897  * \return          a malloc'd character string on success, or NULL on failure
00898  */
00899 EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);
00900 
00906 EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);
00907 
00924 EXPORTMC extern int MC_GetAgentReturnData(
00925         MCAgent_t agent,
00926         int task_num,
00927         void **data,
00928         int *dim,
00929         int **extent);
00930 
00936 EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);
00937 
00943 EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);
00944 
00950 EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);
00951 
00959 EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);
00960 
00971 EXPORTMC extern MCAgency_t MC_Initialize(
00972         int port,
00973         MCAgencyOptions_t *options);
00974 
00987 EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);
00988 
00994  EXPORTMC extern int MC_MainLoop(MCAgency_t attr);
00995 
01004 EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);
01005 
01015 EXPORTMC extern int MC_MigrateAgent(MCAgent_t agent, const char* hostname, int port);
01016 
01031 EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 
01032 
01033 /*
01034  * \brief           Unlocks a MobileC synchronization variable
01035  *
01036  * \param attr      a MobileC agency handle
01037  * \param id        the synchronization variable id to unlock
01038  *
01039  * \return          0 on success, error_code_t type on failure
01040  *
01041  * \see             MC_MutexLock()
01042  */
01043 EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 
01044 
01062 EXPORTMC extern int MC_RegisterService(
01063         MCAgency_t agency,
01064         /* Optional input args: Must input 
01065          * MCAgent_t OR
01066          * agentID AND agentName */
01067         MCAgent_t agent,
01068         int agentID,
01069         const char *agentName,
01070         char **serviceNames,
01071         int numServices);
01072 
01080 EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);
01081 
01087 EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);
01088 
01100 EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);
01101 
01115 EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);
01116 
01128 EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);
01129 
01143 EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);
01144 
01153 EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);
01154 
01168 EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );
01169 
01178 EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);
01179 
01185 EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);
01186 
01192 EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);
01193 
01201 EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);
01202 
01218 EXPORTMC extern int MC_SearchForService(
01219         /* Input args */
01220         MCAgency_t attr, 
01221         const char *searchString,
01222         /* Return Args */
01223         char*** agentNames,
01224         char*** serviceNames,
01225         int** agentIDs,
01226         int* numResults);
01227 
01236 EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
01237         const char *message,
01238         const char *hostname,
01239         int port);
01240 
01249 EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
01250         const char *filename,
01251         const char *hostname,
01252         int port);
01253 
01262 EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);
01263 
01279 EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);
01280 
01289 EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);
01290 
01299 EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);
01300 
01316 EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);
01317 
01323 EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);
01324 
01325 
01326 EXPORTMC extern int 
01327 MC_TerminateAgentWG(MCAgent_t calling_agent, MCAgent_t agent);
01333 /* EXPORTMC extern int MC_Wait(MCAgency_t attr); */
01334 
01341 EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);
01342 
01351 EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);
01352 
01366 EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);
01367 
01368 #ifdef __cplusplus
01369 }
01370 #endif
01371 
01372 #endif /* _MOBILEC_H_ */
01373