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_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_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.