TrustedQSL Library API: ADIF API

TrustedQSL Library API

Classes | Macros | Typedefs | Enumerations | Functions
ADIF API

## Classes
struct | tqsl_adifFieldDefinitions
struct | tqsl_adifFieldResults

## Macros
#define | TQSL_ADIF_FIELD_NAME_LENGTH_MAX 64
| Max length of ADIF field.
#define | TQSL_ADIF_FIELD_SIZE_LENGTH_MAX 10
| Max length of field name.
#define | TQSL_ADIF_FIELD_TYPE_LENGTH_MAX 1
| Max length of field type.

## Typedefs
typedef void * | tQSL_ADIF
| Opaque ADIF type.

## Enumerations
enum | TQSL_ADIF_BOOLEAN { TQSL_FALSE , TQSL_TRUE }
enum | TQSL_ADIF_RANGE_TYPE { TQSL_ADIF_RANGE_TYPE_NONE , TQSL_ADIF_RANGE_TYPE_MINMAX , TQSL_ADIF_RANGE_TYPE_ENUMERATION }
| Specifies the type of range limits to apply to a field.
enum | TQSL_ADIF_GET_FIELD_ERROR { TQSL_ADIF_GET_FIELD_SUCCESS , TQSL_ADIF_GET_FIELD_NO_NAME_MATCH , TQSL_ADIF_GET_FIELD_NO_TYPE_MATCH , TQSL_ADIF_GET_FIELD_NO_RANGE_MATCH , TQSL_ADIF_GET_FIELD_NO_ENUMERATION_MATCH , TQSL_ADIF_GET_FIELD_NO_RESULT_ALLOCATION , TQSL_ADIF_GET_FIELD_NAME_LENGTH_OVERFLOW , TQSL_ADIF_GET_FIELD_DATA_LENGTH_OVERFLOW , TQSL_ADIF_GET_FIELD_SIZE_OVERFLOW , TQSL_ADIF_GET_FIELD_TYPE_OVERFLOW , TQSL_ADIF_GET_FIELD_ERRONEOUS_STATE , TQSL_ADIF_GET_FIELD_EOF }
| Response values returned from tqsl_getADIFField()

## Functions
DLLEXPORT const char *CALLCONVENTION | tqsl_adifGetError (TQSL_ADIF_GET_FIELD_ERROR status)
DLLEXPORT int CALLCONVENTION | tqsl_beginADIF (tQSL_ADIF *adifp, const char *filename)
DLLEXPORT int CALLCONVENTION | tqsl_getADIFField (tQSL_ADIF adif, tqsl_adifFieldResults *field, TQSL_ADIF_GET_FIELD_ERROR *status, const tqsl_adifFieldDefinitions *adifFields, const char *const *typesDefined, unsigned char *(*allocator)(size_t))
DLLEXPORT int CALLCONVENTION | tqsl_getADIFLine (tQSL_ADIF adif, int *lineno)
DLLEXPORT int CALLCONVENTION | tqsl_endADIF (tQSL_ADIF *adifp)
DLLEXPORT int CALLCONVENTION | tqsl_adifMakeField (const char *fieldname, char type, const unsigned char *value, int len, unsigned char *buf, int buflen)

## Detailed Description

These functions and data structures provide a means of parsing an ADIF file into its component fields, along with range-checking the field contents.

## Enumeration Type Documentation

## ◆ TQSL_ADIF_BOOLEAN

enum TQSL_ADIF_BOOLEAN

Boolean type - TRUE/FALSE

## Function Documentation

## ◆ tqsl_adifGetError()

DLLEXPORT const char* CALLCONVENTION tqsl_adifGetError | ( | TQSL_ADIF_GET_FIELD_ERROR | status | ) |

Get the ADIF error message that corresponds to a particular error value

## ◆ tqsl_adifMakeField()

DLLEXPORT int CALLCONVENTION tqsl_adifMakeField | ( | const char * | fieldname,
|  | char | type,
|  | const unsigned char * | value,
|  | int | len,
|  | unsigned char * | buf,
|  | int | buflen
| ) |  |

Form an ADIF field string.

N.B. On systems that distinguish text-mode files from binary-mode files, notably Windows, the text should be written in binary mode.

## ◆ tqsl_beginADIF()

DLLEXPORT int CALLCONVENTION tqsl_beginADIF | ( | tQSL_ADIF * | adifp,
|  | const char * | filename
| ) |  |

Initialize an ADIF file for reading

## ◆ tqsl_endADIF()

DLLEXPORT int CALLCONVENTION tqsl_endADIF | ( | tQSL_ADIF * | adifp | ) |

End and release an ADIF file

## ◆ tqsl_getADIFField()

DLLEXPORT int CALLCONVENTION tqsl_getADIFField | ( | tQSL_ADIF | adif,
|  | tqsl_adifFieldResults * | field,
|  | TQSL_ADIF_GET_FIELD_ERROR * | status,
|  | const tqsl_adifFieldDefinitions * | adifFields,
|  | const char *const * | typesDefined,
|  | unsigned char *(*)(size_t) | allocator
| ) |  |

Get the next field from an ADIF file

- `adif` - ADIF handle returned from tqsl_beginADIF()
- `field` - pointer to struct that contains the field data and description
- `status` - pointer to returned status variable
- `adifFields` - pointer to an array of field-definition structures. The last item in the array should have an empty string as its `name` member.
- `typesDefined` - pointer to an array of char pointers that define the allowed field-type strings. The last item in the array should point to an empty string.
- `allocator` - pointer to a function that returns a pointer to a memory block of the specified size. This function will be called at most one time during a call to tqsl_getADIFField. The returned pointer will then be used to populate the `data` member of `field`. The caller is responsible for freeing this memory, if needed.

## ◆ tqsl_getADIFLine()

DLLEXPORT int CALLCONVENTION tqsl_getADIFLine | ( | tQSL_ADIF | adif,
|  | int * | lineno
| ) |  |

Get the current line number (starting from 1) of the input file