This is the TrustedQSL project, which provides tools for digitally
signing Amateur Radio QSO records.
src: Source code and documentation for tqsllib, the TrustedQSL
apps: Source code for "tqsl" and "tqslcert" applications.
html: Various legacy documents
This document describes the changes to TrustedQSL since version 1.13 and
explains how applications can use TQSL in their applications.
Command Line Changes
Many applications use the 'tqsl' application in command line mode to sign
log files. There are several new capabilities added to command line operation
in 1.14. The first is that tqsl can now automatically sign and upload a log to
the LoTW site for the user. This allows your application to simply write
an adif file which is then processed and uploaded to LoTW without requiring
the application to read the output file and either upload it or tell your user
to upload it.
The command line parser in 1.14 has been rewritten and is less
forgiving of improperly formatted command lines.
Command Line Options
The following summarizes the command line options and what they do:
Usage: tqsl [-a <str>] [-d] [-l <str>] [-s] [-o <str>] [-u] [-x]
[-p <str>] [-q] [-v] [-h] [Input ADIF or Cabrillo log file to sign]
The following command line options may be specified on the command line:
-a <str> Specify dialog action - abort, all, compliant or ask
This option instructs TQSL on how to handle QSOs that do not appear to be
valid. There are many potential causes for invalid QSOs. Examples include QSOs
with dates outside the valid range for the certificate being used, QSOs
with invalid amateur callsigns, duplicate QSOs, and attempts to sign with an
This option specifies how tqsl should handle these exceptions. Using "-a ask"
instructs tqsl to use a dialog to ask the user how to proceed. This is the
default behavior if "-a" is not provided on the command line.
Using "-a abort" instructs tqsl to issue an error message when an exception
QSO is processed and immediately abort signing.
Using "-a compliant" instructs tqsl to sign the QSOs which are compliant
(not duplicates, in date range, and with valid callsigns) and ignore any
exception QSOs. This is the recommended behavior for command line applications
but is not the default action for compatibility reasons.
Using "-a all" instructs tqsl to process all QSOs, ignoring duplicates and
invalid callsigns. QSOs outside the range of valid dates for the selected
station certificate will not be signed, as they would not be accepted by
-d Suppress date range dialog
This option instructs tqsl to not ask the user to select a range of dates
for processing QSOs. If this is used, all QSOs in the input file will be
selected for processing. Command line tools will usually include this
option to suppress tqsl dialogs. However, this means that the logging
program is responsible for filtering QSOs before delivering them to tqsl.
-l <str> Select Station Location.
This option selects a station location. This is used for signing logs or
in conjunction with the "-s" option to define a location for editing.
-s Edit (if used with -l) or create Station Location
This option can be used to create a new Station Location (-s without -l) or
to edit an existing Station Location (when both -s and -l are provided).
-o <str> Output file name (defaults to input name minus extension plus .tq8)
This option instructs tqsl where the signed output file will be stored. If it
is not provided, the output file will be written to the same location as the
input file with the extension changed to ".tq8"
-u Upload after signing instead of saving
This option instructs tqsl to upload the log file after it is successfully
signed. The exit status from tqsl can be used by a logging program to determine
if the signing and upload succeeded:
0 - Success
1 - Cancelled, or no action (empty log)
2 - The log was rejected by the LoTW server
3 - The response from the LoTW server was unexpected
4 - An error occurred in tqsl
5 - An error occurred in tqsllib (invalid filename, bad file format)
-x Operate in batch mode, not menu-driven mode.
-q Operate in batch mode, not menu-driven mode.
If -x or -q are included on the command line, tqsl suppresses user dialogs
and sends error messages to standard error. A logging application is expected
to read this file and possibly display the contents to the user so they
can see the results of the command action. If these options are not included,
a calling application cannot distinguish between a successful signing and
one where a user cancels the signing.
-p <str> Password for the signing key
This option allows an application to provide the password for the private key
that will be used to sign the log file.
-v Display the version information and exit
-h Display command line help
These options allow the user to display the version number of tqsl or to
obtain help on the command line usage.
Command Line Usage
An application that uses the command line invokes the tqsl binary, optionally
providing a set of options that dictate how tqsl operates. Normally, such
an application should include the "-x" or "-q" options to indicate to tqsl
that application popups should be suppressed.
Errors discovered during the signing process are sent to the standard error
file. Callers would normally indicate where those messages should be sent
by adding "2> file.txt" to the command line used to run tqsl. This directs
the shell (Windows or Unix) to write the error messages to that file.
An example usage for signing a log would be
tqsl -q -l "K1MU home" -p "Insecure" -a compliant -u -d k1mu.adi 2>temp.txt
This indicates quiet mode (-a), selects a station location and a password,
indicates that only compliant QSOs will be written (-a), uploads to LoTW (-u),
suppresses date popups (-d), provides an input file (k1mu.adi), and finally
writes log messages to temp.txt. The logging program would read and process
that log once tqsl is done. An application would add "-o" to indicate where
tqsl should write the signed log if "-u" (upload) is not provided.
Command line applications are strongly encouraged to add "-a=compliant" to
their invocations of tqsl, and to consider storing and displaying the log
messages to their users.
Some logging applications directly call tqsllib functions to sign log files.
The application programming interface (API) to tqsllib has not changed in
ways that introduce incompatibilities, but there are additional API calls
which are necessary for applications to allow duplicate QSO processing to
After successful processing of a log, an application should call either
tqsl_convertCommit(conv) or tqsl_convertRollBack(conv) prior to calling
tqsl_endConverter() to signal that a log conversion has completed.
tqsl_converterCommit() indicates to tqsllib that the log has been successfully
processed and that the QSOs should be added to the duplicate detection
database. Calling tqsl_converterRollBack() indicates to tqsllib that the
log has not been successfully processed and that the QSO records should
not be added to the duplicate database. Simply adding the necessary call
before the converter is closed is enough to bring the application up to date.
Tqsllib 1.14 also adds a new call to allow an application to specify how
duplicate QSOs should be handled (tqsl_setConverterAllowDuplicates).
A minimal set of calls to permit an application to sign a log is the following.
Of course, error checking should be performed for each call.
tqsl_getLocationCallSign(loc, callsign, sizeof callsign);
tqsl_selectCertificates(&certlist, &ncerts, callsign, dxcc);
tqsl_beginADIFConverter(&conv, input_file, certlist, ncerts, loc);
write the GABBI header to the output file.
This is an ADIF-format record of the form
<TQSL_IDENT:nn>YourApp V1.0 Lib: V1.1 Config: V1.1 AllowDupes: false
Use tqsl_getVersion and tqsl_GetConfigVersion to determine the
tqsllib version and configuration file version.
while (cp = tqsl_getConverterGABBI(conv) != 0)
write the string pointed to by "cp" to your file
The tq8 files created by tqsl are compressed using zlib functions. You can
also submit uncompressed files using a .tq7 extension.