ext/rtree/sqlite3rtree.h

   1 /*
   2 ** 2010 August 30
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 */
  13
  14 #ifndef _SQLITE3RTREE_H_
  15 #define _SQLITE3RTREE_H_
  16
  17 #include <sqlite3.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
  24 typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
  25
  26 /* The double-precision datatype used by RTree depends on the
  27 ** SQLITE_RTREE_INT_ONLY compile-time option.
  28 */
  29 #ifdef SQLITE_RTREE_INT_ONLY
  30   typedef sqlite3_int64 sqlite3_rtree_dbl;
  31 #else
  32   typedef double sqlite3_rtree_dbl;
  33 #endif
  34
  35 /*
  36 ** Register a geometry callback named zGeom that can be used as part of an
  37 ** R-Tree geometry query as follows:
  38 **
  39 **   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
  40 */
  41 int sqlite3_rtree_geometry_callback(
  42   sqlite3 *db,
  43   const char *zGeom,
  44   int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
  45   void *pContext
  46 );
  47
  48
  49 /*
  50 ** A pointer to a structure of the following type is passed as the first
  51 ** argument to callbacks registered using rtree_geometry_callback().
  52 */
  53 struct sqlite3_rtree_geometry {
  54   void *pContext;                 /* Copy of pContext passed to s_r_g_c() */
  55   int nParam;                     /* Size of array aParam[] */
  56   sqlite3_rtree_dbl *aParam;      /* Parameters passed to SQL geom function */
  57   void *pUser;                    /* Callback implementation user data */
  58   void (*xDelUser)(void *);       /* Called by SQLite to clean up pUser */
  59 };
  60
  61 /*
  62 ** Register a 2nd-generation geometry callback named zScore that can be
  63 ** used as part of an R-Tree geometry query as follows:
  64 **
  65 **   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
  66 */
  67 int sqlite3_rtree_query_callback(
  68   sqlite3 *db,
  69   const char *zQueryFunc,
  70   int (*xQueryFunc)(sqlite3_rtree_query_info*),
  71   void *pContext,
  72   void (*xDestructor)(void*)
  73 );
  74
  75
  76 /*
  77 ** A pointer to a structure of the following type is passed as the
  78 ** argument to scored geometry callback registered using
  79 ** sqlite3_rtree_query_callback().
  80 **
  81 ** Note that the first 5 fields of this structure are identical to
  82 ** sqlite3_rtree_geometry.  This structure is a subclass of
  83 ** sqlite3_rtree_geometry.
  84 */
  85 struct sqlite3_rtree_query_info {
  86   void *pContext;                   /* pContext from when function registered */
  87   int nParam;                       /* Number of function parameters */
  88   sqlite3_rtree_dbl *aParam;        /* value of function parameters */
  89   void *pUser;                      /* callback can use this, if desired */
  90   void (*xDelUser)(void*);          /* function to free pUser */
  91   sqlite3_rtree_dbl *aCoord;        /* Coordinates of node or entry to check */
  92   unsigned int *anQueue;            /* Number of pending entries in the queue */
  93   int nCoord;                       /* Number of coordinates */
  94   int iLevel;                       /* Level of current node or entry */
  95   int mxLevel;                      /* The largest iLevel value in the tree */
  96   sqlite3_int64 iRowid;             /* Rowid for current entry */
  97   sqlite3_rtree_dbl rParentScore;   /* Score of parent node */
  98   int eParentWithin;                /* Visibility of parent node */
  99   int eWithin;                      /* OUT: Visibility */
 100   sqlite3_rtree_dbl rScore;         /* OUT: Write the score here */
 101   /* The following fields are only available in 3.8.11 and later */
 102   sqlite3_value **apSqlParam;       /* Original SQL values of parameters */
 103 };
 104
 105 /*
 106 ** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
 107 */
 108 #define NOT_WITHIN       0   /* Object completely outside of query region */
 109 #define PARTLY_WITHIN    1   /* Object partially overlaps query region */
 110 #define FULLY_WITHIN     2   /* Object fully contained within query region */
 111
 112
 113 #ifdef __cplusplus
 114 }  /* end of the 'extern "C"' block */
 115 #endif
 116
 117 #endif  /* ifndef _SQLITE3RTREE_H_ */