Rig (transceiver) API

Files

file  conf.c
 

Rig configuration interface.


file  event.c
 

Event handling.


file  ext.c
 

Extension request parameter interface.


file  mem.c
 

Memory and channel interface.


file  rig.c
 

Ham Radio Control Libraries interface.


file  settings.c
 

func/level/parm interface


file  tones.c
 

CTCSS and DCS interface and tables.


Functions

int rig_token_foreach (RIG *rig, int(*cfunc)(const struct confparams *, char *), char *data)
 call a function against each configuration token of a rig
struct confparams * rig_confparam_lookup (RIG *rig, const char *name)
 lookup a confparam struct
token_t rig_token_lookup (RIG *rig, const char *name)
 lookup a token id
int rig_set_conf (RIG *rig, token_t token, const char *val)
 set a radio configuration parameter
int rig_get_conf (RIG *rig, token_t token, char *val)
 get the value of a configuration parameter
int rig_set_freq_callback (RIG *rig, freq_cb_t cb, char *arg)
 set the callback for freq events
int rig_set_mode_callback (RIG *rig, mode_cb_t cb, char *arg)
 set the callback for mode events
int rig_set_vfo_callback (RIG *rig, vfo_cb_t cb, char *arg)
 set the callback for vfo events
int rig_set_ptt_callback (RIG *rig, ptt_cb_t cb, char *arg)
 set the callback for ptt events
int rig_set_dcd_callback (RIG *rig, dcd_cb_t cb, char *arg)
 set the callback for dcd events
int rig_set_pltune_callback (RIG *rig, pltune_cb_t cb, char *arg)
 set the callback for pipelined tuning module
int rig_set_trn (RIG *rig, int trn)
 control the transceive mode
int rig_get_trn (RIG *rig, int *trn)
 get the current transceive mode
int rig_ext_level_foreach (RIG *rig, int(*cfunc)(RIG *, const struct confparams *, char *), char *data)
 Executes cfunc on all the elements stored in the extlevels table The callback cfunc is called until it returns a value which is not strictly positive. A zero value means a normal end of iteration, and a negative value an abnormal end, which will be the return value of rig_ext_level_foreach.
int rig_ext_parm_foreach (RIG *rig, int(*cfunc)(RIG *, const struct confparams *, char *), char *data)
 Executes cfunc on all the elements stored in the extparms table The callback cfunc is called until it returns a value which is not strictly positive. A zero value means a normal end of iteration, and a negative value an abnormal end, which will be the return value of rig_ext_parm_foreach.
struct confparams * rig_ext_lookup (RIG *rig, const char *name)
 lookup ext token by its name, return pointer to confparams struct.
struct confparams * rig_ext_lookup_tok (RIG *rig, token_t token)
 lookup ext token, return pointer to confparams struct.
token_t rig_ext_token_lookup (RIG *rig, const char *name)
 Simple lookup returning token id assicated with name.
int rig_set_mem (RIG *rig, vfo_t vfo, int ch)
 set the current memory channel number
int rig_get_mem (RIG *rig, vfo_t vfo, int *ch)
 get the current memory channel number
int rig_set_bank (RIG *rig, vfo_t vfo, int bank)
 set the current memory bank
int rig_set_channel (RIG *rig, const channel_t *chan)
 set channel data
int rig_get_channel (RIG *rig, channel_t *chan)
 get channel data
int rig_set_chan_all_cb (RIG *rig, chan_cb_t chan_cb, char *arg)
 set all channel data, by callback
int rig_get_chan_all_cb (RIG *rig, chan_cb_t chan_cb, char *arg)
 get all channel data, by callback
int rig_set_chan_all (RIG *rig, const channel_t chans[])
 set all channel data
int rig_get_chan_all (RIG *rig, channel_t chans[])
 get all channel data
int rig_set_mem_all_cb (RIG *rig, chan_cb_t chan_cb, confval_cb_t parm_cb, char *arg)
 set all channel and non-channel data by call-back
int rig_get_mem_all_cb (RIG *rig, chan_cb_t chan_cb, confval_cb_t parm_cb, char *arg)
 get all channel and non-channel data by call-back
int rig_set_mem_all (RIG *rig, const channel_t chans[], const struct confparams cfgps[], const value_t vals[])
 set all channel and non-channel data
int rig_get_mem_all (RIG *rig, channel_t chans[], const struct confparams cfgps[], value_t vals[])
 get all channel and non-channel data
const chan_t * rig_lookup_mem_caps (RIG *rig, int ch)
 lookup the memory type and capabilities
int rig_mem_count (RIG *rig)
 get memory channel count
const char * rigerror (int errnum)
 get string describing the error code
RIG * rig_init (rig_model_t rig_model)
 allocate a new RIG handle
int rig_open (RIG *rig)
 open the communication to the rig
int rig_close (RIG *rig)
 close the communication to the rig
int rig_cleanup (RIG *rig)
 release a rig handle and free associated memory
int rig_set_freq (RIG *rig, vfo_t vfo, freq_t freq)
 set the frequency of the target VFO
int rig_get_freq (RIG *rig, vfo_t vfo, freq_t *freq)
 get the frequency of the target VFO
int rig_set_mode (RIG *rig, vfo_t vfo, rmode_t mode, pbwidth_t width)
 set the mode of the target VFO
int rig_get_mode (RIG *rig, vfo_t vfo, rmode_t *mode, pbwidth_t *width)
 get the mode of the target VFO
pbwidth_t rig_passband_normal (RIG *rig, rmode_t mode)
 get the normal passband of a mode
pbwidth_t rig_passband_narrow (RIG *rig, rmode_t mode)
 get the narrow passband of a mode
pbwidth_t rig_passband_wide (RIG *rig, rmode_t mode)
 get the wide passband of a mode
int rig_set_vfo (RIG *rig, vfo_t vfo)
 set the current VFO
int rig_get_vfo (RIG *rig, vfo_t *vfo)
 get the current VFO
int rig_set_ptt (RIG *rig, vfo_t vfo, ptt_t ptt)
 set PTT on/off
int rig_get_ptt (RIG *rig, vfo_t vfo, ptt_t *ptt)
 get the status of the PTT
int rig_get_dcd (RIG *rig, vfo_t vfo, dcd_t *dcd)
 get the status of the DCD
int rig_set_rptr_shift (RIG *rig, vfo_t vfo, rptr_shift_t rptr_shift)
 set the repeater shift
int rig_get_rptr_shift (RIG *rig, vfo_t vfo, rptr_shift_t *rptr_shift)
 get the current repeater shift
int rig_set_rptr_offs (RIG *rig, vfo_t vfo, shortfreq_t rptr_offs)
 set the repeater offset
int rig_get_rptr_offs (RIG *rig, vfo_t vfo, shortfreq_t *rptr_offs)
 get the current repeater offset
int rig_set_split_freq (RIG *rig, vfo_t vfo, freq_t tx_freq)
 set the split frequencies
int rig_get_split_freq (RIG *rig, vfo_t vfo, freq_t *tx_freq)
 get the current split frequencies
int rig_set_split_mode (RIG *rig, vfo_t vfo, rmode_t tx_mode, pbwidth_t tx_width)
 set the split modes
int rig_get_split_mode (RIG *rig, vfo_t vfo, rmode_t *tx_mode, pbwidth_t *tx_width)
 get the current split modes
int rig_set_split_vfo (RIG *rig, vfo_t vfo, split_t split, vfo_t tx_vfo)
 set the split mode
int rig_get_split_vfo (RIG *rig, vfo_t vfo, split_t *split, vfo_t *tx_vfo)
 get the current split mode
int rig_set_rit (RIG *rig, vfo_t vfo, shortfreq_t rit)
 set the RIT
int rig_get_rit (RIG *rig, vfo_t vfo, shortfreq_t *rit)
 get the current RIT offset
