Main Page | Modules | Class List | File List | File Members

Data API


Defines

#define TQSL_LOCATION_FIELD_TEXT   1
#define TQSL_LOCATION_FIELD_DDLIST   2
#define TQSL_LOCATION_FIELD_LIST   3
#define TQSL_LOCATION_FIELD_CHAR   1
#define TQSL_LOCATION_FIELD_INT   2

Functions

DLLEXPORT int tqsl_initStationLocationCapture (tQSL_Location *locp)
DLLEXPORT int tqsl_endStationLocationCapture (tQSL_Location *locp)
DLLEXPORT int tqsl_updateStationLocationCapture (tQSL_Location loc)
DLLEXPORT int tqsl_getStationLocationCapturePage (tQSL_Location loc, int *page)
DLLEXPORT int tqsl_setStationLocationCapturePage (tQSL_Location loc, int page)
DLLEXPORT int tqsl_nextStationLocationCapture (tQSL_Location loc)
DLLEXPORT int tqsl_prevStationLocationCapture (tQSL_Location loc)
DLLEXPORT int tqsl_hasNextStationLocationCapture (tQSL_Location loc, int *rval)
DLLEXPORT int tqsl_hasPrevStationLocationCapture (tQSL_Location loc, int *rval)
DLLEXPORT int tqsl_saveStationLocationCapture (tQSL_Location loc, int overwrite)
DLLEXPORT int tqsl_getStationLocationCaptureName (tQSL_Location loc, char *namebuf, int bufsiz)
DLLEXPORT int tqsl_setStationLocationCaptureName (tQSL_Location loc, const char *name)
DLLEXPORT int tqsl_getNumStationLocations (tQSL_Location loc, int *nloc)
DLLEXPORT int tqsl_getStationLocationName (tQSL_Location loc, int idx, char *buf, int bufsiz)
DLLEXPORT int tqsl_getStationLocationCallSign (tQSL_Location loc, int idx, char *buf, int bufsiz)
DLLEXPORT int tqsl_getStationLocation (tQSL_Location *loc, const char *name)
DLLEXPORT int tqsl_deleteStationLocation (const char *name)
DLLEXPORT int tqsl_getNumLocationField (tQSL_Location loc, int *numf)
DLLEXPORT int tqsl_getLocationFieldDataLabelSize (tQSL_Location loc, int field_num, int *rval)
DLLEXPORT int tqsl_getLocationFieldDataLabel (tQSL_Location loc, int field_num, char *buf, int bufsiz)
DLLEXPORT int tqsl_getLocationFieldDataGABBISize (tQSL_Location loc, int field_num, int *rval)
DLLEXPORT int tqsl_getLocationFieldDataGABBI (tQSL_Location loc, int field_num, char *buf, int bufsiz)
DLLEXPORT int tqsl_getLocationFieldInputType (tQSL_Location loc, int field_num, int *type)
DLLEXPORT int tqsl_getLocationFieldDataType (tQSL_Location loc, int field_num, int *type)
DLLEXPORT int tqsl_getLocationFieldDataLength (tQSL_Location loc, int field_num, int *rval)
DLLEXPORT int tqsl_getLocationFieldCharData (tQSL_Location loc, int field_num, char *buf, int bufsiz)
DLLEXPORT int tqsl_getLocationFieldIntData (tQSL_Location loc, int field_num, int *dat)
DLLEXPORT int tqsl_getLocationFieldIndex (tQSL_Location loc, int field_num, int *dat)
DLLEXPORT int tqsl_getNumLocationFieldListItems (tQSL_Location loc, int field_num, int *rval)
DLLEXPORT int tqsl_getLocationFieldListItem (tQSL_Location loc, int field_num, int item_idx, char *buf, int bufsiz)
DLLEXPORT int tqsl_setLocationFieldCharData (tQSL_Location loc, int field_num, const char *buf)
DLLEXPORT int tqsl_setLocationFieldIntData (tQSL_Location loc, int field_num, int dat)
DLLEXPORT int tqsl_setLocationFieldIndex (tQSL_Location loc, int field_num, int dat)
DLLEXPORT int tqsl_getLocationFieldChanged (tQSL_Location loc, int field_num, int *changed)
DLLEXPORT int tqsl_getLocationCallSign (tQSL_Location loc, char *buf, int bufsiz)
DLLEXPORT int tqsl_getLocationDXCCEntity (tQSL_Location loc, int *dxcc)
DLLEXPORT int tqsl_getNumDXCCEntity (int *number)
DLLEXPORT int tqsl_getDXCCEntity (int index, int *number, const char **name)
DLLEXPORT int tqsl_getDXCCEntityName (int number, const char **name)
DLLEXPORT int tqsl_getNumBand (int *number)
DLLEXPORT int tqsl_getBand (int index, const char **name, const char **spectrum, int *low, int *high)
DLLEXPORT int tqsl_getNumMode (int *number)
DLLEXPORT int tqsl_getMode (int index, const char **mode, const char **group)
DLLEXPORT int tqsl_getNumPropagationMode (int *number)
DLLEXPORT int tqsl_getPropagationMode (int index, const char **name, const char **descrip)
DLLEXPORT int tqsl_getNumSatellite (int *number)
DLLEXPORT int tqsl_getSatellite (int index, const char **name, const char **descrip, tQSL_Date *start, tQSL_Date *end)
DLLEXPORT int tqsl_clearCabrilloMap ()
DLLEXPORT int tqsl_setCabrilloMapEntry (const char *contest, int field, int contest_type)
DLLEXPORT int tqsl_getCabrilloMapEntry (const char *contest, int *fieldnum, int *contest_type)
DLLEXPORT int tqsl_clearADIFModes ()
DLLEXPORT int tqsl_setADIFMode (const char *adif_item, const char *mode)
DLLEXPORT int tqsl_getADIFMode (const char *adif_item, char *mode, int nmode)
DLLEXPORT const char * tqsl_getGABBItCERT (tQSL_Cert cert, int uid)
DLLEXPORT const char * tqsl_getGABBItSTATION (tQSL_Location loc, int uid, int certuid)
DLLEXPORT const char * tqsl_getGABBItCONTACT (tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *qso, int stationuid)

