/** * SAMP.H -- SAMP interface include file. * * @brief SAMP interface include file. * * @file samp.h * @author Mike FItzpatrick * @date 7/10/09 */ #include /* XMLRPC-C interface */ #include #include #include #include /* for struct stat */ #include #include #include "xrpc.h" /* XRPC Wrapper Definitions */ #ifndef SZ_NAME #define SZ_NAME 256 /** size of a file path */ #endif #ifndef SZ_LINE #define SZ_LINE 256 /** size of a text line */ #endif #define SZ_SECRET 64 /** size of secret string */ #define SZ_DESC 8192 /** len of a description */ #define SZ_URL 1024 /** len of a URL */ #define SZ_CMD 1024 /** len of a command */ #define SZ_SBUF 65536 /** big string buffer */ #define SZ_RESSTR 1024 /** len of result string */ #define DEF_PORT 9876 /** server port */ #define DEF_TIMEOUT "15" /** sync message timeout */ #define MAX_SAMPS 16 /** max clients allowed */ #define MAX_HUBS 16 /** max hubs allowed */ #define MAX_MDATTRS 32 /** max metadata attrs */ #define MAX_SUBS 256 /** max subscriptions allowed */ #define MAX_CLIENTS 32 /** max number of clients */ #define MAX_ROWS 256 /** max rows to highlight */ #define SAMP_ERR -1 /** error return */ #define SAMP_PENDING 0 /** pending operation */ #define SAMP_OK 1 /** ok return */ #define SAMP_CBR 0 /** use call-by-reference */ #define SAMP_CBV 1 /** use call-by-value */ #define SAMP_SYNCH 0 /** synchronous pattern */ #define SAMP_ASYNCH 1 /** asynchronous pattern */ #define SAMP_NOTIFY 2 /** notification pattern */ #define SAMP_INT TY_INT /* values from xrpcP.h */ #define SAMP_DOUBLE TY_DOUBLE #define SAMP_BOOL TY_BOOL #define SAMP_STRING TY_STRING #define SAMP_DATETIME TY_DATETIME #define SAMP_SAMPRUCT TY_STRUCT #define SAMP_ARRAY TY_ARRAY #define SAMP_TRACE 0 /** debug trace */ /** * Special Hub events */ #define HUB_SHUTDOWN 0 /** Hub is shutting down */ #define HUB_REGISTER 1 /** An app has registered */ #define HUB_UNREGISTER 2 /** An app has unregistered */ #define HUB_SUBSCRIPTIONS 3 /** An app declared subscritions */ #define HUB_METADATA 4 /** An app declared metadata */ #define HUB_DISCONNECT 5 /** An app is forcibly disconnected */ #define LEN_DESC 32768 /** max len of description */ #ifdef min #undef min #endif #ifdef max #undef max #endif #define min(a,b) (ab?a:b) typedef long handle_t; /** generic object handle */ typedef int Map; /** SAMP Map datatype */ typedef int List; /** SAMP List datatype */ typedef int Msg; /** SAMP Msg datatype */ typedef int Param; /** SAMP Param datatype */ typedef char *String; /** SAMP String datatype */ /** * Application (and Hub) metadata. */ typedef struct { char name[SZ_LINE]; /** name */ char desc[SZ_DESC]; /** descriptive text */ char iconURL[SZ_URL]; /** icon URL */ char docURL[SZ_URL]; /** documentation URL */ char *descHTML; /** descriptive text (HTML) */ int nkeys; /** number of meta keys */ char *aKey[MAX_MDATTRS]; /** attr keyword */ char *aVal[MAX_MDATTRS]; /** attr value */ } appMD, *appMDP; /** * Message subscription. */ typedef struct { char mtype[SZ_LINE]; /** mtype string */ int (*userFunc)(void *p); /** user handler function */ /** samp handler function */ int (*sampFunc)(char *sid, char *sender, char *msgid, Map map); } Subs, *SubsP; /** * Registered Client name mappings. */ typedef struct { char pubId[SZ_NAME]; /** public name */ char name[SZ_NAME]; /** app name */ } Client, *ClientP; /** * Hub description. Our application connects to this hub by default, but * the structure will be valid for any Hub. */ typedef struct { char appName[SZ_LINE]; /** application name */ char appVer[SZ_LINE]; /** application version */ char description[SZ_LINE]; /** descriptive text */ appMD meta; /** metadata */ char secret[SZ_SECRET]; /** registration string */ char url[SZ_URL]; /** Hub service endpoint */ char version[SZ_NAME]; /** Hub version string */ int id; /** Hub XML-RPC connection */ char appId[SZ_NAME]; /** client key */ char privateKey[SZ_LINE]; /** client key value */ char hubId[SZ_LINE]; /** Hub id value */ char selfId[SZ_LINE]; /** Client id value */ char timeout[SZ_NAME]; /** Sync msg timeout (str) */ void *samp; /** back pointer */ } Hub, *HubP; /** * SAMP application description. By default this describes our app by * may be used to store information about other apps in the network as * well. */ typedef struct { char appName[SZ_NAME]; /** application name */ char appVer[SZ_LINE]; /** application version */ char description[SZ_NAME]; /** application description */ char errortxt[SZ_LINE]; /** last msh error string */ appMD meta; /** metadata */ pthread_t svrThread; /** server thread number */ /** default user handler */ int (*defaultUserFunc)(char *sender, char *msgid, Map map); Subs subs[MAX_SUBS]; /** message subscriptions */ int nsubs; /** number of subscriptions */ Client clients[MAX_CLIENTS]; /** samp clients */ int nclients; /** number of samp clients */ int serverTid; /** samp server threadId */ int serverPort; /** samp server port */ Hub *hub; /** Hub connection */ handle_t hubHandle; /** Hub handle alias */ int hubThreadID; /** Hub thread id */ int active; /** is interface active */ int mapClients; /** map other clients */ int msgMode; /** (a)synch message mode */ int handlerMode; /** CBR / CBV for user handlers */ FILE *logfd; /** log file descriptor */ int debug; /** debug flag */ int verbose; /** verbose flag */ int trace; /** trace flag */ } Samp, *SampP; #define MSG_SYNC 0 #define MSG_ASYNC 1 #define MSG_NOTIFY 2 #define DEF_CALLMODE MSG_ASYNC /** * Prototype declarations. */ /****************************************************************************** ** Public Interface Methods *****************************************************************************/ /* samp.c -- Methods called by user apps to initialize the interface. */ handle_t sampInit (String appName, String description); void samp_Metadata (handle_t handle, String field, String value); void samp_Subscribe (handle_t handle, String mtype, void *func); void samp_Unsubscribe (handle_t handle, String mtype); int sampStartup (handle_t handle); int sampShutdown (handle_t handle); int sampDebug (handle_t handle, int value); int sampVerbose (handle_t handle, int value); void sampClose (handle_t handle); int samp_hubActive (handle_t handle); int samp_setOpt (handle_t handle, char *opt, int value); void samp_setSyncMode (handle_t handle); void samp_setASyncMode (handle_t handle); void samp_setNotifyMode (handle_t handle); void samp_setMsgMode (handle_t handle, int mode); void samp_setCallByRef (handle_t handle); void samp_setCallMode (handle_t handle, int mode); void samp_setReplyCallback (handle_t handle, int *func); void samp_setResponseCallback (handle_t handle, int *func); void samp_setTimeout (handle_t handle, int timeout); void samp_setAppName (handle_t handle, String name); void samp_setAppVersion (handle_t handle, String version); void samp_defaultReplyHandler (handle_t handle); void samp_deaultfResponseHandler (handle_t handle); int samp_replyStatus (handle_t handle); int samp_mapClients (handle_t handle); int samp_listClients (handle_t handle); char *samp_getClients (handle_t handle); int samp_addClient (handle_t handle, String name, String id); int samp_removeClient (handle_t handle, String id); Map samp_getOKMap (void); Map samp_getNullMap (void); /* sampCommands.c -- Methods called to send messages to the Hub. */ int samp_Register (handle_t handle); int samp_UnRegister (handle_t handle); int samp_DeclareMetadata (handle_t handle); int samp_Ping (handle_t handle, String appName); Map samp_GetMetadata (handle_t handle, String pubId); int samp_DeclareSubscriptions (handle_t handle); Map samp_GetSubscriptions (handle_t handle, String pubId); List samp_GetRegisteredClients (handle_t handle); List samp_GetSubscribedClients (handle_t handle, String mtype); /* sampMType.c -- Methods called to send messages to other apps. */ int samp_tableLoadVOTable (handle_t handle, String recip, String url, String tableId, String name); int samp_tableLoadFITS (handle_t handle, String recip, String url, String tableId, String name); int samp_imageLoadFITS (handle_t handle, String recip, String url, String imageId, String name); int samp_tableHighlightRow (handle_t handle, String recip, String tableId, String url, int row); int samp_tableSelectRowList (handle_t handle, String recip, String tableId, String url, int rows[], int nrows); int samp_coordPointAtSky (handle_t handle, String recip, float ra, float dec); int samp_specLoadSSAGeneric (handle_t handle, String recip, String url, Map meta, String spectrumId, String name); int samp_cmdExec (handle_t handle, String recip, String cmd); char *samp_envGet (handle_t handle, String recip, String name); int samp_envSet (handle_t handle, String recip, String name, String value); char *samp_paramGet (handle_t handle, String recip, String name); int samp_paramSet(handle_t handle, String recip, String name, String value); int samp_bibLoad (handle_t handle, String recip, String bibcode); int samp_resourceLoad (handle_t handle, String recip, String type, String name, Map resMap); int samp_sendGeneric (handle_t handle, String recip, String mtype, String args[]); int samp_sendMsg (handle_t handle, String recip, Map msg); /* sampClient.c -- Low-level methods to send messages. */ void samp_notify (handle_t handle, String recipId, Map msg); List samp_notifyAll (handle_t handle, Map msg); String samp_call (handle_t handle, String recipId, String tag, Map msg); int samp_callAll (handle_t handle, String msg_tag, Map msg); int samp_callAndWait (handle_t handle, String recipId, String msg_tag, Map msg); int samp_Reply (handle_t handle, String msg_id, Map resp); String samp_clientName (handle_t handle, String pubId); int samp_setErr (handle_t handle, Map resp); String samp_getErr (handle_t handle); /* sampMethods.c -- SAMP methods implemented by a callable client. */ int samp_receiveCall (void *data); int samp_receiveNotification (void *data); int samp_receiveResponse (void *data); void samp_setHandlerReply (Map resp); Map samp_getHandlerReply (void); /* sampHandlers.c -- Handlers to responses from the message. */ void samp_setUserHandler (handle_t handle, String mtype, void *func); void samp_setSampHandler (handle_t handle, String mtype, void *func); void *samp_getUserHandler (String mtype); void *samp_getSampHandler (String mtype); void samp_execUserHandler (String mtype, String sender, String msg_id, Map params); int samp_genericMsgHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_PingHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_StatusHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_imLoadHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_tbLoadHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_tbLoadFITSHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_tbLoadVOTHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_tbHighlightHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_tbSelectHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_pointAtHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_specLoadHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_specSSAHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_cmdExecHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_envGetHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_envSetHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_paramGetHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_paramSetHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_bibcodeHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resLoadHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resConeHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resSiapHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resSsapHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resTapHandler (String sender, String mtype, String msg_id, Map msg_map); int samp_resVOSpaceHandler (String sender, String mtype, String msg_id, Map msg_map); void samp_printMessage (String mtype, String sender, String msg_id, Map params); void samp_printMap (String name, Map map); int samp_nullResponse (void *data); int samp_testEcho (void *data); /****************************************************************************** ** Internal Interface Methods *****************************************************************************/ /* sampHub.c */ handle_t samp_hubOpen (Samp *samp); int samp_hubClose (handle_t handle); List samp_getAvailableHubs (handle_t handle); char *samp_getActiveHubName (handle_t handle); int samp_getActiveHub (handle_t handle); int samp_hubRunning (void); int samp_hubInit (handle_t samp, char *appName, char *descr); int samp_processHubEvent (String mtype, Map params); int samp_hubEvent (String mtype); int samp_hubRegister (Hub *hub); int samp_hubUnRegister (Hub *hub); int samp_hubSendShutdown (Hub *hub); int samp_hubSetXmlrpcCallback (Hub *hub); int samp_hubPing (Hub *hub); int samp_hubDeclareMetadata (Hub *hub); int samp_hubDeclareSubscriptions (Hub *hub); /* sampList.c */ handle_t samp_newList (); void samp_freeList (List list); int samp_listLen (List list); void samp_setStringInList (List list, char *value); void samp_setMapInList (List list, Map map); void samp_setListInList (List list1, List list2); void samp_setIntInList (List list, int value); void samp_setFloatInList (List list, float value); char *samp_getStringFromList (List list, int index); Map samp_getMapFromList (List list, int index); List samp_getListFromList (List list, int index); int samp_getIntFromList (List list, int index); float samp_getFloatFromList (List list, int index); /* sampMap.c */ handle_t samp_newMap (void); void samp_freeMap (Map map); int samp_getMapSize (Map map); char *samp_getMapKey (Map map, int index); char *samp_getMapVal (Map map, int index); void samp_setStringInMap (Map map, char *key, char *value); void samp_setMapInMap (Map map1, char *key, Map map2); void samp_setListInMap (Map map, char *key, List list); void samp_setIntInMap (Map map, char *key, int value); void samp_setFloatInMap (Map map, char *key, float value); char *samp_getStringFromMap (Map map, char *key); Map samp_getMapFromMap (Map map, char *key); List samp_getListFromMap (Map map, char *key); int samp_getIntFromMap (Map map, char *key); float samp_getFloatFromMap (Map map, char *key); /* sampMsg.c */ Msg samp_newMsg (void); void samp_freeMsg (Msg msg); void samp_msgMType (Msg msg, String mtype); void samp_msgParam (Msg msg, Param param); char *samp_msgTag (void); /* sampParam.c */ Param samp_newParam (void); void samp_freeParam (Param param); Param samp_paramInit (Msg msg); void samp_addStringParam (Msg msg, char *keyw, String val); void samp_addMapParam (Msg msg, char *keyw, Map val); void samp_addListParam (Msg msg, char *keyw, List val); void samp_addIntParam (Msg msg, char *keyw, int val); void samp_addFloatParam (Msg msg, char *keyw, float val); int samp_paramLen (Msg msg); /* sampLog.c */ void sampLog (handle_t handle, char *format, ...); void sampTrace (handle_t handle, char *format, ...); /* sampUtil.c */ handle_t samp_newHandle (void *ptr); void samp_freeHandle (handle_t handle); handle_t samp_P2H (void *ptr); void *samp_H2P (handle_t handle); char *samp_app2id (handle_t handle, char *appName); char *samp_id2app (handle_t handle, char *pubId); int samp_serverPort (void); void samp_printMetadata (handle_t handle, String name); char *samp_getMetadata (handle_t handle, String name);