int rig_set_xit (RIG *rig, vfo_t vfo, shortfreq_t xit)
 set the XIT
int rig_get_xit (RIG *rig, vfo_t vfo, shortfreq_t *xit)
 get the current XIT offset
int rig_set_ts (RIG *rig, vfo_t vfo, shortfreq_t ts)
 set the Tuning Step
int rig_get_ts (RIG *rig, vfo_t vfo, shortfreq_t *ts)
 get the current Tuning Step
int rig_set_ant (RIG *rig, vfo_t vfo, ant_t ant)
 set the antenna
int rig_get_ant (RIG *rig, vfo_t vfo, ant_t *ant)
 get the current antenna
int rig_power2mW (RIG *rig, unsigned int *mwpower, float power, freq_t freq, rmode_t mode)
 conversion utility from relative range to absolute in mW
int rig_mW2power (RIG *rig, float *power, unsigned int mwpower, freq_t freq, rmode_t mode)
 conversion utility from absolute in mW to relative range
shortfreq_t rig_get_resolution (RIG *rig, rmode_t mode)
 get the best frequency resolution of the rig
int rig_set_powerstat (RIG *rig, powerstat_t status)
 turn on/off the radio
int rig_get_powerstat (RIG *rig, powerstat_t *status)
 get the on/off status of the radio
int rig_reset (RIG *rig, reset_t reset)
 reset the radio
rig_model_t rig_probe (hamlib_port_t *port)
 try to guess a rig
int rig_probe_all (hamlib_port_t *port, rig_probe_func_t cfunc, char *data)
 try to guess rigs
vfo_op_t rig_has_vfo_op (RIG *rig, vfo_op_t op)
 check retrieval ability of VFO operations
int rig_vfo_op (RIG *rig, vfo_t vfo, vfo_op_t op)
 perform Memory/VFO operations
scan_t rig_has_scan (RIG *rig, scan_t scan)
 check availability of scaning functions
int rig_scan (RIG *rig, vfo_t vfo, scan_t scan, int ch)
 perform Memory/VFO operations
int rig_send_dtmf (RIG *rig, vfo_t vfo, const char *digits)
 send DTMF digits
int rig_recv_dtmf (RIG *rig, vfo_t vfo, char *digits, int *length)
 receive DTMF digits
int rig_send_morse (RIG *rig, vfo_t vfo, const char *msg)
 send morse code
const freq_range_t * rig_get_range (const freq_range_t range_list[], freq_t freq, rmode_t mode)
 find the freq_range of freq/mode
const char * rig_get_info (RIG *rig)
 get general information from the radio
int rig_set_level (RIG *rig, vfo_t vfo, setting_t level, value_t val)
 set a radio level setting
int rig_get_level (RIG *rig, vfo_t vfo, setting_t level, value_t *val)
 get the value of a level
int rig_set_parm (RIG *rig, setting_t parm, value_t val)
 set a radio parameter
int rig_get_parm (RIG *rig, setting_t parm, value_t *val)
 get the value of a parameter
setting_t rig_has_get_level (RIG *rig, setting_t level)
 check retrieval ability of level settings
setting_t rig_has_set_level (RIG *rig, setting_t level)
 check settable ability of level settings
setting_t rig_has_get_parm (RIG *rig, setting_t parm)
 check retrieval ability of parameter settings
setting_t rig_has_set_parm (RIG *rig, setting_t parm)
 check settable ability of parameter settings
setting_t rig_has_get_func (RIG *rig, setting_t func)
 check ability of radio functions
setting_t rig_has_set_func (RIG *rig, setting_t func)
 check ability of radio functions
int rig_set_func (RIG *rig, vfo_t vfo, setting_t func, int status)
 activate/de-activate functions of radio
int rig_get_func (RIG *rig, vfo_t vfo, setting_t func, int *status)
 get the status of functions of the radio
int rig_set_ext_level (RIG *rig, vfo_t vfo, token_t token, value_t val)
 set a radio level extra parameter
int rig_get_ext_level (RIG *rig, vfo_t vfo, token_t token, value_t *val)
 get the value of a level extra parameter
int rig_set_ext_parm (RIG *rig, token_t token, value_t val)
 set a radio parm extra parameter
int rig_get_ext_parm (RIG *rig, token_t token, value_t *val)
 get the value of a parm extra parameter
int rig_setting2idx (setting_t s)
 basically convert setting_t expressed 2^n to n
int rig_set_ctcss_tone (RIG *rig, vfo_t vfo, tone_t tone)
 set CTCSS sub-tone frequency
int rig_get_ctcss_tone (RIG *rig, vfo_t vfo, tone_t *tone)
 get the current CTCSS sub-tone frequency
int rig_set_dcs_code (RIG *rig, vfo_t vfo, tone_t code)
 set the current encoding DCS code
int rig_get_dcs_code (RIG *rig, vfo_t vfo, tone_t *code)
 get the current encoding DCS code
int rig_set_ctcss_sql (RIG *rig, vfo_t vfo, tone_t tone)
 set CTCSS squelch
int rig_get_ctcss_sql (RIG *rig, vfo_t vfo, tone_t *tone)
 get the current CTCSS squelch
int rig_set_dcs_sql (RIG *rig, vfo_t vfo, tone_t code)
 set the current DCS code
int rig_get_dcs_sql (RIG *rig, vfo_t vfo, tone_t *code)
 get the current DCS code

Variables

const char hamlib_version [21] = "Hamlib " PACKAGE_VERSION
 Hamlib release number The version number has the format x.y.z.
const char hamlib_copyright [231]
 Hamlib copyright notice.
const tone_t full_ctcss_list [] = { 600, 670, 693, 719, 744, 770, 797, 825, 854, 885, 915, 948, 974, 1000, 1035, 1072, 1109, 1148, 1188, 1200, 1230, 1273, 1318, 1365, 1413, 1462, 1514, 1567, 1598, 1622, 1655, 1679, 1713, 1738, 1773, 1799, 1835, 1862, 1899, 1928, 1966, 1995, 2035, 2065, 2107, 2181, 2257, 2291, 2336, 2418, 2503, 2541, 0, }
const tone_t common_ctcss_list [] = { 670, 693, 719, 744, 770, 797, 825, 854, 885, 915, 948, 974, 1000, 1035, 1072, 1109, 1148, 1188, 1230, 1273, 1318, 1365, 1413, 1462, 1514, 1567, 1598, 1622, 1655, 1679, 1713, 1738, 1773, 1799, 1835, 1862, 1899, 1928, 1966, 1995, 2035, 2065, 2107, 2181, 2257, 2291, 2336, 2418, 2503, 2541, 0, }
const tone_t common_dcs_list [] = { 23, 25, 26, 31, 32, 36, 43, 47, 51, 53, 54, 65, 71, 72, 73, 74, 114, 115, 116, 122, 125, 131, 132, 134, 143, 145, 152, 155, 156, 162, 165, 172, 174, 205, 212, 223, 225, 226, 243, 244, 245, 246, 251, 252, 255, 261, 263, 265, 266, 271, 274, 306, 311, 315, 325, 331, 332, 343, 346, 351, 356, 364, 365, 371, 411, 412, 413, 423, 431, 432, 445, 446, 452, 454, 455, 462, 464, 465, 466, 503, 506, 516, 523, 526, 532, 546, 565, 606, 612, 624, 627, 631, 632, 654, 662, 664, 703, 712, 723, 731, 732, 734, 743, 754, 0, }
const tone_t full_dcs_list [] = { 17, 23, 25, 26, 31, 32, 36, 43, 47, 50, 51, 53, 54, 65, 71, 72, 73, 74, 114, 115, 116, 122, 125, 131, 132, 134, 143, 145, 152, 155, 156, 162, 165, 172, 174, 205, 212, 223, 225, 226, 243, 244, 245, 246, 251, 252, 255, 261, 263, 265, 266, 271, 274, 306, 311, 315, 325, 331, 332, 343, 346, 351, 356, 364, 365, 371, 411, 412, 413, 423, 431, 432, 445, 446, 452, 454, 455, 462, 464, 465, 466, 503, 506, 516, 523, 526, 532, 546, 565, 606, 612, 624, 627, 631, 632, 654, 662, 664, 703, 712, 723, 731, 732, 734, 743, 754, 0, }