Detailed Description

The Data API is used to form data into TrustedQSL records. A TrustedQSL record consists of a station record and a QSO record. Together, the two records fully describe one station's end of the QSO -- just as a paper QSL card does.

The station record contains the callsign and geographic location of the station submitting the QSO record. The library manages the station records. The tqsl_xxxStationLocationCapture functions are used to generate and save a station record. The intent is to provide an interface that makes a step-by-step system (such as a GUI "wizard") easily implemented.

The tqsl_getStationLocation() function is used to retrieve station records.

With the necessary station location available, a signed GABBI output file can be generated using the tqsl_getGABBIxxxxx functions:

The GABBI format requires that the tCERT record contain an integer identifier that is unique within the GABBI file. Similarly, each tSTATION record must contain a unique identifier. Aditionally, the tSTATION record must reference the identifier of a preceding tCERT record. Finally, each tCONTACT record must reference a preceding tSTATION record. (A GABBI processor uses these identifiers and references to tie the station and contact records together and to verify their signature via the certificate.) It is the responsibility of the caller to supply these identifiers and to ensure that the supplied references match the tQSL_Cert and tQSL_Location used to create the referenced GABBI records.

Station Location Generation

The station-location generation process involves determining the values for a number of station-location parameters. Normally this will be done by prompting the user for the values. The responses given by the user may determine which later fields are required. For example, if the user indicates that the DXCC entity is UNITED STATES, a later field would ask for the US state. This field would not be required if the DXCC entity were not in the US.

To accommodate the dynamic nature of the field requirements, the fields are ordered such that dependent fields are queried after the field(s) on which they depend. To make this process acceptable in a GUI system, the fields are grouped into pages, where multiple fields may be displayed on the same page. The grouping is such that which fields are within the page is not dependent on any of the values of the fields within the page. That is, a page of fields contains the same fields no matter what value any of the fields contains. (However, the values of fields within the page can depend on the values of fields that precede them in the page.)

Here is a brief overview of the sequence of events involved in generating a station location interactively, one field at a time:

1) Call tqsl_initStationLocationCapture() (new location) or tqsl_getStationLocation() (existing location).

2) For field from 0 to tqsl_getNumLocationField():

3) If tqsl_hasNextStationLocationCapture() returns 1, call tqsl_nextStationLocationCapture() and go back to step 2.

In the case of a GUI system, you'll probably want to display the fields in pages. The sequence of events is a bit different:

