mas01cr@421: #ifndef AUDIODB_API_H
mas01cr@421: #define AUDIODB_API_H
mas01cr@421: 
mas01cr@392: #include <stdbool.h>
mas01cr@398: #include <stdint.h>
mas01cr@398: 
mas01ik@355: /* for API questions contact 
mas01ik@355:  * Christophe Rhodes c.rhodes@gold.ac.uk
mas01ik@355:  * Ian Knopke mas01ik@gold.ac.uk, ian.knopke@gmail.com */
mas01ik@355: 
mas01cr@392: /* Temporary workarounds */
mas01cr@388: typedef struct dbTableHeader adb_header_t;
mas01cr@392: int acquire_lock(int, bool);
mas01cr@496: int divest_lock(int);
mas01cr@388: 
mas01cr@400: 
mas01cr@401: /*******************************************************************/
mas01cr@401: /* Data types for API */
mas01cr@400: 
mas01ik@355: /* The main struct that stores the name of the database, and in future will hold all
mas01ik@355:  * kinds of other interesting information */
mas01ik@355: /* This basically gets passed around to all of the other functions */
mas01cr@388: 
mas01cr@388: /* FIXME: it might be that "adb_" isn't such a good prefix to use, and
mas01cr@419:    that we should prefer "audiodb_".  Or else maybe we should be
mas01cr@419:    calling ourselves libadb? */
mas01ik@355: typedef struct adb adb_t, *adb_ptr;
mas01ik@355: 
mas01cr@404: struct adb_datum {
mas01cr@404:   uint32_t nvectors;
mas01cr@404:   uint32_t dim;
mas01cr@404:   const char *key;
mas01cr@404:   double *data;
mas01cr@404:   double *power;
mas01cr@404:   double *times;
mas01cr@404: };
mas01cr@404: typedef struct adb_datum adb_datum_t;
mas01cr@404: 
mas01ik@355: //used for both insert and batchinsert
mas01ik@355: struct adbinsert {
mas01cr@405:   const char *features;
mas01cr@405:   const char *power;
mas01cr@405:   const char *key;
mas01cr@405:   const char *times;
mas01ik@355: };
mas01cr@441: typedef struct adbinsert adb_insert_t, adb_reference_t, *adb_insert_ptr;
mas01ik@355: 
mas01ik@355: /* struct for returning status results */
mas01ik@355: struct adbstatus {
mas01ik@355:     unsigned int numFiles;  
mas01ik@355:     unsigned int dim;
mas01ik@355:     unsigned int dudCount;
mas01ik@355:     unsigned int nullCount;
mas01ik@355:     unsigned int flags;
mas01cr@398:     uint64_t length;
mas01cr@398:     uint64_t data_region_size;
mas01ik@355: };
mas01ik@355: typedef struct adbstatus adb_status_t, *adb_status_ptr;
mas01ik@355: 
mas01ik@355: /* needed for constructing a query */
mas01ik@355: struct adbquery {
mas01ik@355: 
mas01ik@355:     char * querytype;
mas01ik@355:     char * feature; //usually a file of some kind
mas01ik@355:     char * power; //also a file
mas01ik@355:     char * keylist; //also a file
mas01ik@355:     char * qpoint;  //position 
mas01ik@355:     char * numpoints;
mas01ik@355:     char * radius; 
mas01ik@355:     char * resultlength; //how many results to make
mas01ik@355:     char * sequencelength; 
mas01ik@355:     char * sequencehop; 
mas01ik@355:     double absolute_threshold; 
mas01ik@355:     double relative_threshold;
mas01ik@355:     int exhaustive; //hidden option in gengetopt
mas01ik@355:     double expandfactor; //hidden
mas01ik@355:     int rotate; //hidden
mas01ik@355: 
mas01ik@355: };
mas01ik@355: typedef struct adbquery adb_query_t,*adb_query_ptr;
mas01ik@355: 
mas01ik@355: /* ... and for getting query results back */
mas01ik@355: struct adbqueryresult {
mas01ik@355: 
mas01ik@355:     int sizeRlist; /* do I really need to return all 4 sizes here */
mas01ik@355:     int sizeDist;
mas01ik@355:     int sizeQpos;
mas01ik@355:     int sizeSpos;
mas01ik@355:     char **Rlist;
mas01ik@355:     double *Dist;
mas01ik@355:     unsigned int *Qpos;
mas01ik@355:     unsigned int *Spos;
mas01ik@355: 
mas01ik@355: };
mas01ik@355: typedef struct adbqueryresult adb_queryresult_t, *adb_queryresult_ptr;
mas01ik@355: 
mas01cr@419: /* New ("new" == December 2008) query API */
mas01cr@419: 
mas01cr@419: typedef struct adbresult {
mas01cr@419:   const char *key;
mas01cr@419:   double dist;
mas01cr@419:   uint32_t qpos;
mas01cr@419:   uint32_t ipos;
mas01cr@419: } adb_result_t;
mas01cr@419: 
mas01cr@453: #define ADB_REFINE_INCLUDE_KEYLIST 1
mas01cr@453: #define ADB_REFINE_EXCLUDE_KEYLIST 2
mas01cr@453: #define ADB_REFINE_RADIUS 4
mas01cr@453: #define ADB_REFINE_ABSOLUTE_THRESHOLD 8
mas01cr@453: #define ADB_REFINE_RELATIVE_THRESHOLD 16
mas01cr@453: #define ADB_REFINE_DURATION_RATIO 32
mas01cr@453: #define ADB_REFINE_HOP_SIZE 64
mas01cr@453: 
mas01cr@453: typedef struct adbkeylist {
mas01cr@453:   uint32_t nkeys;
mas01cr@453:   const char **keys;
mas01cr@453: } adb_keylist_t;
mas01cr@419: 
mas01cr@419: typedef struct adbqueryrefine {
mas01cr@419:   uint32_t flags;
mas01cr@453:   adb_keylist_t include;
mas01cr@453:   adb_keylist_t exclude;
mas01cr@419:   double radius;
mas01cr@419:   double absolute_threshold;
mas01cr@419:   double relative_threshold;
mas01cr@419:   double duration_ratio; /* expandfactor */
mas01cr@419:   uint32_t hopsize;
mas01cr@419: } adb_query_refine_t;
mas01cr@419: 
mas01cr@419: #define ADB_ACCUMULATION_DB 1
mas01cr@419: #define ADB_ACCUMULATION_PER_TRACK 2
mas01cr@419: #define ADB_ACCUMULATION_ONE_TO_ONE 3
mas01cr@419: 
mas01cr@419: #define ADB_DISTANCE_DOT_PRODUCT 1
mas01cr@419: #define ADB_DISTANCE_EUCLIDEAN_NORMED 2
mas01cr@419: #define ADB_DISTANCE_EUCLIDEAN 3
mas01cr@419: 
mas01cr@419: typedef struct adbqueryparameters {
mas01cr@419:   uint32_t accumulation;
mas01cr@419:   uint32_t distance;
mas01cr@419:   uint32_t npoints;
mas01cr@419:   uint32_t ntracks;
mas01cr@419: } adb_query_parameters_t;
mas01cr@419: 
mas01cr@419: typedef struct adbqueryresults {
mas01cr@419:   uint32_t nresults;
mas01cr@419:   adb_result_t *results;
mas01cr@419: } adb_query_results_t;
mas01cr@419: 
mas01cr@468: #define ADB_QID_FLAG_EXHAUSTIVE 1
mas01cr@468: #define ADB_QID_FLAG_ALLOW_FALSE_POSITIVES 2
mas01cr@434: 
mas01cr@419: typedef struct adbqueryid {
mas01cr@419:   adb_datum_t *datum;
mas01cr@419:   uint32_t sequence_length;
mas01cr@434:   uint32_t flags;
mas01cr@419:   uint32_t sequence_start;
mas01cr@419: } adb_query_id_t;
mas01cr@419: 
mas01cr@419: typedef struct adbqueryspec {
mas01cr@419:   adb_query_id_t qid;
mas01cr@435:   adb_query_parameters_t params;
mas01cr@435:   adb_query_refine_t refine;
mas01cr@419: } adb_query_spec_t;
mas01ik@355: 
mas01ik@355: /*******************************************************************/
mas01ik@355: /* Function prototypes for API */
mas01ik@355: 
mas01ik@355: /* open an existing database */
mas01ik@355: /* returns a struct or NULL on failure */
mas01cr@392: adb_ptr audiodb_open(const char *path, int flags);
mas01ik@355: 
mas01ik@355: /* create a new database */
mas01ik@355: /* returns a struct or NULL on failure */
mas01cr@381: adb_ptr audiodb_create(const char *path, unsigned datasize, unsigned ntracks, unsigned datadim);
mas01ik@355: 
mas01ik@355: /* close a database */
mas01ik@355: void audiodb_close(adb_ptr db);
mas01ik@355: 
mas01ik@355: /* You'll need to turn both of these on to do anything useful */
mas01ik@355: int audiodb_l2norm(adb_ptr mydb);
mas01ik@355: int audiodb_power(adb_ptr mydb);
mas01ik@355: 
mas01ik@355: /* insert functions */
mas01cr@473: int audiodb_insert_datum(adb_t *, const adb_datum_t *);
mas01cr@473: int audiodb_insert_reference(adb_t *, const adb_reference_t *);
mas01ik@355: int audiodb_insert(adb_ptr mydb, adb_insert_ptr ins);
mas01ik@355: int audiodb_batchinsert(adb_ptr mydb, adb_insert_ptr ins, unsigned int size);
mas01ik@355: 
mas01ik@355: /* query function */
mas01ik@355: int audiodb_query(adb_ptr mydb, adb_query_ptr adbq, adb_queryresult_ptr adbqres);
mas01cr@473: adb_query_results_t *audiodb_query_spec(adb_t *, const adb_query_spec_t *);
mas01cr@473: int audiodb_query_free_results(adb_t *, const adb_query_spec_t *, adb_query_results_t *);
mas01cr@419: 
mas01ik@355: /* database status */  
mas01ik@355: int audiodb_status(adb_ptr mydb, adb_status_ptr status);
mas01ik@355: 
mas01ik@355: /* varoius dump formats */
mas01cr@399: int audiodb_dump(adb_ptr mydb, const char *outputdir);
mas01cr@421: 
mas01cr@421: #endif