Detailed Description

Define groups for Doxygen

Rig (radio) interface

For us, a "rig" is an item of general remote controllable radio equipment. Generally, there are a VFO settings, gain controls, etc.


Function Documentation

int rig_cleanup ( RIG *  rig  ) 

release a rig handle and free associated memory

Parameters:
rig The RIG handle of the radio to be closed

Releases a rig struct which port has eventualy been closed already with rig_close().

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_init(), rig_close()
Examples:
/tests/testrig.c.
int rig_close ( RIG *  rig  ) 

close the communication to the rig

Parameters:
rig The RIG handle of the radio to be closed

Closes communication to a radio which RIG handle has been passed by argument that was previously open with rig_open().

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_cleanup(), rig_open()
Examples:
/tests/testrig.c.
struct confparams* rig_confparam_lookup ( RIG *  rig,
const char *  name 
) [read]

lookup a confparam struct

Parameters:
rig The rig handle
name The name of the configuration parameter

Lookup conf token by its name.

Returns:
a pointer to the confparams struct if found, otherwise NULL.
int rig_ext_level_foreach ( RIG *  rig,
int(*)(RIG *, const struct confparams *, char *)  cfunc,
char *  data 
)

Executes cfunc on all the elements stored in the extlevels table The callback cfunc is called until it returns a value which is not strictly positive. A zero value means a normal end of iteration, and a negative value an abnormal end, which will be the return value of rig_ext_level_foreach.

Parameters:
rig The rig handle
cfunc callback function of each extlevel
data cookie to be passed to cfunc callback
struct confparams* rig_ext_lookup ( RIG *  rig,
const char *  name 
) [read]

lookup ext token by its name, return pointer to confparams struct.

Parameters:
rig 
name Lookup extlevels table first, then fall back to extparms.

Returns NULL if nothing found

TODO: should use Lex to speed it up, strcmp hurts!

struct confparams* rig_ext_lookup_tok ( RIG *  rig,
token_t  token 
) [read]

lookup ext token, return pointer to confparams struct.

Parameters:
rig 
token lookup extlevels table first, then fall back to extparms.

Returns NULL if nothing found

int rig_ext_parm_foreach ( RIG *  rig,
int(*)(RIG *, const struct confparams *, char *)  cfunc,
char *  data 
)

Executes cfunc on all the elements stored in the extparms table The callback cfunc is called until it returns a value which is not strictly positive. A zero value means a normal end of iteration, and a negative value an abnormal end, which will be the return value of rig_ext_parm_foreach.

Parameters:
rig The rig handle
cfunc callback function of each extparm
data cookie to be passed to cfunc callback
token_t rig_ext_token_lookup ( RIG *  rig,
const char *  name 
)

Simple lookup returning token id assicated with name.

Parameters:
rig 
name 
int rig_get_ant ( RIG *  rig,
vfo_t  vfo,
ant_t *  ant 
)

get the current antenna

Parameters:
rig The rig handle
vfo The target VFO
ant The location where to store the current antenna

Retrieves the current antenna.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ant()
int rig_get_chan_all ( RIG *  rig,
channel_t  chans[] 
)

get all channel data

Parameters:
rig The rig handle
chans The location where to store all the channel data

Retrieves the data associated with all the memory channels.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_chan_all_cb(), rig_set_chan_all()
int rig_get_chan_all_cb ( RIG *  rig,
chan_cb_t  chan_cb,
char *  arg 
)

get all channel data, by callback

Parameters:
rig The rig handle
chan_cb Pointer to a callback function to retrieve channel data
arg Arbitrary argument passed back to chan_cb

Retrieves the data associated with a all the memory channels. This is the prefered method to support clonable rigs.

chan_cb is called first with no data in chan (chan equals NULL). This means the application has to provide a struct where to store future data for channel channel_num. If channel_num == chan->channel_num, the application does not need to provide a new allocated structure.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_chan_all(), rig_set_chan_all_cb()
int rig_get_channel ( RIG *  rig,
channel_t *  chan 
)

get channel data

Parameters:
rig The rig handle
chan The location where to store the channel data

Retrieves the data associated with a channel. This channel can either be the state of a VFO specified by chan->vfo, or a memory channel specified with chan->vfo = RIG_VFO_MEM and chan->channel_num. See channel_t for more information.

Example:

  channel_t chan;
  int err;

  chan->vfo = RIG_VFO_MEM;
  chan->channel_num = 10;
  err = rig_get_channel(rig, &chan);
  if (err != RIG_OK)
        error("get_channel failed: %s", rigerror(err));

The rig_get_channel is supposed to have no impact on the current VFO and memory number selected. Depending on backend and rig capabilities, the chan struct may not be filled in completely.

Note: chan->ext_levels is a pointer to a newly mallocated memory. This is the responsability of the caller to manage and eventually free it.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_channel()
int rig_get_conf ( RIG *  rig,
token_t  token,
char *  val 
)

get the value of a configuration parameter

Parameters:
rig The rig handle
token The parameter
val The location where to store the value of config token

Retrieves the value of a configuration paramter associated with token. The location pointed to by val must be large enough to hold the value of the config.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_conf()
int rig_get_ctcss_sql ( RIG *  rig,
vfo_t  vfo,
tone_t *  tone 
)

get the current CTCSS squelch

Parameters:
rig The rig handle
vfo The target VFO
tone The location where to store the current tone

Retrieves the current Continuous Tone Controlled Squelch System (CTCSS) sub-audible *squelch* tone.

Note:
*tone is NOT in Hz, but in tenth of Hz! This way, if the function rig_get_ctcss_sql() returns a subaudible tone of 885 for example, then the real tone is 88.5 Hz. Also, a value of 0 for tone means the Tone squelch is disabled.
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ctcss_sql(), rig_get_ctcss_tone()
int rig_get_ctcss_tone ( RIG *  rig,
vfo_t  vfo,
tone_t *  tone 
)

get the current CTCSS sub-tone frequency

Parameters:
rig The rig handle
vfo The target VFO
tone The location where to store the current tone

Retrieves the current Continuous Tone Controlled Squelch System (CTCSS) sub-audible tone frequency.

Note:
the *tone integer is NOT in Hz, but in tenth of Hz! This way, if the function rig_get_ctcss_tone() returns a subaudible tone of 885 for example, then the real tone is 88.5 Hz. Also, a value of 0 for *tone means the Tone encoding is disabled.
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ctcss_tone(), rig_get_ctcss_sql()
int rig_get_dcd ( RIG *  rig,
vfo_t  vfo,
dcd_t *  dcd 
)

get the status of the DCD

Parameters:
rig The rig handle
vfo The target VFO
dcd The location where to store the status of the DCD

Retrieves the status of DCD (is squelch open?).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_get_dcs_code ( RIG *  rig,
vfo_t  vfo,
tone_t *  code 
)

get the current encoding DCS code

Parameters:
rig The rig handle
vfo The target VFO
code The location where to store the current tone

Retrieves the current encoding Digitally-Coded Squelch code.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_dcs_code(), rig_get_dcs_sql()
int rig_get_dcs_sql ( RIG *  rig,
vfo_t  vfo,
tone_t *  code 
)

get the current DCS code

Parameters:
rig The rig handle
vfo The target VFO
code The location where to store the current tone