1) Call tqsl_initStationLocationCapture() (new location) or tqsl_getStationLocation() (existing location).

2) For field from 0 to tqsl_getNumLocationField(),

3) Each time the user changes a field, call tqsl_updateStationLocationCapture(). This may change the allowable selection for fields that follow the field the user changed, so the control for each of those fields should be updated as in step 2.

4) Once the user has completed entries for the page, if tqsl_hasNextStationLocationCapture() returns 1, call tqsl_nextStationLocationCapture() and go back to step 2.

N.B. The first two fields in the station-location capture process are always call sign and DXCC entity, in that order. As a practical matter, these two fields must match the corresponding fields in the available certificates. The library will therefore constrain the values of these fields to match what's available in the certificate store. See Certificate Handling API.


Function Documentation

DLLEXPORT int tqsl_clearADIFModes  ) 
 

Clear the map of ADIF modes

DLLEXPORT int tqsl_clearCabrilloMap  ) 
 

Clear the map of Cabrillo contests.

DLLEXPORT int tqsl_deleteStationLocation const char *  name  ) 
 

Remove the stored station location by name.

DLLEXPORT int tqsl_endStationLocationCapture tQSL_Location *  locp  ) 
 

Release the station-location resources. This should be called for any tQSL_Location that was initialized via tqsl_initStationLocationCapture() or tqsl_getStationLocation()

DLLEXPORT int tqsl_getADIFMode const char *  adif_item,
char *  mode,
int  nmode
 

Map an ADIF mode to its TQSL equivalent.

DLLEXPORT int tqsl_getBand int  index,
const char **  name,
const char **  spectrum,
int *  low,
int *  high
 

Get a band by its index.

name - The GAABI name of the band. spectrum - HF | VHF | UHF low - The low end of the band in kHz (HF) or MHz (VHF/UHF) high - The low high of the band in kHz (HF) or MHz (VHF/UHF)

Note: spectrum, low and/or high may be NULL.

DLLEXPORT int tqsl_getCabrilloMapEntry const char *  contest,
int *  fieldnum,
int *  contest_type
 

Get the mapping of a Cabrillo contest name (as found in the CONTEST line of a Cabrillo file) to a call-worked field number and the contest type.

fieldnum will be set to 0 if the contest name isn't in the Cabrillo map. Otherwise it is set to the QSO line field number of the call-worked field, with field counting starting at 1.

contest_type may be NULL. If not, it is set to the Cabrillo contest type (TQSL_CABRILLO_HF or TQSL_CABRILLO_VHF), defined in cabrillo.h.

DLLEXPORT int tqsl_getDXCCEntity int  index,
int *  number,
const char **  name
 

Get a DXCC entity from the list of DXCC entities by its index.

DLLEXPORT int tqsl_getDXCCEntityName int  number,
const char **  name
 

Get the name of a DXCC Entity by its DXCC number.

DLLEXPORT const char* tqsl_getGABBItCERT tQSL_Cert  cert,
int  uid
 

Get a GABBI record that contains the certificate.

uid is the value for the CERT_UID field

Returns the NULL pointer on error.

N.B. On systems that distinguish text-mode files from binary-mode files, notably Windows, the GABBI records should be written in binary mode.

DLLEXPORT const char* tqsl_getGABBItCONTACT tQSL_Cert  cert,
tQSL_Location  loc,
TQSL_QSO_RECORD qso,
int  stationuid
 

Get a GABBI record that contains the QSO data.

  • uid is the value of the associated STATION_UID field.
N.B.: If cert is not initialized for signing (see tqsl_beginSigning()) the function will return with a TQSL_SIGNINIT_ERROR error.

Returns the NULL pointer on error.

N.B. On systems that distinguish text-mode files from binary-mode files, notably Windows, the GABBI records should be written in binary mode.

DLLEXPORT const char* tqsl_getGABBItSTATION tQSL_Location  loc,
int  uid,
int  certuid
 

Get a GABBI record that contains the Staion Location data.

  • uid is the value for the STATION_UID field.
  • certuid is the value of the asociated CERT_UID field.
Returns the NULL pointer on error.

N.B. On systems that distinguish text-mode files from binary-mode files, notably Windows, the GABBI records should be written in binary mode.

DLLEXPORT int tqsl_getLocationCallSign tQSL_Location  loc,
char *  buf,
int  bufsiz
 

