view audioDB_API.h @ 417:c52561457dcd api-inversion

Add a text file explaining my plan for the accumulators.

#include <stdbool.h>
#include <stdint.h>

/* for API questions contact 
 * Christophe Rhodes [e-mail]
 * Ian Knopke [e-mail], [e-mail] */

/* Temporary workarounds */
typedef struct dbTableHeader adb_header_t;
int acquire_lock(int, bool);


/*******************************************************************/
/* Data types for API */

/* The main struct that stores the name of the database, and in future will hold all
 * kinds of other interesting information */
/* This basically gets passed around to all of the other functions */

/* FIXME: it might be that "adb_" isn't such a good prefix to use, and
   that we should prefer "audiodb_" */
typedef struct adb adb_t, *adb_ptr;

struct adb_datum {
  uint32_t nvectors;
  uint32_t dim;
  const char *key;
  double *data;
  double *power;
  double *times;
};
typedef struct adb_datum adb_datum_t;

//used for both insert and batchinsert
struct adbinsert {
  const char *features;
  const char *power;
  const char *key;
  const char *times;
};
typedef struct adbinsert adb_insert_t, *adb_insert_ptr;

/* struct for returning status results */
struct adbstatus {
    unsigned int numFiles;  
    unsigned int dim;
    unsigned int dudCount;
    unsigned int nullCount;
    unsigned int flags;
    uint64_t length;
    uint64_t data_region_size;
};
typedef struct adbstatus adb_status_t, *adb_status_ptr;

/* needed for constructing a query */
struct adbquery {

    char * querytype;
    char * feature; //usually a file of some kind
    char * power; //also a file
    char * keylist; //also a file
    char * qpoint;  //position 
    char * numpoints;
    char * radius; 
    char * resultlength; //how many results to make
    char * sequencelength; 
    char * sequencehop; 
    double absolute_threshold; 
    double relative_threshold;
    int exhaustive; //hidden option in gengetopt
    double expandfactor; //hidden
    int rotate; //hidden

};
typedef struct adbquery adb_query_t,*adb_query_ptr;

typedef struct adbresult {
  const char *key;
  double dist;
  uint32_t qpos;
  uint32_t ipos;
} adb_result_t;

#define ADB_REFINE_KEYLIST 1
#define ADB_REFINE_RADIUS 2
#define ADB_REFINE_ABSOLUTE_THRESHOLD 4
#define ADB_REFINE_RELATIVE_THRESHOLD 8
#define ADB_REFINE_DURATION_RATIO 16
#define ADB_REFINE_HOP_SIZE 32

typedef struct adbrefine {
  uint32_t flags;
  uint32_t nkeys;
  const char **keys;
  double radius;
  double absolute_threshold;
  double relative_threshold;
  double duration_ratio; /* expandfactor */
  uint32_t hopsize;
} adb_refine_t;

typedef struct adbqueryparameters {
  uint32_t query_kind;
} adb_query_parameters_t;

typedef struct adbqueryresults {
  uint32_t nresults;
  adb_result_t *results;
} adb_query_results_t;

/* ... and for getting query results back */
struct adbqueryresult {

    int sizeRlist; /* do I really need to return all 4 sizes here */
    int sizeDist;
    int sizeQpos;
    int sizeSpos;
    char **Rlist;
    double *Dist;
    unsigned int *Qpos;
    unsigned int *Spos;

};
typedef struct adbqueryresult adb_queryresult_t, *adb_queryresult_ptr;


/*******************************************************************/
/* Function prototypes for API */

/* open an existing database */
/* returns a struct or NULL on failure */
adb_ptr audiodb_open(const char *path, int flags);

/* create a new database */
/* returns a struct or NULL on failure */
adb_ptr audiodb_create(const char *path, unsigned datasize, unsigned ntracks, unsigned datadim);

/* close a database */
void audiodb_close(adb_ptr db);

/* You'll need to turn both of these on to do anything useful */
int audiodb_l2norm(adb_ptr mydb);
int audiodb_power(adb_ptr mydb);

/* insert functions */
int audiodb_insert_datum(adb_t *, adb_datum_t *);
int audiodb_insert(adb_ptr mydb, adb_insert_ptr ins);
int audiodb_batchinsert(adb_ptr mydb, adb_insert_ptr ins, unsigned int size);

/* query function */
int audiodb_query(adb_ptr mydb, adb_query_ptr adbq, adb_queryresult_ptr adbqres);
  
/* database status */  
int audiodb_status(adb_ptr mydb, adb_status_ptr status);

/* varoius dump formats */
int audiodb_dump(adb_ptr mydb, const char *outputdir);