Retrieves the current Digitally-Coded *Squelch* code.

Returns:
RIG_OK if the operation has been sucessful, ortherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_dcs_sql(), rig_get_dcs_code()
int rig_get_ext_level ( RIG *  rig,
vfo_t  vfo,
token_t  token,
value_t *  val 
)

get the value of a level extra parameter

Parameters:
rig The rig handle
vfo The target VFO
token The parameter
val The location where to store the value of token

Retrieves the value of a level extra parameter associated with token.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ext_level()
int rig_get_ext_parm ( RIG *  rig,
token_t  token,
value_t *  val 
)

get the value of a parm extra parameter

Parameters:
rig The rig handle
token The parameter
val The location where to store the value of token

Retrieves the value of a parm extra parameter associated with token.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ext_parm()
int rig_get_freq ( RIG *  rig,
vfo_t  vfo,
freq_t *  freq 
)

get the frequency of the target VFO

Parameters:
rig The rig handle
vfo The target VFO
freq The location where to store the current frequency

Retrieves the frequency of the target VFO. The value stored at freq location equals RIG_FREQ_NONE when the current frequency of the VFO is not defined (e.g. blank memory).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_freq()
Examples:
/tests/testrig.c.
int rig_get_func ( RIG *  rig,
vfo_t  vfo,
setting_t  func,
int *  status 
)

get the status of functions of the radio

Parameters:
rig The rig handle
vfo The target VFO
func The functions to get the status
status The location where to store the function status

Retrieves the status (on/off) of a function of the radio. Upon return, status will hold the status of the function, The value pointer to by the status argument is a non null value for "on", "off" otherwise, much as TRUE/FALSE definitions in C language.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_func()
const char* rig_get_info ( RIG *  rig  ) 

get general information from the radio

Parameters:
rig The rig handle

Retrieves some general information from the radio. This can include firmware revision, exact model name, or just nothing.

Returns:
a pointer to freshly allocated memory containing the ASCIIZ string if the operation has been sucessful, otherwise NULL if an error occured or get_info not part of capabilities.
int rig_get_level ( RIG *  rig,
vfo_t  vfo,
setting_t  level,
value_t *  val 
)

get the value of a level

Parameters:
rig The rig handle
vfo The target VFO
level The level setting
val The location where to store the value of level

Retrieves the value of a level. The level value val can be a float or an integer. See value_t for more information.

RIG_LEVEL_STRENGTH: val is an integer, representing the S Meter level in dB relative to S9, according to the ideal S Meter scale. The ideal S Meter scale is as follow: S0=-54, S1=-48, S2=-42, S3=-36, S4=-30, S5=-24, S6=-18, S7=-12, S8=-6, S9=0, +10=10, +20=20, +30=30, +40=40, +50=50 and +60=60. This is the responsability of the backend to return values calibrated for this scale.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_get_level(), rig_set_level()
int rig_get_mem ( RIG *  rig,
vfo_t  vfo,
int *  ch 
)

get the current memory channel number

Parameters:
rig The rig handle
vfo The target VFO
ch The location where to store the current memory channel number

Retrieves the current memory channel number. It is not mandatory for the radio to be in memory mode. Actually it depends on rigs. YMMV.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_mem()
int rig_get_mem_all ( RIG *  rig,
channel_t  chans[],
const struct confparams  cfgps[],
value_t  vals[] 
)

get all channel and non-channel data

Parameters:
rig The rig handle
chans Array of channels where to store the data
cfgps Array of config parameters to retrieve
vals Array of values where to store the data

Retrieves the data associated with all the memory channels, and rigs memory parameters. This is the prefered method to support clonable rigs.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mem_all(), rig_set_mem_all_cb()
Todo:
finish coding and testing of mem_all functions
int rig_get_mem_all_cb ( RIG *  rig,
chan_cb_t  chan_cb,
confval_cb_t  parm_cb,
char *  arg 
)

get all channel and non-channel data by call-back

Parameters:
rig The rig handle
chan_cb The callback for channel data
parm_cb The callback for non-channel(aka parm) data
arg Cookie passed to chan_cb and parm_cb

Retrieves the data associated with all the memory channels, and rigs memory parameters, by callback. This is the prefered method to support clonable rigs.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mem_all_cb(), rig_set_mem_all()
Todo:

get all parm's

finish coding and testing of mem_all functions

int rig_get_mode ( RIG *  rig,
vfo_t  vfo,
rmode_t *  mode,
pbwidth_t *  width 
)

get the mode of the target VFO

Parameters:
rig The rig handle
vfo The target VFO
mode The location where to store the current mode
width The location where to store the current passband width

Retrieves the mode and passband of the target VFO. If the backend is unable to determine the width, the width will be set to RIG_PASSBAND_NORMAL as a default. The value stored at mode location equals RIG_MODE_NONE when the current mode of the VFO is not defined (e.g. blank memory).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_mode()
Examples:
/tests/testrig.c.
int rig_get_parm ( RIG *  rig,
setting_t  parm,
value_t *  val 
)

get the value of a parameter

Parameters:
rig The rig handle
parm The parameter
val The location where to store the value of parm

Retrieves the value of a parm. The parameter value val can be a float or an integer. See value_t for more information.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_get_parm(), rig_set_parm()
int rig_get_powerstat ( RIG *  rig,
powerstat_t *  status 
)

get the on/off status of the radio

Parameters:
rig The rig handle
status The locatation where to store the current status

Retrieve the status of the radio. See RIG_POWER_ON, RIG_POWER_OFF and RIG_POWER_STANDBY defines for the status.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_powerstat()
int rig_get_ptt ( RIG *  rig,
vfo_t  vfo,
ptt_t *  ptt 
)

get the status of the PTT

Parameters:
rig The rig handle
vfo The target VFO
ptt The location where to store the status of the PTT

Retrieves the status of PTT (are we on the air?).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ptt()
const freq_range_t* rig_get_range ( const freq_range_t  range_list[],
freq_t  freq,
rmode_t  mode 
)

find the freq_range of freq/mode

Parameters:
range_list The range list to search from
freq The frequency that will be part of this range
mode The mode that will be part of this range

Returns a pointer to the freq_range_t including freq and mode. Works for rx and tx range list as well.

Returns:
the location of the freq_range_t if found, otherwise NULL if not found or if range_list is invalid.
shortfreq_t rig_get_resolution ( RIG *  rig,
rmode_t  mode 
)

get the best frequency resolution of the rig

Parameters:
rig The rig handle
mode The mode where the conversion should take place

Returns the best frequency resolution of the rig, for a given mode.

Returns:
the frequency resolution in Hertz if the operation h has been sucessful, otherwise a negative value if an error occured.
int rig_get_rit ( RIG *  rig,
vfo_t  vfo,
shortfreq_t *  rit 
)

get the current RIT offset

Parameters:
rig The rig handle
vfo The target VFO
rit The location where to store the current RIT offset

Retrieves the current RIT offset.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_rit()
int rig_get_rptr_offs ( RIG *  rig,
vfo_t  vfo,
shortfreq_t *  rptr_offs 
)

get the current repeater offset

Parameters:
rig The rig handle
vfo The target VFO
rptr_offs The location where to store the current repeater offset

Retrieves the current repeater offset.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_rptr_offs()
int rig_get_rptr_shift ( RIG *  rig,
vfo_t  vfo,
rptr_shift_t *  rptr_shift 
)

get the current repeater shift

Parameters:
rig The rig handle
vfo The target VFO
rptr_shift The location where to store the current repeater shift

Retrieves the current repeater shift.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_rptr_shift()
int rig_get_split_freq ( RIG *  rig,
vfo_t  vfo,
freq_t *  tx_freq 
)

get the current split frequencies

Parameters:
rig The rig handle
vfo The target VFO
tx_freq The location where to store the current transmit split frequency

