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.
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 [TQSL_MAX_PATH_LEN]
	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.
DLLEXPORTDATA long	tQSL_ImportSerial
	Serial number of recent certificate import.
DLLEXPORTDATA FILE *	tQSL_DiagFile
	Diagnostic log file.

Detailed Description

Function Documentation

tqsl_compareDates()

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

tqsl_convertDateToText()

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

tqsl_convertTimeToText()

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

tqsl_decodeBase64()

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.

tqsl_encodeBase64()

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

tqsl_getConfigVersion()

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

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

tqsl_getErrorString()

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().

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.

tqsl_getVersion()

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

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

tqsl_init()

DLLEXPORT int CALLCONVENTION tqsl_init

(

)

Initialize the tQSL library

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

tqsl_initDate()

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

tqsl_initTime()

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

tqsl_isDateNull()

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

tqsl_isDateValid()

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

tqsl_isTimeValid()

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

tqsl_setDirectory()

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 appropriate directory if tqsl_setDirectory isn't called. Unless there is some particular need to set the directory explicitly, programs should refrain from doing so.

tqsl_subtractDates()

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

tQSL_Error

DLLEXPORTDATA int tQSL_Error

extern

Error code from most recent tQSL library call.

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