|
TrustedQSL Library API
|
Macros | |
| #define | TQSL_LOCATION_FIELD_TEXT 1 |
| Text type input field. | |
| #define | TQSL_LOCATION_FIELD_DDLIST 2 |
| Dropdown list input field. | |
| #define | TQSL_LOCATION_FIELD_LIST 3 |
| List type input field. | |
| #define | TQSL_LOCATION_FIELD_BADZONE 4 |
| Used to return zone selection errors. | |
| #define | TQSL_LOCATION_FIELD_CHAR 1 |
| Character field. | |
| #define | TQSL_LOCATION_FIELD_INT 2 |
| Integer field. | |
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.
| DLLEXPORT int CALLCONVENTION tqsl_clearADIFModes | ( | ) |
Clear the map of ADIF modes
| DLLEXPORT int CALLCONVENTION tqsl_clearCabrilloMap | ( | ) |
Clear the map of Cabrillo contests.
| DLLEXPORT int CALLCONVENTION tqsl_deleteStationLocation | ( | const char * | name | ) |
Remove the stored station location by name.
| DLLEXPORT int CALLCONVENTION 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 void CALLCONVENTION tqsl_freeDeletedLocationList | ( | char ** | list, |
| int | nloc | ||
| ) |
Free the list of restorable station locations.
| DLLEXPORT int CALLCONVENTION tqsl_freeStationDataEnc | ( | tQSL_StationDataEnc | sdata | ) |
Free the pointer returned by tqsl_getStationDataEnc(tQSL_StationDataEnc*)
| DLLEXPORT int CALLCONVENTION tqsl_getADIFMode | ( | const char * | adif_item, |
| char * | mode, | ||
| int | nmode | ||
| ) |
Map an ADIF mode to its TQSL equivalent.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getCallsignLocationInfo | ( | const char * | callsign, |
| char * | buf, | ||
| int | buflen | ||
| ) |
Retrieve the json results for a given callsign location Detail.
| DLLEXPORT int CALLCONVENTION tqsl_getDeletedStationLocations | ( | char *** | locp, |
| int * | nloc | ||
| ) |
Get the list of restorable station locations.
| DLLEXPORT int CALLCONVENTION tqsl_getDXCCEndDate | ( | int | number, |
| tQSL_Date * | d | ||
| ) |
Get the end date of a DXCC Entity by its DXCC number.
| DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntity | ( | int | index, |
| int * | number, | ||
| const char ** | name | ||
| ) |
Get a DXCC entity from the list of DXCC entities by its index.
| DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntityName | ( | int | number, |
| const char ** | name | ||
| ) |
Get the name of a DXCC Entity by its DXCC number.
| DLLEXPORT int CALLCONVENTION tqsl_getDXCCStartDate | ( | int | number, |
| tQSL_Date * | d | ||
| ) |
Get the start date of a DXCC Entity by its DXCC number.
| DLLEXPORT int CALLCONVENTION tqsl_getDXCCZoneMap | ( | int | number, |
| const char ** | zonemap | ||
| ) |
Get the zonemap of a DXCC Entity by its DXCC number.
| DLLEXPORT const char* CALLCONVENTION 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* CALLCONVENTION tqsl_getGABBItCONTACT | ( | tQSL_Cert | cert, |
| tQSL_Location | loc, | ||
| TQSL_QSO_RECORD * | qso, | ||
| int | stationuid | ||
| ) |
Get a GABBI record that contains the QSO data.
stationuid 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* CALLCONVENTION tqsl_getGABBItCONTACTData | ( | tQSL_Cert | cert, |
| tQSL_Location | loc, | ||
| TQSL_QSO_RECORD * | qso, | ||
| int | stationuid, | ||
| char * | signdata, | ||
| int | sdlen | ||
| ) |
Get a GABBI record that contains the QSO data along with the associated signdata (QSO data signed to validate the QSO).
stationuid 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* CALLCONVENTION 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 CALLCONVENTION tqsl_getLocationCallSign | ( | tQSL_Location | loc, |
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get the call sign from the station location.
| DLLEXPORT int CALLCONVENTION tqsl_getLocationDXCCEntity | ( | tQSL_Location | loc, |
| int * | dxcc | ||
| ) |
Get the DXCC entity from the station location.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getLocationFieldDataGABBI | ( | tQSL_Location | loc, |
| int | field_num, | ||
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get the GABBI name of the specified field
| DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBISize | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int * | rval | ||
| ) |
Get the size of the GABBI name of the specified field
| DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabel | ( | tQSL_Location | loc, |
| int | field_num, | ||
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get the label for the specified field
| DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabelSize | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int * | rval | ||
| ) |
Get the number of characters in the label for the specified field
| DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLength | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int * | rval | ||
| ) |
Get the length of the input field data.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_getLocationFieldFlags | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int * | flags | ||
| ) |
Get the flags for the input field.
flags will be either TQSL_LOCATION_FIELD_UPPER Field is to be uppercased on input TQSL_LOCATION_FIELD_MUSTSEL Value must be selected TQSL_LOCATION_FIELD_SELNXT Value must be selected to allow Next/Finish
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getLocationQSODetails | ( | tQSL_Location | locp, |
| char * | buf, | ||
| int | buflen | ||
| ) |
Get the QSO details in canonical form.
| DLLEXPORT int CALLCONVENTION tqsl_getLocationStationDetails | ( | tQSL_Location | locp, |
| char * | buf, | ||
| int | buflen | ||
| ) |
Get the station location details in canonical form.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_getNumBand | ( | int * | number | ) |
Get the number of Band entries in the Band list
| DLLEXPORT int CALLCONVENTION tqsl_getNumDXCCEntity | ( | int * | number | ) |
Get the number of DXCC entities in the master DXCC list.
| DLLEXPORT int CALLCONVENTION tqsl_getNumLocationField | ( | tQSL_Location | loc, |
| int * | numf | ||
| ) |
Get the number of fields on the current station location page
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_LISTGet the number of fields on the current station location page
| DLLEXPORT int CALLCONVENTION tqsl_getNumLocationFieldListItems | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int * | rval | ||
| ) |
Get the number of items in the specified field's pick list.
| DLLEXPORT int CALLCONVENTION tqsl_getNumMode | ( | int * | number | ) |
Get the number of Mode entries in the Mode list
| DLLEXPORT int CALLCONVENTION tqsl_getNumPropagationMode | ( | int * | number | ) |
Get the number of Propagation Mode entries in the Propagation Mode list
| DLLEXPORT int CALLCONVENTION tqsl_getNumSatellite | ( | int * | number | ) |
Get the number of Satellite entries in the Satellite list
| DLLEXPORT int CALLCONVENTION tqsl_getNumStationLocationCapturePages | ( | tQSL_Location | loc, |
| int * | npages | ||
| ) |
Return the number of station location capture pages.
| DLLEXPORT int CALLCONVENTION tqsl_getNumStationLocations | ( | tQSL_Location | loc, |
| int * | nloc | ||
| ) |
Get the number of saved station locations
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION 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 CALLCONVENTION tqsl_getStationDataEnc | ( | tQSL_StationDataEnc * | sdata | ) |
Return the contents of the station data file as a byte stream. The caller is required to tqsl_freeStationDataEnc() this pointer when done with it.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_getStationLocationCallSign | ( | tQSL_Location | loc, |
| int | idx, | ||
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get the call sign from the station location
| DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCaptureName | ( | tQSL_Location | loc, |
| char * | namebuf, | ||
| int | bufsiz | ||
| ) |
Get the name of the station location
| DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCapturePage | ( | tQSL_Location | loc, |
| int * | page | ||
| ) |
Get the current page number
| DLLEXPORT int CALLCONVENTION tqsl_getStationLocationErrors | ( | tQSL_Location | loc, |
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get any errors returned from parsing the selected station location. This should be called after tqsl_getStationLocation to determine if any of the existing fields failed validation. Currently only zone data is validated here, but future validations for things like properly formatted grid squares is likely.
| DLLEXPORT int CALLCONVENTION tqsl_getStationLocationField | ( | tQSL_Location | locp, |
| const char * | name, | ||
| char * | namebuf, | ||
| int | bufsize | ||
| ) |
Get a named field from the station location
| DLLEXPORT int CALLCONVENTION tqsl_getStationLocationName | ( | tQSL_Location | loc, |
| int | idx, | ||
| char * | buf, | ||
| int | bufsiz | ||
| ) |
Get the name of the specified (by idx) saved station location
| DLLEXPORT int CALLCONVENTION tqsl_hasNextStationLocationCapture | ( | tQSL_Location | loc, |
| int * | rval | ||
| ) |
Returns 1 (in rval) if there is a next page
| DLLEXPORT int CALLCONVENTION tqsl_hasPrevStationLocationCapture | ( | tQSL_Location | loc, |
| int * | rval | ||
| ) |
Returns 1 (in rval) if there is a previous page
| DLLEXPORT int CALLCONVENTION tqsl_initStationLocationCapture | ( | tQSL_Location * | locp | ) |
Begin the process of generating a station record
| DLLEXPORT int CALLCONVENTION tqsl_mergeStationLocations | ( | const char * | locdata | ) |
Merge saved location data with existing
| DLLEXPORT int CALLCONVENTION tqsl_nextStationLocationCapture | ( | tQSL_Location | loc | ) |
Advance the page to the next one in the page sequence
| DLLEXPORT int CALLCONVENTION tqsl_prevStationLocationCapture | ( | tQSL_Location | loc | ) |
Return the page to the previous one in the page sequence.
| DLLEXPORT int CALLCONVENTION tqsl_restoreStationLocation | ( | const char * | name | ) |
Restore the deleted station location by name.
| DLLEXPORT int CALLCONVENTION tqsl_saveCallsignLocationInfo | ( | const char * | callsign, |
| const char * | json | ||
| ) |
Save the json results for a given callsign location Detail.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_setADIFMode | ( | const char * | adif_item, |
| const char * | mode | ||
| ) |
Set the mapping of an ADIF mode to a TQSL mode.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_setLocationCallSign | ( | tQSL_Location | loc, |
| const char * | buf | ||
| ) |
Set the call sign for the station location.
| DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldCharData | ( | tQSL_Location | loc, |
| int | field_num, | ||
| const char * | buf | ||
| ) |
Set the text data of a specified field.
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_setLocationFieldIntData | ( | tQSL_Location | loc, |
| int | field_num, | ||
| int | dat | ||
| ) |
Set the integer data of a specified field.
| DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCaptureName | ( | tQSL_Location | loc, |
| const char * | name | ||
| ) |
Set the name of the station location
| DLLEXPORT int CALLCONVENTION 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 CALLCONVENTION tqsl_setStationLocationCertFlags | ( | tQSL_Location | loc, |
| int | flags | ||
| ) |
Set the certificate flags used in a location page. This is used to enable expired certs (or disable).
| DLLEXPORT int CALLCONVENTION tqsl_updateStationLocationCapture | ( | tQSL_Location | loc | ) |
Update the pages based on the currently selected settings.
1.8.10