Hamlib/common/API_Candidates

#	$Id: API_Candidates,v 1.3 2000-09-16 17:58:07 javabear Exp $	



Updated API notes -- FS 


previously, on this channel.....
> 
> > > cmd_set_freq(RIG *rig,freq_t freq, rig_mode_t mode, vfo_t vfo )
> > > long int cmd_get_freq_mode_status(RIG *rig, unsigned char *mode, vfo_t
> > > vfo);
> > >
> >   Looks definitely better this way!
> >   Just a question: what if the application just wants to change
> >   the mode only? It might be troublesome in certain case to have
> >   to remember the current frequency or having to query it.
> 
> true, I guess we have some options...
> 
> API provides
> cmd_set_freq_(RIG *rig,freq_t freq, rig_mode_t mode, vfo_t vfo )
> 
> and possibly
> cmd_set_mode(RIG *rig, rig_mode_t mode)
> cmd_set_vfo(RIG *rig, vfo_t vfo)


I must have had too many beers during the Olympic opening
ceremony :-)


Actually now that I think about it, the cleanest approach
is probably for the frontend API to provide as a minimum functions
like 

cmd_set_mode(RIG *rig, rig_mode_t mode)
cmd_set_vfo(RIG *rig, vfo_t vfo)
cmd_set_freq_(RIG *rig, freq_t freq)
cmd_set_filter_(RIG *rig, filter_t filter)

and in general
cmd_set_xxx_(RIG *rig, xxx_t xxx)

and that optional  convenience functions like 

cmd_set_channel_(RIG *rig,freq_t freq, rig_mode_t mode, vfo_t vfo
....,,,, filter_t filter..)

is some frontend convenience function that backend libs can handle
either directly as is toward the rig if the rig can handle it that way, 
or the backend lib breaks it into the simpler functions shown above if 
the rig needs it that way. We dont care up the front how its done
int the back of course (apart from efficiency issues of course)!


So, 1 frontend convenience functions may cause multiple backend
calls to the rig as it iterates through the convenience functions
argumant list and  calls individual "primitives" towards the rig.


Should be no state issues to deal with..

just trying to avoid long function names like
cmd_set_freq_mode_vfo_filter_power_this_that_whatever(....)

/FS





/*
 *  
 * API Notes -- FS
 *
 */


I think it is more intuitive  to code things as follows...

backend must implement all opcodes (of course)
this may infer function names like thus (at least according
to yaesu docs not passing vfo as a parameter  - aaarrrgh).


eg 6 functions in backend ..

int cmd_set_freq_main_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);
int cmd_set_freq_sat_rx_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);
int cmd_set_freq_sat_tx_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);

long int cmd_get_freq_mode_status_main_vfo(RIG *rig, unsigned char *mode);
long int cmd_get_freq_mode_status_sat_rx_vfo(RIG *rig, unsigned char *mode);
long int cmd_get_freq_mode_status_sat_tx_vfo(RIG *rig, unsigned char *mode);

This creates a large function namespace, this is ok as there
shall be wrappers for them up front anyway. Also, bakend must test
all opcodes anyway.

However, frontend should have reduced namespace for function calls.

eg result, 2 functions up front ....

cmd_set_freq(RIG *rig,freq_t freq, rig_mode_t mode, vfo_t vfo )
long int cmd_get_freq_mode_status(RIG *rig, unsigned char *mode, vfo_t vfo);

ie: 3 to 1 reduction, and an emphasis on what parameters
you are setting on the rig, driven more by the parameter
list, than extending function names.

so, lets create some enums

enum rig_vfo_e {
	RIG_VFO_MAIN = 0,
	RIG_VFO_RX,
	RIG_VFO_TX,
	RIG_VFO_SUB,

	/* etc */

}

typedef enum rig_vfo_e rig_vfo_t;

enum rig_rptr_shift_e {
	RIG_RPT_SHIFT_NONE = 0,
	RIG_RPT_SHIFT_MINUS,
	RIG_RPT_SHIFT_PLUS,
	/* etc */

}

typedef enum rig_rptr_shift_e rig_rptr_shift_t;




#include <rigcaps.h>

/* These are all potential candidates that can go into the API,
 * after some cleanup, like type standardization, etc..
 */

void cmd_set_ptt_on(RIG *rig);
void cmd_set_ptt_off(RIG *rig);

void cmd_set_freq_main_vfo(RIG *rig, unsigned char d1,  unsigned char d2,
			   unsigned char d3, unsigned char d4);

void cmd_set_freq_sat_rx_vfo(RIG *rig, unsigned char d1,  unsigned char d2,
			   unsigned char d3, unsigned char d4);

void cmd_set_freq_sat_tx_vfo(RIG *rig, unsigned char d1,  unsigned char d2,
			   unsigned char d3, unsigned char d4);

void cmd_set_opmode_main_vfo(RIG *rig, unsigned char d1);
void cmd_set_opmode_sat_rx_vfo(RIG *rig, unsigned char d1);
void cmd_set_opmode_sat_tx_vfo(RIG *rig, unsigned char d1);

void cmd_set_ctcss_dcs_main_vfo(RIG *rig, unsigned char d1);
void cmd_set_ctcss_dcs_sat_rx_vfo(RIG *rig, unsigned char d1);
void cmd_set_ctcss_dcs_sat_tx_vfo(RIG *rig, unsigned char d1);

void cmd_set_ctcss_freq_main_vfo(RIG *rig, unsigned char d1);
void cmd_set_ctcss_freq_sat_rx_vfo(RIG *rig, unsigned char d1);
void cmd_set_ctcss_freq_sat_tx_vfo(RIG *rig, unsigned char d1);

void cmd_set_dcs_code_main_vfo(RIG *rig, unsigned char d1, unsigned char d2);
void cmd_set_dcs_code_sat_rx_vfo(RIG *rig, unsigned char d1, unsigned char d2);
void cmd_set_dcs_code_sat_tx_vfo(RIG *rig, unsigned char d1, unsigned char d2);

void cmd_set_repeater_shift_minus(RIG *rig);
void cmd_set_repeater_shift_plus(RIG *rig);
void cmd_set_repeater_shift_simplex(RIG *rig);

void cmd_set_repeater_offset(RIG *rig, unsigned char d1,  unsigned char d2,
			   unsigned char d3, unsigned char d4);

unsigned char cmd_get_rx_status(RIG *rig);
unsigned char cmd_get_tx_status(RIG *rig);

/*
 * Get frequency and mode info
 *
 */

long int cmd_get_freq_mode_status_main_vfo(RIG *rig, unsigned char *mode);
long int cmd_get_freq_mode_status_sat_rx_vfo(RIG *rig, unsigned char *mode);
long int cmd_get_freq_mode_status_sat_tx_vfo(RIG *rig, unsigned char *mode);


/*
 * Set frequency in Hz and mode
 *
 */

void cmd_set_freq_main_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);
void cmd_set_freq_sat_rx_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);
void cmd_set_freq_sat_tx_vfo_hz(RIG *rig,freq_t freq, rig_mode_t mode);


/*
 * Set Repeater offset in Hz.
 *
 */

void cmd_set_repeater_offset_hz(RIG *rig,freq_t freq);