path: root/vendor/voclient/include/sampDecl.h

/**
 *  SAMPDECL.H -- SAMP interface method declarations.
 *
 *  @brief      SAMP interface method declarations.
 *
 *  @file       sampDecl.h
 *  @author     Mike FItzpatrick
 *  @date       8/10/11
 */



typedef  XINT   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            */

#define  SZ_NAME             256        /** size of a file path 	    */
#define  SZ_LINE             256        /** size of a text line 	    */
#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  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  	    */


/**
 *  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	      msgMode;			/** (a)synch message mode	    */
    int	      handlerMode;		/** CBR / CBV for user handlers     */

    FILE     *logfd;			/** log file descriptor		    */
    int	      debug;			/** debug 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);
void 	  sampClose (handle_t handle);

void 	  samp_setSyncMode (handle_t handle);
void 	  samp_setASyncMode (handle_t handle);
void 	  samp_setNotifyMode (handle_t handle);
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);
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);


/*  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_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_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_bibcodeHandler (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_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_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, char *name);
char	 *samp_getMetadata (handle_t handle, char *name);