Main Page   Modules   Compound 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

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

int tqsl_clearADIFModes ( )
 

Clear the map of ADIF modes

int tqsl_clearCabrilloMap ( )
 

Clear the map of Cabrillo contests.

int tqsl_deleteStationLocation ( const char * name )
 

Remove the stored station location by name.

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()

int tqsl_getADIFMode ( const char * adif_item,
char * mode,
int nmode )
 

Map an ADIF mode to its TQSL equivalent.

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.

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.

int tqsl_getDXCCEntity ( int index,
int * number,
const char ** name )
 

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

int tqsl_getDXCCEntityName ( int number,
const char ** name )
 

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

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.

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.

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.

int tqsl_getLocationCallSign ( tQSL_Location loc,
char * buf,
int bufsiz )
 

Get the call sign from the station location.

int tqsl_getLocationDXCCEntity ( tQSL_Location loc,
int * dxcc )
 

Get the DXCC entity from the station location.

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.

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.

int tqsl_getLocationFieldDataGABBI ( tQSL_Location loc,
int field_num,
char * buf,
int bufsiz )
 

Get the GABBI name of the specified field

int tqsl_getLocationFieldDataGABBISize ( tQSL_Location loc,
int field_num,
int * rval )
 

Get the size of the GABBI name of the specified field

int tqsl_getLocationFieldDataLabel ( tQSL_Location loc,
int field_num,
char * buf,
int bufsiz )
 

Get the label for the specified field

int tqsl_getLocationFieldDataLabelSize ( tQSL_Location loc,
int field_num,
int * rval )
 

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

int tqsl_getLocationFieldDataLength ( tQSL_Location loc,
int field_num,
int * rval )
 

Get the length of the input field data.

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

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.

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

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.

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

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.

int tqsl_getNumBand ( int * number )
 

Get the number of Band entries in the Band list

int tqsl_getNumDXCCEntity ( int * number )
 

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

int tqsl_getNumLocationField ( tQSL_Location loc,
int * numf )
 

Get the number of fields on the current station location page

int tqsl_getNumLocationFieldListItems ( tQSL_Location loc,
int field_num,
int * rval )
 

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

int tqsl_getNumMode ( int * number )
 

Get the number of Mode entries in the Mode list

int tqsl_getNumPropagationMode ( int * number )
 

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

int tqsl_getNumSatellite ( int * number )
 

Get the number of Satellite entries in the Satellite list

int tqsl_getNumStationLocations ( tQSL_Location loc,
int * nloc )
 

Get the number of saved station locations

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.

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.

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.

int tqsl_getStationLocationCallSign ( tQSL_Location loc,
int idx,
char * buf,
int bufsiz )
 

Get the call sign from the station location

int tqsl_getStationLocationCaptureName ( tQSL_Location loc,
char * namebuf,
int bufsiz )
 

Get the name of the station location

int tqsl_getStationLocationCapturePage ( tQSL_Location loc,
int * page )
 

Get the current page number

int tqsl_getStationLocationName ( tQSL_Location loc,
int idx,
char * buf,
int bufsiz )
 

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

int tqsl_hasNextStationLocationCapture ( tQSL_Location loc,
int * rval )
 

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

int tqsl_hasPrevStationLocationCapture ( tQSL_Location loc,
int * rval )
 

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

int tqsl_initStationLocationCapture ( tQSL_Location * locp )
 

Begin the process of generating a station record

int tqsl_nextStationLocationCapture ( tQSL_Location loc )
 

Advance the page to the next one in the page sequence

int tqsl_prevStationLocationCapture ( tQSL_Location loc )
 

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

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.

int tqsl_setADIFMode ( const char * adif_item,
const char * mode )
 

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

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

int tqsl_setLocationFieldCharData ( tQSL_Location loc,
int field_num,
const char * buf )
 

Set the text data of a specified field.

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.

int tqsl_setLocationFieldIntData ( tQSL_Location loc,
int field_num,
int dat )
 

Set the integer data of a specified field.

int tqsl_setStationLocationCaptureName ( tQSL_Location loc,
const char * name )
 

Set the name of the station location

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().

int tqsl_updateStationLocationCapture ( tQSL_Location loc )
 

Update the pages based on the currently selected settings.


Generated at Sun Oct 12 10:02:48 2003 for TrustedQSL Library API by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001