[Hamlib-developer] RFC: API changes

[Stephane F. <f4...@fr...>]

Hi there,

Adding new backends is an important task, but more important is 
the completion of the API specification. Actually, I'm ready
to add definition for ~40 Icom rigs, but maintenance in this
condition is a pain when a new field appears in the caps.
So let's do it. Here's a non-exhaustive list of modification
I'd like to see happening. Let me know what you think about it.


(1) Preamp & Attenuator ability:

    Goal: Describe what preamp and att levels are available. This is not
	  mandatory for rig control, but rather useful for a GUI.
    Mod: add the following in caps:

	#define MAXDBLSTSIZ 8

	char preamp[MAXDBLSTSIZ];		/* in db, 0 terminated */
	char attenuator[MAXDBLSTSIZ];		/* in db, 0 terminated */

    and for example, a backend having 6db, 10db and 20db support
    would initialize this way:

	.... { 6, 10, 20, 0, }, ....

(2) Announce and Antenna may not be set with rig_set_level.
    I propose to create rig_set_ann/rig_get_ann and rig_set_ant/rig_get_ant,
    which would be less confusing.

(3) VFO resolution
    Goal: tell the resolution of set_freq. Most rigs have 10Hz, some
    can do 1Hz. Question: does it depend on mode?
    Mod: add the following field in caps:

	shortfreq_t resolution;		/* in Hz */

(4) has_func, has_set_func
    Goal: as for has_level/has_set_level, add a new field has_set_func
	  to tell what function is controlable.
	  Question: would has_get_func/has_set_func be better ?
    Mod: add the following field in caps:

	setting_t has_set_func;

(5) Bank setting
    Goal: add a few new API calls to handle memory banks
    Mod: add new API calls plus their counterparts in the caps struct.
	 Question: what should be the type of bank_t ? Is it always
	 a number? We will need also a bank_qty field to tell how many
	 banks are availables.

	rig_get_bank(RIG *rig, vfo_t vfo, bank_t *bank);
	rig_set_bank_name(RIG *rig, vfo_t vfo, bank_t bank, const char *name);
	rig_get_bank_name(RIG *rig, vfo_t vfo, bank_t bank, char *name);

(6) Frequency ranges and ITU regions
    Goal: do you remember my mail on different ITU region support 
	  pertaining to the rx_range_list and esp. the tx_range_list fields?
	  Let's have an example. In ITU region 1 (eg. Europe), the 2m band
	  is 144MHz to 146MHz, whereas in region 2, this is 144MHz to 148MHz.
	  Given a rig model, manufacturers would sell 2 different versions
	  in these regions. That's why I propose to add in the caps
	  the frequency ranges for all ITU regions.
    Mod: I can see 2 solutions:

	/* first solution: */
	  freq_range_t rx_range_list1[FRQRANGESIZ];	/* region 1 */
  	  freq_range_t tx_range_list1[FRQRANGESIZ];
	  freq_range_t rx_range_list2[FRQRANGESIZ];	/* region 2 */
  	  freq_range_t tx_range_list2[FRQRANGESIZ];

	/* second solution: */
	  freq_range_t rx_range_list[FRQRANGESIZ][2];	/* 0->region 1, */
  	  freq_range_t tx_range_list[FRQRANGESIZ][2];	/* 1->region 2  */

	and add a 'itu_region' field in rig_state. Actualy, we should
	add frequency ranges in rig_state too, since one might want to
	override the defaults (eg. a modified rig).
	Ideas? Comments?

(x) Scanning
	We still haven't specified something for scan support.
	I'll try to come up with a proposal soon. Any ideas/requirements
	on the subject?


Feedback more than welcome!

Cheers,
-- 
Stephane / F4CFE