view audioDB_API.h @ 395:bc7a821004bb api-inversion

Invert audioDB::status / audiodb_status().

To do that without breaking abstractions, we actually need a new field
in the status structure, storing the size of the data region.
Previously, this was computed in the audioDB::status request from the
database header, but I'm assuming that "user" code doesn't have access
to such internals.  While we're at it, name some intermediate values in
audioDB::status() so that I don't get confused.

Here's the thing, though: we need to make sure that the adb_t * that we
have from audiodb_open() or audiodb_create() is propagated all the way
through into the C++ routines that implement library functions -- in
particular those which actually write to the database; otherwise we
won't have a consistent view in memory of the header on-disk (as the adb
header that will have been written to disk won't be the same as the one
in memory).

We can do that, by altering the "API" audioDB constructors to take the
adb_t * argument, and setting the adb field in the audioDB object that
we've already introduced to that.  But now we need to be careful a
couple of times: if we have one, then audioDB::initTables() mustn't
stomp on it; also, if we're only constructing an audioDB instance to
fulfil an API request, we mustn't audiodb_close() the one we have when
we destroy the audioDB object, because the adb_t * is the one we have
passed in and are going to reuse in later calls to the API.

The good news is that we can be careful in just these ways with minimal
code.  The really good news is that once the inversion is complete, all
of this horribleness will automatically go away (as there will be no
code which constructs audioDB objects to fulfil API functions).  Hooray!
It's almost like it was all planned this way.

#include <stdbool.h>
/* for API questions contact 
 * Christophe Rhodes [e-mail]
 * Ian Knopke [e-mail], [e-mail] */


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

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

/* 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 */

struct adb {
  char *path;
  int fd;
  int flags;
  adb_header_t *header;
};
/* 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;

//used for both insert and batchinsert
struct adbinsert {

    char * features;
    char * power;
    char * key;
    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 length;
    unsigned int dudCount;
    unsigned int nullCount;
    unsigned int flags;
    off_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;

/* ... 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(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);
int audiodb_dump_withdir(adb_ptr mydb, const char *outputdir);