1 /*************************************************************************** 2 tqsllib.h - description 3 ------------------- 4 begin : Mon May 20 2002 5 copyright : (C) 2002 by ARRL 6 author : Jon Bloom 7 email : jbloom@arrl.org 8 revision : $Id: tqsllib.h,v 1.14 2013/03/01 13:26:44 k1mu Exp $ 9 ***************************************************************************/ 10 11 #ifndef TQSLLIB_H 12 #define TQSLLIB_H 13 14 #if defined(_WIN32) && !defined(TQSL_NODLL) 15 #ifdef TQSLLIB_DEF 16 #define DLLEXPORT __declspec(dllexport) 17 #define DLLEXPORTDATA __declspec(dllexport) 18 #define CALLCONVENTION __stdcall 19 #else 20 #define DLLEXPORT __declspec(dllimport) 21 #define DLLEXPORTDATA __declspec(dllimport) 22 #define CALLCONVENTION __stdcall 23 #endif 24 #else 25 #define DLLEXPORT ///< Symbol exports - Windows only 26 #define DLLEXPORTDATA ///< Symbol exports - Windows only 27 #define CALLCONVENTION ///< Symbol exports - Windows only 28 #endif 29 30 #include "adif.h" 31 #include "cabrillo.h" 32 33 /** \file 34 * tQSL library functions. 35 */ 36 37 /* Sizes */ 38 #define TQSL_MAX_PATH_LEN 256 ///< Max length of a FS path 39 #define TQSL_PASSWORD_MAX 80 ///< Max password length 40 #define TQSL_NAME_ELEMENT_MAX 256 ///< Max Org name length 41 #define TQSL_CALLSIGN_MAX 13 ///< Max callsign length 42 #define TQSL_CRQ_NAME_MAX 60 ///< Max length of request name 43 #define TQSL_CRQ_ADDR_MAX 80 ///< Max length of request addr 44 #define TQSL_CRQ_CITY_MAX 80 ///< Max length of request city 45 #define TQSL_CRQ_STATE_MAX 80 ///< Max length of request state 46 #define TQSL_CRQ_POSTAL_MAX 20 ///< Max length of request zip 47 #define TQSL_CRQ_COUNTRY_MAX 80 ///< Max length of req entity 48 #define TQSL_CRQ_EMAIL_MAX 180 ///< Max length of req email 49 #define TQSL_BAND_MAX 6 ///< Max length of a band name 50 #define TQSL_MODE_MAX 16 ///< Max length of a mode name 51 #define TQSL_FREQ_MAX 20 ///< Max length of a frequency 52 #define TQSL_SATNAME_MAX 20 ///< Max length of a sat name 53 #define TQSL_PROPMODE_MAX 20 ///< Max length of a prop mode 54 55 #define TQSL_CERT_CB_USER 0 ///< Callback is for user cert 56 #define TQSL_CERT_CB_CA 1 ///< Callback is for CA cert 57 #define TQSL_CERT_CB_ROOT 2 ///< Callback is for root cert 58 #define TQSL_CERT_CB_PKEY 3 ///< Callback is for private key 59 #define TQSL_CERT_CB_CONFIG 4 ///< Callback for config file 60 #define TQSL_CERT_CB_CERT_TYPE(x) ((x) & 0xf) ///< Type of the cert 61 #define TQSL_CERT_CB_MILESTONE 0 ///< New certificate 62 #define TQSL_CERT_CB_RESULT 0x10 ///< Cert import result 63 #define TQSL_CERT_CB_CALL_TYPE(x) ((x) & TQSL_CERT_CB_RESULT) ///< Callback type 64 #define TQSL_CERT_CB_PROMPT 0 ///< Callback prompt 65 #define TQSL_CERT_CB_DUPLICATE 0x100 ///< Dupe cert callback 66 #define TQSL_CERT_CB_ERROR 0x200 ///< Error import callback 67 #define TQSL_CERT_CB_LOADED 0x300 ///< Cert loaded callback 68 #define TQSL_CERT_CB_RESULT_TYPE(x) ((x) & 0x0f00) ///< Result type mask 69 70 typedef void * tQSL_Cert; ///< Opaque certificate type 71 typedef void * tQSL_Location; ///< Opaque location type 72 typedef char * tQSL_StationDataEnc; ///< Opaque station data type 73 74 /** Struct that holds y-m-d */ 75 typedef struct { 76 int year; ///< Numeric year 77 int month; ///< Numeric month 78 int day; ///< Numeric day 79 } tQSL_Date; 80 81 /** Struct that holds h-m-s */ 82 typedef struct { 83 int hour; ///< Time hour field 84 int minute; ///< Time minute field 85 int second; ///< Time seconds field 86 } tQSL_Time; 87 88 /** Certificate provider data */ 89 typedef struct tqsl_provider_st { 90 char organizationName[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider name 91 char organizationalUnitName[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider unit 92 char emailAddress[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider e-mail 93 char url[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider URL 94 } TQSL_PROVIDER; 95 96 /** Certificate request data */ 97 typedef struct tqsl_cert_req_st { ///< Cert request data 98 char providerName[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider name 99 char providerUnit[TQSL_NAME_ELEMENT_MAX+1]; ///< Provider unit 100 char callSign[TQSL_CALLSIGN_MAX+1]; ///< Callsign 101 char name[TQSL_CRQ_NAME_MAX+1]; ///< Name 102 char address1[TQSL_CRQ_ADDR_MAX+1]; ///< Address 1 103 char address2[TQSL_CRQ_ADDR_MAX+1]; ///< Address 2 104 char city[TQSL_CRQ_CITY_MAX+1]; ///< City 105 char state[TQSL_CRQ_STATE_MAX+1]; ///< State 106 char postalCode[TQSL_CRQ_POSTAL_MAX+1]; ///< Postal Code 107 char country[TQSL_CRQ_COUNTRY_MAX+1]; ///< Country 108 char emailAddress[TQSL_CRQ_EMAIL_MAX+1]; ///< e-mail 109 int dxccEntity; ///< DXCC Entity code 110 tQSL_Date qsoNotBefore; ///< QSOs not before date 111 tQSL_Date qsoNotAfter; ///< QSOs not after date 112 char password[TQSL_PASSWORD_MAX+1]; ///< Password 113 tQSL_Cert signer; ///< Signing cert 114 char renew; ///< Rewewal reference 115 } TQSL_CERT_REQ; 116 117 /** QSO data */ 118 typedef struct { 119 char callsign[TQSL_CALLSIGN_MAX+1]; ///< QSO callsign 120 char band[TQSL_BAND_MAX+1]; ///< QSO band 121 char mode[TQSL_MODE_MAX+1]; ///< QSO mode 122 char submode[TQSL_MODE_MAX+1]; ///< QSO submode 123 tQSL_Date date; ///< QSO date 124 tQSL_Time time; ///< QSO time 125 char freq[TQSL_FREQ_MAX+1]; ///< QSO frequency 126 char rxfreq[TQSL_FREQ_MAX+1]; ///< QSO receive frequency 127 char rxband[TQSL_BAND_MAX+1]; ///< QSO RX band 128 char propmode[TQSL_PROPMODE_MAX+1]; ///< QSO prop mode 129 char satname[TQSL_SATNAME_MAX+1]; ///< QSO satellite name 130 bool callsign_set; ///< QSO specifies a call worked 131 bool mode_set; ///< QSO specifies a mode 132 bool band_set; ///< QSO specifies a band or frequency 133 bool date_set; ///< QSO specifies a date 134 bool time_set; ///< QSO specifies a time 135 } TQSL_QSO_RECORD; 136 137 /// Base directory for tQSL library working files. 138 DLLEXPORTDATA extern const char *tQSL_BaseDir; 139 140 #ifdef __cplusplus 141 extern "C" { 142 #endif 143 144 /** \defgroup Util Utility API 145 */ 146 /** @{ */ 147 148 /// Error code from most recent tQSL library call. 149 /** 150 * The values for the error code are defined in tqslerrno.h */ 151 DLLEXPORTDATA extern int tQSL_Error; 152 /// The ADIF error code 153 DLLEXPORTDATA extern TQSL_ADIF_GET_FIELD_ERROR tQSL_ADIF_Error; 154 /// The ADIF error code 155 DLLEXPORTDATA extern TQSL_CABRILLO_ERROR_TYPE tQSL_Cabrillo_Error; 156 /// File name of file giving error. (May be empty.) 157 DLLEXPORTDATA extern char tQSL_ErrorFile[256]; 158 /// Custom error message string 159 DLLEXPORTDATA extern char tQSL_CustomError[256]; 160 /// System errno - stored when tQSL_Error == TQSL_SYSTEM_ERROR 161 DLLEXPORTDATA extern int tQSL_Errno; 162 /// Callsign used in import - used for missing public key error 163 DLLEXPORTDATA extern char tQSL_ImportCall[256]; 164 /// Serial number of recent certificate import 165 DLLEXPORTDATA extern long tQSL_ImportSerial; 166 /// Diagnostic log file 167 DLLEXPORTDATA extern FILE* tQSL_DiagFile; 168 169 /** Initialize the tQSL library 170 * 171 * This function should be called prior to calling any other library functions. 172 */ 173 DLLEXPORT int CALLCONVENTION tqsl_init(); 174 175 /** Set the directory where the TQSL files are kept. 176 * May be called either before of after tqsl_init(), but should be called 177 * before calling any other functions in the library. 178 * 179 * Note that this is purely optional. The library will figure out an 180 * approriate directory if tqsl_setDirectory isn't called. Unless there is 181 * some particular need to set the directory explicitly, programs should 182 * refrain from doing so. 183 */ 184 DLLEXPORT int CALLCONVENTION tqsl_setDirectory(const char *dir); 185 186 /** Gets the error string for the current tQSL library error and resets the error status. 187 * See tqsl_getErrorString_v(). 188 */ 189 DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString(); 190 191 /** Gets the error string corresponding to the given error number. 192 * The error string is available only until the next call to 193 * tqsl_getErrorString_v or tqsl_getErrorString. 194 */ 195 DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString_v(int err); 196 197 /** Encode a block of data into Base64 text. 198 * 199 * \li \c data = block of data to encode 200 * \li \c datalen = length of \c data in bytes 201 * \li \c output = pointer to output buffer 202 * \li \c outputlen = size of output buffer in bytes 203 */ 204 DLLEXPORT int CALLCONVENTION tqsl_encodeBase64(const unsigned char *data, int datalen, char *output, int outputlen); 205 206 /** Decode Base64 text into binary data. 207 * 208 * \li \c input = NUL-terminated text string of Base64-encoded data 209 * \li \c data = pointer to output buffer 210 * \li \c datalen = pointer to int containing the size of the output buffer in bytes 211 * 212 * Places the number of resulting data bytes into \c *datalen. 213 */ 214 DLLEXPORT int CALLCONVENTION tqsl_decodeBase64(const char *input, unsigned char *data, int *datalen); 215 216 /** Initialize a tQSL_Date object from a date string. 217 * 218 * The date string must be YYYY-MM-DD or YYYYMMDD format. 219 * 220 * Returns 0 on success, nonzero on failure 221 */ 222 DLLEXPORT int CALLCONVENTION tqsl_initDate(tQSL_Date *date, const char *str); 223 224 /** Initialize a tQSL_Time object from a time string. 225 * 226 * The time string must be HH[:]MM[[:]SS] format. 227 * 228 * Returns 0 on success, nonzero on failure 229 */ 230 DLLEXPORT int CALLCONVENTION tqsl_initTime(tQSL_Time *time, const char *str); 231 232 /** Compare two tQSL_Date objects. 233 * 234 * Returns: 235 * - -1 if \c a < \c b 236 * 237 * - 0 if \c a == \c b 238 * 239 * - 1 if \c a > \c b 240 */ 241 DLLEXPORT int CALLCONVENTION tqsl_compareDates(const tQSL_Date *a, const tQSL_Date *b); 242 243 /** Calculate the number of days between two tQSL_Date objects. 244 * 245 * Returns a positive result if the first date is earlier, otherwise 246 * negative. 247 */ 248 DLLEXPORT int CALLCONVENTION tqsl_subtractDates(const tQSL_Date *a, const tQSL_Date *b, int *diff); 249 250 /** Converts a tQSL_Date object to a YYYY-MM-DD string. 251 * 252 * Returns a pointer to \c buf or NULL on error 253 */ 254 DLLEXPORT char* CALLCONVENTION tqsl_convertDateToText(const tQSL_Date *date, char *buf, int bufsiz); 255 256 /** Test whether a tQSL_Date contains a valid date value 257 * 258 * Returns 1 if the date is valid 259 */ 260 DLLEXPORT int CALLCONVENTION tqsl_isDateValid(const tQSL_Date *d); 261 262 /** Test whether a tQSL_Date is empty (contains all zeroes) 263 * 264 * Returns 1 if the date is null 265 */ 266 DLLEXPORT int CALLCONVENTION tqsl_isDateNull(const tQSL_Date *d); 267 268 /** Test whether a tQSL_Time contains a valid time value 269 * 270 * Returns 1 if the time is valid 271 */ 272 DLLEXPORT int CALLCONVENTION tqsl_isTimeValid(const tQSL_Time *t); 273 274 /** Converts a tQSL_Time object to a HH:MM:SSZ string. 275 * 276 * Returns a pointer to \c buf or NULL on error 277 */ 278 DLLEXPORT char* CALLCONVENTION tqsl_convertTimeToText(const tQSL_Time *time, char *buf, int bufsiz); 279 280 /** Returns the library version. \c major and/or \c minor may be NULL. 281 */ 282 DLLEXPORT int CALLCONVENTION tqsl_getVersion(int *major, int *minor); 283 284 /** Returns the configuration-file version. \c major and/or \c minor may be NULL. 285 */ 286 DLLEXPORT int CALLCONVENTION tqsl_getConfigVersion(int *major, int *minor); 287 288 /** @} */ 289 290 291 /** \defgroup CertStuff Certificate Handling API 292 * 293 * Certificates are managed by manipulating \c tQSL_Cert objects. A \c tQSL_Cert 294 * contains: 295 * 296 * \li The identity of the organization that issued the certificate (the "issuer"). 297 * \li The name and call sign of the amateur radio operator (ARO). 298 * \li The DXCC entity number for which this certificate is valid. 299 * \li The range of QSO dates for which this certificate can be used. 300 * \li The resources needed to digitally sign and verify QSO records. 301 * 302 * The certificate management process consists of: 303 * 304 * \li <B>Applying for a certificate.</b> Certificate requests are produced via the 305 * tqsl_createCertRequest() function, which produces a certificate-request 306 * file to send to the issuer. 307 * \li <B>Importing the certificate</B> file received from the issuer into the local 308 * "certificate store," a directory managed by the tQSL library, via 309 * tqsl_importTQSLFile(). 310 * \li <B>Selecting an appropriate certificate</B> to use to sign a QSO record via 311 * tqsl_selectCertificates(). 312 */ 313 314 /** @{ */ 315 316 #define TQSL_SELECT_CERT_WITHKEYS 1 ///< Private keys only (no cert) 317 #define TQSL_SELECT_CERT_EXPIRED 2 ///< Include expired certs 318 #define TQSL_SELECT_CERT_SUPERCEDED 4 ///< Include superseded certs 319 320 /** Get a list of certificates 321 * 322 * Selects a set of certificates from the user's certificate store 323 * based on optional selection criteria. The function produces a 324 * list of tQSL_Cert objects. 325 * 326 * \li \c certlist - Pointer to a variable that is set by the 327 * function to point to the list of tQSL_Cert objects. 328 * \li \c ncerts - Pointer to an int that is set to the number 329 * of objects in the \c certlist list. 330 * \li \c callsign - Optional call sign to match. 331 * \li \c date - Optional QSO date string in ISO format. Only certs 332 * that have a QSO date range that encompasses this date will be 333 * returned. 334 * \li \c issuer - Optional issuer (DN) string to match. 335 * \li \c flag - OR of \c TQSL_SELECT_CERT_EXPIRED (include expired 336 * certs), \c TQSL_SELECT_CERT_SUPERCEDED and \c TQSL_SELECT_CERT_WITHKEYS 337 * (keys that don't have associated certs will be returned). 338 * 339 * Returns 0 on success, nonzero on failure. 340 * 341 * Each of the tQSL_Cert objects in the list should be freed 342 * by calling tqsl_freeCertificate(). tqsl_freeCertificateList() is a better 343 * function to use for that as it also frees the allocated array that 344 * holds the certificate pointers. 345 * 346 */ 347 DLLEXPORT int CALLCONVENTION tqsl_selectCertificates(tQSL_Cert **certlist, int *ncerts, 348 const char *callsign, int dxcc, const tQSL_Date *date, const TQSL_PROVIDER *issuer, int flag); 349 350 /** Get a list of authority certificates 351 * 352 * Selects a set of certificates from the root or authorities certificate stores 353 * The function produces a list of tQSL_Cert objects. 354 * 355 * Each of the tQSL_Cert objects in the list should be freed 356 * by calling tqsl_freeCertificate(). tqsl_freeCertificateList() is a better 357 * function to use for that as it also frees the allocated array that 358 * holds the certificate pointers. 359 * 360 */ 361 DLLEXPORT int CALLCONVENTION tqsl_selectCACertificates(tQSL_Cert **certlist, int *ncerts, const char *type); 362 363 /** Get a particulat certificate from the list returnded by 364 * tqsl_selectCertificates. This function exists principally 365 * to make it easier for VB programs to access the list of 366 * certificates. 367 * 368 * It is the caller's responsibility to ensure that 0 <= idx < ncerts 369 * (where ncerts is the value returned by tqsl_selectCertificates) 370 */ 371 DLLEXPORT int CALLCONVENTION tqsl_getSelectedCertificate(tQSL_Cert *cert, const tQSL_Cert **certlist, 372 int idx); 373 374 /** Find out if the "certificate" is expired 375 */ 376 DLLEXPORT int CALLCONVENTION tqsl_isCertificateExpired(tQSL_Cert cert, int *status); 377 378 /** Find out if the "certificate" is superceded 379 */ 380 DLLEXPORT int CALLCONVENTION tqsl_isCertificateSuperceded(tQSL_Cert cert, int *status); 381 382 /** Find out if the "certificate" is just a key pair. 383 */ 384 DLLEXPORT int CALLCONVENTION tqsl_getCertificateKeyOnly(tQSL_Cert cert, int *keyonly); 385 386 /** Get the encoded certificate for inclusion in a GABBI file. 387 */ 388 DLLEXPORT int CALLCONVENTION tqsl_getCertificateEncoded(tQSL_Cert cert, char *buf, int bufsiz); 389 390 /** Get the encoded private key for inclusion in a backup file. 391 */ 392 DLLEXPORT int CALLCONVENTION tqsl_getKeyEncoded(tQSL_Cert cert, char *buf, int bufsiz); 393 394 /** Import a base64 encoded certificate and private key from a backup file. 395 */ 396 DLLEXPORT int CALLCONVENTION tqsl_importKeyPairEncoded(const char *callsign, const char *type, const char *keybuf, const char *certbuf); 397 398 /** Get the issuer's serial number of the certificate. 399 */ 400 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerial(tQSL_Cert cert, long *serial); 401 402 /** Get the issuer's serial number of the certificate as a hexadecimal string. 403 * Needed for certs with long serial numbers (typically root certs). 404 */ 405 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialExt(tQSL_Cert cert, char *serial, int serialsiz); 406 407 /** Get the length of the issuer's serial number of the certificate as it will be 408 * returned by tqsl_getCertificateSerialExt. 409 */ 410 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialLength(tQSL_Cert cert); 411 412 /** Get the issuer (DN) string from a tQSL_Cert. 413 * 414 * \li \c cert - a tQSL_Cert object, normally one returned from 415 * tqsl_selectCertificates() 416 * \li \c buf - Buffer to hold the returned string. 417 * \li \c bufsiz - Size of \c buf. 418 * 419 * Returns 0 on success, nonzero on failure. 420 */ 421 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuer(tQSL_Cert cert, char *buf, int bufsiz); 422 423 /** Get the issuer's organization name from a tQSL_Cert. 424 * 425 * \li \c cert - a tQSL_Cert object, normally one returned from 426 * tqsl_selectCertificates() 427 * \li \c buf - Buffer to hold the returned string. 428 * \li \c bufsiz - Size of \c buf. 429 * 430 * Returns 0 on success, nonzero on failure. 431 */ 432 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganization(tQSL_Cert cert, char *buf, int bufsiz); 433 /** Get the issuer's organizational unit name from a tQSL_Cert. 434 * 435 * \li \c cert - a tQSL_Cert object, normally one returned from 436 * tqsl_selectCertificates() 437 * \li \c buf - Buffer to hold the returned string. 438 * \li \c bufsiz - Size of \c buf. 439 * 440 * Returns 0 on success, nonzero on failure. 441 */ 442 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganizationalUnit(tQSL_Cert cert, char *buf, int bufsiz); 443 /** Get the ARO call sign string from a tQSL_Cert. 444 * 445 * \li \c cert - a tQSL_Cert object, normally one returned from 446 * tqsl_selectCertificates() 447 * \li \c buf - Buffer to hold the returned string. 448 * \li \c bufsiz - Size of \c buf. 449 * 450 * Returns 0 on success, nonzero on failure. 451 */ 452 DLLEXPORT int CALLCONVENTION tqsl_getCertificateCallSign(tQSL_Cert cert, char *buf, int bufsiz); 453 /** Get the ARO name string from a tQSL_Cert. 454 * 455 * \li \c cert - a tQSL_Cert object, normally one returned from 456 * tqsl_selectCertificates() 457 * \li \c buf - Buffer to hold the returned string. 458 * \li \c bufsiz - Size of \c buf. 459 * 460 * Returns 0 on success, nonzero on failure. 461 */ 462 DLLEXPORT int CALLCONVENTION tqsl_getCertificateAROName(tQSL_Cert cert, char *buf, int bufsiz); 463 464 /** Get the email address from a tQSL_Cert. 465 * 466 * \li \c cert - a tQSL_Cert object, normally one returned from 467 * tqsl_selectCertificates() 468 * \li \c buf - Buffer to hold the returned string. 469 * \li \c bufsiz - Size of \c buf. 470 * 471 * Returns 0 on success, nonzero on failure. 472 */ 473 DLLEXPORT int CALLCONVENTION tqsl_getCertificateEmailAddress(tQSL_Cert cert, char *buf, int bufsiz); 474 475 /** Get the QSO not-before date from a tQSL_Cert. 476 * 477 * \li \c cert - a tQSL_Cert object, normally one returned from 478 * tqsl_selectCertificates() 479 * \li \c date - Pointer to a tQSL_Date struct to hold the returned date. 480 * 481 * Returns 0 on success, nonzero on failure. 482 */ 483 DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotBeforeDate(tQSL_Cert cert, tQSL_Date *date); 484 485 /** Get the QSO not-after date from a tQSL_Cert. 486 * 487 * \li \c cert - a tQSL_Cert object, normally one returned from 488 * tqsl_selectCertificates() 489 * \li \c date - Pointer to a tQSL_Date struct to hold the returned date. 490 * 491 * Returns 0 on success, nonzero on failure. 492 */ 493 DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotAfterDate(tQSL_Cert cert, tQSL_Date *date); 494 495 /** Get the certificate's not-before date from a tQSL_Cert. 496 * 497 * \li \c cert - a tQSL_Cert object, normally one returned from 498 * tqsl_selectCertificates() 499 * \li \c date - Pointer to a tQSL_Date struct to hold the returned date. 500 * 501 * Returns 0 on success, nonzero on failure. 502 */ 503 DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotBeforeDate(tQSL_Cert cert, tQSL_Date *date); 504 505 /** Get the certificate's not-after date from a tQSL_Cert. 506 * 507 * \li \c cert - a tQSL_Cert object, normally one returned from 508 * tqsl_selectCertificates() 509 * \li \c date - Pointer to a tQSL_Date struct to hold the returned date. 510 * 511 * Returns 0 on success, nonzero on failure. 512 */ 513 DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotAfterDate(tQSL_Cert cert, tQSL_Date *date); 514 515 /** Get the DXCC entity number from a tQSL_Cert. 516 * 517 * \li \c cert - a tQSL_Cert object, normally one returned from 518 * tqsl_selectCertificates() 519 * \li \c dxcc - Pointer to an int to hold the returned date. 520 * 521 * Returns 0 on success, nonzero on failure. 522 */ 523 DLLEXPORT int CALLCONVENTION tqsl_getCertificateDXCCEntity(tQSL_Cert cert, int *dxcc); 524 525 /** Get the first address line from the certificate request used in applying 526 * for a tQSL_Cert certificate. 527 * 528 * \li \c cert - a tQSL_Cert object, normally one returned from 529 * tqsl_selectCertificates() 530 * \li \c buf - Buffer to hold the returned string. 531 * \li \c bufsiz - Size of \c buf. 532 * 533 * Returns 0 on success, nonzero on failure. 534 */ 535 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress1(tQSL_Cert cert, char *str, int bufsiz); 536 537 /** Get the second address line from the certificate request used in applying 538 * for a tQSL_Cert certificate. 539 * 540 * \li \c cert - a tQSL_Cert object, normally one returned from 541 * tqsl_selectCertificates() 542 * \li \c buf - Buffer to hold the returned string. 543 * \li \c bufsiz - Size of \c buf. 544 * 545 * Returns 0 on success, nonzero on failure. 546 */ 547 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress2(tQSL_Cert cert, char *str, int bufsiz); 548 549 /** Get the city from the certificate request used in applying 550 * for a tQSL_Cert certificate. 551 * 552 * \li \c cert - a tQSL_Cert object, normally one returned from 553 * tqsl_selectCertificates() 554 * \li \c buf - Buffer to hold the returned string. 555 * \li \c bufsiz - Size of \c buf. 556 * 557 * Returns 0 on success, nonzero on failure. 558 */ 559 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCity(tQSL_Cert cert, char *str, int bufsiz); 560 561 /** Get the state from the certificate request used in applying 562 * for a tQSL_Cert certificate. 563 * 564 * \li \c cert - a tQSL_Cert object, normally one returned from 565 * tqsl_selectCertificates() 566 * \li \c buf - Buffer to hold the returned string. 567 * \li \c bufsiz - Size of \c buf. 568 * 569 * Returns 0 on success, nonzero on failure. 570 */ 571 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestState(tQSL_Cert cert, char *str, int bufsiz); 572 573 /** Get the postal (ZIP) code from the certificate request used in applying 574 * for a tQSL_Cert certificate. 575 * 576 * \li \c cert - a tQSL_Cert object, normally one returned from 577 * tqsl_selectCertificates() 578 * \li \c buf - Buffer to hold the returned string. 579 * \li \c bufsiz - Size of \c buf. 580 * 581 * Returns 0 on success, nonzero on failure. 582 */ 583 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestPostalCode(tQSL_Cert cert, char *str, int bufsiz); 584 585 /** Get the country from the certificate request used in applying 586 * for a tQSL_Cert certificate. 587 * 588 * \li \c cert - a tQSL_Cert object, normally one returned from 589 * tqsl_selectCertificates() 590 * \li \c buf - Buffer to hold the returned string. 591 * \li \c bufsiz - Size of \c buf. 592 * 593 * Returns 0 on success, nonzero on failure. 594 */ 595 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCountry(tQSL_Cert cert, char *str, int bufsiz); 596 597 #define TQSL_PK_TYPE_ERR 0 ///< Error retrieving private key 598 #define TQSL_PK_TYPE_NONE 1 ///< No private key 599 #define TQSL_PK_TYPE_UNENC 2 ///< Private key is not encrypted 600 #define TQSL_PK_TYPE_ENC 3 ///< Private key is encrypted 601 602 /** Determine the nature of the private key associated with a 603 * certificate. 604 * 605 * \li \c cert - a tQSL_Cert object, normally one returned from 606 * tqsl_selectCertificates() 607 * 608 * Returns one of the following values: 609 * 610 * \li \c TQSL_PK_TYPE_ERR - An error occurred. Use tqsl_getErrorString() to examine. 611 * \li \c TQSL_PK_TYPE_NONE - No matching private key was found. 612 * \li \c TQSL_PK_TYPE_UNENC - The matching private key is unencrypted. 613 * \li \c TQSL_PK_TYPE_ENC - The matching private key is encrypted 614 * (password protected). 615 */ 616 DLLEXPORT int CALLCONVENTION tqsl_getCertificatePrivateKeyType(tQSL_Cert cert); 617 618 619 /** Free the memory used by the tQSL_Cert. Once this function is called, 620 * \c cert should not be used again in any way. 621 */ 622 DLLEXPORT void CALLCONVENTION tqsl_freeCertificate(tQSL_Cert cert); 623 624 /** Free the memory used by a certificate list. The allocated list 625 * of tQSL_Certs are freed and the pointer array is freed. 626 * Once this function is called, the \c list or the \c cert 627 * should not be used again in any way. 628 */ 629 DLLEXPORT void CALLCONVENTION tqsl_freeCertificateList(tQSL_Cert* list, int ncerts); 630 631 #define TQSL_CERT_STATUS_UNK 0 ///< Status is unknown 632 #define TQSL_CERT_STATUS_SUP 1 ///< Certificate is superceded 633 #define TQSL_CERT_STATUS_EXP 2 ///< Certificate is expired 634 #define TQSL_CERT_STATUS_OK 3 ///< Certificate is valid 635 #define TQSL_CERT_STATUS_INV 4 ///< Invalid serial number 636 637 /** Determine the status of a callsign certificate 638 * \li \c serial - the serial number of the certificate 639 * tqsl_selectCertificates() 640 * \li \c status - an integer to receive the certificate status 641 * 642 * Returns one of the following values: 643 * 644 * \li \c TQSL_CERT_STATUS_UNK - An error occurred and the status is unknown 645 * \li \c TQSL_CERT_STATUS_SUP - The certificate has been superceded 646 * \li \c TQSL_CERT_STATUS_EXP - The certificate has expired 647 * \li \c TQSL_CERT_STATUS_OK - The certificate is valid 648 * \li \c TQSL_CERT_STATUS_INV - The serial number supplied is invalid 649 * 650 */ 651 DLLEXPORT int CALLCONVENTION tqsl_getCertificateStatus(long serial); 652 653 /** Store the status of a callsign certificate 654 * \li \c serial - serial number of the certificate 655 * \li \c status - the status value to store. 656 */ 657 DLLEXPORT int CALLCONVENTION tqsl_setCertificateStatus(long serial, const char *status); 658 659 /* int tqsl_checkCertificate(tQSL_Cert); */ 660 661 /** Import a Gabbi cert file received from a CA 662 * 663 * The callback, \c cb, will be called whenever a certificate is ready 664 * to be imported: 665 * 666 * cb(type, message); 667 * 668 * \c type has several fields that can be accessed via macros: 669 * 670 * \c TQSL_CERT_CB_CALL_TYPE(type) := \c TQSL_CERT_CB_MILESTONE | \c TQSL_CERT_CB_RESULT 671 * 672 * \c TQSL_CERT_CB_CERT_TYPE(type) := \c TQSL_CERT_CB_ROOT | \c TQSL_CERT_CB_CA | \c TQSL_CERT_CB_USER 673 * 674 * \c TQSL_CERT_CB_RESULT_TYPE(type) := \c TQSL_CERT_CB_PROMPT | \c TQSL_CERT_CB_WARNING | \c TQSL_CERT_CB_ERROR 675 * 676 * \c TQSL_CERT_CB_RESULT_TYPE() is meaningful only if \c TQSL_CERT_CB_CALL_TYPE() == \c TQSL_CERT_CB_RESULT 677 */ 678 DLLEXPORT int CALLCONVENTION tqsl_importTQSLFile(const char *file, int(*cb)(int type, const char *message, void *userdata), void *user); 679 680 /** Get the serial for the first user cert from a .tq6 file 681 * used to support asking the user to save their cert after import 682 * \li \c file is the path to the file 683 * \li \c serial is where the serial number is returned 684 * 685 * Returns 0 on success, nonzero on failure. 686 * 687 */ 688 DLLEXPORT int CALLCONVENTION tqsl_getSerialFromTQSLFile(const char *file, long *serial); 689 690 /** Get the number of certificate providers known to tqsllib. 691 */ 692 DLLEXPORT int CALLCONVENTION tqsl_getNumProviders(int *n); 693 694 /** Get the information for a certificate provider. 695 * 696 * \li \c idx is the index, 0 <= idx < tqsl_getNumProviders() 697 */ 698 DLLEXPORT int CALLCONVENTION tqsl_getProvider(int idx, TQSL_PROVIDER *provider); 699 700 /** Create a certificate-request Gabbi file. 701 * 702 * The \c req parameter must be properly populated with the required fields. 703 * 704 * If \c req->password is NULL and \c cb is not NULL, the callback will be 705 * called to acquire the password. Otherwise \c req->password will be used as 706 * the password. If the password is NULL or an empty string the generated 707 * private key will be stored unencrypted. 708 * 709 * If req->signer is not zero and the signing certificate requires a password, 710 * the password may be in req->signer_password, else signer_pwcb is called. 711 */ 712 DLLEXPORT int CALLCONVENTION tqsl_createCertRequest(const char *filename, TQSL_CERT_REQ *req, 713 int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user); 714 715 /** Save a key pair and certificates to a file in PKCS12 format. 716 * 717 * The tQSL_Cert must be initialized for signing (see tqsl_beginSigning()) 718 * if the user certificate is being exported. 719 * 720 * The supplied \c p12password is used to encrypt the PKCS12 data. 721 */ 722 DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12File(tQSL_Cert cert, const char *filename, const char *p12password); 723 724 /** Save a key pair and certificates to a Base64 string in PKCS12 format. 725 * 726 * The tQSL_Cert must be initialized for signing (see tqsl_beginSigning()) 727 * if the user certificate is being exported. 728 * 729 * The supplied \c p12password is used to encrypt the PKCS12 data. 730 */ 731 732 DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12Base64(tQSL_Cert cert, char *base64, int b64len, const char *p12password); 733 734 /** Load certificates and a private key from a PKCS12 file. 735 */ 736 DLLEXPORT int CALLCONVENTION tqsl_importPKCS12File(const char *filename, const char *p12password, const char *password, 737 int (*pwcb)(char *buf, int bufsiz, void *userdata), int(*cb)(int type , const char *message, void *userdata), void *user); 738 739 /** Load certificates and a private key from a Base64 encoded PKCS12 string. 740 */ 741 DLLEXPORT int CALLCONVENTION tqsl_importPKCS12Base64(const char *base64, const char *p12password, const char *password, 742 int (*pwcb)(char *buf, int bufsiz, void *userdata), int(*cb)(int type , const char *message, void *userdata), void *user); 743 744 /** Get the list of restorable station locations. */ 745 DLLEXPORT int CALLCONVENTION tqsl_getDeletedCallsignCertificates(char ***calls, int *ncall, const char *filter); 746 747 /** Free the list of restorable Callsign Certificates. */ 748 DLLEXPORT void CALLCONVENTION tqsl_freeDeletedCertificateList(char **list, int nloc); 749 750 /** Restore a deleted callsign certificate by callsign. */ 751 DLLEXPORT int CALLCONVENTION tqsl_restoreCallsignCertificate(const char *callsign); 752 753 /** Delete a certificate and private key 754 */ 755 DLLEXPORT int CALLCONVENTION tqsl_deleteCertificate(tQSL_Cert cert); 756 757 /** @} */ 758 759 /** \defgroup Sign Signing API 760 * 761 * The Signing API uses a tQSL_Cert (see \ref CertStuff) to digitally 762 * sign a block of data. 763 */ 764 /** @{ */ 765 766 /** Initialize the tQSL_Cert object for use in signing. 767 * 768 * This produces an unencrypted copy of the private key in memory. 769 * 770 * if \c password is not NULL, it must point to the password to use to decrypt 771 * the private key. If \c password is NULL and \c pwcb is not NULL, \c pwcb 772 * is called to get the password. If the private key is encrypted and both 773 * \c password and \c pwcb are NULL, or if the supplied password fails to 774 * decrypt the key, a TQSL_PASSWORD_ERROR error is returned. 775 * 776 * \c pwcb parameters: \c pwbuf is a pointer to a buffer of \c pwsize chars. 777 * The buffer should be NUL-terminated. 778 */ 779 DLLEXPORT int CALLCONVENTION tqsl_beginSigning(tQSL_Cert cert, char *password, int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user); 780 781 /** Test whether the tQSL_Cert object is initialized for signing. 782 * 783 * Returns 0 if initialized. Sets tQSL_Error to TQSL_SIGNINIT_ERROR if not. 784 */ 785 DLLEXPORT int CALLCONVENTION tqsl_checkSigningStatus(tQSL_Cert cert); 786 787 /** Get the maximum size of a signature block that will be produced 788 * when the tQSL_Cert is used to sign data. (Note that the size of the 789 * signature block is unaffected by the size of the data block being signed.) 790 */ 791 DLLEXPORT int CALLCONVENTION tqsl_getMaxSignatureSize(tQSL_Cert cert, int *sigsize); 792 793 /** Sign a data block. 794 * 795 * tqsl_beginSigning() must have been called for 796 * the tQSL_Cert object before calling this function. 797 */ 798 DLLEXPORT int CALLCONVENTION tqsl_signDataBlock(tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int *siglen); 799 800 /** Verify a signed data block. 801 * 802 * tqsl_beginSigning() need \em not have been called. 803 */ 804 DLLEXPORT int CALLCONVENTION tqsl_verifyDataBlock(tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int siglen); 805 806 /** Sign a single QSO record 807 * 808 * tqsl_beginSigning() must have been called for 809 * the tQSL_Cert object before calling this function. 810 * 811 * \c loc must be a valid tQSL_Location object. See \ref Data. 812 */ 813 DLLEXPORT int CALLCONVENTION tqsl_signQSORecord(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *rec, unsigned char *sig, int *siglen); 814 815 /** Terminate signing operations for this tQSL_Cert object. 816 * 817 * This zero-fills the unencrypted private key in memory. 818 */ 819 DLLEXPORT int CALLCONVENTION tqsl_endSigning(tQSL_Cert cert); 820 821 /** @} */ 822 823 /** \defgroup Data Data API 824 * 825 * The Data API is used to form data into TrustedQSL records. A TrustedQSL record 826 * consists of a station record and a QSO record. Together, the two records 827 * fully describe one station's end of the QSO -- just as a paper QSL card does. 828 * 829 * The station record contains the callsign and geographic location of the 830 * station submitting the QSO record. The library manages the station records. 831 * The tqsl_xxxStationLocationCapture functions are used to generate and save 832 * a station record. The intent is to provide an interface that makes a step-by-step 833 * system (such as a GUI "wizard") easily implemented. 834 * 835 * The tqsl_getStationLocation() function is used to retrieve station records. 836 * 837 * With the necessary station location available, a signed GABBI output file can 838 * be generated using the tqsl_getGABBIxxxxx functions: 839 * 840 * \li tqsl_getGABBItCERT() - Returns a GABBI tCERT record for the given tQSL_Cert 841 * \li tqsl_getGABBItSTATION() - Returns a GABBI tSTATION record for the given 842 * tQSL_Location 843 * \li tqsl_getGABBItCONTACT() - Returns a GABBI tCONTACT record for the given 844 * TQSL_QSO_RECORD, using the given tQSL_Cert and tQSL_Location. 845 * \li tqsl_getGABBItCONTACTData() - Returns a GABBI tCONTACT record and the 846 * SIGNDATA for the given TQSL_QSO_RECORD, using the given tQSL_Cert and 847 * tQSL_Location. 848 * 849 * The GABBI format requires that the tCERT record contain an integer identifier 850 * that is unique within the GABBI file. Similarly, each tSTATION record must 851 * contain a unique identifier. Aditionally, the tSTATION record must reference 852 * the identifier of a preceding tCERT record. Finally, each tCONTACT record must 853 * reference a preceding tSTATION record. (A GABBI processor uses these identifiers 854 * and references to tie the station and contact records together and to verify 855 * their signature via the certificate.) It is the responsibility of the caller 856 * to supply these identifiers and to ensure that the supplied references match 857 * the tQSL_Cert and tQSL_Location used to create the referenced GABBI records. 858 * 859 * Station Location Generation 860 * 861 * The station-location generation process involves determining the values 862 * for a number of station-location parameters. Normally this 863 * will be done by prompting the user for the values. The responses given 864 * by the user may determine which later fields are required. For example, 865 * if the user indicates that the DXCC entity is UNITED STATES, a later 866 * field would ask for the US state. This field would not be required if the 867 * DXCC entity were not in the US. 868 * 869 * To accommodate the dynamic nature of the field requirements, the fields 870 * are ordered such that dependent fields are queried after the field(s) 871 * on which they depend. To make this process acceptable in a GUI 872 * system, the fields are grouped into pages, where multiple fields may 873 * be displayed on the same page. The grouping is such that which fields 874 * are within the page is not dependent on any of the values of the 875 * fields within the page. That is, a page of fields contains the same 876 * fields no matter what value any of the fields contains. (However, 877 * the \em values of fields within the page can depend on the values 878 * of fields that precede them in the page.) 879 * 880 * Here is a brief overview of the sequence of events involved in 881 * generating a station location interactively, one field at a time: 882 * 883 * 1) Call tqsl_initStationLocationCapture() (new location) or tqsl_getStationLocation() 884 * (existing location). 885 * 886 * 2) For \c field from 0 to tqsl_getNumLocationField(): 887 * \li Display the field label [tqsl_getLocationFieldDataLabel()] 888 * \li Get the field content from the user. This can be a selection 889 * from a list, an entered integer or an entered character string, 890 * depending on the value returned by tqsl_getLocationFieldInputType(). 891 * 892 * 3) If tqsl_hasNextStationLocationCapture() returns 1, call 893 * tqsl_nextStationLocationCapture() and go back to step 2. 894 * 895 * In the case of a GUI system, you'll probably want to display the 896 * fields in pages. The sequence of events is a bit different: 897 * 898 * 1) Call tqsl_initStationLocationCapture() (new location) or tqsl_getStationLocation() 899 * (existing location). 900 * 901 * 2) For \c field from 0 to tqsl_getNumLocationField(), 902 * \li Display the field label [tqsl_getLocationFieldDataLabel()] 903 * \li Display the field-input control This can be a list-selection 904 * or an entered character string or integer, depending on the value 905 * returned by tqsl_getLocationFieldInputType(). 906 * 907 * 3) Each time the user changes a field, call tqsl_updateStationLocationCapture(). 908 * This may change the allowable selection for fields that follow the field 909 * the user changed, so the control for each of those fields should be updated 910 * as in step 2. 911 * 912 * 4) Once the user has completed entries for the page, if 913 * tqsl_hasNextStationLocationCapture() returns 1, call 914 * tqsl_nextStationLocationCapture() and go back to step 2. 915 * 916 * N.B. The first two fields in the station-location capture process are 917 * always call sign and DXCC entity, in that order. As a practical matter, these 918 * two fields must match the corresponding fields in the available certificates. 919 * The library will therefore constrain the values of these fields to match 920 * what's available in the certificate store. See \ref CertStuff. 921 */ 922 923 /** @{ */ 924 925 /* Location field input types */ 926 927 #define TQSL_LOCATION_FIELD_TEXT 1 ///< Text type input field 928 #define TQSL_LOCATION_FIELD_DDLIST 2 ///< Dropdown list input field 929 #define TQSL_LOCATION_FIELD_LIST 3 ///< List type input field 930 #define TQSL_LOCATION_FIELD_BADZONE 4 ///< Used to return zone selection errors 931 932 /* Location field data types */ 933 #define TQSL_LOCATION_FIELD_CHAR 1 ///< Character field 934 #define TQSL_LOCATION_FIELD_INT 2 ///< Integer field 935 936 /** Begin the process of generating a station record */ 937 DLLEXPORT int CALLCONVENTION tqsl_initStationLocationCapture(tQSL_Location *locp); 938 939 /** Release the station-location resources. This should be called for 940 * any tQSL_Location that was initialized via tqsl_initStationLocationCapture() 941 * or tqsl_getStationLocation() 942 */ 943 DLLEXPORT int CALLCONVENTION tqsl_endStationLocationCapture(tQSL_Location *locp); 944 945 /** Update the pages based on the currently selected settings. */ 946 DLLEXPORT int CALLCONVENTION tqsl_updateStationLocationCapture(tQSL_Location loc); 947 948 /** Return the number of station location capture pages. */ 949 950 DLLEXPORT int CALLCONVENTION tqsl_getNumStationLocationCapturePages(tQSL_Location loc, int *npages); 951 952 /** Get the current page number */ 953 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCapturePage(tQSL_Location loc, int *page); 954 955 /** Set the current page number. 956 * Typically, the page number will be 1 (the starting page) or a value 957 * obtained from tqsl_getStationLocationCapturePage(). 958 */ 959 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCapturePage(tQSL_Location loc, int page); 960 961 /** Set the certificate flags used in a location page. 962 * This is used to enable expired certs (or disable). 963 */ 964 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCertFlags(tQSL_Location loc, int flags); 965 966 /** Advance the page to the next one in the page sequence */ 967 DLLEXPORT int CALLCONVENTION tqsl_nextStationLocationCapture(tQSL_Location loc); 968 969 /** Return the page to the previous one in the page sequence. */ 970 DLLEXPORT int CALLCONVENTION tqsl_prevStationLocationCapture(tQSL_Location loc); 971 972 /** Returns 1 (in rval) if there is a next page */ 973 DLLEXPORT int CALLCONVENTION tqsl_hasNextStationLocationCapture(tQSL_Location loc, int *rval); 974 975 /** Returns 1 (in rval) if there is a previous page */ 976 DLLEXPORT int CALLCONVENTION tqsl_hasPrevStationLocationCapture(tQSL_Location loc, int *rval); 977 978 /** Save the station location data. Note that the name must have been 979 * set via tqsl_setStationLocationCaptureName if this is a new 980 * station location. If the \c overwrite parameter is zero and a 981 * station location of that name is already in existance, an error 982 * occurs with tQSL_Error set to TQSL_NAME_EXISTS. 983 */ 984 DLLEXPORT int CALLCONVENTION tqsl_saveStationLocationCapture(tQSL_Location loc, int overwrite); 985 986 /** Get the name of the station location */ 987 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCaptureName(tQSL_Location loc, char *namebuf, int bufsiz); 988 989 /** Set the name of the station location */ 990 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCaptureName(tQSL_Location loc, const char *name); 991 992 /** Get the number of saved station locations */ 993 DLLEXPORT int CALLCONVENTION tqsl_getNumStationLocations(tQSL_Location loc, int *nloc); 994 995 /** Get the name of the specified (by \c idx) saved station location */ 996 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationName(tQSL_Location loc, int idx, char *buf, int bufsiz); 997 998 /** Get the call sign from the station location */ 999 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCallSign(tQSL_Location loc, int idx, char *buf, int bufsiz); 1000 1001 /** Get a named field from the station location */ 1002 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationField(tQSL_Location locp, const char *name, char *namebuf, int bufsize); 1003 1004 /** Retrieve a saved station location. 1005 * Once finished wih the station location, tqsl_endStationLocationCapture() 1006 * should be called to release resources. 1007 */ 1008 DLLEXPORT int CALLCONVENTION tqsl_getStationLocation(tQSL_Location *loc, const char *name); 1009 1010 /** Get any errors returned from parsing the selected station location. 1011 * This should be called after tqsl_getStationLocation to determine if 1012 * any of the existing fields failed validation. Currently only zone 1013 * data is validated here, but future validations for things like 1014 * properly formatted grid squares is likely. 1015 */ 1016 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationErrors(tQSL_Location loc, char *buf, int bufsiz); 1017 1018 /** Return the contents of the station data file as a byte stream. 1019 * The caller is required to tqsl_freeStationDataEnc() this pointer when done with it. 1020 */ 1021 DLLEXPORT int CALLCONVENTION tqsl_getStationDataEnc(tQSL_StationDataEnc *sdata); 1022 1023 /** Free the pointer returned by tqsl_getStationDataEnc(tQSL_StationDataEnc*) 1024 */ 1025 DLLEXPORT int CALLCONVENTION tqsl_freeStationDataEnc(tQSL_StationDataEnc sdata); 1026 1027 /** Merge saved location data with existing */ 1028 DLLEXPORT int CALLCONVENTION tqsl_mergeStationLocations(const char *locdata); 1029 1030 /** Remove the stored station location by name. */ 1031 DLLEXPORT int CALLCONVENTION tqsl_deleteStationLocation(const char *name); 1032 1033 /** Restore the deleted station location by name. */ 1034 DLLEXPORT int CALLCONVENTION tqsl_restoreStationLocation(const char *name); 1035 1036 /** Get the list of restorable station locations. */ 1037 DLLEXPORT int CALLCONVENTION tqsl_getDeletedStationLocations(char ***locp, int *nloc); 1038 1039 /** Free the list of restorable station locations. */ 1040 DLLEXPORT void CALLCONVENTION tqsl_freeDeletedLocationList(char **list, int nloc); 1041 1042 /** Get the number of fields on the current station location page */ 1043 DLLEXPORT int CALLCONVENTION tqsl_getNumLocationField(tQSL_Location loc, int *numf); 1044 1045 /** Get the number of characters in the label for the specified field */ 1046 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabelSize(tQSL_Location loc, int field_num, int *rval); 1047 1048 /** Get the label for the specified field */ 1049 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabel(tQSL_Location loc, int field_num, char *buf, int bufsiz); 1050 1051 /** Get the size of the GABBI name of the specified field */ 1052 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBISize(tQSL_Location loc, int field_num, int *rval); 1053 1054 /** Get the GABBI name of the specified field */ 1055 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBI(tQSL_Location loc, int field_num, char *buf, int bufsiz); 1056 1057 /** Get the input type of the input field. 1058 * 1059 * \c type will be one of TQSL_LOCATION_FIELD_TEXT, TQSL_LOCATION_FIELD_DDLIST 1060 * or TQSL_LOCATION_FIELD_LIST 1061 */ 1062 /** Get the number of fields on the current station location page */ 1063 DLLEXPORT int CALLCONVENTION tqsl_getNumLocationField(tQSL_Location loc, int *numf); 1064 1065 /** Get the number of characters in the label for the specified field */ 1066 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabelSize(tQSL_Location loc, int field_num, int *rval); 1067 1068 /** Get the label for the specified field */ 1069 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabel(tQSL_Location loc, int field_num, char *buf, int bufsiz); 1070 1071 /** Get the size of the GABBI name of the specified field */ 1072 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBISize(tQSL_Location loc, int field_num, int *rval); 1073 1074 /** Get the GABBI name of the specified field */ 1075 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBI(tQSL_Location loc, int field_num, char *buf, int bufsiz); 1076 1077 /** Get the input type of the input field. 1078 * 1079 * \c type will be one of TQSL_LOCATION_FIELD_TEXT, TQSL_LOCATION_FIELD_DDLIST 1080 * or TQSL_LOCATION_FIELD_LIST 1081 */ 1082 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldInputType(tQSL_Location loc, int field_num, int *type); 1083 1084 /** Get the data type of the input field. 1085 * 1086 * \c type will be either TQSL_LOCATION_FIELD_CHAR or TQSL_LOCATION_FIELD_INT 1087 */ 1088 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataType(tQSL_Location loc, int field_num, int *type); 1089 1090 /** Get the flags for the input field. 1091 * 1092 * \c flags will be either 1093 * TQSL_LOCATION_FIELD_UPPER Field is to be uppercased on input 1094 * TQSL_LOCATION_FIELD_MUSTSEL Value must be selected 1095 * TQSL_LOCATION_FIELD_SELNXT Value must be selected to allow Next/Finish 1096 * 1097 */ 1098 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldFlags(tQSL_Location loc, int field_num, int *flags); 1099 1100 /** Get the length of the input field data. */ 1101 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLength(tQSL_Location loc, int field_num, int *rval); 1102 1103 /** Get the character data from the specified field. 1104 * 1105 * If the field input type (see tqsl_getLocationFieldInputType()) is 1106 * TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, this will 1107 * return the text of the selected item. 1108 */ 1109 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldCharData(tQSL_Location loc, int field_num, char *buf, int bufsiz); 1110 1111 /** Get the integer data from the specified field. 1112 * 1113 * This is only meaningful if the field data type (see tqsl_getLocationFieldDataType()) 1114 * is TQSL_LOCATION_FIELD_INT. 1115 */ 1116 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldIntData(tQSL_Location loc, int field_num, int *dat); 1117 1118 /** If the field input type (see tqsl_getLocationFieldInputType()) is 1119 * TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, gets the 1120 * index of the selected list item. 1121 */ 1122 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldIndex(tQSL_Location loc, int field_num, int *dat); 1123 1124 /** Get the number of items in the specified field's pick list. */ 1125 DLLEXPORT int CALLCONVENTION tqsl_getNumLocationFieldListItems(tQSL_Location loc, int field_num, int *rval); 1126 1127 /** Get the text of a specified item of a specified field */ 1128 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldListItem(tQSL_Location loc, int field_num, int item_idx, char *buf, int bufsiz); 1129 1130 /** Set the text data of a specified field. */ 1131 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldCharData(tQSL_Location loc, int field_num, const char *buf); 1132 1133 /** Set the integer data of a specified field. 1134 */ 1135 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldIntData(tQSL_Location loc, int field_num, int dat); 1136 1137 /** If the field input type (see tqsl_getLocationFieldInputType()) is 1138 * TQSL_LOCATION_FIELD_DDLIST or TQSL_LOCATION_FIELD_LIST, sets the 1139 * index of the selected list item. 1140 */ 1141 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldIndex(tQSL_Location loc, int field_num, int dat); 1142 1143 /** Get the \e changed status of a field. The changed flag is set to 1 if the 1144 * field's pick list was changed during the last call to tqsl_updateStationLocationCapture 1145 * or zero if the list was not changed. 1146 */ 1147 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldChanged(tQSL_Location loc, int field_num, int *changed); 1148 1149 /** Get the call sign from the station location. */ 1150 DLLEXPORT int CALLCONVENTION tqsl_getLocationCallSign(tQSL_Location loc, char *buf, int bufsiz); 1151 1152 /** Set the call sign for the station location. */ 1153 DLLEXPORT int CALLCONVENTION tqsl_setLocationCallSign(tQSL_Location loc, const char *buf); 1154 1155 /** Get the DXCC entity from the station location. */ 1156 DLLEXPORT int CALLCONVENTION tqsl_getLocationDXCCEntity(tQSL_Location loc, int *dxcc); 1157 1158 /** Get the QSO details in canonical form. */ 1159 DLLEXPORT int CALLCONVENTION tqsl_getLocationQSODetails(tQSL_Location locp, char *buf, int buflen); 1160 1161 /** Get the station location details in canonical form. */ 1162 DLLEXPORT int CALLCONVENTION tqsl_getLocationStationDetails(tQSL_Location locp, char *buf, int buflen); 1163 1164 /** Save the json results for a given callsign location Detail. */ 1165 DLLEXPORT int CALLCONVENTION tqsl_saveCallsignLocationInfo(const char *callsign, const char *json); 1166 1167 /** Retrieve the json results for a given callsign location Detail. */ 1168 DLLEXPORT int CALLCONVENTION tqsl_getCallsignLocationInfo(const char *callsign, char **buf); 1169 1170 /** Get the number of DXCC entities in the master DXCC list. 1171 */ 1172 DLLEXPORT int CALLCONVENTION tqsl_getNumDXCCEntity(int *number); 1173 1174 /** Get a DXCC entity from the list of DXCC entities by its index. 1175 */ 1176 DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntity(int index, int *number, const char **name); 1177 1178 /** Get the name of a DXCC Entity by its DXCC number. 1179 */ 1180 DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntityName(int number, const char **name); 1181 1182 /** Get the zonemap of a DXCC Entity by its DXCC number. 1183 */ 1184 DLLEXPORT int CALLCONVENTION tqsl_getDXCCZoneMap(int number, const char **zonemap); 1185 1186 /** Get the start date of a DXCC Entity by its DXCC number. 1187 */ 1188 DLLEXPORT int CALLCONVENTION tqsl_getDXCCStartDate(int number, tQSL_Date *d); 1189 1190 /** Get the end date of a DXCC Entity by its DXCC number. 1191 */ 1192 DLLEXPORT int CALLCONVENTION tqsl_getDXCCEndDate(int number, tQSL_Date *d); 1193 1194 /** Get the number of Band entries in the Band list */ 1195 DLLEXPORT int CALLCONVENTION tqsl_getNumBand(int *number); 1196 1197 /** Get a band by its index. 1198 * 1199 * \c name - The GAABI name of the band. 1200 * \c spectrum - HF | VHF | UHF 1201 * \c low - The low end of the band in kHz (HF) or MHz (VHF/UHF) 1202 * \c high - The low high of the band in kHz (HF) or MHz (VHF/UHF) 1203 * 1204 * Note: \c spectrum, \c low and/or \c high may be NULL. 1205 */ 1206 DLLEXPORT int CALLCONVENTION tqsl_getBand(int index, const char **name, const char **spectrum, int *low, int *high); 1207 1208 /** Get the number of Mode entries in the Mode list */ 1209 DLLEXPORT int CALLCONVENTION tqsl_getNumMode(int *number); 1210 1211 /** Get a mode by its index. 1212 * 1213 * \c mode - The GAABI mode name 1214 * \c group - CW | PHONE | IMAGE | DATA 1215 * 1216 * Note: \c group may be NULL. 1217 */ 1218 DLLEXPORT int CALLCONVENTION tqsl_getMode(int index, const char **mode, const char **group); 1219 1220 /** Get the number of Propagation Mode entries in the Propagation Mode list */ 1221 DLLEXPORT int CALLCONVENTION tqsl_getNumPropagationMode(int *number); 1222 1223 /** Get a propagation mode by its index. 1224 * 1225 * \c name - The GAABI propagation mode name 1226 * \c descrip - Text description of the propagation mode 1227 * 1228 * Note: \c descrip may be NULL. 1229 */ 1230 DLLEXPORT int CALLCONVENTION tqsl_getPropagationMode(int index, const char **name, const char **descrip); 1231 1232 /** Get the number of Satellite entries in the Satellite list */ 1233 DLLEXPORT int CALLCONVENTION tqsl_getNumSatellite(int *number); 1234 1235 /** Get a satellite by its index. 1236 * 1237 * \c name - The GAABI satellite name 1238 * \c descrip - Text description of the satellite 1239 * \c start - The date the satellite entered service 1240 * \c end - The last date the satellite was in service 1241 * 1242 * Note: \c descrip, start and/or end may be NULL. 1243 */ 1244 DLLEXPORT int CALLCONVENTION tqsl_getSatellite(int index, const char **name, const char **descrip, 1245 tQSL_Date *start, tQSL_Date *end); 1246 1247 /** Clear the map of Cabrillo contests. 1248 */ 1249 DLLEXPORT int CALLCONVENTION tqsl_clearCabrilloMap(); 1250 1251 /** Set the mapping of a Cabrillo contest name (as found in the 1252 * CONTEST line of a Cabrillo file) to the QSO line call-worked field number 1253 * and the contest type. 1254 * 1255 * \c field can have a value of TQSL_MIN_CABRILLO_MAP_FIELD (cabrillo.h) 1256 * or greater. Field number starts at 1. 1257 * 1258 * \c contest_type must be TQSL_CABRILLO_HF or TQSL_CABRILLO_VHF, 1259 * defined in cabrillo.h 1260 */ 1261 DLLEXPORT int CALLCONVENTION tqsl_setCabrilloMapEntry(const char *contest, int field, int contest_type); 1262 1263 /** Get the mapping of a Cabrillo contest name (as found in the 1264 * CONTEST line of a Cabrillo file) to a call-worked field number 1265 * and the contest type. 1266 * 1267 * \c fieldnum will be set to 0 if the contest name isn't in the Cabrillo 1268 * map. Otherwise it is set to the QSO line field number of the call-worked 1269 * field, with field counting starting at 1. 1270 * 1271 * \c contest_type may be NULL. If not, it is set to the Cabrillo contest 1272 * type (TQSL_CABRILLO_HF or TQSL_CABRILLO_VHF), defined in cabrillo.h. 1273 */ 1274 DLLEXPORT int CALLCONVENTION tqsl_getCabrilloMapEntry(const char *contest, int *fieldnum, int *contest_type); 1275 1276 /** Clear the map of ADIF modes 1277 */ 1278 DLLEXPORT int CALLCONVENTION tqsl_clearADIFModes(); 1279 1280 /** Set the mapping of an ADIF mode to a TQSL mode. 1281 */ 1282 DLLEXPORT int CALLCONVENTION tqsl_setADIFMode(const char *adif_item, const char *mode); 1283 1284 /** Map an ADIF mode to its TQSL equivalent. 1285 */ 1286 DLLEXPORT int CALLCONVENTION tqsl_getADIFMode(const char *adif_item, char *mode, int nmode); 1287 1288 /** Get a GABBI record that contains the certificate. 1289 * 1290 * \c uid is the value for the CERT_UID field 1291 * 1292 * Returns the NULL pointer on error. 1293 * 1294 * N.B. On systems that distinguish text-mode files from binary-mode files, 1295 * notably Windows, the GABBI records should be written in binary mode. 1296 */ 1297 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCERT(tQSL_Cert cert, int uid); 1298 1299 /** Get a GABBI record that contains the Staion Location data. 1300 * 1301 * \li \c uid is the value for the STATION_UID field. 1302 * \li \c certuid is the value of the asociated CERT_UID field. 1303 * 1304 * Returns the NULL pointer on error. 1305 * 1306 * N.B. On systems that distinguish text-mode files from binary-mode files, 1307 * notably Windows, the GABBI records should be written in binary mode. 1308 */ 1309 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItSTATION(tQSL_Location loc, int uid, int certuid); 1310 1311 /** Get a GABBI record that contains the QSO data. 1312 * 1313 * \li \c stationuid is the value of the associated STATION_UID field. 1314 * 1315 * N.B.: If \c cert is not initialized for signing (see tqsl_beginSigning()) 1316 * the function will return with a TQSL_SIGNINIT_ERROR error. 1317 * 1318 * Returns the NULL pointer on error. 1319 * 1320 * N.B. On systems that distinguish text-mode files from binary-mode files, 1321 * notably Windows, the GABBI records should be written in binary mode. 1322 */ 1323 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCONTACT(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *qso, 1324 int stationuid); 1325 1326 /** Get a GABBI record that contains the QSO data along with the associated 1327 * signdata (QSO data signed to validate the QSO). 1328 * 1329 * \li \c stationuid is the value of the associated STATION_UID field. 1330 * 1331 * N.B.: If \c cert is not initialized for signing (see tqsl_beginSigning()) 1332 * the function will return with a TQSL_SIGNINIT_ERROR error. 1333 * 1334 * Returns the NULL pointer on error. 1335 * 1336 * N.B. On systems that distinguish text-mode files from binary-mode files, 1337 * notably Windows, the GABBI records should be written in binary mode. 1338 */ 1339 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCONTACTData(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *qso, 1340 int stationuid, char *signdata, int sdlen); 1341 1342 /** @} */ 1343 1344 /** Output to a diagnostic trace file (if one is opened. 1345 * 1346 * \li \c name is the name of the function being executed 1347 */ 1348 DLLEXPORT void CALLCONVENTION tqslTrace(const char *name, const char *format, ...); 1349 /** Close the diagnostic trace file (if it is open) 1350 */ 1351 DLLEXPORT void CALLCONVENTION tqsl_closeDiagFile(void); 1352 /** Close the diagnostic trace file (if it is open) 1353 */ 1354 DLLEXPORT int CALLCONVENTION tqsl_diagFileOpen(void); 1355 /** Returns true if the log file is open 1356 * 1357 */ 1358 DLLEXPORT int CALLCONVENTION tqsl_openDiagFile(const char* file); 1359 1360 #ifdef _WIN32 1361 DLLEXPORT wchar_t* CALLCONVENTION utf8_to_wchar(const char* str); 1362 DLLEXPORT char* CALLCONVENTION wchar_to_utf8(const wchar_t* str, bool forceUTF8); 1363 DLLEXPORT void CALLCONVENTION free_wchar(wchar_t* ptr); 1364 #endif 1365 1366 #ifdef __cplusplus 1367 } 1368 #endif 1369 1370 /* Useful defines */ 1371 #define TQSL_MAX_PW_LENGTH 32 ///< Password buffer length 1372 1373 #endif /* TQSLLIB_H */ 1374