Retrieves the current split(TX) frequency.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_split_freq()
int rig_get_split_mode ( RIG *  rig,
vfo_t  vfo,
rmode_t *  tx_mode,
pbwidth_t *  tx_width 
)

get the current split modes

Parameters:
rig The rig handle
vfo The target VFO
tx_mode The location where to store the current transmit split mode
tx_width The location where to store the current transmit split width

Retrieves the current split(TX) mode and passband. If the backend is unable to determine the width, the tx_width will be set to RIG_PASSBAND_NORMAL as a default. The value stored at tx_mode location equals RIG_MODE_NONE when the current mode of the VFO is not defined (e.g. blank memory).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_split_mode()
int rig_get_split_vfo ( RIG *  rig,
vfo_t  vfo,
split_t *  split,
vfo_t *  tx_vfo 
)

get the current split mode

Parameters:
rig The rig handle
vfo The target VFO
split The location where to store the current split mode
tx_vfo The transmit VFO

Retrieves the current split mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_split_vfo()
int rig_get_trn ( RIG *  rig,
int *  trn 
)

get the current transceive mode

Parameters:
rig The rig handle
trn The location where to store the current transceive mode

Retrieves the current status of the transceive mode, i.e. if radio sends new status automatically when some changes happened on the radio.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_get_ts ( RIG *  rig,
vfo_t  vfo,
shortfreq_t *  ts 
)

get the current Tuning Step

Parameters:
rig The rig handle
vfo The target VFO
ts The location where to store the current tuning step

Retrieves the current tuning step.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_ts()
int rig_get_vfo ( RIG *  rig,
vfo_t *  vfo 
)

get the current VFO

Parameters:
rig The rig handle
vfo The location where to store the current VFO

Retrieves the current VFO. The VFO can be RIG_VFO_A, RIG_VFO_B, RIG_VFO_C for VFOA, VFOB, VFOC respectively or RIG_VFO_MEM for Memory mode. Supported VFOs depends on rig capabilities.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_vfo()
Examples:
/tests/testrig.c.
int rig_get_xit ( RIG *  rig,
vfo_t  vfo,
shortfreq_t *  xit 
)

get the current XIT offset

Parameters:
rig The rig handle
vfo The target VFO
xit The location where to store the current XIT offset

Retrieves the current XIT offset.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_xit()
setting_t rig_has_get_func ( RIG *  rig,
setting_t  func 
)

check ability of radio functions

Parameters:
rig The rig handle
func The functions

Checks if a rig supports a set of functions. Since the func is an OR'ed bitwise argument, more than one function can be checked at the same time.

EXAMPLE: if (rig_has_get_func(my_rig,RIG_FUNC_FAGC)) disp_fagc_button();

Returns:
a bit map of supported functions, otherwise 0 if none supported.
See also:
rig_has_set_func(), rig_get_func()
setting_t rig_has_get_level ( RIG *  rig,
setting_t  level 
)

check retrieval ability of level settings

Parameters:
rig The rig handle
level The level settings

Checks if a rig is capable of *getting* a level setting. Since the level is an OR'ed bitwise argument, more than one level can be checked at the same time.

EXAMPLE: if (rig_has_get_level(my_rig, RIG_LVL_STRENGTH)) disp_Smeter();

Returns:
a bit map of supported level settings that can be retrieved, otherwise 0 if none supported.
See also:
rig_has_set_level(), rig_get_level()
setting_t rig_has_get_parm ( RIG *  rig,
setting_t  parm 
)

check retrieval ability of parameter settings

Parameters:
rig The rig handle
parm The parameter settings

Checks if a rig is capable of *getting* a parm setting. Since the parm is an OR'ed bitwise argument, more than one parameter can be checked at the same time.

EXAMPLE: if (rig_has_get_parm(my_rig, RIG_PARM_ANN)) good4you();

Returns:
a bit map of supported parameter settings that can be retrieved, otherwise 0 if none supported.
See also:
rig_has_set_parm(), rig_get_parm()
scan_t rig_has_scan ( RIG *  rig,
scan_t  scan 
)

check availability of scaning functions

Parameters:
rig The rig handle
scan The scan op

Checks if a rig is capable of performing a scan operation. Since the scan parameter is an OR'ed bitmap argument, more than one op can be checked at the same time.

EXAMPLE: if (rig_has_scan(my_rig, RIG_SCAN_PRIO)) disp_SCANprio_btn();

Returns:
a bit map of supported scan settings that can be retrieved, otherwise 0 if none supported.
See also:
rig_scan()
setting_t rig_has_set_func ( RIG *  rig,
setting_t  func 
)

check ability of radio functions

Parameters:
rig The rig handle
func The functions

Checks if a rig supports a set of functions. Since the func is an OR'ed bitwise argument, more than one function can be checked at the same time.

EXAMPLE: if (rig_has_set_func(my_rig,RIG_FUNC_FAGC)) disp_fagc_button();

Returns:
a bit map of supported functions, otherwise 0 if none supported.
See also:
rig_set_func(), rig_has_get_func()
setting_t rig_has_set_level ( RIG *  rig,
setting_t  level 
)

check settable ability of level settings

Parameters:
rig The rig handle
level The level settings

Checks if a rig can *set* a level setting. Since the level is an OR'ed bitwise argument, more than one level can be check at the same time.

EXAMPLE: if (rig_has_set_level(my_rig, RIG_LVL_RFPOWER)) crank_tx();

Returns:
a bit map of supported level settings that can be set, otherwise 0 if none supported.
See also:
rig_has_get_level(), rig_set_level()
setting_t rig_has_set_parm ( RIG *  rig,
setting_t  parm 
)

check settable ability of parameter settings

Parameters:
rig The rig handle
parm The parameter settings

Checks if a rig can *set* a parameter setting. Since the parm is an OR'ed bitwise argument, more than one parameter can be check at the same time.

EXAMPLE: if (rig_has_set_parm(my_rig, RIG_PARM_ANN)) announce_all();

Returns:
a bit map of supported parameter settings that can be set, otherwise 0 if none supported.
See also:
rig_has_get_parm(), rig_set_parm()
vfo_op_t rig_has_vfo_op ( RIG *  rig,
vfo_op_t  op 
)

check retrieval ability of VFO operations

Parameters:
rig The rig handle
op The VFO op

Checks if a rig is capable of executing a VFO operation. Since the op is an OR'ed bitmap argument, more than one op can be checked at the same time.

EXAMPLE: if (rig_has_vfo_op(my_rig, RIG_OP_CPY)) disp_VFOcpy_btn();

Returns:
a bit map mask of supported op settings that can be retrieved, otherwise 0 if none supported.
See also:
rig_vfo_op()
RIG* rig_init ( rig_model_t  rig_model  ) 

allocate a new RIG handle

Parameters:
rig_model The rig model for this new handle

Allocates a new RIG handle and initializes the associated data for rig_model.

Returns:
a pointer to the RIG handle otherwise NULL if memory allocation failed or rig_model is unknown (e.g. backend autoload failed).
See also:
rig_cleanup(), rig_open()
Examples:
/tests/testrig.c.
const chan_t* rig_lookup_mem_caps ( RIG *  rig,
int  ch 
)

lookup the memory type and capabilities

Parameters:
rig The rig handle
ch The memory channel number

Lookup the memory type and capabilities associated with a channel number. If ch equals RIG_MEM_CAPS_ALL, then a union of all the mem_caps sets is returned (pointer to static memory).

Returns:
a pointer to a chan_t structure if the operation has been sucessful, otherwise a NULL pointer, most probably because of incorrect channel number or buggy backend.
int rig_mem_count ( RIG *  rig  ) 

get memory channel count

Parameters:
rig The rig handle

Get the total memory channel count, computed from the rig caps