Get the call sign from the station location.

DLLEXPORT int tqsl_getLocationDXCCEntity tQSL_Location  loc,
int *  dxcc
 

Get the DXCC entity from the station location.

DLLEXPORT int tqsl_getLocationFieldChanged tQSL_Location  loc,
int  field_num,
int *  changed
 

Get the changed status of a field. The changed flag is set to 1 if the field's pick list was changed during the last call to tqsl_updateStationLocationCapture or zero if the list was not changed.

DLLEXPORT int tqsl_getLocationFieldCharData tQSL_Location  loc,
int  field_num,
char *  buf,
int  bufsiz
 

Get the character data from the specified field.

If the field input type (see tqsl_getLocationFieldInputType()) is TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, this will return the text of the selected item.

DLLEXPORT int tqsl_getLocationFieldDataGABBI tQSL_Location  loc,
int  field_num,
char *  buf,
int  bufsiz
 

Get the GABBI name of the specified field

DLLEXPORT int tqsl_getLocationFieldDataGABBISize tQSL_Location  loc,
int  field_num,
int *  rval
 

Get the size of the GABBI name of the specified field

DLLEXPORT int tqsl_getLocationFieldDataLabel tQSL_Location  loc,
int  field_num,
char *  buf,
int  bufsiz
 

Get the label for the specified field

DLLEXPORT int tqsl_getLocationFieldDataLabelSize tQSL_Location  loc,
int  field_num,
int *  rval
 

Get the number of characters in the label for the specified field

DLLEXPORT int tqsl_getLocationFieldDataLength tQSL_Location  loc,
int  field_num,
int *  rval
 

Get the length of the input field data.

DLLEXPORT int tqsl_getLocationFieldDataType tQSL_Location  loc,
int  field_num,
int *  type
 

Get the data type of the input field.

type will be either TQSL_LOCATION_FIELD_CHAR or TQSL_LOCATION_FIELD_INT

DLLEXPORT int tqsl_getLocationFieldIndex tQSL_Location  loc,
int  field_num,
int *  dat
 

If the field input type (see tqsl_getLocationFieldInputType()) is TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, gets the index of the selected list item.

DLLEXPORT int tqsl_getLocationFieldInputType tQSL_Location  loc,
int  field_num,
int *  type
 

Get the input type of the input field.

type will be one of TQSL_LOCATION_FIELD_TEXT, TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST

DLLEXPORT int tqsl_getLocationFieldIntData tQSL_Location  loc,
int  field_num,
int *  dat
 

Get the integer data from the specified field.

This is only meaningful if the field data type (see tqsl_getLocationFieldDataType()) is TQSL_LOCATION_FIELD_INT.

DLLEXPORT int tqsl_getLocationFieldListItem tQSL_Location  loc,
int  field_num,
int  item_idx,
char *  buf,
int  bufsiz
 

Get the text of a specified item of a specified field

DLLEXPORT int tqsl_getMode int  index,
const char **  mode,
const char **  group
 

Get a mode by its index.

mode - The GAABI mode name group - CW | PHONE | IMAGE | DATA

Note: group may be NULL.

DLLEXPORT int tqsl_getNumBand int *  number  ) 
 

Get the number of Band entries in the Band list

DLLEXPORT int tqsl_getNumDXCCEntity int *  number  ) 
 

Get the number of DXCC entities in the master DXCC list.

DLLEXPORT int tqsl_getNumLocationField tQSL_Location  loc,
int *  numf
 

Get the number of fields on the current station location page

DLLEXPORT int tqsl_getNumLocationFieldListItems tQSL_Location  loc,
int  field_num,
int *  rval
 

Get the number of items in the specified field's pick list.

DLLEXPORT int tqsl_getNumMode int *  number  ) 
 

Get the number of Mode entries in the Mode list

DLLEXPORT int tqsl_getNumPropagationMode int *  number  ) 
 

Get the number of Propagation Mode entries in the Propagation Mode list

DLLEXPORT int tqsl_getNumSatellite int *  number  ) 
 

Get the number of Satellite entries in the Satellite list

DLLEXPORT int tqsl_getNumStationLocations tQSL_Location  loc,
int *  nloc
 

Get the number of saved station locations

DLLEXPORT int tqsl_getPropagationMode int  index,
const char **  name,
const char **  descrip
 

