TrustedQSL Library API
tqsllib.h
Go to the documentation of this file.
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
26  #define DLLEXPORTDATA
27  #define CALLCONVENTION
28 #endif
29 
30 #include "adif.h"
31 #include "cabrillo.h"
32 
37 /* Sizes */
38 #define TQSL_MAX_PATH_LEN 256
39 #define TQSL_PASSWORD_MAX 80
40 #define TQSL_NAME_ELEMENT_MAX 256
41 #define TQSL_CALLSIGN_MAX 13
42 #define TQSL_CRQ_NAME_MAX 60
43 #define TQSL_CRQ_ADDR_MAX 80
44 #define TQSL_CRQ_CITY_MAX 80
45 #define TQSL_CRQ_STATE_MAX 80
46 #define TQSL_CRQ_POSTAL_MAX 20
47 #define TQSL_CRQ_COUNTRY_MAX 80
48 #define TQSL_CRQ_EMAIL_MAX 180
49 #define TQSL_BAND_MAX 6
50 #define TQSL_MODE_MAX 16
51 #define TQSL_FREQ_MAX 20
52 #define TQSL_SATNAME_MAX 6
53 #define TQSL_PROPMODE_MAX 6
54 
55 #define TQSL_CERT_CB_USER 0
56 #define TQSL_CERT_CB_CA 1
57 #define TQSL_CERT_CB_ROOT 2
58 #define TQSL_CERT_CB_PKEY 3
59 #define TQSL_CERT_CB_CONFIG 4
60 #define TQSL_CERT_CB_CERT_TYPE(x) ((x) & 0xf)
61 #define TQSL_CERT_CB_MILESTONE 0
62 #define TQSL_CERT_CB_RESULT 0x10
63 #define TQSL_CERT_CB_CALL_TYPE(x) ((x) & TQSL_CERT_CB_RESULT)
64 #define TQSL_CERT_CB_PROMPT 0
65 #define TQSL_CERT_CB_DUPLICATE 0x100
66 #define TQSL_CERT_CB_ERROR 0x200
67 #define TQSL_CERT_CB_LOADED 0x300
68 #define TQSL_CERT_CB_RESULT_TYPE(x) ((x) & 0x0f00)
69 
70 typedef void * tQSL_Cert;
71 typedef void * tQSL_Location;
72 
74 typedef struct {
75  int year;
76  int month;
77  int day;
78 } tQSL_Date;
79 
81 typedef struct {
82  int hour;
83  int minute;
84  int second;
85 } tQSL_Time;
86 
88 typedef struct tqsl_provider_st {
89  char organizationName[TQSL_NAME_ELEMENT_MAX+1];
90  char organizationalUnitName[TQSL_NAME_ELEMENT_MAX+1];
91  char emailAddress[TQSL_NAME_ELEMENT_MAX+1];
92  char url[TQSL_NAME_ELEMENT_MAX+1];
94 
96 typedef struct tqsl_cert_req_st {
97  char providerName[TQSL_NAME_ELEMENT_MAX+1];
98  char providerUnit[TQSL_NAME_ELEMENT_MAX+1];
99  char callSign[TQSL_CALLSIGN_MAX+1];
100  char name[TQSL_CRQ_NAME_MAX+1];
101  char address1[TQSL_CRQ_ADDR_MAX+1];
102  char address2[TQSL_CRQ_ADDR_MAX+1];
103  char city[TQSL_CRQ_CITY_MAX+1];
104  char state[TQSL_CRQ_STATE_MAX+1];
105  char postalCode[TQSL_CRQ_POSTAL_MAX+1];
106  char country[TQSL_CRQ_COUNTRY_MAX+1];
107  char emailAddress[TQSL_CRQ_EMAIL_MAX+1];
108  int dxccEntity;
109  tQSL_Date qsoNotBefore;
110  tQSL_Date qsoNotAfter;
111  char password[TQSL_PASSWORD_MAX+1];
112  tQSL_Cert signer;
113  char renew;
114 } TQSL_CERT_REQ;
115 
117 typedef struct {
118  char callsign[TQSL_CALLSIGN_MAX+1];
119  char band[TQSL_BAND_MAX+1];
120  char mode[TQSL_MODE_MAX+1];
121  tQSL_Date date;
122  tQSL_Time time;
123  char freq[TQSL_FREQ_MAX+1];
124  char rxfreq[TQSL_FREQ_MAX+1];
125  char rxband[TQSL_BAND_MAX+1];
126  char propmode[TQSL_PROPMODE_MAX+1];
127  char satname[TQSL_SATNAME_MAX+1];
129 
131 extern const char *tQSL_BaseDir;
132 
133 #ifdef __cplusplus
134 extern "C" {
135 #endif
136 
141 
142 
144 DLLEXPORTDATA extern int tQSL_Error;
146 DLLEXPORTDATA extern TQSL_ADIF_GET_FIELD_ERROR tQSL_ADIF_Error;
148 DLLEXPORTDATA extern TQSL_CABRILLO_ERROR_TYPE tQSL_Cabrillo_Error;
150 DLLEXPORTDATA extern char tQSL_ErrorFile[256];
152 DLLEXPORTDATA extern char tQSL_CustomError[256];
154 DLLEXPORTDATA extern int tQSL_Errno;
155 
160 DLLEXPORT int CALLCONVENTION tqsl_init();
161 
171 DLLEXPORT int CALLCONVENTION tqsl_setDirectory(const char *dir);
172 
176 DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString();
177 
182 DLLEXPORT const char* CALLCONVENTION tqsl_getErrorString_v(int err);
183 
191 DLLEXPORT int CALLCONVENTION tqsl_encodeBase64(const unsigned char *data, int datalen, char *output, int outputlen);
192 
201 DLLEXPORT int CALLCONVENTION tqsl_decodeBase64(const char *input, unsigned char *data, int *datalen);
202 
209 DLLEXPORT int CALLCONVENTION tqsl_initDate(tQSL_Date *date, const char *str);
210 
217 DLLEXPORT int CALLCONVENTION tqsl_initTime(tQSL_Time *time, const char *str);
218 
228 DLLEXPORT int CALLCONVENTION tqsl_compareDates(const tQSL_Date *a, const tQSL_Date *b);
229 
234 DLLEXPORT char* CALLCONVENTION tqsl_convertDateToText(const tQSL_Date *date, char *buf, int bufsiz);
235 
240 DLLEXPORT int CALLCONVENTION tqsl_isDateValid(const tQSL_Date *d);
241 
246 DLLEXPORT int CALLCONVENTION tqsl_isDateNull(const tQSL_Date *d);
247 
252 DLLEXPORT int CALLCONVENTION tqsl_isTimeValid(const tQSL_Time *t);
253 
258 DLLEXPORT char* CALLCONVENTION tqsl_convertTimeToText(const tQSL_Time *time, char *buf, int bufsiz);
259 
262 DLLEXPORT int CALLCONVENTION tqsl_getVersion(int *major, int *minor);
263 
266 DLLEXPORT int CALLCONVENTION tqsl_getConfigVersion(int *major, int *minor);
267 
296 #define TQSL_SELECT_CERT_WITHKEYS 1
297 #define TQSL_SELECT_CERT_EXPIRED 2
298 #define TQSL_SELECT_CERT_SUPERCEDED 4
299 
325 DLLEXPORT int CALLCONVENTION tqsl_selectCertificates(tQSL_Cert **certlist, int *ncerts,
326  const char *callsign, int dxcc, const tQSL_Date *date, const TQSL_PROVIDER *issuer, int flag);
327 
336 DLLEXPORT int CALLCONVENTION tqsl_getSelectedCertificate(tQSL_Cert *cert, const tQSL_Cert **certlist,
337  int idx);
338 
341 DLLEXPORT int CALLCONVENTION tqsl_getCertificateKeyOnly(tQSL_Cert cert, int *keyonly);
342 
345 DLLEXPORT int CALLCONVENTION tqsl_getCertificateEncoded(tQSL_Cert cert, char *buf, int bufsiz);
346 
349 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerial(tQSL_Cert cert, long *serial);
350 
354 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialExt(tQSL_Cert cert, char *serial, int serialsiz);
355 
359 DLLEXPORT int CALLCONVENTION tqsl_getCertificateSerialLength(tQSL_Cert cert);
360 
370 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuer(tQSL_Cert cert, char *buf, int bufsiz);
371 
381 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganization(tQSL_Cert cert, char *buf, int bufsiz);
391 DLLEXPORT int CALLCONVENTION tqsl_getCertificateIssuerOrganizationalUnit(tQSL_Cert cert, char *buf, int bufsiz);
401 DLLEXPORT int CALLCONVENTION tqsl_getCertificateCallSign(tQSL_Cert cert, char *buf, int bufsiz);
411 DLLEXPORT int CALLCONVENTION tqsl_getCertificateAROName(tQSL_Cert cert, char *buf, int bufsiz);
412 
422 DLLEXPORT int CALLCONVENTION tqsl_getCertificateEmailAddress(tQSL_Cert cert, char *buf, int bufsiz);
423 
432 DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotBeforeDate(tQSL_Cert cert, tQSL_Date *date);
433 
442 DLLEXPORT int CALLCONVENTION tqsl_getCertificateQSONotAfterDate(tQSL_Cert cert, tQSL_Date *date);
443 
452 DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotBeforeDate(tQSL_Cert cert, tQSL_Date *date);
453 
462 DLLEXPORT int CALLCONVENTION tqsl_getCertificateNotAfterDate(tQSL_Cert cert, tQSL_Date *date);
463 
472 DLLEXPORT int CALLCONVENTION tqsl_getCertificateDXCCEntity(tQSL_Cert cert, int *dxcc);
473 
484 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress1(tQSL_Cert cert, char *str, int bufsiz);
485 
496 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestAddress2(tQSL_Cert cert, char *str, int bufsiz);
497 
508 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCity(tQSL_Cert cert, char *str, int bufsiz);
509 
520 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestState(tQSL_Cert cert, char *str, int bufsiz);
521 
532 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestPostalCode(tQSL_Cert cert, char *str, int bufsiz);
533 
544 DLLEXPORT int CALLCONVENTION tqsl_getCertificateRequestCountry(tQSL_Cert cert, char *str, int bufsiz);
545 
546 #define TQSL_PK_TYPE_ERR 0
547 #define TQSL_PK_TYPE_NONE 1
548 #define TQSL_PK_TYPE_UNENC 2
549 #define TQSL_PK_TYPE_ENC 3
550 
565 DLLEXPORT int CALLCONVENTION tqsl_getCertificatePrivateKeyType(tQSL_Cert cert);
566 
567 
571 DLLEXPORT void CALLCONVENTION tqsl_freeCertificate(tQSL_Cert cert);
572 
573 /* int tqsl_checkCertificate(tQSL_Cert); */
574 
592 DLLEXPORT int CALLCONVENTION tqsl_importTQSLFile(const char *file, int(*cb)(int type, const char *message, void *userdata), void *user);
593 
602 DLLEXPORT int CALLCONVENTION tqsl_getSerialFromTQSLFile(const char *file, long *serial);
603 
606 DLLEXPORT int CALLCONVENTION tqsl_getNumProviders(int *n);
607 
612 DLLEXPORT int CALLCONVENTION tqsl_getProvider(int idx, TQSL_PROVIDER *provider);
613 
626 DLLEXPORT int CALLCONVENTION tqsl_createCertRequest(const char *filename, TQSL_CERT_REQ *req,
627  int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user);
628 
636 DLLEXPORT int CALLCONVENTION tqsl_exportPKCS12File(tQSL_Cert cert, const char *filename, const char *p12password);
637 
640 DLLEXPORT int CALLCONVENTION tqsl_importPKCS12File(const char *filename, const char *p12password, const char *password,
641  int (*pwcb)(char *buf, int bufsiz, void *userdata), int(*cb)(int type , const char *message, void *userdata), void *user);
642 
645 DLLEXPORT int CALLCONVENTION tqsl_deleteCertificate(tQSL_Cert cert);
646 
669 DLLEXPORT int CALLCONVENTION tqsl_beginSigning(tQSL_Cert cert, char *password, int(*pwcb)(char *pwbuf, int pwsize, void *userdata), void *user);
670 
675 DLLEXPORT int CALLCONVENTION tqsl_checkSigningStatus(tQSL_Cert cert);
676 
681 DLLEXPORT int CALLCONVENTION tqsl_getMaxSignatureSize(tQSL_Cert cert, int *sigsize);
682 
688 DLLEXPORT int CALLCONVENTION tqsl_signDataBlock(tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int *siglen);
689 
694 DLLEXPORT int CALLCONVENTION tqsl_verifyDataBlock(tQSL_Cert cert, const unsigned char *data, int datalen, unsigned char *sig, int siglen);
695 
703 DLLEXPORT int CALLCONVENTION tqsl_signQSORecord(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *rec, unsigned char *sig, int *siglen);
704 
709 DLLEXPORT int CALLCONVENTION tqsl_endSigning(tQSL_Cert cert);
710 
815 /* Location field input types */
816 
817 #define TQSL_LOCATION_FIELD_TEXT 1
818 #define TQSL_LOCATION_FIELD_DDLIST 2
819 #define TQSL_LOCATION_FIELD_LIST 3
820 #define TQSL_LOCATION_FIELD_BADZONE 4 // Used to return zone selection errors
821 
822 /* Location field data types */
823 #define TQSL_LOCATION_FIELD_CHAR 1
824 #define TQSL_LOCATION_FIELD_INT 2
825 
827 DLLEXPORT int CALLCONVENTION tqsl_initStationLocationCapture(tQSL_Location *locp);
828 
833 DLLEXPORT int CALLCONVENTION tqsl_endStationLocationCapture(tQSL_Location *locp);
834 
836 DLLEXPORT int CALLCONVENTION tqsl_updateStationLocationCapture(tQSL_Location loc);
837 
838 //int tqsl_getNumStationLocationCapturePages(tQSL_Location loc, int *npages);
839 
841 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCapturePage(tQSL_Location loc, int *page);
842 
847 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCapturePage(tQSL_Location loc, int page);
848 
852 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCertFlags(tQSL_Location loc, int flags);
853 
855 DLLEXPORT int CALLCONVENTION tqsl_nextStationLocationCapture(tQSL_Location loc);
856 
858 DLLEXPORT int CALLCONVENTION tqsl_prevStationLocationCapture(tQSL_Location loc);
859 
861 DLLEXPORT int CALLCONVENTION tqsl_hasNextStationLocationCapture(tQSL_Location loc, int *rval);
862 
864 DLLEXPORT int CALLCONVENTION tqsl_hasPrevStationLocationCapture(tQSL_Location loc, int *rval);
865 
872 DLLEXPORT int CALLCONVENTION tqsl_saveStationLocationCapture(tQSL_Location loc, int overwrite);
873 
875 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCaptureName(tQSL_Location loc, char *namebuf, int bufsiz);
876 
878 DLLEXPORT int CALLCONVENTION tqsl_setStationLocationCaptureName(tQSL_Location loc, const char *name);
879 
881 DLLEXPORT int CALLCONVENTION tqsl_getNumStationLocations(tQSL_Location loc, int *nloc);
882 
884 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationName(tQSL_Location loc, int idx, char *buf, int bufsiz);
885 
887 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationCallSign(tQSL_Location loc, int idx, char *buf, int bufsiz);
888 
893 DLLEXPORT int CALLCONVENTION tqsl_getStationLocation(tQSL_Location *loc, const char *name);
894 
901 DLLEXPORT int CALLCONVENTION tqsl_getStationLocationErrors(tQSL_Location loc, char *buf, int bufsiz);
902 
904 DLLEXPORT int CALLCONVENTION tqsl_deleteStationLocation(const char *name);
905 
907 DLLEXPORT int CALLCONVENTION tqsl_getNumLocationField(tQSL_Location loc, int *numf);
908 
910 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabelSize(tQSL_Location loc, int field_num, int *rval);
911 
913 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLabel(tQSL_Location loc, int field_num, char *buf, int bufsiz);
914 
916 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBISize(tQSL_Location loc, int field_num, int *rval);
917 
919 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataGABBI(tQSL_Location loc, int field_num, char *buf, int bufsiz);
920 
926 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldInputType(tQSL_Location loc, int field_num, int *type);
927 
932 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataType(tQSL_Location loc, int field_num, int *type);
933 
942 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldFlags(tQSL_Location loc, int field_num, int *flags);
943 
945 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldDataLength(tQSL_Location loc, int field_num, int *rval);
946 
953 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldCharData(tQSL_Location loc, int field_num, char *buf, int bufsiz);
954 
960 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldIntData(tQSL_Location loc, int field_num, int *dat);
961 
966 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldIndex(tQSL_Location loc, int field_num, int *dat);
967 
969 DLLEXPORT int CALLCONVENTION tqsl_getNumLocationFieldListItems(tQSL_Location loc, int field_num, int *rval);
970 
972 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldListItem(tQSL_Location loc, int field_num, int item_idx, char *buf, int bufsiz);
973 
975 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldCharData(tQSL_Location loc, int field_num, const char *buf);
976 
979 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldIntData(tQSL_Location loc, int field_num, int dat);
980 
985 DLLEXPORT int CALLCONVENTION tqsl_setLocationFieldIndex(tQSL_Location loc, int field_num, int dat);
986 
991 DLLEXPORT int CALLCONVENTION tqsl_getLocationFieldChanged(tQSL_Location loc, int field_num, int *changed);
992 
994 DLLEXPORT int CALLCONVENTION tqsl_getLocationCallSign(tQSL_Location loc, char *buf, int bufsiz);
995 
997 DLLEXPORT int CALLCONVENTION tqsl_getLocationDXCCEntity(tQSL_Location loc, int *dxcc);
998 
1001 DLLEXPORT int CALLCONVENTION tqsl_getNumDXCCEntity(int *number);
1002 
1005 DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntity(int index, int *number, const char **name);
1006 
1009 DLLEXPORT int CALLCONVENTION tqsl_getDXCCEntityName(int number, const char **name);
1010 
1013 DLLEXPORT int CALLCONVENTION tqsl_getDXCCZoneMap(int number, const char **zonemap);
1014 
1016 DLLEXPORT int CALLCONVENTION tqsl_getNumBand(int *number);
1017 
1027 DLLEXPORT int CALLCONVENTION tqsl_getBand(int index, const char **name, const char **spectrum, int *low, int *high);
1028 
1030 DLLEXPORT int CALLCONVENTION tqsl_getNumMode(int *number);
1031 
1039 DLLEXPORT int CALLCONVENTION tqsl_getMode(int index, const char **mode, const char **group);
1040 
1042 DLLEXPORT int CALLCONVENTION tqsl_getNumPropagationMode(int *number);
1043 
1051 DLLEXPORT int CALLCONVENTION tqsl_getPropagationMode(int index, const char **name, const char **descrip);
1052 
1054 DLLEXPORT int CALLCONVENTION tqsl_getNumSatellite(int *number);
1055 
1065 DLLEXPORT int CALLCONVENTION tqsl_getSatellite(int index, const char **name, const char **descrip,
1066  tQSL_Date *start, tQSL_Date *end);
1067 
1070 DLLEXPORT int CALLCONVENTION tqsl_clearCabrilloMap();
1071 
1082 DLLEXPORT int CALLCONVENTION tqsl_setCabrilloMapEntry(const char *contest, int field, int contest_type);
1083 
1095 DLLEXPORT int CALLCONVENTION tqsl_getCabrilloMapEntry(const char *contest, int *fieldnum, int *contest_type);
1096 
1099 DLLEXPORT int CALLCONVENTION tqsl_clearADIFModes();
1100 
1103 DLLEXPORT int CALLCONVENTION tqsl_setADIFMode(const char *adif_item, const char *mode);
1104 
1107 DLLEXPORT int CALLCONVENTION tqsl_getADIFMode(const char *adif_item, char *mode, int nmode);
1108 
1118 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCERT(tQSL_Cert cert, int uid);
1119 
1130 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItSTATION(tQSL_Location loc, int uid, int certuid);
1131 
1144 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCONTACT(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *qso,
1145  int stationuid);
1146 DLLEXPORT const char* CALLCONVENTION tqsl_getGABBItCONTACTData(tQSL_Cert cert, tQSL_Location loc, TQSL_QSO_RECORD *qso,
1147  int stationuid, char *signdata, int sdlen);
1148 
1151 #ifdef __cplusplus
1152 }
1153 #endif
1154 
1155 /* Useful defines */
1156 #define TQSL_MAX_PW_LENGTH 32 /* Password buffer length */
1157 
1158 #endif /* TQSLLIB_H */