Returns:
the memory count
int rig_mW2power ( RIG *  rig,
float *  power,
unsigned int  mwpower,
freq_t  freq,
rmode_t  mode 
)

conversion utility from absolute in mW to relative range

Parameters:
rig The rig handle
power The location where to store the converted relative power
mwpower The power in mW
freq The frequency where the conversion should take place
mode The mode where the conversion should take place

Converts a power value expressed in the real transmit power in milli Watts the radio would emit to a range on a [0.0 .. 1.0] relative scale. The freq and mode where the conversion should take place must be also provided since the relative power is peculiar to a specific freq and mode range of the radio.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_power2mW()
int rig_open ( RIG *  rig  ) 

open the communication to the rig

Parameters:
rig The RIG handle of the radio to be opened

Opens communication to a radio which RIG handle has been passed by argument.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
Return values:
RIG_EINVAL rig is NULL or unconsistent.
RIG_ENIMPL port type communication is not implemented yet.
See also:
rig_init(), rig_close()
Examples:
/tests/testrig.c.
pbwidth_t rig_passband_narrow ( RIG *  rig,
rmode_t  mode 
)

get the narrow passband of a mode

Parameters:
rig The rig handle
mode The mode to get the passband

Returns the narrow (closest) passband for the given mode. EXAMPLE: rig_set_mode(my_rig, RIG_MODE_LSB, rig_passband_narrow(my_rig, RIG_MODE_LSB) );

Returns:
the passband in Hz if the operation has been sucessful, or a 0 if an error occured (passband not found, whatever).
See also:
rig_passband_normal(), rig_passband_wide()
Examples:
/tests/testrig.c.
pbwidth_t rig_passband_normal ( RIG *  rig,
rmode_t  mode 
)

get the normal passband of a mode

Parameters:
rig The rig handle
mode The mode to get the passband

Returns the normal (default) passband for the given mode.

Returns:
the passband in Hz if the operation has been sucessful, or a 0 if an error occured (passband not found, whatever).
See also:
rig_passband_narrow(), rig_passband_wide()
pbwidth_t rig_passband_wide ( RIG *  rig,
rmode_t  mode 
)

get the wide passband of a mode

Parameters:
rig The rig handle
mode The mode to get the passband

Returns the wide (default) passband for the given mode. EXAMPLE: rig_set_mode(my_rig, RIG_MODE_AM, rig_passband_wide(my_rig, RIG_MODE_AM) );

Returns:
the passband in Hz if the operation has been sucessful, or a 0 if an error occured (passband not found, whatever).
See also:
rig_passband_narrow(), rig_passband_normal()
int rig_power2mW ( RIG *  rig,
unsigned int *  mwpower,
float  power,
freq_t  freq,
rmode_t  mode 
)

conversion utility from relative range to absolute in mW

Parameters:
rig The rig handle
mwpower The location where to store the converted power in mW
power The relative power
freq The frequency where the conversion should take place
mode The mode where the conversion should take place

Converts a power value expressed in a range on a [0.0 .. 1.0] relative scale to the real transmit power in milli Watts the radio would emit. The freq and mode where the conversion should take place must be also provided since the relative power is peculiar to a specific freq and mode range of the radio.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_mW2power()
rig_model_t rig_probe ( hamlib_port_t *  port  ) 

try to guess a rig

Parameters:
port A pointer describing a port linking the host to the rig

Try to guess what is the model of the first rig attached to the port. It can be very buggy, and mess up the radio at the other end. (but fun if it works!)

Warning:
this is really Experimental, It has been tested only with IC-706MkIIG. any feedback welcome! --SF
Returns:
the rig model id according to the rig_model_t type if found, otherwise RIG_MODEL_NONE if unable to determine rig model.
Examples:
/tests/testrig.c.
int rig_probe_all ( hamlib_port_t *  port,
rig_probe_func_t  cfunc,
char *  data 
)

try to guess rigs

Parameters:
port A pointer describing a port linking the host to the rigs
cfunc Function to be called each time a rig is found
data Arbitrary data passed to cfunc

Try to guess what are the model of all rigs attached to the port. It can be very buggy, and mess up the radio at the other end. (but fun if it works!)

Warning:
this is really Experimental, It has been tested only with IC-706MkIIG. any feedback welcome! --SF
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_recv_dtmf ( RIG *  rig,
vfo_t  vfo,
char *  digits,
int *  length 
)

receive DTMF digits

Parameters:
rig The rig handle
vfo The target VFO
digits Location where the digits are to be stored
length in: max length of buffer, out: number really read.

Receives DTMF digits (not blocking). See DTMF change speed, etc. (TODO).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_reset ( RIG *  rig,
reset_t  reset 
)

reset the radio

Parameters:
rig The rig handle
reset The reset operation to perform

Resets the radio. See RIG_RESET_NONE, RIG_RESET_SOFT and RIG_RESET_MCALL defines for the reset.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_scan ( RIG *  rig,
vfo_t  vfo,
scan_t  scan,
int  ch 
)

perform Memory/VFO operations

Parameters:
rig The rig handle
vfo The target VFO
scan The scanning operation to perform
ch Optional channel argument used for the scan.

Performs scanning operation. See scan_t for more information.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_scan()
int rig_send_dtmf ( RIG *  rig,
vfo_t  vfo,
const char *  digits 
)

send DTMF digits

Parameters:
rig The rig handle
vfo The target VFO
digits Digits to be send

Sends DTMF digits. See DTMF change speed, etc. (TODO).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_send_morse ( RIG *  rig,
vfo_t  vfo,
const char *  msg 
)

send morse code

Parameters:
rig The rig handle
vfo The target VFO
msg Message to be sent

Sends morse message. See keyer change speed, etc. (TODO).

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
int rig_set_ant ( RIG *  rig,
vfo_t  vfo,
ant_t  ant 
)

set the antenna

Parameters:
rig The rig handle
vfo The target VFO
ant The anntena to select

Select the antenna connector.

        rig_set_ant(rig, RIG_VFO_CURR, RIG_ANT_1);  // apply to both TX&RX
        rig_set_ant(rig, RIG_VFO_RX, RIG_ANT_2);
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ant()
int rig_set_bank ( RIG *  rig,
vfo_t  vfo,
int  bank 
)

set the current memory bank

Parameters:
rig The rig handle
vfo The target VFO
bank The memory bank

Sets the current memory bank number. It is not mandatory for the radio to be in memory mode. Actually it depends on rigs. YMMV.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_mem()
int rig_set_chan_all ( RIG *  rig,
const channel_t  chans[] 
)

set all channel data

Parameters:
rig The rig handle
chans The location of data to set for all channels

Write the data associated with all the memory channels.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_chan_all_cb(), rig_get_chan_all()
int rig_set_chan_all_cb ( RIG *  rig,
chan_cb_t  chan_cb,
char *  arg 
)

set all channel data, by callback

Parameters:
rig The rig handle
chan_cb Pointer to a callback function to provide channel data
arg Arbitrary argument passed back to chan_cb

Write the data associated with a all the memory channels. This is the prefered method to support clonable rigs.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_chan_all(), rig_get_chan_all_cb()
int rig_set_channel ( RIG *  rig,
const channel_t *  chan 
)

set channel data

Parameters:
rig The rig handle
chan The location of data to set for this channel

Sets the data associated with a channel. This channel can either be the state of a VFO specified by chan->vfo, or a memory channel specified with chan->vfo = RIG_VFO_MEM and chan->channel_num. See channel_t for more information.

The rig_set_channel is supposed to have no impact on the current VFO and memory number selected. Depending on backend and rig capabilities, the chan struct may not be set completely.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_channel()
int rig_set_conf ( RIG *  rig,
token_t  token,
const char *  val 
)

set a radio configuration parameter

Parameters:
rig The rig handle
token The parameter
val The value to set the parameter to