Get a propagation mode by its index.

name - The GAABI propagation mode name descrip - Text description of the propagation mode

Note: descrip may be NULL.

DLLEXPORT int tqsl_getSatellite int  index,
const char **  name,
const char **  descrip,
tQSL_Date start,
tQSL_Date end
 

Get a satellite by its index.

name - The GAABI satellite name descrip - Text description of the satellite start - The date the satellite entered service end - The last date the satellite was in service

Note: descrip, start and/or end may be NULL.

DLLEXPORT int tqsl_getStationLocation tQSL_Location *  loc,
const char *  name
 

Retrieve a saved station location. Once finished wih the station location, tqsl_endStationLocationCapture() should be called to release resources.

DLLEXPORT int tqsl_getStationLocationCallSign tQSL_Location  loc,
int  idx,
char *  buf,
int  bufsiz
 

Get the call sign from the station location

DLLEXPORT int tqsl_getStationLocationCaptureName tQSL_Location  loc,
char *  namebuf,
int  bufsiz
 

Get the name of the station location

DLLEXPORT int tqsl_getStationLocationCapturePage tQSL_Location  loc,
int *  page
 

Get the current page number

DLLEXPORT int tqsl_getStationLocationName tQSL_Location  loc,
int  idx,
char *  buf,
int  bufsiz
 

Get the name of the specified (by idx) saved station location

DLLEXPORT int tqsl_hasNextStationLocationCapture tQSL_Location  loc,
int *  rval
 

Returns 1 (in rval) if there is a next page

DLLEXPORT int tqsl_hasPrevStationLocationCapture tQSL_Location  loc,
int *  rval
 

Returns 1 (in rval) if there is a previous page

DLLEXPORT int tqsl_initStationLocationCapture tQSL_Location *  locp  ) 
 

Begin the process of generating a station record

DLLEXPORT int tqsl_nextStationLocationCapture tQSL_Location  loc  ) 
 

Advance the page to the next one in the page sequence

DLLEXPORT int tqsl_prevStationLocationCapture tQSL_Location  loc  ) 
 

Return the page to the previous one in the page sequence.

DLLEXPORT int tqsl_saveStationLocationCapture tQSL_Location  loc,
int  overwrite
 

Save the station location data. Note that the name must have been set via tqsl_setStationLocationCaptureName if this is a new station location. If the overwrite parameter is zero and a station location of that name is already in existance, an error occurs with tQSL_Error set to TQSL_NAME_EXISTS.

DLLEXPORT int tqsl_setADIFMode const char *  adif_item,
const char *  mode
 

Set the mapping of an ADIF mode to a TQSL mode.

DLLEXPORT int tqsl_setCabrilloMapEntry const char *  contest,
int  field,
int  contest_type
 

Set the mapping of a Cabrillo contest name (as found in the CONTEST line of a Cabrillo file) to the QSO line call-worked field number and the contest type.

field can have a value of TQSL_MIN_CABRILLO_MAP_FIELD (cabrillo.h) or greater. Field number starts at 1.

contest_type must be TQSL_CABRILLO_HF or TQSL_CABRILLO_VHF, defined in cabrillo.h

DLLEXPORT int tqsl_setLocationFieldCharData tQSL_Location  loc,
int  field_num,
const char *  buf
 

Set the text data of a specified field.

DLLEXPORT int tqsl_setLocationFieldIndex tQSL_Location  loc,
int  field_num,
int  dat
 

If the field input type (see tqsl_getLocationFieldInputType()) is TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, sets the index of the selected list item.

DLLEXPORT int tqsl_setLocationFieldIntData tQSL_Location  loc,
int  field_num,
int  dat
 

Set the integer data of a specified field.

DLLEXPORT int tqsl_setStationLocationCaptureName tQSL_Location  loc,
const char *  name
 

Set the name of the station location

DLLEXPORT int tqsl_setStationLocationCapturePage tQSL_Location  loc,
int  page
 

Set the current page number. Typically, the page number will be 1 (the starting page) or a value obtained from tqsl_getStationLocationCapturePage().

DLLEXPORT int tqsl_updateStationLocationCapture tQSL_Location  loc  ) 
 

Update the pages based on the currently selected settings.


Generated on Tue Feb 22 08:15:36 2005 for TrustedQSL Library API by doxygen 1.3.4