1 /*************************************************************************** 2 convert.h - description 3 ------------------- 4 begin : Sun Nov 17 2002 5 copyright : (C) 2002 by ARRL 6 author : Jon Bloom 7 email : jbloom@arrl.org 8 revision : $Id$ 9 ***************************************************************************/ 10 11 #ifndef __tqslconvert_h 12 #define __tqslconvert_h 13 14 #include "tqsllib.h" 15 16 /** \file 17 * tQSL library converter functions. 18 */ 19 20 /** \defgroup Convert Converter API 21 * 22 * The Converter API provides the capability of converting Cabrillo 23 * and ADIF files to GABBI output. 24 */ 25 /** @{ */ 26 27 typedef void * tQSL_Converter; //!< Opaque converter type used by applications 28 //!< to access conversion functions 29 //!< 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** Create a simple converter object 36 * 37 * Allocates resources for converting logs and processing duplicate records. 38 */ 39 40 DLLEXPORT int CALLCONVENTION 41 tqsl_beginConverter(tQSL_Converter *convp); 42 43 /** Initiates the conversion process for an ADIF file. 44 * 45 * \c certs and \c ncerts define a set of certificates that are available to the 46 * converter for signing records. Typically, this list will be obtained by 47 * calling tqsl_selectCertificates(). 48 * 49 * tqsl_endConverter() should be called to free the resources when the conversion 50 * is finished. 51 */ 52 DLLEXPORT int CALLCONVENTION tqsl_beginADIFConverter(tQSL_Converter *conv, const char *filename, 53 tQSL_Cert *certs, int ncerts, tQSL_Location loc); 54 55 /** Initiates the conversion process for a Cabrillo file. 56 * 57 * \c certs and \c ncerts define a set of certificates that are available to the 58 * converter for signing records. Typically, this list will be obtained by 59 * calling tqsl_selectCertificates(). 60 * 61 * tqsl_endConverter() should be called to free the resources when the conversion 62 * is finished. 63 */ 64 DLLEXPORT int CALLCONVENTION tqsl_beginCabrilloConverter(tQSL_Converter *conv, const char *filename, 65 tQSL_Cert *certs, int ncerts, tQSL_Location loc); 66 67 /** End the conversion process by freeing the used resources. */ 68 DLLEXPORT int CALLCONVENTION tqsl_endConverter(tQSL_Converter *conv); 69 70 /** Configure the converter to allow (allow != 0) or disallow (allow == 0) 71 * nonamateur call signs in the CALL field. (Note: the test for 72 * validity is fairly trivial and will allow some nonamateur calls to 73 * get through, but it does catch most common errors.) 74 * 75 * \c allow defaults to 0 when tqsl_beginADIFConverter or 76 * tqsl_beginCabrilloConverter is called. 77 */ 78 DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowBadCall(tQSL_Converter conv, int allow); 79 80 /** Configure the converter to allow (allow != 0) or disallow (allow == 0) 81 * duplicate QSOs in a signed log. 82 * Duplicate detection is done using QSO details, location details, and 83 * certificate serial number. 84 * 85 * \c allow defaults to 1 for backwards compatibility when tqsl_beginADIFConverter or 86 * tqsl_beginCabrilloConverter is called. 87 */ 88 DLLEXPORT int CALLCONVENTION tqsl_setConverterAllowDuplicates(tQSL_Converter convp, int allow); 89 90 /** Specify the name of the application using the conversion library. 91 * This is output in a header record in the exported log file. 92 * Call this before calling tqsl_getConverterGABBI. 93 * 94 * \c app is a c string containing the application name. 95 */ 96 DLLEXPORT int CALLCONVENTION tqsl_setConverterAppName(tQSL_Converter convp, const char *app); 97 98 /** Roll back insertions into the duplicates database. 99 * 100 * This is called when cancelling creating a log, and causes any records 101 * added to the duplicates database to be removed so re-processing that 102 * log does not cause the records to be mis-marked as duplicates. 103 */ 104 DLLEXPORT int CALLCONVENTION tqsl_converterRollBack(tQSL_Converter convp); 105 106 /** Commits insertions into the duplicates database. 107 * 108 * This is called when a log is created normally and without issue, and so 109 * the presumption is that we are "done" with these QSOs. 110 */ 111 DLLEXPORT int CALLCONVENTION tqsl_converterCommit(tQSL_Converter convp); 112 113 /** Bulk read the duplicate DB records 114 * 115 * This is called to retrieve the QSO records from the dupe database. 116 * It returns the key/value pair upon each call. 117 * Return -1 for end of file, 0 for success, 1 for errors. 118 */ 119 DLLEXPORT int CALLCONVENTION 120 tqsl_getDuplicateRecords(tQSL_Converter convp, char *key, char *data, int keylen); 121 122 /** Bulk read the duplicate DB records 123 * 124 * This is called to retrieve the QSO records from the dupe database. 125 * It returns the key/value pair upon each call. 126 * Return -1 for end of file, 0 for success, 1 for errors. 127 * V2 expects a 256 byte buffer for the "data" string. 128 */ 129 DLLEXPORT int CALLCONVENTION 130 tqsl_getDuplicateRecordsV2(tQSL_Converter convp, char *key, char *data, int keylen); 131 132 /** Bulk write duplicate DB records 133 * 134 * This is called to store a QSO record into the dupe database. 135 * 136 * Return -1 for duplicate insertion, 0 for success, 1 for errors. 137 */ 138 DLLEXPORT int CALLCONVENTION 139 tqsl_putDuplicateRecord(tQSL_Converter convp, const char *key, const char *data, int keylen); 140 141 /** Set QSO date filtering in the converter. 142 * 143 * If \c start points to a valid date, QSOs prior to that date will be ignored 144 * by the converter. Similarly, if \c end points to a valid date, QSOs after 145 * that date will be ignored. Either or both may be NULL (or point to an 146 * invalid date) to disable date filtering for the respective range. 147 */ 148 149 DLLEXPORT int CALLCONVENTION tqsl_setADIFConverterDateFilter(tQSL_Converter conv, tQSL_Date *start, 150 tQSL_Date *end); 151 152 /** This is the main converter function. It returns a single GABBI 153 * record. 154 * 155 * Returns the NULL pointer on error or EOF. (Test tQSL_Error to determine which.) 156 * 157 * tQSL_Error is set to TQSL_DATE_OUT_OF_RANGE if QSO date range checking 158 * is active and the QSO date is outside the specified range. 159 * This is a non-fatal error. 160 * 161 * tQSL_Error is set to TQSL_DUPLICATE_QSO if the QSO has already been 162 * processed on the current computer. 163 * 164 * N.B. On systems that distinguish text-mode files from binary-mode files, 165 * notably Windows, the GABBI records should be written in binary mode. 166 * 167 * N.B. If the selected certificate has not been initialized for signing via 168 * tqsl_beginSigning(), this function will return a TQSL_SIGNINIT_ERROR. 169 * The cert that caused the error can be obtained via tqsl_getConverterCert(), 170 * initialized for signing, and then this function can be called again. No 171 * data records will be lost in this process. 172 */ 173 DLLEXPORT const char* CALLCONVENTION tqsl_getConverterGABBI(tQSL_Converter conv); 174 175 /** Get the certificate used to sign the most recent QSO record. */ 176 DLLEXPORT int CALLCONVENTION tqsl_getConverterCert(tQSL_Converter conv, tQSL_Cert *certp); 177 178 /** Get the input-file line number last read by the converter, starting 179 * at line 1. */ 180 DLLEXPORT int CALLCONVENTION tqsl_getConverterLine(tQSL_Converter conv, int *lineno); 181 182 /** Get the text of the last record read by the converter. 183 * 184 * Returns NULL on error. 185 */ 186 DLLEXPORT const char* CALLCONVENTION tqsl_getConverterRecordText(tQSL_Converter conv); 187 188 /** @} */ 189 190 #ifdef __cplusplus 191 } 192 #endif 193 194 #endif /* __tqslconvert_h */ 195 196