Sets a configuration parameter.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_conf()
int rig_set_ctcss_sql ( RIG *  rig,
vfo_t  vfo,
tone_t  tone 
)

set CTCSS squelch

Parameters:
rig The rig handle
vfo The target VFO
tone The PL tone to set the squelch to

Sets the current Continuous Tone Controlled Squelch System (CTCSS) sub-audible *squelch* tone.

Note:
tone is NOT in Hz, but in tenth of Hz! This way, if you want to set subaudible squelch tone of 88.5 Hz for example, then pass 885 to this function. Also, to disable Tone squelch, set tone to 0 (FIXME: not clear in API).
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ctcss_sql(), rig_set_ctcss_tone()
int rig_set_ctcss_tone ( RIG *  rig,
vfo_t  vfo,
tone_t  tone 
)

set CTCSS sub-tone frequency

Parameters:
rig The rig handle
vfo The target VFO
tone The tone to set to

Sets the current Continuous Tone Controlled Squelch System (CTCSS) sub-audible tone frequency.

Note:
the tone integer is NOT in Hz, but in tenth of Hz! This way, if you want to set a subaudible tone of 88.5 Hz for example, then pass 885 to this function. Also, to disable Tone encoding, set tone to 0 (FIXME: not clear in API).
Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ctcss_tone(), rig_set_ctcss_sql()
int rig_set_dcd_callback ( RIG *  rig,
dcd_cb_t  cb,
char *  arg 
)

set the callback for dcd events

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback

Install a callback for dcd events, to be called when in transceive mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_dcs_code ( RIG *  rig,
vfo_t  vfo,
tone_t  code 
)

set the current encoding DCS code

Parameters:
rig The rig handle
vfo The target VFO
code The tone to set to

Sets the current encoding Digitally-Coded Squelch code.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_dcs_code(), rig_set_dcs_sql()
int rig_set_dcs_sql ( RIG *  rig,
vfo_t  vfo,
tone_t  code 
)

set the current DCS code

Parameters:
rig The rig handle
vfo The target VFO
code The tone to set to

Sets the current Digitally-Coded *Squelch* code.

Returns:
returns RIG_OK if the operation has been sucessful, ortherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_dcs_sql(), rig_set_dcs_code()
int rig_set_ext_level ( RIG *  rig,
vfo_t  vfo,
token_t  token,
value_t  val 
)

set a radio level extra parameter

Parameters:
rig The rig handle
vfo The target VFO
token The parameter
val The value to set the parameter to

Sets an level extra parameter.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ext_level()
int rig_set_ext_parm ( RIG *  rig,
token_t  token,
value_t  val 
)

set a radio parm extra parameter

Parameters:
rig The rig handle
token The parameter
val The value to set the parameter to

Sets an parm extra parameter.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ext_parm()
int rig_set_freq ( RIG *  rig,
vfo_t  vfo,
freq_t  freq 
)

set the frequency of the target VFO

Parameters:
rig The rig handle
vfo The target VFO
freq The frequency to set to

Sets the frequency of the target VFO.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_freq()
Examples:
/tests/testrig.c.
int rig_set_freq_callback ( RIG *  rig,
freq_cb_t  cb,
char *  arg 
)

set the callback for freq events

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback

Install a callback for freq events, to be called when in transceive mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_func ( RIG *  rig,
vfo_t  vfo,
setting_t  func,
int  status 
)

activate/de-activate functions of radio

Parameters:
rig The rig handle
vfo The target VFO
func The functions to activate
status The status (on or off) to set to

Activate/de-activate a function of the radio.

The status argument is a non null value for "activate", "de-activate" otherwise, much as TRUE/FALSE definitions in C language.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_func()
int rig_set_level ( RIG *  rig,
vfo_t  vfo,
setting_t  level,
value_t  val 
)

set a radio level setting

Parameters:
rig The rig handle
vfo The target VFO
level The level setting
val The value to set the level setting to

Sets the level of a setting. The level value val can be a float or an integer. See value_t for more information.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_set_level(), rig_get_level()
int rig_set_mem ( RIG *  rig,
vfo_t  vfo,
int  ch 
)

set the current memory channel number

Parameters:
rig The rig handle
vfo The target VFO
ch The memory channel number

Sets the current memory channel number. It is not mandatory for the radio to be in memory mode. Actually it depends on rigs. YMMV.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mem()
int rig_set_mem_all ( RIG *  rig,
const channel_t  chans[],
const struct confparams  cfgps[],
const value_t  vals[] 
)

set all channel and non-channel data

Parameters:
rig The rig handle
chans Channel data
cfgps ??
vals ??

Writes the data associated with all the memory channels, and rigs memory parameters.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mem_all(), rig_set_mem_all_cb()
Todo:

set all parm's

finish coding and testing of mem_all functions

int rig_set_mem_all_cb ( RIG *  rig,
chan_cb_t  chan_cb,
confval_cb_t  parm_cb,
char *  arg 
)

set all channel and non-channel data by call-back

Parameters:
rig The rig handle
chan_cb The callback for channel data
parm_cb The callback for non-channel(aka parm) data
arg Cookie passed to chan_cb and parm_cb

Writes the data associated with all the memory channels, and rigs memory parameters, by callback. This is the prefered method to support clonable rigs.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mem_all_cb(), rig_set_mem_all()
Todo:
finish coding and testing of mem_all functions
int rig_set_mode ( RIG *  rig,
vfo_t  vfo,
rmode_t  mode,
pbwidth_t  width 
)

set the mode of the target VFO

Parameters:
rig The rig handle
vfo The target VFO
mode The mode to set to
width The passband width to set to

Sets the mode and associated passband of the target VFO. The passband width must be supported by the backend of the rig.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_mode()
Examples:
/tests/testrig.c.
int rig_set_mode_callback ( RIG *  rig,
mode_cb_t  cb,
char *  arg 
)

set the callback for mode events

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback

Install a callback for mode events, to be called when in transceive mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_parm ( RIG *  rig,
setting_t  parm,
value_t  val 
)

set a radio parameter

Parameters:
rig The rig handle
parm The parameter
val The value to set the parameter

Sets a parameter. The parameter value val can be a float or an integer. See value_t for more information.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_set_parm(), rig_get_parm()
int rig_set_pltune_callback ( RIG *  rig,
pltune_cb_t  cb,
char *  arg 
)

set the callback for pipelined tuning module

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback used to maintain state during pipelined tuning.

Install a callback for pipelined tuning module, to be called when the rig_scan( SCAN_PLT ) loop needs a new frequency, mode and width.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_powerstat ( RIG *  rig,
powerstat_t  status 
)

turn on/off the radio

Parameters:
rig The rig handle
status The status to set to

turns on/off the radio. See RIG_POWER_ON, RIG_POWER_OFF and RIG_POWER_STANDBY defines for the status.

Returns:
RIG_OK if the operation has been sucessful, ortherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_powerstat()
int rig_set_ptt ( RIG *  rig,
vfo_t  vfo,
ptt_t  ptt 
)

set PTT on/off

Parameters:
rig The rig handle
vfo The target VFO
ptt The PTT status to set to

Sets "Push-To-Talk" on/off.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ptt()
Examples:
/tests/testrig.c.
int rig_set_ptt_callback ( RIG *  rig,
ptt_cb_t  cb,
char *  arg 
)

set the callback for ptt events

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback

Install a callback for ptt events, to be called when in transceive mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_rit ( RIG *  rig,
vfo_t  vfo,
shortfreq_t  rit 
)

set the RIT

Parameters:
rig The rig handle
vfo The target VFO
rit The RIT offset to adjust to

Sets the current RIT offset. A value of 0 for rit disables RIT.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_rit()
int rig_set_rptr_offs ( RIG *  rig,
vfo_t  vfo,
shortfreq_t  rptr_offs 
)

