Artifact c77b6a4a56d80f70fc4f0444030c88724397ed10:

• File ext/fts5/fts5.h — part of check-in [8c6b0aff] at 2014-07-21 14:22:38 on branch fts5 — Add the xTokenize extension API. (user: dan size: 3112)

0000: 2f 2a 0a 2a 2a 20 32 30 31 34 20 4d 61 79 20 33  /*.** 2014 May 3
0010: 31 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  1.**.** The auth
0020: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0030: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0040: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0050: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0060: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0070: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0080: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0090: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
00a0: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
00b0: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
00c0: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
00d0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
00e0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
00f0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
0100: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
0110: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
0120: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 6e 74 65  *****.**.** Inte
0180: 72 66 61 63 65 73 20 74 6f 20 65 78 74 65 6e 64  rfaces to extend
0190: 20 46 54 53 35 2e 20 55 73 69 6e 67 20 74 68 65   FTS5. Using the
01a0: 20 69 6e 74 65 72 66 61 63 65 73 20 64 65 66 69   interfaces defi
01b0: 6e 65 64 20 69 6e 20 74 68 69 73 20 66 69 6c 65  ned in this file
01c0: 2c 20 0a 2a 2a 20 46 54 53 35 20 6d 61 79 20 62  , .** FTS5 may b
01d0: 65 20 65 78 74 65 6e 64 65 64 20 77 69 74 68 3a  e extended with:
01e0: 0a 2a 2a 0a 2a 2a 20 20 20 20 20 2a 20 63 75 73  .**.**     * cus
01f0: 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 73 2c 20  tom tokenizers, 
0200: 61 6e 64 0a 2a 2a 20 20 20 20 20 2a 20 63 75 73  and.**     * cus
0210: 74 6f 6d 20 61 75 78 69 6c 69 61 72 79 20 66 75  tom auxiliary fu
0220: 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 0a 0a 23 69  nctions..*/...#i
0230: 66 6e 64 65 66 20 5f 46 54 53 35 5f 48 0a 23 64  fndef _FTS5_H.#d
0240: 65 66 69 6e 65 20 5f 46 54 53 35 5f 48 0a 0a 23  efine _FTS5_H..#
0250: 69 6e 63 6c 75 64 65 20 22 73 71 6c 69 74 65 33  include "sqlite3
0260: 2e 68 22 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h"../**********
0270: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0280: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0290: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
02a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
02b0: 2a 2a 20 43 55 53 54 4f 4d 20 41 55 58 49 4c 49  ** CUSTOM AUXILI
02c0: 41 52 59 20 46 55 4e 43 54 49 4f 4e 53 0a 2a 2a  ARY FUNCTIONS.**
02d0: 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
02e0: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 73  e implemenations
02f0: 20 6d 61 79 20 6f 76 65 72 6c 6f 61 64 20 53 51   may overload SQ
0300: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 62 79 20 69  L functions by i
0310: 6d 70 6c 65 6d 65 6e 74 69 6e 67 0a 2a 2a 20 74  mplementing.** t
0320: 68 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  he sqlite3_modul
0330: 65 2e 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28  e.xFindFunction(
0340: 29 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 0a 74 79  ) method..*/..ty
0350: 70 65 64 65 66 20 73 74 72 75 63 74 20 46 74 73  pedef struct Fts
0360: 35 45 78 74 65 6e 73 69 6f 6e 41 70 69 20 46 74  5ExtensionApi Ft
0370: 73 35 45 78 74 65 6e 73 69 6f 6e 41 70 69 3b 0a  s5ExtensionApi;.
0380: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 46  typedef struct F
0390: 74 73 35 43 6f 6e 74 65 78 74 20 46 74 73 35 43  ts5Context Fts5C
03a0: 6f 6e 74 65 78 74 3b 0a 0a 74 79 70 65 64 65 66  ontext;..typedef
03b0: 20 76 6f 69 64 20 28 2a 66 74 73 35 5f 65 78 74   void (*fts5_ext
03c0: 65 6e 73 69 6f 6e 5f 66 75 6e 63 74 69 6f 6e 29  ension_function)
03d0: 28 0a 20 20 63 6f 6e 73 74 20 46 74 73 35 45 78  (.  const Fts5Ex
03e0: 74 65 6e 73 69 6f 6e 41 70 69 20 2a 70 41 70 69  tensionApi *pApi
03f0: 2c 20 20 20 2f 2a 20 41 50 49 20 6f 66 66 65 72  ,   /* API offer
0400: 65 64 20 62 79 20 63 75 72 72 65 6e 74 20 46 54  ed by current FT
0410: 53 20 76 65 72 73 69 6f 6e 20 2a 2f 0a 20 20 46  S version */.  F
0420: 74 73 35 43 6f 6e 74 65 78 74 20 2a 70 46 74 73  ts5Context *pFts
0430: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
0440: 2a 20 46 69 72 73 74 20 61 72 67 20 74 6f 20 70  * First arg to p
0450: 61 73 73 20 74 6f 20 70 41 70 69 20 66 75 6e 63  ass to pApi func
0460: 74 69 6f 6e 73 20 2a 2f 0a 20 20 73 71 6c 69 74  tions */.  sqlit
0470: 65 33 5f 63 6f 6e 74 65 78 74 20 2a 70 43 74 78  e3_context *pCtx
0480: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  ,          /* Co
0490: 6e 74 65 78 74 20 66 6f 72 20 72 65 74 75 72 6e  ntext for return
04a0: 69 6e 67 20 72 65 73 75 6c 74 2f 65 72 72 6f 72  ing result/error
04b0: 20 2a 2f 0a 20 20 69 6e 74 20 6e 56 61 6c 2c 20   */.  int nVal, 
04c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
04d0: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
04e0: 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 61 70 56  of values in apV
04f0: 61 6c 5b 5d 20 61 72 72 61 79 20 2a 2f 0a 20 20  al[] array */.  
0500: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
0510: 61 70 56 61 6c 20 20 20 20 20 20 20 20 20 20 20  apVal           
0520: 2f 2a 20 41 72 72 61 79 20 6f 66 20 74 72 61 69  /* Array of trai
0530: 6c 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 2a  ling arguments *
0540: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 0a 2a 2a 20 78  /.);../*.**.** x
0550: 55 73 65 72 44 61 74 61 3a 0a 2a 2a 20 20 20 52  UserData:.**   R
0560: 65 74 75 72 6e 20 61 20 63 6f 70 79 20 6f 66 20  eturn a copy of 
0570: 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
0580: 74 65 72 20 74 68 65 20 65 78 74 65 6e 73 69 6f  ter the extensio
0590: 6e 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 0a  n function was .
05a0: 2a 2a 20 20 20 72 65 67 69 73 74 65 72 65 64 20  **   registered 
05b0: 77 69 74 68 2e 0a 2a 2a 0a 2a 2a 20 78 43 6f 6c  with..**.** xCol
05c0: 75 6d 6e 43 6f 75 6e 74 3a 0a 2a 2a 20 20 20 52  umnCount:.**   R
05d0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
05e0: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
05f0: 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 2e 0a  the FTS5 table..
0600: 2a 2a 0a 2a 2a 20 78 43 6f 6c 75 6d 6e 53 69 7a  **.** xColumnSiz
0610: 65 3a 0a 2a 2a 20 20 20 52 65 70 6f 72 74 73 20  e:.**   Reports 
0620: 74 68 65 20 73 69 7a 65 20 69 6e 20 74 6f 6b 65  the size in toke
0630: 6e 73 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20 76  ns of a column v
0640: 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 75  alue from the cu
0650: 72 72 65 6e 74 20 72 6f 77 2e 0a 2a 2a 0a 2a 2a  rrent row..**.**
0660: 20 78 43 6f 6c 75 6d 6e 54 65 78 74 3a 0a 2a 2a   xColumnText:.**
0670: 20 20 20 52 65 70 6f 72 74 73 20 74 68 65 20 73     Reports the s
0680: 69 7a 65 20 69 6e 20 74 6f 6b 65 6e 73 20 6f 66  ize in tokens of
0690: 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20   a column value 
06a0: 66 72 6f 6d 20 74 68 65 20 63 75 72 72 65 6e 74  from the current
06b0: 20 72 6f 77 2e 0a 2a 2a 0a 2a 2a 20 78 50 68 72   row..**.** xPhr
06c0: 61 73 65 43 6f 75 6e 74 3a 0a 2a 2a 20 20 20 52  aseCount:.**   R
06d0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
06e0: 72 20 6f 66 20 70 68 72 61 73 65 73 20 69 6e 20  r of phrases in 
06f0: 74 68 65 20 63 75 72 72 65 6e 74 20 71 75 65 72  the current quer
0700: 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a  y expression..**
0710: 0a 2a 2a 20 78 50 68 72 61 73 65 53 69 7a 65 3a  .** xPhraseSize:
0720: 0a 2a 2a 20 20 20 52 65 74 75 72 6e 73 20 74 68  .**   Returns th
0730: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65  e number of toke
0740: 6e 73 20 69 6e 20 70 68 72 61 73 65 20 69 50 68  ns in phrase iPh
0750: 72 61 73 65 20 6f 66 20 74 68 65 20 71 75 65 72  rase of the quer
0760: 79 2e 20 50 68 72 61 73 65 73 0a 2a 2a 20 20 20  y. Phrases.**   
0770: 61 72 65 20 6e 75 6d 62 65 72 65 64 20 73 74 61  are numbered sta
0780: 72 74 69 6e 67 20 66 72 6f 6d 20 7a 65 72 6f 2e  rting from zero.
0790: 0a 2a 2a 0a 2a 2a 20 78 52 6f 77 69 64 3a 0a 2a  .**.** xRowid:.*
07a0: 2a 20 20 20 52 65 74 75 72 6e 73 20 74 68 65 20  *   Returns the 
07b0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 63 75 72  rowid of the cur
07c0: 72 65 6e 74 20 72 6f 77 2e 0a 2a 2a 0a 2a 2a 20  rent row..**.** 
07d0: 78 50 6f 73 6c 69 73 74 3a 0a 2a 2a 20 20 20 49  xPoslist:.**   I
07e0: 74 65 72 61 74 65 20 74 68 72 6f 75 67 68 20 69  terate through i
07f0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 70 68 72 61  nstances of phra
0800: 73 65 20 69 50 68 72 61 73 65 20 69 6e 20 74 68  se iPhrase in th
0810: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 0a  e current row. .
0820: 2a 2a 0a 2a 2a 20 78 54 6f 6b 65 6e 69 7a 65 3a  **.** xTokenize:
0830: 0a 2a 2a 20 20 20 54 6f 6b 65 6e 69 7a 65 20 74  .**   Tokenize t
0840: 65 78 74 20 75 73 69 6e 67 20 74 68 65 20 74 6f  ext using the to
0850: 6b 65 6e 69 7a 65 72 20 62 65 6c 6f 6e 67 69 6e  kenizer belongin
0860: 67 20 74 6f 20 74 68 65 20 46 54 53 35 20 74 61  g to the FTS5 ta
0870: 62 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 46  ble..*/.struct F
0880: 74 73 35 45 78 74 65 6e 73 69 6f 6e 41 70 69 20  ts5ExtensionApi 
0890: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
08a0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
08b0: 20 20 20 20 2f 2a 20 43 75 72 72 65 6e 74 6c 79      /* Currently
08c0: 20 61 6c 77 61 79 73 20 73 65 74 20 74 6f 20 31   always set to 1
08d0: 20 2a 2f 0a 0a 20 20 76 6f 69 64 20 2a 28 2a 78   */..  void *(*x
08e0: 55 73 65 72 44 61 74 61 29 28 46 74 73 35 43 6f  UserData)(Fts5Co
08f0: 6e 74 65 78 74 2a 29 3b 0a 0a 20 20 69 6e 74 20  ntext*);..  int 
0900: 28 2a 78 43 6f 6c 75 6d 6e 43 6f 75 6e 74 29 28  (*xColumnCount)(
0910: 46 74 73 35 43 6f 6e 74 65 78 74 2a 29 3b 0a 20  Fts5Context*);. 
0920: 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 41 76   int (*xColumnAv
0930: 67 53 69 7a 65 29 28 46 74 73 35 43 6f 6e 74 65  gSize)(Fts5Conte
0940: 78 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 2c 20 69  xt*, int iCol, i
0950: 6e 74 20 2a 70 6e 54 6f 6b 65 6e 29 3b 0a 20 20  nt *pnToken);.  
0960: 69 6e 74 20 28 2a 78 54 6f 6b 65 6e 69 7a 65 29  int (*xTokenize)
0970: 28 46 74 73 35 43 6f 6e 74 65 78 74 2a 2c 20 0a  (Fts5Context*, .
0980: 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a      const char *
0990: 70 54 65 78 74 2c 20 69 6e 74 20 6e 54 65 78 74  pText, int nText
09a0: 2c 20 2f 2a 20 54 65 78 74 20 74 6f 20 74 6f 6b  , /* Text to tok
09b0: 65 6e 69 7a 65 20 2a 2f 0a 20 20 20 20 76 6f 69  enize */.    voi
09c0: 64 20 2a 70 43 74 78 2c 20 20 20 20 20 20 20 20  d *pCtx,        
09d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
09e0: 6e 74 65 78 74 20 70 61 73 73 65 64 20 74 6f 20  ntext passed to 
09f0: 78 54 6f 6b 65 6e 28 29 20 2a 2f 0a 20 20 20 20  xToken() */.    
0a00: 69 6e 74 20 28 2a 78 54 6f 6b 65 6e 29 28 76 6f  int (*xToken)(vo
0a10: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
0a20: 2c 20 69 6e 74 2c 20 69 6e 74 2c 20 69 6e 74 2c  , int, int, int,
0a30: 20 69 6e 74 29 20 20 20 20 2f 2a 20 43 61 6c 6c   int)    /* Call
0a40: 62 61 63 6b 20 2a 2f 0a 20 20 29 3b 0a 0a 20 20  back */.  );..  
0a50: 69 6e 74 20 28 2a 78 50 68 72 61 73 65 43 6f 75  int (*xPhraseCou
0a60: 6e 74 29 28 46 74 73 35 43 6f 6e 74 65 78 74 2a  nt)(Fts5Context*
0a70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 68 72 61  );.  int (*xPhra
0a80: 73 65 53 69 7a 65 29 28 46 74 73 35 43 6f 6e 74  seSize)(Fts5Cont
0a90: 65 78 74 2a 2c 20 69 6e 74 20 69 50 68 72 61 73  ext*, int iPhras
0aa0: 65 29 3b 0a 0a 20 20 73 71 6c 69 74 65 33 5f 69  e);..  sqlite3_i
0ab0: 6e 74 36 34 20 28 2a 78 52 6f 77 69 64 29 28 46  nt64 (*xRowid)(F
0ac0: 74 73 35 43 6f 6e 74 65 78 74 2a 29 3b 0a 20 20  ts5Context*);.  
0ad0: 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 54 65 78  int (*xColumnTex
0ae0: 74 29 28 46 74 73 35 43 6f 6e 74 65 78 74 2a 2c  t)(Fts5Context*,
0af0: 20 69 6e 74 20 69 43 6f 6c 2c 20 63 6f 6e 73 74   int iCol, const
0b00: 20 63 68 61 72 20 2a 2a 70 7a 2c 20 69 6e 74 20   char **pz, int 
0b10: 2a 70 6e 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  *pn);.  int (*xC
0b20: 6f 6c 75 6d 6e 53 69 7a 65 29 28 46 74 73 35 43  olumnSize)(Fts5C
0b30: 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 69 43 6f  ontext*, int iCo
0b40: 6c 2c 20 69 6e 74 20 2a 70 6e 54 6f 6b 65 6e 29  l, int *pnToken)
0b50: 3b 0a 20 20 69 6e 74 20 28 2a 78 50 6f 73 6c 69  ;.  int (*xPosli
0b60: 73 74 29 28 46 74 73 35 43 6f 6e 74 65 78 74 2a  st)(Fts5Context*
0b70: 2c 20 69 6e 74 20 69 50 68 72 61 73 65 2c 20 69  , int iPhrase, i
0b80: 6e 74 20 2a 70 69 2c 20 69 6e 74 20 2a 70 69 43  nt *pi, int *piC
0b90: 6f 6c 2c 20 69 6e 74 20 2a 70 69 4f 66 66 29 3b  ol, int *piOff);
0ba0: 0a 7d 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 55 53 54  .};../* .** CUST
0bb0: 4f 4d 20 41 55 58 49 4c 49 41 52 59 20 46 55 4e  OM AUXILIARY FUN
0bc0: 43 54 49 4f 4e 53 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  CTIONS.*********
0bd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0be0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0bf0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0c00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0c10: 2f 0a 23 65 6e 64 69 66 20 2f 2a 20 5f 46 54 53  /.#endif /* _FTS
0c20: 35 5f 48 20 2a 2f 0a 0a                          5_H */..