TrustedQSL Library API
Typedefs | Functions
Converter API

Typedefs

typedef void * tQSL_Converter
 

Functions

DLLEXPORT int CALLCONVENTION tqsl_beginConverter (tQSL_Converter *convp)
 
DLLEXPORT int CALLCONVENTION tqsl_beginADIFConverter (tQSL_Converter *conv, const char *filename, tQSL_Cert *certs, int ncerts, tQSL_Location loc)
 
DLLEXPORT int CALLCONVENTION tqsl_beginCabrilloConverter (tQSL_Converter *conv, const char *filename, tQSL_Cert *certs, int ncerts, tQSL_Location loc)
 
DLLEXPORT int CALLCONVENTION tqsl_endConverter (tQSL_Converter *conv)
 
DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowBadCall (tQSL_Converter conv, int allow)
 
DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowDuplicates (tQSL_Converter convp, int allow)
 
DLLEXPORT int CALLCONVENTION tqsl_setConverterAppName (tQSL_Converter convp, const char *app)
 
DLLEXPORT int CALLCONVENTION tqsl_converterRollBack (tQSL_Converter convp)
 
DLLEXPORT int CALLCONVENTION tqsl_converterCommit (tQSL_Converter convp)
 
DLLEXPORT int CALLCONVENTION tqsl_getDuplicateRecords (tQSL_Converter convp, char *key, char *data, int keylen)
 
DLLEXPORT int CALLCONVENTION tqsl_getDuplicateRecordsV2 (tQSL_Converter convp, char *key, char *data, int keylen)
 
DLLEXPORT int CALLCONVENTION tqsl_putDuplicateRecord (tQSL_Converter convp, const char *key, const char *data, int keylen)
 
DLLEXPORT int CALLCONVENTION tqsl_setADIFConverterDateFilter (tQSL_Converter conv, tQSL_Date *start, tQSL_Date *end)
 
DLLEXPORT const char *CALLCONVENTION tqsl_getConverterGABBI (tQSL_Converter conv)
 
DLLEXPORT int CALLCONVENTION tqsl_getConverterCert (tQSL_Converter conv, tQSL_Cert *certp)
 
DLLEXPORT int CALLCONVENTION tqsl_getConverterLine (tQSL_Converter conv, int *lineno)
 
DLLEXPORT const char *CALLCONVENTION tqsl_getConverterRecordText (tQSL_Converter conv)
 

Detailed Description

The Converter API provides the capability of converting Cabrillo and ADIF files to GABBI output.

Typedef Documentation

typedef void* tQSL_Converter

Opaque converter type used by applications to access conversion functions

Function Documentation

DLLEXPORT int CALLCONVENTION tqsl_beginADIFConverter ( tQSL_Converter conv,
const char *  filename,
tQSL_Cert certs,
int  ncerts,
tQSL_Location  loc 
)

Initiates the conversion process for an ADIF file.

certs and ncerts define a set of certificates that are available to the converter for signing records. Typically, this list will be obtained by calling tqsl_selectCertificates().

tqsl_endConverter() should be called to free the resources when the conversion is finished.

DLLEXPORT int CALLCONVENTION tqsl_beginCabrilloConverter ( tQSL_Converter conv,
const char *  filename,
tQSL_Cert certs,
int  ncerts,
tQSL_Location  loc 
)

Initiates the conversion process for a Cabrillo file.

certs and ncerts define a set of certificates that are available to the converter for signing records. Typically, this list will be obtained by calling tqsl_selectCertificates().

tqsl_endConverter() should be called to free the resources when the conversion is finished.

DLLEXPORT int CALLCONVENTION tqsl_beginConverter ( tQSL_Converter convp)

Create a simple converter object

Allocates resources for converting logs and processing duplicate records.

DLLEXPORT int CALLCONVENTION tqsl_converterCommit ( tQSL_Converter  convp)

Commits insertions into the duplicates database.

This is called when a log is created normally and without issue, and so the presumption is that we are "done" with these QSOs.

DLLEXPORT int CALLCONVENTION tqsl_converterRollBack ( tQSL_Converter  convp)

Roll back insertions into the duplicates database.