set the repeater offset

Parameters:
rig The rig handle
vfo The target VFO
rptr_offs The VFO to set to

Sets the current repeater offset.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_rptr_offs()
int rig_set_rptr_shift ( RIG *  rig,
vfo_t  vfo,
rptr_shift_t  rptr_shift 
)

set the repeater shift

Parameters:
rig The rig handle
vfo The target VFO
rptr_shift The repeater shift to set to

Sets the current repeater shift.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_rptr_shift()
int rig_set_split_freq ( RIG *  rig,
vfo_t  vfo,
freq_t  tx_freq 
)

set the split frequencies

Parameters:
rig The rig handle
vfo The target VFO
tx_freq The transmit split frequency to set to

Sets the split(TX) frequency.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_split_freq(), rig_set_split_vfo()
int rig_set_split_mode ( RIG *  rig,
vfo_t  vfo,
rmode_t  tx_mode,
pbwidth_t  tx_width 
)

set the split modes

Parameters:
rig The rig handle
vfo The target VFO
tx_mode The transmit split mode to set to
tx_width The transmit split width to set to

Sets the split(TX) mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_split_mode()
int rig_set_split_vfo ( RIG *  rig,
vfo_t  vfo,
split_t  split,
vfo_t  tx_vfo 
)

set the split mode

Parameters:
rig The rig handle
vfo The target VFO
split The split mode to set to
tx_vfo The transmit VFO

Sets the current split mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_split_vfo()
int rig_set_trn ( RIG *  rig,
int  trn 
)

control the transceive mode

Parameters:
rig The rig handle
trn The transceive status to set to

Enable/disable the transceive handling of a rig and kick off async mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_trn()
int rig_set_ts ( RIG *  rig,
vfo_t  vfo,
shortfreq_t  ts 
)

set the Tuning Step

Parameters:
rig The rig handle
vfo The target VFO
ts The tuning step to set to

Sets the Tuning Step.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_ts()
int rig_set_vfo ( RIG *  rig,
vfo_t  vfo 
)

set the current VFO

Parameters:
rig The rig handle
vfo The VFO to set to

Sets the current VFO. The VFO can be RIG_VFO_A, RIG_VFO_B, RIG_VFO_C for VFOA, VFOB, VFOC respectively or RIG_VFO_MEM for Memory mode. Supported VFOs depends on rig capabilities.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_vfo()
Examples:
/tests/testrig.c.
int rig_set_vfo_callback ( RIG *  rig,
vfo_cb_t  cb,
char *  arg 
)

set the callback for vfo events

Parameters:
rig The rig handle
cb The callback to install
arg A Pointer to some private data to pass later on to the callback

Install a callback for vfo events, to be called when in transceive mode.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_set_trn()
int rig_set_xit ( RIG *  rig,
vfo_t  vfo,
shortfreq_t  xit 
)

set the XIT

Parameters:
rig The rig handle
vfo The target VFO
xit The XIT offset to adjust to

Sets the current XIT offset. A value of 0 for xit disables XIT.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_get_xit()
int rig_setting2idx ( setting_t  s  ) 

basically convert setting_t expressed 2^n to n

Parameters:
s The setting to convert to

Converts a setting_t value expressed by 2^n to the value of n.

Returns:
the index such that 2^n is the setting, otherwise 0 if the setting was not found.
int rig_token_foreach ( RIG *  rig,
int(*)(const struct confparams *, char *)  cfunc,
char *  data 
)

call a function against each configuration token of a rig

Parameters:
rig The rig handle
cfunc The function to perform on each token
data Any data to be passed to cfunc

Executes cfunc on all the elements stored in the conf table. rig_token_foreach starts first with backend conf table, then finish with frontend table.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
token_t rig_token_lookup ( RIG *  rig,
const char *  name 
)

lookup a token id

Parameters:
rig The rig handle
name The name of the configuration parameter

Simple lookup returning token id assicated with name.

Returns:
the token id if found, otherwise RIG_CONF_END
int rig_vfo_op ( RIG *  rig,
vfo_t  vfo,
vfo_op_t  op 
)

perform Memory/VFO operations

Parameters:
rig The rig handle
vfo The target VFO
op The Memory/VFO operation to perform

Performs Memory/VFO operation. See vfo_op_t for more information.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rig_has_vfo_op()
const char* rigerror ( int  errnum  ) 

get string describing the error code

Parameters:
errnum The error code
Returns:
the appropriate description string, ortherwise a NULL pointer if the error code is unknown.

Returns a string describing the error code passed in the argument errnum.

Todo:
support gettext/localization
Examples:
/tests/testrig.c.

Variable Documentation

const tone_t common_ctcss_list[] = { 670, 693, 719, 744, 770, 797, 825, 854, 885, 915, 948, 974, 1000, 1035, 1072, 1109, 1148, 1188, 1230, 1273, 1318, 1365, 1413, 1462, 1514, 1567, 1598, 1622, 1655, 1679, 1713, 1738, 1773, 1799, 1835, 1862, 1899, 1928, 1966, 1995, 2035, 2065, 2107, 2181, 2257, 2291, 2336, 2418, 2503, 2541, 0, }

50 CTCSS sub-audible tones, from 67.0Hz to 254.1Hz

Note:
Don't even think about changing a bit of this array, several backends depend on it. If you need to, create a copy for your own caps. --SF
const tone_t common_dcs_list[] = { 23, 25, 26, 31, 32, 36, 43, 47, 51, 53, 54, 65, 71, 72, 73, 74, 114, 115, 116, 122, 125, 131, 132, 134, 143, 145, 152, 155, 156, 162, 165, 172, 174, 205, 212, 223, 225, 226, 243, 244, 245, 246, 251, 252, 255, 261, 263, 265, 266, 271, 274, 306, 311, 315, 325, 331, 332, 343, 346, 351, 356, 364, 365, 371, 411, 412, 413, 423, 431, 432, 445, 446, 452, 454, 455, 462, 464, 465, 466, 503, 506, 516, 523, 526, 532, 546, 565, 606, 612, 624, 627, 631, 632, 654, 662, 664, 703, 712, 723, 731, 732, 734, 743, 754, 0, }

104 DCS codes

const tone_t full_ctcss_list[] = { 600, 670, 693, 719, 744, 770, 797, 825, 854, 885, 915, 948, 974, 1000, 1035, 1072, 1109, 1148, 1188, 1200, 1230, 1273, 1318, 1365, 1413, 1462, 1514, 1567, 1598, 1622, 1655, 1679, 1713, 1738, 1773, 1799, 1835, 1862, 1899, 1928, 1966, 1995, 2035, 2065, 2107, 2181, 2257, 2291, 2336, 2418, 2503, 2541, 0, }

52 CTCSS sub-audible tones

const tone_t full_dcs_list[] = { 17, 23, 25, 26, 31, 32, 36, 43, 47, 50, 51, 53, 54, 65, 71, 72, 73, 74, 114, 115, 116, 122, 125, 131, 132, 134, 143, 145, 152, 155, 156, 162, 165, 172, 174, 205, 212, 223, 225, 226, 243, 244, 245, 246, 251, 252, 255, 261, 263, 265, 266, 271, 274, 306, 311, 315, 325, 331, 332, 343, 346, 351, 356, 364, 365, 371, 411, 412, 413, 423, 431, 432, 445, 446, 452, 454, 455, 462, 464, 465, 466, 503, 506, 516, 523, 526, 532, 546, 565, 606, 612, 624, 627, 631, 632, 654, 662, 664, 703, 712, 723, 731, 732, 734, 743, 754, 0, }

106 DCS codes

 All Data Structures Files Functions Variables Defines

Hamlib documentation for version 1.2.10 -- Tue Mar 23 02:05:48 2010
Project page: http://hamlib.org