Utility API

## Functions

DLLEXPORT int CALLCONVENTION | tqsl_init ()
DLLEXPORT int CALLCONVENTION | tqsl_setDirectory (const char *dir)
DLLEXPORT const char *CALLCONVENTION | tqsl_getErrorString ()
DLLEXPORT const char *CALLCONVENTION | tqsl_getErrorString_v (int err)
DLLEXPORT int CALLCONVENTION | tqsl_encodeBase64 (const unsigned char *data, int datalen, char *output, int outputlen)
DLLEXPORT int CALLCONVENTION | tqsl_decodeBase64 (const char *input, unsigned char *data, int *datalen)
DLLEXPORT int CALLCONVENTION | tqsl_initDate (tQSL_Date *date, const char *str)
DLLEXPORT int CALLCONVENTION | tqsl_initTime (tQSL_Time *time, const char *str)
DLLEXPORT int CALLCONVENTION | tqsl_compareDates (const tQSL_Date *a, const tQSL_Date *b)
DLLEXPORT int CALLCONVENTION | tqsl_subtractDates (const tQSL_Date *a, const tQSL_Date *b, int *diff)
DLLEXPORT char *CALLCONVENTION | tqsl_convertDateToText (const tQSL_Date *date, char *buf, int bufsiz)
DLLEXPORT int CALLCONVENTION | tqsl_isDateValid (const tQSL_Date *d)
DLLEXPORT int CALLCONVENTION | tqsl_isDateNull (const tQSL_Date *d)
DLLEXPORT int CALLCONVENTION | tqsl_isTimeValid (const tQSL_Time *t)
DLLEXPORT char *CALLCONVENTION | tqsl_convertTimeToText (const tQSL_Time *time, char *buf, int bufsiz)
DLLEXPORT int CALLCONVENTION | tqsl_getVersion (int *major, int *minor)
DLLEXPORT int CALLCONVENTION | tqsl_getConfigVersion (int *major, int *minor)

## Variables

DLLEXPORTDATA int | tQSL_Error
| Error code from most recent tQSL library call. More...
DLLEXPORTDATA TQSL_ADIF_GET_FIELD_ERROR | tQSL_ADIF_Error
| The ADIF error code.
DLLEXPORTDATA TQSL_CABRILLO_ERROR_TYPE | tQSL_Cabrillo_Error
| The ADIF error code.
DLLEXPORTDATA char | tQSL_ErrorFile [256]
| File name of file giving error. (May be empty.)
DLLEXPORTDATA char | tQSL_CustomError [256]
| Custom error message string.
DLLEXPORTDATA int | tQSL_Errno
| System errno - stored when tQSL_Error == TQSL_SYSTEM_ERROR.
DLLEXPORTDATA char | tQSL_ImportCall [256]
| Callsign used in import - used for missing public key error.

## Detailed Description

## Function Documentation

DLLEXPORT int CALLCONVENTION tqsl_compareDates | ( | const tQSL_Date * | a,
|  | const tQSL_Date * | b
| ) |  |

Compare two tQSL_Date objects.

Returns:

- -1 if `a` < `b`

- 0 if `a` == `b`

- 1 if `a` > `b`

DLLEXPORT char* CALLCONVENTION tqsl_convertDateToText | ( | const tQSL_Date * | date,
|  | char * | buf,
|  | int | bufsiz
| ) |  |

Converts a tQSL_Date object to a YYYY-MM-DD string.

Returns a pointer to `buf` or NULL on error

DLLEXPORT char* CALLCONVENTION tqsl_convertTimeToText | ( | const tQSL_Time * | time,
|  | char * | buf,
|  | int | bufsiz
| ) |  |

Converts a tQSL_Time object to a HH:MM:SSZ string.

Returns a pointer to `buf` or NULL on error

DLLEXPORT int CALLCONVENTION tqsl_decodeBase64 | ( | const char * | input,
|  | unsigned char * | data,
|  | int * | datalen
| ) |  |

Decode Base64 text into binary data.

- `input` = NUL-terminated text string of Base64-encoded data
- `data` = pointer to output buffer
- `datalen` = pointer to int containing the size of the output buffer in bytes

Places the number of resulting data bytes into `*datalen`.

DLLEXPORT int CALLCONVENTION tqsl_encodeBase64 | ( | const unsigned char * | data,
|  | int | datalen,
|  | char * | output,
|  | int | outputlen
| ) |  |

Encode a block of data into Base64 text.

- `data` = block of data to encode
- `datalen` = length of `data` in bytes
- `output` = pointer to output buffer
- `outputlen` = size of output buffer in bytes

DLLEXPORT int CALLCONVENTION tqsl_getConfigVersion | ( | int * | major,
|  | int * | minor
| ) |  |

Returns the configuration-file version. `major` and/or `minor` may be NULL.

DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString | ( |  | ) |

Gets the error string for the current tQSL library error and resets the error status. See tqsl_getErrorString_v().

DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString_v | ( | int | err | ) |

Gets the error string corresponding to the given error number. The error string is available only until the next call to tqsl_getErrorString_v or tqsl_getErrorString.

DLLEXPORT int CALLCONVENTION tqsl_getVersion | ( | int * | major,
|  | int * | minor
| ) |  |

Returns the library version. `major` and/or `minor` may be NULL.

DLLEXPORT int CALLCONVENTION tqsl_init | ( |  | ) |

Initialize the tQSL library

This function should be called prior to calling any other library functions.

DLLEXPORT int CALLCONVENTION tqsl_initDate | ( | tQSL_Date * | date,
|  | const char * | str
| ) |  |

Initialize a tQSL_Date object from a date string.

The date string must be YYYY-MM-DD or YYYYMMDD format.

Returns 0 on success, nonzero on failure

DLLEXPORT int CALLCONVENTION tqsl_initTime | ( | tQSL_Time * | time,
|  | const char * | str
| ) |  |

Initialize a tQSL_Time object from a time string.

The time string must be HH[:]MM[[:]SS] format.

Returns 0 on success, nonzero on failure

DLLEXPORT int CALLCONVENTION tqsl_isDateNull | ( | const tQSL_Date * | d | ) |

Test whether a tQSL_Date is empty (contains all zeroes)

Returns 1 if the date is null

DLLEXPORT int CALLCONVENTION tqsl_isDateValid | ( | const tQSL_Date * | d | ) |

Test whether a tQSL_Date contains a valid date value

Returns 1 if the date is valid

DLLEXPORT int CALLCONVENTION tqsl_isTimeValid | ( | const tQSL_Time * | t | ) |

Test whether a tQSL_Time contains a valid time value

Returns 1 if the time is valid

DLLEXPORT int CALLCONVENTION tqsl_setDirectory | ( | const char * | dir | ) |

Set the directory where the TQSL files are kept. May be called either before of after tqsl_init(), but should be called before calling any other functions in the library.

Note that this is purely optional. The library will figure out an approriate directory if tqsl_setDirectory isn't called. Unless there is some particular need to set the directory explicitly, programs should refrain from doing so.

DLLEXPORT int CALLCONVENTION tqsl_subtractDates | ( | const tQSL_Date * | a,
|  | const tQSL_Date * | b,
|  | int * | diff
| ) |  |

Calculate the number of days between two tQSL_Date objects.

Returns a positive result if the first date is earlier, otherwise negative.

## Variable Documentation

DLLEXPORTDATA int tQSL_Error

Error code from most recent tQSL library call.

The values for the error code are defined in tqslerrno.h