This is called when cancelling creating a log, and causes any records added to the duplicates database to be removed so re-processing that log does not cause the records to be mis-marked as duplicates.

DLLEXPORT int CALLCONVENTION tqsl_endConverter ( tQSL_Converter conv)

End the conversion process by freeing the used resources.

DLLEXPORT int CALLCONVENTION tqsl_getConverterCert ( tQSL_Converter  conv,
tQSL_Cert certp 
)

Get the certificate used to sign the most recent QSO record.

DLLEXPORT const char* CALLCONVENTION tqsl_getConverterGABBI ( tQSL_Converter  conv)

This is the main converter function. It returns a single GABBI record.

Returns the NULL pointer on error or EOF. (Test tQSL_Error to determine which.)

tQSL_Error is set to TQSL_DATE_OUT_OF_RANGE if QSO date range checking is active and the QSO date is outside the specified range. This is a non-fatal error.

tQSL_Error is set to TQSL_DUPLICATE_QSO if the QSO has already been processed on the current computer.

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

N.B. If the selected certificate has not been initialized for signing via tqsl_beginSigning(), this function will return a TQSL_SIGNINIT_ERROR. The cert that caused the error can be obtained via tqsl_getConverterCert(), initialized for signing, and then this function can be called again. No data records will be lost in this process.

DLLEXPORT int CALLCONVENTION tqsl_getConverterLine ( tQSL_Converter  conv,
int *  lineno 
)

Get the input-file line number last read by the converter, starting at line 1.

DLLEXPORT const char* CALLCONVENTION tqsl_getConverterRecordText ( tQSL_Converter  conv)

Get the text of the last record read by the converter.

Returns NULL on error.

DLLEXPORT int CALLCONVENTION tqsl_getDuplicateRecords ( tQSL_Converter  convp,
char *  key,
char *  data,
int  keylen 
)

Bulk read the duplicate DB records

This is called to retrieve the QSO records from the dupe database. It returns the key/value pair upon each call. Return -1 for end of file, 0 for success, 1 for errors.

DLLEXPORT int CALLCONVENTION tqsl_getDuplicateRecordsV2 ( tQSL_Converter  convp,
char *  key,
char *  data,
int  keylen 
)

Bulk read the duplicate DB records

This is called to retrieve the QSO records from the dupe database. It returns the key/value pair upon each call. Return -1 for end of file, 0 for success, 1 for errors. V2 expects a 256 byte buffer for the "data" string.

DLLEXPORT int CALLCONVENTION tqsl_putDuplicateRecord ( tQSL_Converter  convp,
const char *  key,
const char *  data,
int  keylen 
)

Bulk write duplicate DB records

This is called to store a QSO record into the dupe database.

Return -1 for duplicate insertion, 0 for success, 1 for errors.

DLLEXPORT int CALLCONVENTION tqsl_setADIFConverterDateFilter ( tQSL_Converter  conv,
tQSL_Date start,
tQSL_Date end 
)

Set QSO date filtering in the converter.

If start points to a valid date, QSOs prior to that date will be ignored by the converter. Similarly, if end points to a valid date, QSOs after that date will be ignored. Either or both may be NULL (or point to an invalid date) to disable date filtering for the respective range.

DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowBadCall ( tQSL_Converter  conv,
int  allow 
)

Configure the converter to allow (allow != 0) or disallow (allow == 0) nonamateur call signs in the CALL field. (Note: the test for validity is fairly trivial and will allow some nonamateur calls to get through, but it does catch most common errors.)

allow defaults to 0 when tqsl_beginADIFConverter or tqsl_beginCabrilloConverter is called.

DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowDuplicates ( tQSL_Converter  convp,
int  allow 
)

Configure the converter to allow (allow != 0) or disallow (allow == 0) duplicate QSOs in a signed log. Duplicate detection is done using QSO details, location details, and certificate serial number.

allow defaults to 1 for backwards compatibility when tqsl_beginADIFConverter or tqsl_beginCabrilloConverter is called.

DLLEXPORT int CALLCONVENTION tqsl_setConverterAppName ( tQSL_Converter  convp,
const char *  app 
)

Specify the name of the application using the conversion library. This is output in a header record in the exported log file. Call this before calling tqsl_getConverterGABBI.

app is a c string containing the application name.