1 /*************************************************************************** 2 adif.h - description 3 ------------------- 4 begin : Wed May 15 2002 5 copyright : (C) 2002 by ARRL 6 email : MSimcik@localhost.localdomain 7 revision : $Id$ 8 ***************************************************************************/ 9 10 #ifndef __ADIF_H 11 #define __ADIF_H 12 13 #include "tqsllib.h" 14 15 #include <stdio.h> 16 #include <stdlib.h> 17 18 /*! \file */ 19 20 /** \defgroup ADIF ADIF API 21 * 22 * These functions and data structures provide a means of parsing an ADIF 23 * file into its component fields, along with range-checking the field contents. 24 */ 25 /** @{ */ 26 27 28 #define TQSL_ADIF_FIELD_NAME_LENGTH_MAX 64 ///< Max length of ADIF field 29 #define TQSL_ADIF_FIELD_SIZE_LENGTH_MAX 10 ///< Max length of field name 30 #define TQSL_ADIF_FIELD_TYPE_LENGTH_MAX 1 ///< Max length of field type 31 32 /*! \enum TQSL_ADIF_BOOLEAN 33 * Boolean type - TRUE/FALSE 34 */ 35 #ifndef TQSL_ADIF_BOOLEAN 36 typedef enum { 37 TQSL_FALSE, 38 TQSL_TRUE 39 } TQSL_ADIF_BOOLEAN; 40 #endif 41 42 typedef void * tQSL_ADIF; ///< Opaque ADIF type 43 44 /// Specifies the type of range limits to apply to a field 45 typedef enum { 46 TQSL_ADIF_RANGE_TYPE_NONE, 47 TQSL_ADIF_RANGE_TYPE_MINMAX, 48 TQSL_ADIF_RANGE_TYPE_ENUMERATION 49 } TQSL_ADIF_RANGE_TYPE; 50 51 /// Response values returned from tqsl_getADIFField() 52 typedef enum { 53 TQSL_ADIF_GET_FIELD_SUCCESS, 54 TQSL_ADIF_GET_FIELD_NO_NAME_MATCH, 55 TQSL_ADIF_GET_FIELD_NO_TYPE_MATCH, 56 TQSL_ADIF_GET_FIELD_NO_RANGE_MATCH, 57 TQSL_ADIF_GET_FIELD_NO_ENUMERATION_MATCH, 58 TQSL_ADIF_GET_FIELD_NO_RESULT_ALLOCATION, 59 TQSL_ADIF_GET_FIELD_NAME_LENGTH_OVERFLOW, 60 TQSL_ADIF_GET_FIELD_DATA_LENGTH_OVERFLOW, 61 TQSL_ADIF_GET_FIELD_SIZE_OVERFLOW, 62 TQSL_ADIF_GET_FIELD_TYPE_OVERFLOW, 63 TQSL_ADIF_GET_FIELD_ERRONEOUS_STATE, 64 TQSL_ADIF_GET_FIELD_EOF 65 } TQSL_ADIF_GET_FIELD_ERROR; 66 67 /** An ADIF field definition */ 68 typedef struct { 69 char name[TQSL_ADIF_FIELD_NAME_LENGTH_MAX + 1]; ///< Field name 70 char type[TQSL_ADIF_FIELD_TYPE_LENGTH_MAX + 1]; ///< Field type 71 TQSL_ADIF_RANGE_TYPE rangeType; ///< Range type 72 unsigned int max_length; ///< Max length 73 long signed min_value; ///< Min value 74 long signed max_value; ///< Max value 75 const char **enumStrings; ///< Enumerated values 76 void *userPointer; ///< user poitner 77 } tqsl_adifFieldDefinitions; 78 79 /** Field returned from parsing */ 80 typedef struct { 81 char name[TQSL_ADIF_FIELD_NAME_LENGTH_MAX + 1]; ///< Field name 82 char size[TQSL_ADIF_FIELD_SIZE_LENGTH_MAX + 1]; ///< Size 83 char type[TQSL_ADIF_FIELD_TYPE_LENGTH_MAX + 1]; ///< Type 84 unsigned char *data; ///< data 85 unsigned int adifNameIndex; ///< Name index 86 void *userPointer; ///< User pointer 87 } tqsl_adifFieldResults; 88 89 90 /* function prototypes */ 91 92 #ifdef __cplusplus 93 extern "C" { 94 #endif 95 96 /** Get the ADIF error message that corresponds to a particular error value */ 97 DLLEXPORT const char* CALLCONVENTION tqsl_adifGetError(TQSL_ADIF_GET_FIELD_ERROR status); 98 99 /** Initialize an ADIF file for reading */ 100 DLLEXPORT int CALLCONVENTION tqsl_beginADIF(tQSL_ADIF *adifp, const char *filename); 101 102 /** Get the next field from an ADIF file 103 * 104 * \li \c adif - ADIF handle returned from tqsl_beginADIF() 105 * \li \c field - pointer to struct that contains the field data and description 106 * \li \c status - pointer to returned status variable 107 * \li \c adifFields - pointer to an array of field-definition structures. The last 108 * item in the array should have an empty string as its \c name member. 109 * \li \c typesDefined - pointer to an array of char pointers that define the 110 * allowed field-type strings. The last item in the array should point to 111 * an empty string. 112 * \li \c allocator - pointer to a function that returns a pointer to a memory 113 * block of the specified size. This function will be called at most one 114 * time during a call to tqsl_getADIFField. The returned pointer will then 115 * be used to populate the \c data member of \c field. The caller is 116 * responsible for freeing this memory, if needed. 117 */ 118 DLLEXPORT int CALLCONVENTION tqsl_getADIFField(tQSL_ADIF adif, tqsl_adifFieldResults *field, TQSL_ADIF_GET_FIELD_ERROR *status, 119 const tqsl_adifFieldDefinitions *adifFields, const char * const *typesDefined, 120 unsigned char *(*allocator)(size_t) ); 121 122 /** Get the current line number (starting from 1) of the input file */ 123 DLLEXPORT int CALLCONVENTION tqsl_getADIFLine(tQSL_ADIF adif, int *lineno); 124 125 /** End and release an ADIF file */ 126 DLLEXPORT int CALLCONVENTION tqsl_endADIF(tQSL_ADIF *adifp); 127 128 /** Form an ADIF field string. 129 * 130 * N.B. On systems that distinguish text-mode files from binary-mode files, 131 * notably Windows, the text should be written in binary mode. 132 */ 133 DLLEXPORT int CALLCONVENTION tqsl_adifMakeField(const char *fieldname, char type, const unsigned char *value, int len, 134 unsigned char *buf, int buflen); 135 136 #ifdef __cplusplus 137 } 138 #endif 139 140 /** @} */ 141 142 #endif /* __ADIF_H */ 143