sqlite3.h 509 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346934793489349935093519352935393549355935693579358935993609361936293639364936593669367936893699370937193729373937493759376937793789379938093819382938393849385938693879388938993909391939293939394939593969397939893999400940194029403940494059406940794089409941094119412941394149415941694179418941994209421942294239424942594269427942894299430943194329433943494359436943794389439944094419442944394449445944694479448944994509451945294539454945594569457945894599460946194629463946494659466946794689469947094719472947394749475947694779478947994809481948294839484948594869487948894899490949194929493949494959496949794989499950095019502950395049505950695079508950995109511951295139514951595169517951895199520952195229523952495259526952795289529953095319532953395349535953695379538953995409541954295439544954595469547954895499550955195529553955495559556955795589559956095619562956395649565956695679568956995709571957295739574957595769577957895799580958195829583958495859586958795889589959095919592959395949595959695979598959996009601960296039604960596069607960896099610961196129613961496159616961796189619962096219622962396249625962696279628962996309631963296339634963596369637963896399640964196429643964496459646964796489649965096519652965396549655965696579658965996609661966296639664966596669667966896699670967196729673967496759676967796789679968096819682968396849685968696879688968996909691969296939694969596969697969896999700970197029703970497059706970797089709971097119712971397149715971697179718971997209721972297239724972597269727972897299730973197329733973497359736973797389739974097419742974397449745974697479748974997509751975297539754975597569757975897599760976197629763976497659766976797689769977097719772977397749775977697779778977997809781978297839784978597869787978897899790979197929793979497959796979797989799980098019802980398049805980698079808980998109811981298139814981598169817981898199820982198229823982498259826982798289829983098319832983398349835983698379838983998409841984298439844984598469847984898499850985198529853985498559856985798589859986098619862986398649865986698679868986998709871987298739874987598769877987898799880988198829883988498859886988798889889989098919892989398949895989698979898989999009901990299039904990599069907990899099910991199129913991499159916991799189919992099219922992399249925992699279928992999309931993299339934993599369937993899399940994199429943994499459946994799489949995099519952995399549955995699579958995999609961996299639964996599669967996899699970997199729973997499759976997799789979998099819982998399849985998699879988998999909991999299939994999599969997999899991000010001100021000310004100051000610007100081000910010100111001210013100141001510016100171001810019100201002110022100231002410025100261002710028100291003010031100321003310034100351003610037100381003910040100411004210043100441004510046100471004810049100501005110052100531005410055100561005710058100591006010061100621006310064100651006610067100681006910070100711007210073100741007510076100771007810079100801008110082100831008410085100861008710088100891009010091100921009310094100951009610097100981009910100101011010210103101041010510106101071010810109101101011110112101131011410115101161011710118101191012010121101221012310124101251012610127101281012910130101311013210133101341013510136101371013810139101401014110142101431014410145101461014710148101491015010151101521015310154101551015610157101581015910160101611016210163101641016510166101671016810169101701017110172101731017410175101761017710178101791018010181101821018310184101851018610187101881018910190101911019210193101941019510196101971019810199102001020110202102031020410205102061020710208102091021010211102121021310214102151021610217102181021910220102211022210223102241022510226102271022810229102301023110232102331023410235102361023710238102391024010241102421024310244102451024610247102481024910250102511025210253102541025510256102571025810259102601026110262102631026410265102661026710268102691027010271102721027310274102751027610277102781027910280102811028210283102841028510286102871028810289102901029110292102931029410295102961029710298102991030010301103021030310304103051030610307103081030910310103111031210313103141031510316103171031810319103201032110322103231032410325103261032710328103291033010331103321033310334103351033610337103381033910340103411034210343103441034510346103471034810349103501035110352103531035410355103561035710358103591036010361103621036310364103651036610367103681036910370103711037210373103741037510376103771037810379103801038110382103831038410385103861038710388103891039010391103921039310394103951039610397103981039910400104011040210403104041040510406104071040810409104101041110412104131041410415104161041710418104191042010421104221042310424104251042610427104281042910430104311043210433104341043510436104371043810439104401044110442104431044410445104461044710448104491045010451104521045310454104551045610457104581045910460104611046210463104641046510466104671046810469104701047110472104731047410475104761047710478104791048010481104821048310484104851048610487104881048910490104911049210493104941049510496104971049810499105001050110502105031050410505105061050710508105091051010511105121051310514105151051610517105181051910520105211052210523105241052510526105271052810529105301053110532105331053410535105361053710538105391054010541105421054310544105451054610547105481054910550105511055210553105541055510556105571055810559105601056110562105631056410565105661056710568105691057010571105721057310574105751057610577105781057910580105811058210583105841058510586105871058810589105901059110592105931059410595105961059710598105991060010601106021060310604106051060610607106081060910610106111061210613106141061510616106171061810619106201062110622106231062410625106261062710628106291063010631106321063310634106351063610637106381063910640106411064210643106441064510646106471064810649106501065110652106531065410655106561065710658106591066010661106621066310664106651066610667106681066910670106711067210673106741067510676106771067810679106801068110682106831068410685106861068710688106891069010691106921069310694106951069610697106981069910700107011070210703107041070510706107071070810709107101071110712107131071410715107161071710718107191072010721107221072310724107251072610727
  1. /*
  2. ** 2001-09-15
  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. ** This header file defines the interface that the SQLite library
  13. ** presents to client programs. If a C-function, structure, datatype,
  14. ** or constant definition does not appear in this file, then it is
  15. ** not a published API of SQLite, is subject to change without
  16. ** notice, and should not be referenced by programs that use SQLite.
  17. **
  18. ** Some of the definitions that are in this file are marked as
  19. ** "experimental". Experimental interfaces are normally new
  20. ** features recently added to SQLite. We do not anticipate changes
  21. ** to experimental interfaces but reserve the right to make minor changes
  22. ** if experience from use "in the wild" suggest such changes are prudent.
  23. **
  24. ** The official C-language API documentation for SQLite is derived
  25. ** from comments in this file. This file is the authoritative source
  26. ** on how SQLite interfaces are supposed to operate.
  27. **
  28. ** The name of this file under configuration management is "sqlite.h.in".
  29. ** The makefile makes some minor changes to this file (such as inserting
  30. ** the version number) and changes its name to "sqlite3.h" as
  31. ** part of the build process.
  32. */
  33. #ifndef SQLITE3_H
  34. #define SQLITE3_H
  35. #include <stdarg.h> /* Needed for the definition of va_list */
  36. /*
  37. ** Make sure we can call this stuff from C++.
  38. */
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42. /*
  43. ** Provide the ability to override linkage features of the interface.
  44. */
  45. #ifndef SQLITE_EXTERN
  46. # define SQLITE_EXTERN extern
  47. #endif
  48. #ifndef SQLITE_API
  49. # define SQLITE_API
  50. #endif
  51. #ifndef SQLITE_CDECL
  52. # define SQLITE_CDECL
  53. #endif
  54. #ifndef SQLITE_APICALL
  55. # define SQLITE_APICALL
  56. #endif
  57. #ifndef SQLITE_STDCALL
  58. # define SQLITE_STDCALL SQLITE_APICALL
  59. #endif
  60. #ifndef SQLITE_CALLBACK
  61. # define SQLITE_CALLBACK
  62. #endif
  63. #ifndef SQLITE_SYSAPI
  64. # define SQLITE_SYSAPI
  65. #endif
  66. /*
  67. ** These no-op macros are used in front of interfaces to mark those
  68. ** interfaces as either deprecated or experimental. New applications
  69. ** should not use deprecated interfaces - they are supported for backwards
  70. ** compatibility only. Application writers should be aware that
  71. ** experimental interfaces are subject to change in point releases.
  72. **
  73. ** These macros used to resolve to various kinds of compiler magic that
  74. ** would generate warning messages when they were used. But that
  75. ** compiler magic ended up generating such a flurry of bug reports
  76. ** that we have taken it all out and gone back to using simple
  77. ** noop macros.
  78. */
  79. #define SQLITE_DEPRECATED
  80. #define SQLITE_EXPERIMENTAL
  81. /*
  82. ** Ensure these symbols were not defined by some previous header file.
  83. */
  84. #ifdef SQLITE_VERSION
  85. # undef SQLITE_VERSION
  86. #endif
  87. #ifdef SQLITE_VERSION_NUMBER
  88. # undef SQLITE_VERSION_NUMBER
  89. #endif
  90. /*
  91. ** CAPI3REF: Compile-Time Library Version Numbers
  92. **
  93. ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
  94. ** evaluates to a string literal that is the SQLite version in the
  95. ** format "X.Y.Z" where X is the major version number (always 3 for
  96. ** SQLite3) and Y is the minor version number and Z is the release number.)^
  97. ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
  98. ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
  99. ** numbers used in [SQLITE_VERSION].)^
  100. ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
  101. ** be larger than the release from which it is derived. Either Y will
  102. ** be held constant and Z will be incremented or else Y will be incremented
  103. ** and Z will be reset to zero.
  104. **
  105. ** Since [version 3.6.18] ([dateof:3.6.18]),
  106. ** SQLite source code has been stored in the
  107. ** <a href="http://www.fossil-scm.org/">Fossil configuration management
  108. ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
  109. ** a string which identifies a particular check-in of SQLite
  110. ** within its configuration management system. ^The SQLITE_SOURCE_ID
  111. ** string contains the date and time of the check-in (UTC) and a SHA1
  112. ** or SHA3-256 hash of the entire source tree. If the source code has
  113. ** been edited in any way since it was last checked in, then the last
  114. ** four hexadecimal digits of the hash may be modified.
  115. **
  116. ** See also: [sqlite3_libversion()],
  117. ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
  118. ** [sqlite_version()] and [sqlite_source_id()].
  119. */
  120. #define SQLITE_VERSION "3.21.0"
  121. #define SQLITE_VERSION_NUMBER 3021000
  122. #define SQLITE_SOURCE_ID "2017-10-24 18:55:49 1a584e499906b5c87ec7d43d4abce641fdf017c42125b083109bc77c4de48827"
  123. /*
  124. ** CAPI3REF: Run-Time Library Version Numbers
  125. ** KEYWORDS: sqlite3_version sqlite3_sourceid
  126. **
  127. ** These interfaces provide the same information as the [SQLITE_VERSION],
  128. ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
  129. ** but are associated with the library instead of the header file. ^(Cautious
  130. ** programmers might include assert() statements in their application to
  131. ** verify that values returned by these interfaces match the macros in
  132. ** the header, and thus ensure that the application is
  133. ** compiled with matching library and header files.
  134. **
  135. ** <blockquote><pre>
  136. ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
  137. ** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
  138. ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
  139. ** </pre></blockquote>)^
  140. **
  141. ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
  142. ** macro. ^The sqlite3_libversion() function returns a pointer to the
  143. ** to the sqlite3_version[] string constant. The sqlite3_libversion()
  144. ** function is provided for use in DLLs since DLL users usually do not have
  145. ** direct access to string constants within the DLL. ^The
  146. ** sqlite3_libversion_number() function returns an integer equal to
  147. ** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
  148. ** a pointer to a string constant whose value is the same as the
  149. ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
  150. ** using an edited copy of [the amalgamation], then the last four characters
  151. ** of the hash might be different from [SQLITE_SOURCE_ID].)^
  152. **
  153. ** See also: [sqlite_version()] and [sqlite_source_id()].
  154. */
  155. SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
  156. SQLITE_API const char *sqlite3_libversion(void);
  157. SQLITE_API const char *sqlite3_sourceid(void);
  158. SQLITE_API int sqlite3_libversion_number(void);
  159. /*
  160. ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
  161. **
  162. ** ^The sqlite3_compileoption_used() function returns 0 or 1
  163. ** indicating whether the specified option was defined at
  164. ** compile time. ^The SQLITE_ prefix may be omitted from the
  165. ** option name passed to sqlite3_compileoption_used().
  166. **
  167. ** ^The sqlite3_compileoption_get() function allows iterating
  168. ** over the list of options that were defined at compile time by
  169. ** returning the N-th compile time option string. ^If N is out of range,
  170. ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
  171. ** prefix is omitted from any strings returned by
  172. ** sqlite3_compileoption_get().
  173. **
  174. ** ^Support for the diagnostic functions sqlite3_compileoption_used()
  175. ** and sqlite3_compileoption_get() may be omitted by specifying the
  176. ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
  177. **
  178. ** See also: SQL functions [sqlite_compileoption_used()] and
  179. ** [sqlite_compileoption_get()] and the [compile_options pragma].
  180. */
  181. #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
  182. SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
  183. SQLITE_API const char *sqlite3_compileoption_get(int N);
  184. #endif
  185. /*
  186. ** CAPI3REF: Test To See If The Library Is Threadsafe
  187. **
  188. ** ^The sqlite3_threadsafe() function returns zero if and only if
  189. ** SQLite was compiled with mutexing code omitted due to the
  190. ** [SQLITE_THREADSAFE] compile-time option being set to 0.
  191. **
  192. ** SQLite can be compiled with or without mutexes. When
  193. ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
  194. ** are enabled and SQLite is threadsafe. When the
  195. ** [SQLITE_THREADSAFE] macro is 0,
  196. ** the mutexes are omitted. Without the mutexes, it is not safe
  197. ** to use SQLite concurrently from more than one thread.
  198. **
  199. ** Enabling mutexes incurs a measurable performance penalty.
  200. ** So if speed is of utmost importance, it makes sense to disable
  201. ** the mutexes. But for maximum safety, mutexes should be enabled.
  202. ** ^The default behavior is for mutexes to be enabled.
  203. **
  204. ** This interface can be used by an application to make sure that the
  205. ** version of SQLite that it is linking against was compiled with
  206. ** the desired setting of the [SQLITE_THREADSAFE] macro.
  207. **
  208. ** This interface only reports on the compile-time mutex setting
  209. ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
  210. ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
  211. ** can be fully or partially disabled using a call to [sqlite3_config()]
  212. ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
  213. ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
  214. ** sqlite3_threadsafe() function shows only the compile-time setting of
  215. ** thread safety, not any run-time changes to that setting made by
  216. ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
  217. ** is unchanged by calls to sqlite3_config().)^
  218. **
  219. ** See the [threading mode] documentation for additional information.
  220. */
  221. SQLITE_API int sqlite3_threadsafe(void);
  222. /*
  223. ** CAPI3REF: Database Connection Handle
  224. ** KEYWORDS: {database connection} {database connections}
  225. **
  226. ** Each open SQLite database is represented by a pointer to an instance of
  227. ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
  228. ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
  229. ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
  230. ** and [sqlite3_close_v2()] are its destructors. There are many other
  231. ** interfaces (such as
  232. ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
  233. ** [sqlite3_busy_timeout()] to name but three) that are methods on an
  234. ** sqlite3 object.
  235. */
  236. typedef struct sqlite3 sqlite3;
  237. /*
  238. ** CAPI3REF: 64-Bit Integer Types
  239. ** KEYWORDS: sqlite_int64 sqlite_uint64
  240. **
  241. ** Because there is no cross-platform way to specify 64-bit integer types
  242. ** SQLite includes typedefs for 64-bit signed and unsigned integers.
  243. **
  244. ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
  245. ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
  246. ** compatibility only.
  247. **
  248. ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
  249. ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
  250. ** sqlite3_uint64 and sqlite_uint64 types can store integer values
  251. ** between 0 and +18446744073709551615 inclusive.
  252. */
  253. #ifdef SQLITE_INT64_TYPE
  254. typedef SQLITE_INT64_TYPE sqlite_int64;
  255. # ifdef SQLITE_UINT64_TYPE
  256. typedef SQLITE_UINT64_TYPE sqlite_uint64;
  257. # else
  258. typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
  259. # endif
  260. #elif defined(_MSC_VER) || defined(__BORLANDC__)
  261. typedef __int64 sqlite_int64;
  262. typedef unsigned __int64 sqlite_uint64;
  263. #else
  264. typedef long long int sqlite_int64;
  265. typedef unsigned long long int sqlite_uint64;
  266. #endif
  267. typedef sqlite_int64 sqlite3_int64;
  268. typedef sqlite_uint64 sqlite3_uint64;
  269. /*
  270. ** If compiling for a processor that lacks floating point support,
  271. ** substitute integer for floating-point.
  272. */
  273. #ifdef SQLITE_OMIT_FLOATING_POINT
  274. # define double sqlite3_int64
  275. #endif
  276. /*
  277. ** CAPI3REF: Closing A Database Connection
  278. ** DESTRUCTOR: sqlite3
  279. **
  280. ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
  281. ** for the [sqlite3] object.
  282. ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
  283. ** the [sqlite3] object is successfully destroyed and all associated
  284. ** resources are deallocated.
  285. **
  286. ** ^If the database connection is associated with unfinalized prepared
  287. ** statements or unfinished sqlite3_backup objects then sqlite3_close()
  288. ** will leave the database connection open and return [SQLITE_BUSY].
  289. ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
  290. ** and/or unfinished sqlite3_backups, then the database connection becomes
  291. ** an unusable "zombie" which will automatically be deallocated when the
  292. ** last prepared statement is finalized or the last sqlite3_backup is
  293. ** finished. The sqlite3_close_v2() interface is intended for use with
  294. ** host languages that are garbage collected, and where the order in which
  295. ** destructors are called is arbitrary.
  296. **
  297. ** Applications should [sqlite3_finalize | finalize] all [prepared statements],
  298. ** [sqlite3_blob_close | close] all [BLOB handles], and
  299. ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
  300. ** with the [sqlite3] object prior to attempting to close the object. ^If
  301. ** sqlite3_close_v2() is called on a [database connection] that still has
  302. ** outstanding [prepared statements], [BLOB handles], and/or
  303. ** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
  304. ** of resources is deferred until all [prepared statements], [BLOB handles],
  305. ** and [sqlite3_backup] objects are also destroyed.
  306. **
  307. ** ^If an [sqlite3] object is destroyed while a transaction is open,
  308. ** the transaction is automatically rolled back.
  309. **
  310. ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
  311. ** must be either a NULL
  312. ** pointer or an [sqlite3] object pointer obtained
  313. ** from [sqlite3_open()], [sqlite3_open16()], or
  314. ** [sqlite3_open_v2()], and not previously closed.
  315. ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
  316. ** argument is a harmless no-op.
  317. */
  318. SQLITE_API int sqlite3_close(sqlite3*);
  319. SQLITE_API int sqlite3_close_v2(sqlite3*);
  320. /*
  321. ** The type for a callback function.
  322. ** This is legacy and deprecated. It is included for historical
  323. ** compatibility and is not documented.
  324. */
  325. typedef int (*sqlite3_callback)(void*,int,char**, char**);
  326. /*
  327. ** CAPI3REF: One-Step Query Execution Interface
  328. ** METHOD: sqlite3
  329. **
  330. ** The sqlite3_exec() interface is a convenience wrapper around
  331. ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
  332. ** that allows an application to run multiple statements of SQL
  333. ** without having to use a lot of C code.
  334. **
  335. ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
  336. ** semicolon-separate SQL statements passed into its 2nd argument,
  337. ** in the context of the [database connection] passed in as its 1st
  338. ** argument. ^If the callback function of the 3rd argument to
  339. ** sqlite3_exec() is not NULL, then it is invoked for each result row
  340. ** coming out of the evaluated SQL statements. ^The 4th argument to
  341. ** sqlite3_exec() is relayed through to the 1st argument of each
  342. ** callback invocation. ^If the callback pointer to sqlite3_exec()
  343. ** is NULL, then no callback is ever invoked and result rows are
  344. ** ignored.
  345. **
  346. ** ^If an error occurs while evaluating the SQL statements passed into
  347. ** sqlite3_exec(), then execution of the current statement stops and
  348. ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
  349. ** is not NULL then any error message is written into memory obtained
  350. ** from [sqlite3_malloc()] and passed back through the 5th parameter.
  351. ** To avoid memory leaks, the application should invoke [sqlite3_free()]
  352. ** on error message strings returned through the 5th parameter of
  353. ** sqlite3_exec() after the error message string is no longer needed.
  354. ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
  355. ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
  356. ** NULL before returning.
  357. **
  358. ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
  359. ** routine returns SQLITE_ABORT without invoking the callback again and
  360. ** without running any subsequent SQL statements.
  361. **
  362. ** ^The 2nd argument to the sqlite3_exec() callback function is the
  363. ** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
  364. ** callback is an array of pointers to strings obtained as if from
  365. ** [sqlite3_column_text()], one for each column. ^If an element of a
  366. ** result row is NULL then the corresponding string pointer for the
  367. ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
  368. ** sqlite3_exec() callback is an array of pointers to strings where each
  369. ** entry represents the name of corresponding result column as obtained
  370. ** from [sqlite3_column_name()].
  371. **
  372. ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
  373. ** to an empty string, or a pointer that contains only whitespace and/or
  374. ** SQL comments, then no SQL statements are evaluated and the database
  375. ** is not changed.
  376. **
  377. ** Restrictions:
  378. **
  379. ** <ul>
  380. ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
  381. ** is a valid and open [database connection].
  382. ** <li> The application must not close the [database connection] specified by
  383. ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
  384. ** <li> The application must not modify the SQL statement text passed into
  385. ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
  386. ** </ul>
  387. */
  388. SQLITE_API int sqlite3_exec(
  389. sqlite3*, /* An open database */
  390. const char *sql, /* SQL to be evaluated */
  391. int (*callback)(void*,int,char**,char**), /* Callback function */
  392. void *, /* 1st argument to callback */
  393. char **errmsg /* Error msg written here */
  394. );
  395. /*
  396. ** CAPI3REF: Result Codes
  397. ** KEYWORDS: {result code definitions}
  398. **
  399. ** Many SQLite functions return an integer result code from the set shown
  400. ** here in order to indicate success or failure.
  401. **
  402. ** New error codes may be added in future versions of SQLite.
  403. **
  404. ** See also: [extended result code definitions]
  405. */
  406. #define SQLITE_OK 0 /* Successful result */
  407. /* beginning-of-error-codes */
  408. #define SQLITE_ERROR 1 /* Generic error */
  409. #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
  410. #define SQLITE_PERM 3 /* Access permission denied */
  411. #define SQLITE_ABORT 4 /* Callback routine requested an abort */
  412. #define SQLITE_BUSY 5 /* The database file is locked */
  413. #define SQLITE_LOCKED 6 /* A table in the database is locked */
  414. #define SQLITE_NOMEM 7 /* A malloc() failed */
  415. #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
  416. #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
  417. #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
  418. #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
  419. #define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
  420. #define SQLITE_FULL 13 /* Insertion failed because database is full */
  421. #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
  422. #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
  423. #define SQLITE_EMPTY 16 /* Internal use only */
  424. #define SQLITE_SCHEMA 17 /* The database schema changed */
  425. #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
  426. #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
  427. #define SQLITE_MISMATCH 20 /* Data type mismatch */
  428. #define SQLITE_MISUSE 21 /* Library used incorrectly */
  429. #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
  430. #define SQLITE_AUTH 23 /* Authorization denied */
  431. #define SQLITE_FORMAT 24 /* Not used */
  432. #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
  433. #define SQLITE_NOTADB 26 /* File opened that is not a database file */
  434. #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
  435. #define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
  436. #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
  437. #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
  438. /* end-of-error-codes */
  439. /*
  440. ** CAPI3REF: Extended Result Codes
  441. ** KEYWORDS: {extended result code definitions}
  442. **
  443. ** In its default configuration, SQLite API routines return one of 30 integer
  444. ** [result codes]. However, experience has shown that many of
  445. ** these result codes are too coarse-grained. They do not provide as
  446. ** much information about problems as programmers might like. In an effort to
  447. ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
  448. ** and later) include
  449. ** support for additional result codes that provide more detailed information
  450. ** about errors. These [extended result codes] are enabled or disabled
  451. ** on a per database connection basis using the
  452. ** [sqlite3_extended_result_codes()] API. Or, the extended code for
  453. ** the most recent error can be obtained using
  454. ** [sqlite3_extended_errcode()].
  455. */
  456. #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
  457. #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
  458. #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
  459. #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
  460. #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
  461. #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
  462. #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
  463. #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
  464. #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
  465. #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
  466. #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
  467. #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
  468. #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
  469. #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
  470. #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
  471. #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
  472. #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
  473. #define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
  474. #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
  475. #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
  476. #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
  477. #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
  478. #define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
  479. #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
  480. #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
  481. #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
  482. #define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
  483. #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
  484. #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
  485. #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
  486. #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
  487. #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
  488. #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
  489. #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
  490. #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
  491. #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
  492. #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
  493. #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
  494. #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
  495. #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
  496. #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
  497. #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
  498. #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
  499. #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
  500. #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
  501. #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
  502. #define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
  503. #define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
  504. #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
  505. #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
  506. #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
  507. #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
  508. #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
  509. #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
  510. #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
  511. #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
  512. #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
  513. #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
  514. #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
  515. /*
  516. ** CAPI3REF: Flags For File Open Operations
  517. **
  518. ** These bit values are intended for use in the
  519. ** 3rd parameter to the [sqlite3_open_v2()] interface and
  520. ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
  521. */
  522. #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
  523. #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
  524. #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
  525. #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
  526. #define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
  527. #define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
  528. #define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
  529. #define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
  530. #define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
  531. #define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
  532. #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
  533. #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
  534. #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
  535. #define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
  536. #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
  537. #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
  538. #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
  539. #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
  540. #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
  541. #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
  542. /* Reserved: 0x00F00000 */
  543. /*
  544. ** CAPI3REF: Device Characteristics
  545. **
  546. ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
  547. ** object returns an integer which is a vector of these
  548. ** bit values expressing I/O characteristics of the mass storage
  549. ** device that holds the file that the [sqlite3_io_methods]
  550. ** refers to.
  551. **
  552. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  553. ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
  554. ** mean that writes of blocks that are nnn bytes in size and
  555. ** are aligned to an address which is an integer multiple of
  556. ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
  557. ** that when data is appended to a file, the data is appended
  558. ** first then the size of the file is extended, never the other
  559. ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
  560. ** information is written to disk in the same order as calls
  561. ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
  562. ** after reboot following a crash or power loss, the only bytes in a
  563. ** file that were written at the application level might have changed
  564. ** and that adjacent bytes, even bytes within the same sector are
  565. ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  566. ** flag indicates that a file cannot be deleted when open. The
  567. ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
  568. ** read-only media and cannot be changed even by processes with
  569. ** elevated privileges.
  570. **
  571. ** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
  572. ** filesystem supports doing multiple write operations atomically when those
  573. ** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
  574. ** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
  575. */
  576. #define SQLITE_IOCAP_ATOMIC 0x00000001
  577. #define SQLITE_IOCAP_ATOMIC512 0x00000002
  578. #define SQLITE_IOCAP_ATOMIC1K 0x00000004
  579. #define SQLITE_IOCAP_ATOMIC2K 0x00000008
  580. #define SQLITE_IOCAP_ATOMIC4K 0x00000010
  581. #define SQLITE_IOCAP_ATOMIC8K 0x00000020
  582. #define SQLITE_IOCAP_ATOMIC16K 0x00000040
  583. #define SQLITE_IOCAP_ATOMIC32K 0x00000080
  584. #define SQLITE_IOCAP_ATOMIC64K 0x00000100
  585. #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
  586. #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
  587. #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
  588. #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
  589. #define SQLITE_IOCAP_IMMUTABLE 0x00002000
  590. #define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
  591. /*
  592. ** CAPI3REF: File Locking Levels
  593. **
  594. ** SQLite uses one of these integer values as the second
  595. ** argument to calls it makes to the xLock() and xUnlock() methods
  596. ** of an [sqlite3_io_methods] object.
  597. */
  598. #define SQLITE_LOCK_NONE 0
  599. #define SQLITE_LOCK_SHARED 1
  600. #define SQLITE_LOCK_RESERVED 2
  601. #define SQLITE_LOCK_PENDING 3
  602. #define SQLITE_LOCK_EXCLUSIVE 4
  603. /*
  604. ** CAPI3REF: Synchronization Type Flags
  605. **
  606. ** When SQLite invokes the xSync() method of an
  607. ** [sqlite3_io_methods] object it uses a combination of
  608. ** these integer values as the second argument.
  609. **
  610. ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
  611. ** sync operation only needs to flush data to mass storage. Inode
  612. ** information need not be flushed. If the lower four bits of the flag
  613. ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
  614. ** If the lower four bits equal SQLITE_SYNC_FULL, that means
  615. ** to use Mac OS X style fullsync instead of fsync().
  616. **
  617. ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
  618. ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
  619. ** settings. The [synchronous pragma] determines when calls to the
  620. ** xSync VFS method occur and applies uniformly across all platforms.
  621. ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
  622. ** energetic or rigorous or forceful the sync operations are and
  623. ** only make a difference on Mac OSX for the default SQLite code.
  624. ** (Third-party VFS implementations might also make the distinction
  625. ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
  626. ** operating systems natively supported by SQLite, only Mac OSX
  627. ** cares about the difference.)
  628. */
  629. #define SQLITE_SYNC_NORMAL 0x00002
  630. #define SQLITE_SYNC_FULL 0x00003
  631. #define SQLITE_SYNC_DATAONLY 0x00010
  632. /*
  633. ** CAPI3REF: OS Interface Open File Handle
  634. **
  635. ** An [sqlite3_file] object represents an open file in the
  636. ** [sqlite3_vfs | OS interface layer]. Individual OS interface
  637. ** implementations will
  638. ** want to subclass this object by appending additional fields
  639. ** for their own use. The pMethods entry is a pointer to an
  640. ** [sqlite3_io_methods] object that defines methods for performing
  641. ** I/O operations on the open file.
  642. */
  643. typedef struct sqlite3_file sqlite3_file;
  644. struct sqlite3_file {
  645. const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
  646. };
  647. /*
  648. ** CAPI3REF: OS Interface File Virtual Methods Object
  649. **
  650. ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
  651. ** [sqlite3_file] object (or, more commonly, a subclass of the
  652. ** [sqlite3_file] object) with a pointer to an instance of this object.
  653. ** This object defines the methods used to perform various operations
  654. ** against the open file represented by the [sqlite3_file] object.
  655. **
  656. ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
  657. ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
  658. ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
  659. ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
  660. ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
  661. ** to NULL.
  662. **
  663. ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
  664. ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
  665. ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
  666. ** flag may be ORed in to indicate that only the data of the file
  667. ** and not its inode needs to be synced.
  668. **
  669. ** The integer values to xLock() and xUnlock() are one of
  670. ** <ul>
  671. ** <li> [SQLITE_LOCK_NONE],
  672. ** <li> [SQLITE_LOCK_SHARED],
  673. ** <li> [SQLITE_LOCK_RESERVED],
  674. ** <li> [SQLITE_LOCK_PENDING], or
  675. ** <li> [SQLITE_LOCK_EXCLUSIVE].
  676. ** </ul>
  677. ** xLock() increases the lock. xUnlock() decreases the lock.
  678. ** The xCheckReservedLock() method checks whether any database connection,
  679. ** either in this process or in some other process, is holding a RESERVED,
  680. ** PENDING, or EXCLUSIVE lock on the file. It returns true
  681. ** if such a lock exists and false otherwise.
  682. **
  683. ** The xFileControl() method is a generic interface that allows custom
  684. ** VFS implementations to directly control an open file using the
  685. ** [sqlite3_file_control()] interface. The second "op" argument is an
  686. ** integer opcode. The third argument is a generic pointer intended to
  687. ** point to a structure that may contain arguments or space in which to
  688. ** write return values. Potential uses for xFileControl() might be
  689. ** functions to enable blocking locks with timeouts, to change the
  690. ** locking strategy (for example to use dot-file locks), to inquire
  691. ** about the status of a lock, or to break stale locks. The SQLite
  692. ** core reserves all opcodes less than 100 for its own use.
  693. ** A [file control opcodes | list of opcodes] less than 100 is available.
  694. ** Applications that define a custom xFileControl method should use opcodes
  695. ** greater than 100 to avoid conflicts. VFS implementations should
  696. ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
  697. ** recognize.
  698. **
  699. ** The xSectorSize() method returns the sector size of the
  700. ** device that underlies the file. The sector size is the
  701. ** minimum write that can be performed without disturbing
  702. ** other bytes in the file. The xDeviceCharacteristics()
  703. ** method returns a bit vector describing behaviors of the
  704. ** underlying device:
  705. **
  706. ** <ul>
  707. ** <li> [SQLITE_IOCAP_ATOMIC]
  708. ** <li> [SQLITE_IOCAP_ATOMIC512]
  709. ** <li> [SQLITE_IOCAP_ATOMIC1K]
  710. ** <li> [SQLITE_IOCAP_ATOMIC2K]
  711. ** <li> [SQLITE_IOCAP_ATOMIC4K]
  712. ** <li> [SQLITE_IOCAP_ATOMIC8K]
  713. ** <li> [SQLITE_IOCAP_ATOMIC16K]
  714. ** <li> [SQLITE_IOCAP_ATOMIC32K]
  715. ** <li> [SQLITE_IOCAP_ATOMIC64K]
  716. ** <li> [SQLITE_IOCAP_SAFE_APPEND]
  717. ** <li> [SQLITE_IOCAP_SEQUENTIAL]
  718. ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
  719. ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
  720. ** <li> [SQLITE_IOCAP_IMMUTABLE]
  721. ** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
  722. ** </ul>
  723. **
  724. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  725. ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
  726. ** mean that writes of blocks that are nnn bytes in size and
  727. ** are aligned to an address which is an integer multiple of
  728. ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
  729. ** that when data is appended to a file, the data is appended
  730. ** first then the size of the file is extended, never the other
  731. ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
  732. ** information is written to disk in the same order as calls
  733. ** to xWrite().
  734. **
  735. ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
  736. ** in the unread portions of the buffer with zeros. A VFS that
  737. ** fails to zero-fill short reads might seem to work. However,
  738. ** failure to zero-fill short reads will eventually lead to
  739. ** database corruption.
  740. */
  741. typedef struct sqlite3_io_methods sqlite3_io_methods;
  742. struct sqlite3_io_methods {
  743. int iVersion;
  744. int (*xClose)(sqlite3_file*);
  745. int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  746. int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  747. int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  748. int (*xSync)(sqlite3_file*, int flags);
  749. int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  750. int (*xLock)(sqlite3_file*, int);
  751. int (*xUnlock)(sqlite3_file*, int);
  752. int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  753. int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  754. int (*xSectorSize)(sqlite3_file*);
  755. int (*xDeviceCharacteristics)(sqlite3_file*);
  756. /* Methods above are valid for version 1 */
  757. int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  758. int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  759. void (*xShmBarrier)(sqlite3_file*);
  760. int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  761. /* Methods above are valid for version 2 */
  762. int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  763. int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  764. /* Methods above are valid for version 3 */
  765. /* Additional methods may be added in future releases */
  766. };
  767. /*
  768. ** CAPI3REF: Standard File Control Opcodes
  769. ** KEYWORDS: {file control opcodes} {file control opcode}
  770. **
  771. ** These integer constants are opcodes for the xFileControl method
  772. ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
  773. ** interface.
  774. **
  775. ** <ul>
  776. ** <li>[[SQLITE_FCNTL_LOCKSTATE]]
  777. ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
  778. ** opcode causes the xFileControl method to write the current state of
  779. ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
  780. ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
  781. ** into an integer that the pArg argument points to. This capability
  782. ** is used during testing and is only available when the SQLITE_TEST
  783. ** compile-time option is used.
  784. **
  785. ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
  786. ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
  787. ** layer a hint of how large the database file will grow to be during the
  788. ** current transaction. This hint is not guaranteed to be accurate but it
  789. ** is often close. The underlying VFS might choose to preallocate database
  790. ** file space based on this hint in order to help writes to the database
  791. ** file run faster.
  792. **
  793. ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
  794. ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
  795. ** extends and truncates the database file in chunks of a size specified
  796. ** by the user. The fourth argument to [sqlite3_file_control()] should
  797. ** point to an integer (type int) containing the new chunk-size to use
  798. ** for the nominated database. Allocating database file space in large
  799. ** chunks (say 1MB at a time), may reduce file-system fragmentation and
  800. ** improve performance on some systems.
  801. **
  802. ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
  803. ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
  804. ** to the [sqlite3_file] object associated with a particular database
  805. ** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
  806. **
  807. ** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
  808. ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
  809. ** to the [sqlite3_file] object associated with the journal file (either
  810. ** the [rollback journal] or the [write-ahead log]) for a particular database
  811. ** connection. See also [SQLITE_FCNTL_FILE_POINTER].
  812. **
  813. ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
  814. ** No longer in use.
  815. **
  816. ** <li>[[SQLITE_FCNTL_SYNC]]
  817. ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
  818. ** sent to the VFS immediately before the xSync method is invoked on a
  819. ** database file descriptor. Or, if the xSync method is not invoked
  820. ** because the user has configured SQLite with
  821. ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
  822. ** of the xSync method. In most cases, the pointer argument passed with
  823. ** this file-control is NULL. However, if the database file is being synced
  824. ** as part of a multi-database commit, the argument points to a nul-terminated
  825. ** string containing the transactions master-journal file name. VFSes that
  826. ** do not need this signal should silently ignore this opcode. Applications
  827. ** should not call [sqlite3_file_control()] with this opcode as doing so may
  828. ** disrupt the operation of the specialized VFSes that do require it.
  829. **
  830. ** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
  831. ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
  832. ** and sent to the VFS after a transaction has been committed immediately
  833. ** but before the database is unlocked. VFSes that do not need this signal
  834. ** should silently ignore this opcode. Applications should not call
  835. ** [sqlite3_file_control()] with this opcode as doing so may disrupt the
  836. ** operation of the specialized VFSes that do require it.
  837. **
  838. ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
  839. ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
  840. ** retry counts and intervals for certain disk I/O operations for the
  841. ** windows [VFS] in order to provide robustness in the presence of
  842. ** anti-virus programs. By default, the windows VFS will retry file read,
  843. ** file write, and file delete operations up to 10 times, with a delay
  844. ** of 25 milliseconds before the first retry and with the delay increasing
  845. ** by an additional 25 milliseconds with each subsequent retry. This
  846. ** opcode allows these two values (10 retries and 25 milliseconds of delay)
  847. ** to be adjusted. The values are changed for all database connections
  848. ** within the same process. The argument is a pointer to an array of two
  849. ** integers where the first integer is the new retry count and the second
  850. ** integer is the delay. If either integer is negative, then the setting
  851. ** is not changed but instead the prior value of that setting is written
  852. ** into the array entry, allowing the current retry settings to be
  853. ** interrogated. The zDbName parameter is ignored.
  854. **
  855. ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
  856. ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
  857. ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
  858. ** write ahead log and shared memory files used for transaction control
  859. ** are automatically deleted when the latest connection to the database
  860. ** closes. Setting persistent WAL mode causes those files to persist after
  861. ** close. Persisting the files is useful when other processes that do not
  862. ** have write permission on the directory containing the database file want
  863. ** to read the database file, as the WAL and shared memory files must exist
  864. ** in order for the database to be readable. The fourth parameter to
  865. ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  866. ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
  867. ** WAL mode. If the integer is -1, then it is overwritten with the current
  868. ** WAL persistence setting.
  869. **
  870. ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
  871. ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
  872. ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
  873. ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
  874. ** xDeviceCharacteristics methods. The fourth parameter to
  875. ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  876. ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
  877. ** mode. If the integer is -1, then it is overwritten with the current
  878. ** zero-damage mode setting.
  879. **
  880. ** <li>[[SQLITE_FCNTL_OVERWRITE]]
  881. ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
  882. ** a write transaction to indicate that, unless it is rolled back for some
  883. ** reason, the entire database file will be overwritten by the current
  884. ** transaction. This is used by VACUUM operations.
  885. **
  886. ** <li>[[SQLITE_FCNTL_VFSNAME]]
  887. ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
  888. ** all [VFSes] in the VFS stack. The names are of all VFS shims and the
  889. ** final bottom-level VFS are written into memory obtained from
  890. ** [sqlite3_malloc()] and the result is stored in the char* variable
  891. ** that the fourth parameter of [sqlite3_file_control()] points to.
  892. ** The caller is responsible for freeing the memory when done. As with
  893. ** all file-control actions, there is no guarantee that this will actually
  894. ** do anything. Callers should initialize the char* variable to a NULL
  895. ** pointer in case this file-control is not implemented. This file-control
  896. ** is intended for diagnostic use only.
  897. **
  898. ** <li>[[SQLITE_FCNTL_VFS_POINTER]]
  899. ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
  900. ** [VFSes] currently in use. ^(The argument X in
  901. ** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
  902. ** of type "[sqlite3_vfs] **". This opcodes will set *X
  903. ** to a pointer to the top-level VFS.)^
  904. ** ^When there are multiple VFS shims in the stack, this opcode finds the
  905. ** upper-most shim only.
  906. **
  907. ** <li>[[SQLITE_FCNTL_PRAGMA]]
  908. ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
  909. ** file control is sent to the open [sqlite3_file] object corresponding
  910. ** to the database file to which the pragma statement refers. ^The argument
  911. ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
  912. ** pointers to strings (char**) in which the second element of the array
  913. ** is the name of the pragma and the third element is the argument to the
  914. ** pragma or NULL if the pragma has no argument. ^The handler for an
  915. ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
  916. ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
  917. ** or the equivalent and that string will become the result of the pragma or
  918. ** the error message if the pragma fails. ^If the
  919. ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
  920. ** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
  921. ** file control returns [SQLITE_OK], then the parser assumes that the
  922. ** VFS has handled the PRAGMA itself and the parser generates a no-op
  923. ** prepared statement if result string is NULL, or that returns a copy
  924. ** of the result string if the string is non-NULL.
  925. ** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
  926. ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
  927. ** that the VFS encountered an error while handling the [PRAGMA] and the
  928. ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
  929. ** file control occurs at the beginning of pragma statement analysis and so
  930. ** it is able to override built-in [PRAGMA] statements.
  931. **
  932. ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
  933. ** ^The [SQLITE_FCNTL_BUSYHANDLER]
  934. ** file-control may be invoked by SQLite on the database file handle
  935. ** shortly after it is opened in order to provide a custom VFS with access
  936. ** to the connections busy-handler callback. The argument is of type (void **)
  937. ** - an array of two (void *) values. The first (void *) actually points
  938. ** to a function of type (int (*)(void *)). In order to invoke the connections
  939. ** busy-handler, this function should be invoked with the second (void *) in
  940. ** the array as the only argument. If it returns non-zero, then the operation
  941. ** should be retried. If it returns zero, the custom VFS should abandon the
  942. ** current operation.
  943. **
  944. ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
  945. ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
  946. ** to have SQLite generate a
  947. ** temporary filename using the same algorithm that is followed to generate
  948. ** temporary filenames for TEMP tables and other internal uses. The
  949. ** argument should be a char** which will be filled with the filename
  950. ** written into memory obtained from [sqlite3_malloc()]. The caller should
  951. ** invoke [sqlite3_free()] on the result to avoid a memory leak.
  952. **
  953. ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
  954. ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
  955. ** maximum number of bytes that will be used for memory-mapped I/O.
  956. ** The argument is a pointer to a value of type sqlite3_int64 that
  957. ** is an advisory maximum number of bytes in the file to memory map. The
  958. ** pointer is overwritten with the old value. The limit is not changed if
  959. ** the value originally pointed to is negative, and so the current limit
  960. ** can be queried by passing in a pointer to a negative number. This
  961. ** file-control is used internally to implement [PRAGMA mmap_size].
  962. **
  963. ** <li>[[SQLITE_FCNTL_TRACE]]
  964. ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
  965. ** to the VFS about what the higher layers of the SQLite stack are doing.
  966. ** This file control is used by some VFS activity tracing [shims].
  967. ** The argument is a zero-terminated string. Higher layers in the
  968. ** SQLite stack may generate instances of this file control if
  969. ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
  970. **
  971. ** <li>[[SQLITE_FCNTL_HAS_MOVED]]
  972. ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
  973. ** pointer to an integer and it writes a boolean into that integer depending
  974. ** on whether or not the file has been renamed, moved, or deleted since it
  975. ** was first opened.
  976. **
  977. ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
  978. ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
  979. ** underlying native file handle associated with a file handle. This file
  980. ** control interprets its argument as a pointer to a native file handle and
  981. ** writes the resulting value there.
  982. **
  983. ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
  984. ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
  985. ** opcode causes the xFileControl method to swap the file handle with the one
  986. ** pointed to by the pArg argument. This capability is used during testing
  987. ** and only needs to be supported when SQLITE_TEST is defined.
  988. **
  989. ** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
  990. ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
  991. ** be advantageous to block on the next WAL lock if the lock is not immediately
  992. ** available. The WAL subsystem issues this signal during rare
  993. ** circumstances in order to fix a problem with priority inversion.
  994. ** Applications should <em>not</em> use this file-control.
  995. **
  996. ** <li>[[SQLITE_FCNTL_ZIPVFS]]
  997. ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
  998. ** VFS should return SQLITE_NOTFOUND for this opcode.
  999. **
  1000. ** <li>[[SQLITE_FCNTL_RBU]]
  1001. ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
  1002. ** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
  1003. ** this opcode.
  1004. **
  1005. ** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
  1006. ** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
  1007. ** the file descriptor is placed in "batch write mode", which
  1008. ** means all subsequent write operations will be deferred and done
  1009. ** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
  1010. ** that do not support batch atomic writes will return SQLITE_NOTFOUND.
  1011. ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
  1012. ** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
  1013. ** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
  1014. ** no VFS interface calls on the same [sqlite3_file] file descriptor
  1015. ** except for calls to the xWrite method and the xFileControl method
  1016. ** with [SQLITE_FCNTL_SIZE_HINT].
  1017. **
  1018. ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
  1019. ** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
  1020. ** operations since the previous successful call to
  1021. ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
  1022. ** This file control returns [SQLITE_OK] if and only if the writes were
  1023. ** all performed successfully and have been committed to persistent storage.
  1024. ** ^Regardless of whether or not it is successful, this file control takes
  1025. ** the file descriptor out of batch write mode so that all subsequent
  1026. ** write operations are independent.
  1027. ** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
  1028. ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1029. **
  1030. ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
  1031. ** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
  1032. ** operations since the previous successful call to
  1033. ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
  1034. ** ^This file control takes the file descriptor out of batch write mode
  1035. ** so that all subsequent write operations are independent.
  1036. ** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
  1037. ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1038. ** </ul>
  1039. */
  1040. #define SQLITE_FCNTL_LOCKSTATE 1
  1041. #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
  1042. #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
  1043. #define SQLITE_FCNTL_LAST_ERRNO 4
  1044. #define SQLITE_FCNTL_SIZE_HINT 5
  1045. #define SQLITE_FCNTL_CHUNK_SIZE 6
  1046. #define SQLITE_FCNTL_FILE_POINTER 7
  1047. #define SQLITE_FCNTL_SYNC_OMITTED 8
  1048. #define SQLITE_FCNTL_WIN32_AV_RETRY 9
  1049. #define SQLITE_FCNTL_PERSIST_WAL 10
  1050. #define SQLITE_FCNTL_OVERWRITE 11
  1051. #define SQLITE_FCNTL_VFSNAME 12
  1052. #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
  1053. #define SQLITE_FCNTL_PRAGMA 14
  1054. #define SQLITE_FCNTL_BUSYHANDLER 15
  1055. #define SQLITE_FCNTL_TEMPFILENAME 16
  1056. #define SQLITE_FCNTL_MMAP_SIZE 18
  1057. #define SQLITE_FCNTL_TRACE 19
  1058. #define SQLITE_FCNTL_HAS_MOVED 20
  1059. #define SQLITE_FCNTL_SYNC 21
  1060. #define SQLITE_FCNTL_COMMIT_PHASETWO 22
  1061. #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
  1062. #define SQLITE_FCNTL_WAL_BLOCK 24
  1063. #define SQLITE_FCNTL_ZIPVFS 25
  1064. #define SQLITE_FCNTL_RBU 26
  1065. #define SQLITE_FCNTL_VFS_POINTER 27
  1066. #define SQLITE_FCNTL_JOURNAL_POINTER 28
  1067. #define SQLITE_FCNTL_WIN32_GET_HANDLE 29
  1068. #define SQLITE_FCNTL_PDB 30
  1069. #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
  1070. #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
  1071. #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
  1072. /* deprecated names */
  1073. #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
  1074. #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
  1075. #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
  1076. /*
  1077. ** CAPI3REF: Mutex Handle
  1078. **
  1079. ** The mutex module within SQLite defines [sqlite3_mutex] to be an
  1080. ** abstract type for a mutex object. The SQLite core never looks
  1081. ** at the internal representation of an [sqlite3_mutex]. It only
  1082. ** deals with pointers to the [sqlite3_mutex] object.
  1083. **
  1084. ** Mutexes are created using [sqlite3_mutex_alloc()].
  1085. */
  1086. typedef struct sqlite3_mutex sqlite3_mutex;
  1087. /*
  1088. ** CAPI3REF: Loadable Extension Thunk
  1089. **
  1090. ** A pointer to the opaque sqlite3_api_routines structure is passed as
  1091. ** the third parameter to entry points of [loadable extensions]. This
  1092. ** structure must be typedefed in order to work around compiler warnings
  1093. ** on some platforms.
  1094. */
  1095. typedef struct sqlite3_api_routines sqlite3_api_routines;
  1096. /*
  1097. ** CAPI3REF: OS Interface Object
  1098. **
  1099. ** An instance of the sqlite3_vfs object defines the interface between
  1100. ** the SQLite core and the underlying operating system. The "vfs"
  1101. ** in the name of the object stands for "virtual file system". See
  1102. ** the [VFS | VFS documentation] for further information.
  1103. **
  1104. ** The value of the iVersion field is initially 1 but may be larger in
  1105. ** future versions of SQLite. Additional fields may be appended to this
  1106. ** object when the iVersion value is increased. Note that the structure
  1107. ** of the sqlite3_vfs object changes in the transaction between
  1108. ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
  1109. ** modified.
  1110. **
  1111. ** The szOsFile field is the size of the subclassed [sqlite3_file]
  1112. ** structure used by this VFS. mxPathname is the maximum length of
  1113. ** a pathname in this VFS.
  1114. **
  1115. ** Registered sqlite3_vfs objects are kept on a linked list formed by
  1116. ** the pNext pointer. The [sqlite3_vfs_register()]
  1117. ** and [sqlite3_vfs_unregister()] interfaces manage this list
  1118. ** in a thread-safe way. The [sqlite3_vfs_find()] interface
  1119. ** searches the list. Neither the application code nor the VFS
  1120. ** implementation should use the pNext pointer.
  1121. **
  1122. ** The pNext field is the only field in the sqlite3_vfs
  1123. ** structure that SQLite will ever modify. SQLite will only access
  1124. ** or modify this field while holding a particular static mutex.
  1125. ** The application should never modify anything within the sqlite3_vfs
  1126. ** object once the object has been registered.
  1127. **
  1128. ** The zName field holds the name of the VFS module. The name must
  1129. ** be unique across all VFS modules.
  1130. **
  1131. ** [[sqlite3_vfs.xOpen]]
  1132. ** ^SQLite guarantees that the zFilename parameter to xOpen
  1133. ** is either a NULL pointer or string obtained
  1134. ** from xFullPathname() with an optional suffix added.
  1135. ** ^If a suffix is added to the zFilename parameter, it will
  1136. ** consist of a single "-" character followed by no more than
  1137. ** 11 alphanumeric and/or "-" characters.
  1138. ** ^SQLite further guarantees that
  1139. ** the string will be valid and unchanged until xClose() is
  1140. ** called. Because of the previous sentence,
  1141. ** the [sqlite3_file] can safely store a pointer to the
  1142. ** filename if it needs to remember the filename for some reason.
  1143. ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
  1144. ** must invent its own temporary name for the file. ^Whenever the
  1145. ** xFilename parameter is NULL it will also be the case that the
  1146. ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
  1147. **
  1148. ** The flags argument to xOpen() includes all bits set in
  1149. ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
  1150. ** or [sqlite3_open16()] is used, then flags includes at least
  1151. ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
  1152. ** If xOpen() opens a file read-only then it sets *pOutFlags to
  1153. ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
  1154. **
  1155. ** ^(SQLite will also add one of the following flags to the xOpen()
  1156. ** call, depending on the object being opened:
  1157. **
  1158. ** <ul>
  1159. ** <li> [SQLITE_OPEN_MAIN_DB]
  1160. ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
  1161. ** <li> [SQLITE_OPEN_TEMP_DB]
  1162. ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
  1163. ** <li> [SQLITE_OPEN_TRANSIENT_DB]
  1164. ** <li> [SQLITE_OPEN_SUBJOURNAL]
  1165. ** <li> [SQLITE_OPEN_MASTER_JOURNAL]
  1166. ** <li> [SQLITE_OPEN_WAL]
  1167. ** </ul>)^
  1168. **
  1169. ** The file I/O implementation can use the object type flags to
  1170. ** change the way it deals with files. For example, an application
  1171. ** that does not care about crash recovery or rollback might make
  1172. ** the open of a journal file a no-op. Writes to this journal would
  1173. ** also be no-ops, and any attempt to read the journal would return
  1174. ** SQLITE_IOERR. Or the implementation might recognize that a database
  1175. ** file will be doing page-aligned sector reads and writes in a random
  1176. ** order and set up its I/O subsystem accordingly.
  1177. **
  1178. ** SQLite might also add one of the following flags to the xOpen method:
  1179. **
  1180. ** <ul>
  1181. ** <li> [SQLITE_OPEN_DELETEONCLOSE]
  1182. ** <li> [SQLITE_OPEN_EXCLUSIVE]
  1183. ** </ul>
  1184. **
  1185. ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
  1186. ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
  1187. ** will be set for TEMP databases and their journals, transient
  1188. ** databases, and subjournals.
  1189. **
  1190. ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
  1191. ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
  1192. ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
  1193. ** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
  1194. ** SQLITE_OPEN_CREATE, is used to indicate that file should always
  1195. ** be created, and that it is an error if it already exists.
  1196. ** It is <i>not</i> used to indicate the file should be opened
  1197. ** for exclusive access.
  1198. **
  1199. ** ^At least szOsFile bytes of memory are allocated by SQLite
  1200. ** to hold the [sqlite3_file] structure passed as the third
  1201. ** argument to xOpen. The xOpen method does not have to
  1202. ** allocate the structure; it should just fill it in. Note that
  1203. ** the xOpen method must set the sqlite3_file.pMethods to either
  1204. ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
  1205. ** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
  1206. ** element will be valid after xOpen returns regardless of the success
  1207. ** or failure of the xOpen call.
  1208. **
  1209. ** [[sqlite3_vfs.xAccess]]
  1210. ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
  1211. ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
  1212. ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
  1213. ** to test whether a file is at least readable. The file can be a
  1214. ** directory.
  1215. **
  1216. ** ^SQLite will always allocate at least mxPathname+1 bytes for the
  1217. ** output buffer xFullPathname. The exact size of the output buffer
  1218. ** is also passed as a parameter to both methods. If the output buffer
  1219. ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
  1220. ** handled as a fatal error by SQLite, vfs implementations should endeavor
  1221. ** to prevent this by setting mxPathname to a sufficiently large value.
  1222. **
  1223. ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
  1224. ** interfaces are not strictly a part of the filesystem, but they are
  1225. ** included in the VFS structure for completeness.
  1226. ** The xRandomness() function attempts to return nBytes bytes
  1227. ** of good-quality randomness into zOut. The return value is
  1228. ** the actual number of bytes of randomness obtained.
  1229. ** The xSleep() method causes the calling thread to sleep for at
  1230. ** least the number of microseconds given. ^The xCurrentTime()
  1231. ** method returns a Julian Day Number for the current date and time as
  1232. ** a floating point value.
  1233. ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
  1234. ** Day Number multiplied by 86400000 (the number of milliseconds in
  1235. ** a 24-hour day).
  1236. ** ^SQLite will use the xCurrentTimeInt64() method to get the current
  1237. ** date and time if that method is available (if iVersion is 2 or
  1238. ** greater and the function pointer is not NULL) and will fall back
  1239. ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
  1240. **
  1241. ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
  1242. ** are not used by the SQLite core. These optional interfaces are provided
  1243. ** by some VFSes to facilitate testing of the VFS code. By overriding
  1244. ** system calls with functions under its control, a test program can
  1245. ** simulate faults and error conditions that would otherwise be difficult
  1246. ** or impossible to induce. The set of system calls that can be overridden
  1247. ** varies from one VFS to another, and from one version of the same VFS to the
  1248. ** next. Applications that use these interfaces must be prepared for any
  1249. ** or all of these interfaces to be NULL or for their behavior to change
  1250. ** from one release to the next. Applications must not attempt to access
  1251. ** any of these methods if the iVersion of the VFS is less than 3.
  1252. */
  1253. typedef struct sqlite3_vfs sqlite3_vfs;
  1254. typedef void (*sqlite3_syscall_ptr)(void);
  1255. struct sqlite3_vfs {
  1256. int iVersion; /* Structure version number (currently 3) */
  1257. int szOsFile; /* Size of subclassed sqlite3_file */
  1258. int mxPathname; /* Maximum file pathname length */
  1259. sqlite3_vfs *pNext; /* Next registered VFS */
  1260. const char *zName; /* Name of this virtual file system */
  1261. void *pAppData; /* Pointer to application-specific data */
  1262. int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
  1263. int flags, int *pOutFlags);
  1264. int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  1265. int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  1266. int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  1267. void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  1268. void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  1269. void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  1270. void (*xDlClose)(sqlite3_vfs*, void*);
  1271. int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  1272. int (*xSleep)(sqlite3_vfs*, int microseconds);
  1273. int (*xCurrentTime)(sqlite3_vfs*, double*);
  1274. int (*xGetLastError)(sqlite3_vfs*, int, char *);
  1275. /*
  1276. ** The methods above are in version 1 of the sqlite_vfs object
  1277. ** definition. Those that follow are added in version 2 or later
  1278. */
  1279. int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  1280. /*
  1281. ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  1282. ** Those below are for version 3 and greater.
  1283. */
  1284. int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  1285. sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  1286. const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  1287. /*
  1288. ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  1289. ** New fields may be appended in future versions. The iVersion
  1290. ** value will increment whenever this happens.
  1291. */
  1292. };
  1293. /*
  1294. ** CAPI3REF: Flags for the xAccess VFS method
  1295. **
  1296. ** These integer constants can be used as the third parameter to
  1297. ** the xAccess method of an [sqlite3_vfs] object. They determine
  1298. ** what kind of permissions the xAccess method is looking for.
  1299. ** With SQLITE_ACCESS_EXISTS, the xAccess method
  1300. ** simply checks whether the file exists.
  1301. ** With SQLITE_ACCESS_READWRITE, the xAccess method
  1302. ** checks whether the named directory is both readable and writable
  1303. ** (in other words, if files can be added, removed, and renamed within
  1304. ** the directory).
  1305. ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
  1306. ** [temp_store_directory pragma], though this could change in a future
  1307. ** release of SQLite.
  1308. ** With SQLITE_ACCESS_READ, the xAccess method
  1309. ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
  1310. ** currently unused, though it might be used in a future release of
  1311. ** SQLite.
  1312. */
  1313. #define SQLITE_ACCESS_EXISTS 0
  1314. #define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
  1315. #define SQLITE_ACCESS_READ 2 /* Unused */
  1316. /*
  1317. ** CAPI3REF: Flags for the xShmLock VFS method
  1318. **
  1319. ** These integer constants define the various locking operations
  1320. ** allowed by the xShmLock method of [sqlite3_io_methods]. The
  1321. ** following are the only legal combinations of flags to the
  1322. ** xShmLock method:
  1323. **
  1324. ** <ul>
  1325. ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  1326. ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  1327. ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  1328. ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
  1329. ** </ul>
  1330. **
  1331. ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
  1332. ** was given on the corresponding lock.
  1333. **
  1334. ** The xShmLock method can transition between unlocked and SHARED or
  1335. ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
  1336. ** and EXCLUSIVE.
  1337. */
  1338. #define SQLITE_SHM_UNLOCK 1
  1339. #define SQLITE_SHM_LOCK 2
  1340. #define SQLITE_SHM_SHARED 4
  1341. #define SQLITE_SHM_EXCLUSIVE 8
  1342. /*
  1343. ** CAPI3REF: Maximum xShmLock index
  1344. **
  1345. ** The xShmLock method on [sqlite3_io_methods] may use values
  1346. ** between 0 and this upper bound as its "offset" argument.
  1347. ** The SQLite core will never attempt to acquire or release a
  1348. ** lock outside of this range
  1349. */
  1350. #define SQLITE_SHM_NLOCK 8
  1351. /*
  1352. ** CAPI3REF: Initialize The SQLite Library
  1353. **
  1354. ** ^The sqlite3_initialize() routine initializes the
  1355. ** SQLite library. ^The sqlite3_shutdown() routine
  1356. ** deallocates any resources that were allocated by sqlite3_initialize().
  1357. ** These routines are designed to aid in process initialization and
  1358. ** shutdown on embedded systems. Workstation applications using
  1359. ** SQLite normally do not need to invoke either of these routines.
  1360. **
  1361. ** A call to sqlite3_initialize() is an "effective" call if it is
  1362. ** the first time sqlite3_initialize() is invoked during the lifetime of
  1363. ** the process, or if it is the first time sqlite3_initialize() is invoked
  1364. ** following a call to sqlite3_shutdown(). ^(Only an effective call
  1365. ** of sqlite3_initialize() does any initialization. All other calls
  1366. ** are harmless no-ops.)^
  1367. **
  1368. ** A call to sqlite3_shutdown() is an "effective" call if it is the first
  1369. ** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
  1370. ** an effective call to sqlite3_shutdown() does any deinitialization.
  1371. ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
  1372. **
  1373. ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
  1374. ** is not. The sqlite3_shutdown() interface must only be called from a
  1375. ** single thread. All open [database connections] must be closed and all
  1376. ** other SQLite resources must be deallocated prior to invoking
  1377. ** sqlite3_shutdown().
  1378. **
  1379. ** Among other things, ^sqlite3_initialize() will invoke
  1380. ** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
  1381. ** will invoke sqlite3_os_end().
  1382. **
  1383. ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
  1384. ** ^If for some reason, sqlite3_initialize() is unable to initialize
  1385. ** the library (perhaps it is unable to allocate a needed resource such
  1386. ** as a mutex) it returns an [error code] other than [SQLITE_OK].
  1387. **
  1388. ** ^The sqlite3_initialize() routine is called internally by many other
  1389. ** SQLite interfaces so that an application usually does not need to
  1390. ** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
  1391. ** calls sqlite3_initialize() so the SQLite library will be automatically
  1392. ** initialized when [sqlite3_open()] is called if it has not be initialized
  1393. ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
  1394. ** compile-time option, then the automatic calls to sqlite3_initialize()
  1395. ** are omitted and the application must call sqlite3_initialize() directly
  1396. ** prior to using any other SQLite interface. For maximum portability,
  1397. ** it is recommended that applications always invoke sqlite3_initialize()
  1398. ** directly prior to using any other SQLite interface. Future releases
  1399. ** of SQLite may require this. In other words, the behavior exhibited
  1400. ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
  1401. ** default behavior in some future release of SQLite.
  1402. **
  1403. ** The sqlite3_os_init() routine does operating-system specific
  1404. ** initialization of the SQLite library. The sqlite3_os_end()
  1405. ** routine undoes the effect of sqlite3_os_init(). Typical tasks
  1406. ** performed by these routines include allocation or deallocation
  1407. ** of static resources, initialization of global variables,
  1408. ** setting up a default [sqlite3_vfs] module, or setting up
  1409. ** a default configuration using [sqlite3_config()].
  1410. **
  1411. ** The application should never invoke either sqlite3_os_init()
  1412. ** or sqlite3_os_end() directly. The application should only invoke
  1413. ** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
  1414. ** interface is called automatically by sqlite3_initialize() and
  1415. ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
  1416. ** implementations for sqlite3_os_init() and sqlite3_os_end()
  1417. ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
  1418. ** When [custom builds | built for other platforms]
  1419. ** (using the [SQLITE_OS_OTHER=1] compile-time
  1420. ** option) the application must supply a suitable implementation for
  1421. ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
  1422. ** implementation of sqlite3_os_init() or sqlite3_os_end()
  1423. ** must return [SQLITE_OK] on success and some other [error code] upon
  1424. ** failure.
  1425. */
  1426. SQLITE_API int sqlite3_initialize(void);
  1427. SQLITE_API int sqlite3_shutdown(void);
  1428. SQLITE_API int sqlite3_os_init(void);
  1429. SQLITE_API int sqlite3_os_end(void);
  1430. /*
  1431. ** CAPI3REF: Configuring The SQLite Library
  1432. **
  1433. ** The sqlite3_config() interface is used to make global configuration
  1434. ** changes to SQLite in order to tune SQLite to the specific needs of
  1435. ** the application. The default configuration is recommended for most
  1436. ** applications and so this routine is usually not necessary. It is
  1437. ** provided to support rare applications with unusual needs.
  1438. **
  1439. ** <b>The sqlite3_config() interface is not threadsafe. The application
  1440. ** must ensure that no other SQLite interfaces are invoked by other
  1441. ** threads while sqlite3_config() is running.</b>
  1442. **
  1443. ** The sqlite3_config() interface
  1444. ** may only be invoked prior to library initialization using
  1445. ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
  1446. ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
  1447. ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
  1448. ** Note, however, that ^sqlite3_config() can be called as part of the
  1449. ** implementation of an application-defined [sqlite3_os_init()].
  1450. **
  1451. ** The first argument to sqlite3_config() is an integer
  1452. ** [configuration option] that determines
  1453. ** what property of SQLite is to be configured. Subsequent arguments
  1454. ** vary depending on the [configuration option]
  1455. ** in the first argument.
  1456. **
  1457. ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
  1458. ** ^If the option is unknown or SQLite is unable to set the option
  1459. ** then this routine returns a non-zero [error code].
  1460. */
  1461. SQLITE_API int sqlite3_config(int, ...);
  1462. /*
  1463. ** CAPI3REF: Configure database connections
  1464. ** METHOD: sqlite3
  1465. **
  1466. ** The sqlite3_db_config() interface is used to make configuration
  1467. ** changes to a [database connection]. The interface is similar to
  1468. ** [sqlite3_config()] except that the changes apply to a single
  1469. ** [database connection] (specified in the first argument).
  1470. **
  1471. ** The second argument to sqlite3_db_config(D,V,...) is the
  1472. ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
  1473. ** that indicates what aspect of the [database connection] is being configured.
  1474. ** Subsequent arguments vary depending on the configuration verb.
  1475. **
  1476. ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
  1477. ** the call is considered successful.
  1478. */
  1479. SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
  1480. /*
  1481. ** CAPI3REF: Memory Allocation Routines
  1482. **
  1483. ** An instance of this object defines the interface between SQLite
  1484. ** and low-level memory allocation routines.
  1485. **
  1486. ** This object is used in only one place in the SQLite interface.
  1487. ** A pointer to an instance of this object is the argument to
  1488. ** [sqlite3_config()] when the configuration option is
  1489. ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
  1490. ** By creating an instance of this object
  1491. ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
  1492. ** during configuration, an application can specify an alternative
  1493. ** memory allocation subsystem for SQLite to use for all of its
  1494. ** dynamic memory needs.
  1495. **
  1496. ** Note that SQLite comes with several [built-in memory allocators]
  1497. ** that are perfectly adequate for the overwhelming majority of applications
  1498. ** and that this object is only useful to a tiny minority of applications
  1499. ** with specialized memory allocation requirements. This object is
  1500. ** also used during testing of SQLite in order to specify an alternative
  1501. ** memory allocator that simulates memory out-of-memory conditions in
  1502. ** order to verify that SQLite recovers gracefully from such
  1503. ** conditions.
  1504. **
  1505. ** The xMalloc, xRealloc, and xFree methods must work like the
  1506. ** malloc(), realloc() and free() functions from the standard C library.
  1507. ** ^SQLite guarantees that the second argument to
  1508. ** xRealloc is always a value returned by a prior call to xRoundup.
  1509. **
  1510. ** xSize should return the allocated size of a memory allocation
  1511. ** previously obtained from xMalloc or xRealloc. The allocated size
  1512. ** is always at least as big as the requested size but may be larger.
  1513. **
  1514. ** The xRoundup method returns what would be the allocated size of
  1515. ** a memory allocation given a particular requested size. Most memory
  1516. ** allocators round up memory allocations at least to the next multiple
  1517. ** of 8. Some allocators round up to a larger multiple or to a power of 2.
  1518. ** Every memory allocation request coming in through [sqlite3_malloc()]
  1519. ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
  1520. ** that causes the corresponding memory allocation to fail.
  1521. **
  1522. ** The xInit method initializes the memory allocator. For example,
  1523. ** it might allocate any require mutexes or initialize internal data
  1524. ** structures. The xShutdown method is invoked (indirectly) by
  1525. ** [sqlite3_shutdown()] and should deallocate any resources acquired
  1526. ** by xInit. The pAppData pointer is used as the only parameter to
  1527. ** xInit and xShutdown.
  1528. **
  1529. ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
  1530. ** the xInit method, so the xInit method need not be threadsafe. The
  1531. ** xShutdown method is only called from [sqlite3_shutdown()] so it does
  1532. ** not need to be threadsafe either. For all other methods, SQLite
  1533. ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
  1534. ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
  1535. ** it is by default) and so the methods are automatically serialized.
  1536. ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
  1537. ** methods must be threadsafe or else make their own arrangements for
  1538. ** serialization.
  1539. **
  1540. ** SQLite will never invoke xInit() more than once without an intervening
  1541. ** call to xShutdown().
  1542. */
  1543. typedef struct sqlite3_mem_methods sqlite3_mem_methods;
  1544. struct sqlite3_mem_methods {
  1545. void *(*xMalloc)(int); /* Memory allocation function */
  1546. void (*xFree)(void*); /* Free a prior allocation */
  1547. void *(*xRealloc)(void*,int); /* Resize an allocation */
  1548. int (*xSize)(void*); /* Return the size of an allocation */
  1549. int (*xRoundup)(int); /* Round up request size to allocation size */
  1550. int (*xInit)(void*); /* Initialize the memory allocator */
  1551. void (*xShutdown)(void*); /* Deinitialize the memory allocator */
  1552. void *pAppData; /* Argument to xInit() and xShutdown() */
  1553. };
  1554. /*
  1555. ** CAPI3REF: Configuration Options
  1556. ** KEYWORDS: {configuration option}
  1557. **
  1558. ** These constants are the available integer configuration options that
  1559. ** can be passed as the first argument to the [sqlite3_config()] interface.
  1560. **
  1561. ** New configuration options may be added in future releases of SQLite.
  1562. ** Existing configuration options might be discontinued. Applications
  1563. ** should check the return code from [sqlite3_config()] to make sure that
  1564. ** the call worked. The [sqlite3_config()] interface will return a
  1565. ** non-zero [error code] if a discontinued or unsupported configuration option
  1566. ** is invoked.
  1567. **
  1568. ** <dl>
  1569. ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
  1570. ** <dd>There are no arguments to this option. ^This option sets the
  1571. ** [threading mode] to Single-thread. In other words, it disables
  1572. ** all mutexing and puts SQLite into a mode where it can only be used
  1573. ** by a single thread. ^If SQLite is compiled with
  1574. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1575. ** it is not possible to change the [threading mode] from its default
  1576. ** value of Single-thread and so [sqlite3_config()] will return
  1577. ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
  1578. ** configuration option.</dd>
  1579. **
  1580. ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
  1581. ** <dd>There are no arguments to this option. ^This option sets the
  1582. ** [threading mode] to Multi-thread. In other words, it disables
  1583. ** mutexing on [database connection] and [prepared statement] objects.
  1584. ** The application is responsible for serializing access to
  1585. ** [database connections] and [prepared statements]. But other mutexes
  1586. ** are enabled so that SQLite will be safe to use in a multi-threaded
  1587. ** environment as long as no two threads attempt to use the same
  1588. ** [database connection] at the same time. ^If SQLite is compiled with
  1589. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1590. ** it is not possible to set the Multi-thread [threading mode] and
  1591. ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1592. ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
  1593. **
  1594. ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
  1595. ** <dd>There are no arguments to this option. ^This option sets the
  1596. ** [threading mode] to Serialized. In other words, this option enables
  1597. ** all mutexes including the recursive
  1598. ** mutexes on [database connection] and [prepared statement] objects.
  1599. ** In this mode (which is the default when SQLite is compiled with
  1600. ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
  1601. ** to [database connections] and [prepared statements] so that the
  1602. ** application is free to use the same [database connection] or the
  1603. ** same [prepared statement] in different threads at the same time.
  1604. ** ^If SQLite is compiled with
  1605. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1606. ** it is not possible to set the Serialized [threading mode] and
  1607. ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1608. ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
  1609. **
  1610. ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
  1611. ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
  1612. ** a pointer to an instance of the [sqlite3_mem_methods] structure.
  1613. ** The argument specifies
  1614. ** alternative low-level memory allocation routines to be used in place of
  1615. ** the memory allocation routines built into SQLite.)^ ^SQLite makes
  1616. ** its own private copy of the content of the [sqlite3_mem_methods] structure
  1617. ** before the [sqlite3_config()] call returns.</dd>
  1618. **
  1619. ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
  1620. ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
  1621. ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
  1622. ** The [sqlite3_mem_methods]
  1623. ** structure is filled with the currently defined memory allocation routines.)^
  1624. ** This option can be used to overload the default memory allocation
  1625. ** routines with a wrapper that simulations memory allocation failure or
  1626. ** tracks memory usage, for example. </dd>
  1627. **
  1628. ** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
  1629. ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
  1630. ** type int, interpreted as a boolean, which if true provides a hint to
  1631. ** SQLite that it should avoid large memory allocations if possible.
  1632. ** SQLite will run faster if it is free to make large memory allocations,
  1633. ** but some application might prefer to run slower in exchange for
  1634. ** guarantees about memory fragmentation that are possible if large
  1635. ** allocations are avoided. This hint is normally off.
  1636. ** </dd>
  1637. **
  1638. ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1639. ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
  1640. ** interpreted as a boolean, which enables or disables the collection of
  1641. ** memory allocation statistics. ^(When memory allocation statistics are
  1642. ** disabled, the following SQLite interfaces become non-operational:
  1643. ** <ul>
  1644. ** <li> [sqlite3_memory_used()]
  1645. ** <li> [sqlite3_memory_highwater()]
  1646. ** <li> [sqlite3_soft_heap_limit64()]
  1647. ** <li> [sqlite3_status64()]
  1648. ** </ul>)^
  1649. ** ^Memory allocation statistics are enabled by default unless SQLite is
  1650. ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
  1651. ** allocation statistics are disabled by default.
  1652. ** </dd>
  1653. **
  1654. ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
  1655. ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
  1656. ** </dd>
  1657. **
  1658. ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1659. ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
  1660. ** that SQLite can use for the database page cache with the default page
  1661. ** cache implementation.
  1662. ** This configuration option is a no-op if an application-define page
  1663. ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
  1664. ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
  1665. ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
  1666. ** and the number of cache lines (N).
  1667. ** The sz argument should be the size of the largest database page
  1668. ** (a power of two between 512 and 65536) plus some extra bytes for each
  1669. ** page header. ^The number of extra bytes needed by the page header
  1670. ** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
  1671. ** ^It is harmless, apart from the wasted memory,
  1672. ** for the sz parameter to be larger than necessary. The pMem
  1673. ** argument must be either a NULL pointer or a pointer to an 8-byte
  1674. ** aligned block of memory of at least sz*N bytes, otherwise
  1675. ** subsequent behavior is undefined.
  1676. ** ^When pMem is not NULL, SQLite will strive to use the memory provided
  1677. ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
  1678. ** a page cache line is larger than sz bytes or if all of the pMem buffer
  1679. ** is exhausted.
  1680. ** ^If pMem is NULL and N is non-zero, then each database connection
  1681. ** does an initial bulk allocation for page cache memory
  1682. ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
  1683. ** of -1024*N bytes if N is negative, . ^If additional
  1684. ** page cache memory is needed beyond what is provided by the initial
  1685. ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
  1686. ** additional cache line. </dd>
  1687. **
  1688. ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
  1689. ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
  1690. ** that SQLite will use for all of its dynamic memory allocation needs
  1691. ** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
  1692. ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
  1693. ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
  1694. ** [SQLITE_ERROR] if invoked otherwise.
  1695. ** ^There are three arguments to SQLITE_CONFIG_HEAP:
  1696. ** An 8-byte aligned pointer to the memory,
  1697. ** the number of bytes in the memory buffer, and the minimum allocation size.
  1698. ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
  1699. ** to using its default memory allocator (the system malloc() implementation),
  1700. ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
  1701. ** memory pointer is not NULL then the alternative memory
  1702. ** allocator is engaged to handle all of SQLites memory allocation needs.
  1703. ** The first pointer (the memory pointer) must be aligned to an 8-byte
  1704. ** boundary or subsequent behavior of SQLite will be undefined.
  1705. ** The minimum allocation size is capped at 2**12. Reasonable values
  1706. ** for the minimum allocation size are 2**5 through 2**8.</dd>
  1707. **
  1708. ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
  1709. ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
  1710. ** pointer to an instance of the [sqlite3_mutex_methods] structure.
  1711. ** The argument specifies alternative low-level mutex routines to be used
  1712. ** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
  1713. ** the content of the [sqlite3_mutex_methods] structure before the call to
  1714. ** [sqlite3_config()] returns. ^If SQLite is compiled with
  1715. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1716. ** the entire mutexing subsystem is omitted from the build and hence calls to
  1717. ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
  1718. ** return [SQLITE_ERROR].</dd>
  1719. **
  1720. ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
  1721. ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
  1722. ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
  1723. ** [sqlite3_mutex_methods]
  1724. ** structure is filled with the currently defined mutex routines.)^
  1725. ** This option can be used to overload the default mutex allocation
  1726. ** routines with a wrapper used to track mutex usage for performance
  1727. ** profiling or testing, for example. ^If SQLite is compiled with
  1728. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1729. ** the entire mutexing subsystem is omitted from the build and hence calls to
  1730. ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
  1731. ** return [SQLITE_ERROR].</dd>
  1732. **
  1733. ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
  1734. ** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
  1735. ** the default size of lookaside memory on each [database connection].
  1736. ** The first argument is the
  1737. ** size of each lookaside buffer slot and the second is the number of
  1738. ** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
  1739. ** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1740. ** option to [sqlite3_db_config()] can be used to change the lookaside
  1741. ** configuration on individual connections.)^ </dd>
  1742. **
  1743. ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
  1744. ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
  1745. ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
  1746. ** the interface to a custom page cache implementation.)^
  1747. ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
  1748. **
  1749. ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
  1750. ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
  1751. ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
  1752. ** the current page cache implementation into that object.)^ </dd>
  1753. **
  1754. ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
  1755. ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
  1756. ** global [error log].
  1757. ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
  1758. ** function with a call signature of void(*)(void*,int,const char*),
  1759. ** and a pointer to void. ^If the function pointer is not NULL, it is
  1760. ** invoked by [sqlite3_log()] to process each logging event. ^If the
  1761. ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
  1762. ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
  1763. ** passed through as the first parameter to the application-defined logger
  1764. ** function whenever that function is invoked. ^The second parameter to
  1765. ** the logger function is a copy of the first parameter to the corresponding
  1766. ** [sqlite3_log()] call and is intended to be a [result code] or an
  1767. ** [extended result code]. ^The third parameter passed to the logger is
  1768. ** log message after formatting via [sqlite3_snprintf()].
  1769. ** The SQLite logging interface is not reentrant; the logger function
  1770. ** supplied by the application must not invoke any SQLite interface.
  1771. ** In a multi-threaded application, the application-defined logger
  1772. ** function must be threadsafe. </dd>
  1773. **
  1774. ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
  1775. ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
  1776. ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
  1777. ** then URI handling is globally disabled.)^ ^If URI handling is globally
  1778. ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
  1779. ** [sqlite3_open16()] or
  1780. ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
  1781. ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
  1782. ** connection is opened. ^If it is globally disabled, filenames are
  1783. ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
  1784. ** database connection is opened. ^(By default, URI handling is globally
  1785. ** disabled. The default value may be changed by compiling with the
  1786. ** [SQLITE_USE_URI] symbol defined.)^
  1787. **
  1788. ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
  1789. ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
  1790. ** argument which is interpreted as a boolean in order to enable or disable
  1791. ** the use of covering indices for full table scans in the query optimizer.
  1792. ** ^The default setting is determined
  1793. ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
  1794. ** if that compile-time option is omitted.
  1795. ** The ability to disable the use of covering indices for full table scans
  1796. ** is because some incorrectly coded legacy applications might malfunction
  1797. ** when the optimization is enabled. Providing the ability to
  1798. ** disable the optimization allows the older, buggy application code to work
  1799. ** without change even with newer versions of SQLite.
  1800. **
  1801. ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
  1802. ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
  1803. ** <dd> These options are obsolete and should not be used by new code.
  1804. ** They are retained for backwards compatibility but are now no-ops.
  1805. ** </dd>
  1806. **
  1807. ** [[SQLITE_CONFIG_SQLLOG]]
  1808. ** <dt>SQLITE_CONFIG_SQLLOG
  1809. ** <dd>This option is only available if sqlite is compiled with the
  1810. ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
  1811. ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
  1812. ** The second should be of type (void*). The callback is invoked by the library
  1813. ** in three separate circumstances, identified by the value passed as the
  1814. ** fourth parameter. If the fourth parameter is 0, then the database connection
  1815. ** passed as the second argument has just been opened. The third argument
  1816. ** points to a buffer containing the name of the main database file. If the
  1817. ** fourth parameter is 1, then the SQL statement that the third parameter
  1818. ** points to has just been executed. Or, if the fourth parameter is 2, then
  1819. ** the connection being passed as the second parameter is being closed. The
  1820. ** third parameter is passed NULL In this case. An example of using this
  1821. ** configuration option can be seen in the "test_sqllog.c" source file in
  1822. ** the canonical SQLite source tree.</dd>
  1823. **
  1824. ** [[SQLITE_CONFIG_MMAP_SIZE]]
  1825. ** <dt>SQLITE_CONFIG_MMAP_SIZE
  1826. ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
  1827. ** that are the default mmap size limit (the default setting for
  1828. ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
  1829. ** ^The default setting can be overridden by each database connection using
  1830. ** either the [PRAGMA mmap_size] command, or by using the
  1831. ** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
  1832. ** will be silently truncated if necessary so that it does not exceed the
  1833. ** compile-time maximum mmap size set by the
  1834. ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
  1835. ** ^If either argument to this option is negative, then that argument is
  1836. ** changed to its compile-time default.
  1837. **
  1838. ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
  1839. ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
  1840. ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
  1841. ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
  1842. ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
  1843. ** that specifies the maximum size of the created heap.
  1844. **
  1845. ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
  1846. ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
  1847. ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
  1848. ** is a pointer to an integer and writes into that integer the number of extra
  1849. ** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
  1850. ** The amount of extra space required can change depending on the compiler,
  1851. ** target platform, and SQLite version.
  1852. **
  1853. ** [[SQLITE_CONFIG_PMASZ]]
  1854. ** <dt>SQLITE_CONFIG_PMASZ
  1855. ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
  1856. ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
  1857. ** sorter to that integer. The default minimum PMA Size is set by the
  1858. ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
  1859. ** to help with sort operations when multithreaded sorting
  1860. ** is enabled (using the [PRAGMA threads] command) and the amount of content
  1861. ** to be sorted exceeds the page size times the minimum of the
  1862. ** [PRAGMA cache_size] setting and this value.
  1863. **
  1864. ** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
  1865. ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
  1866. ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
  1867. ** becomes the [statement journal] spill-to-disk threshold.
  1868. ** [Statement journals] are held in memory until their size (in bytes)
  1869. ** exceeds this threshold, at which point they are written to disk.
  1870. ** Or if the threshold is -1, statement journals are always held
  1871. ** exclusively in memory.
  1872. ** Since many statement journals never become large, setting the spill
  1873. ** threshold to a value such as 64KiB can greatly reduce the amount of
  1874. ** I/O required to support statement rollback.
  1875. ** The default value for this setting is controlled by the
  1876. ** [SQLITE_STMTJRNL_SPILL] compile-time option.
  1877. ** </dl>
  1878. */
  1879. #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
  1880. #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
  1881. #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
  1882. #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
  1883. #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
  1884. #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
  1885. #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
  1886. #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
  1887. #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
  1888. #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
  1889. #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
  1890. /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
  1891. #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
  1892. #define SQLITE_CONFIG_PCACHE 14 /* no-op */
  1893. #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
  1894. #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
  1895. #define SQLITE_CONFIG_URI 17 /* int */
  1896. #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
  1897. #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
  1898. #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
  1899. #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
  1900. #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
  1901. #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
  1902. #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
  1903. #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
  1904. #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
  1905. #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
  1906. /*
  1907. ** CAPI3REF: Database Connection Configuration Options
  1908. **
  1909. ** These constants are the available integer configuration options that
  1910. ** can be passed as the second argument to the [sqlite3_db_config()] interface.
  1911. **
  1912. ** New configuration options may be added in future releases of SQLite.
  1913. ** Existing configuration options might be discontinued. Applications
  1914. ** should check the return code from [sqlite3_db_config()] to make sure that
  1915. ** the call worked. ^The [sqlite3_db_config()] interface will return a
  1916. ** non-zero [error code] if a discontinued or unsupported configuration option
  1917. ** is invoked.
  1918. **
  1919. ** <dl>
  1920. ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
  1921. ** <dd> ^This option takes three additional arguments that determine the
  1922. ** [lookaside memory allocator] configuration for the [database connection].
  1923. ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
  1924. ** pointer to a memory buffer to use for lookaside memory.
  1925. ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
  1926. ** may be NULL in which case SQLite will allocate the
  1927. ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
  1928. ** size of each lookaside buffer slot. ^The third argument is the number of
  1929. ** slots. The size of the buffer in the first argument must be greater than
  1930. ** or equal to the product of the second and third arguments. The buffer
  1931. ** must be aligned to an 8-byte boundary. ^If the second argument to
  1932. ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
  1933. ** rounded down to the next smaller multiple of 8. ^(The lookaside memory
  1934. ** configuration for a database connection can only be changed when that
  1935. ** connection is not currently using lookaside memory, or in other words
  1936. ** when the "current value" returned by
  1937. ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
  1938. ** Any attempt to change the lookaside memory configuration when lookaside
  1939. ** memory is in use leaves the configuration unchanged and returns
  1940. ** [SQLITE_BUSY].)^</dd>
  1941. **
  1942. ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
  1943. ** <dd> ^This option is used to enable or disable the enforcement of
  1944. ** [foreign key constraints]. There should be two additional arguments.
  1945. ** The first argument is an integer which is 0 to disable FK enforcement,
  1946. ** positive to enable FK enforcement or negative to leave FK enforcement
  1947. ** unchanged. The second parameter is a pointer to an integer into which
  1948. ** is written 0 or 1 to indicate whether FK enforcement is off or on
  1949. ** following this call. The second parameter may be a NULL pointer, in
  1950. ** which case the FK enforcement setting is not reported back. </dd>
  1951. **
  1952. ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
  1953. ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
  1954. ** There should be two additional arguments.
  1955. ** The first argument is an integer which is 0 to disable triggers,
  1956. ** positive to enable triggers or negative to leave the setting unchanged.
  1957. ** The second parameter is a pointer to an integer into which
  1958. ** is written 0 or 1 to indicate whether triggers are disabled or enabled
  1959. ** following this call. The second parameter may be a NULL pointer, in
  1960. ** which case the trigger setting is not reported back. </dd>
  1961. **
  1962. ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
  1963. ** <dd> ^This option is used to enable or disable the two-argument
  1964. ** version of the [fts3_tokenizer()] function which is part of the
  1965. ** [FTS3] full-text search engine extension.
  1966. ** There should be two additional arguments.
  1967. ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
  1968. ** positive to enable fts3_tokenizer() or negative to leave the setting
  1969. ** unchanged.
  1970. ** The second parameter is a pointer to an integer into which
  1971. ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
  1972. ** following this call. The second parameter may be a NULL pointer, in
  1973. ** which case the new setting is not reported back. </dd>
  1974. **
  1975. ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
  1976. ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
  1977. ** interface independently of the [load_extension()] SQL function.
  1978. ** The [sqlite3_enable_load_extension()] API enables or disables both the
  1979. ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
  1980. ** There should be two additional arguments.
  1981. ** When the first argument to this interface is 1, then only the C-API is
  1982. ** enabled and the SQL function remains disabled. If the first argument to
  1983. ** this interface is 0, then both the C-API and the SQL function are disabled.
  1984. ** If the first argument is -1, then no changes are made to state of either the
  1985. ** C-API or the SQL function.
  1986. ** The second parameter is a pointer to an integer into which
  1987. ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
  1988. ** is disabled or enabled following this call. The second parameter may
  1989. ** be a NULL pointer, in which case the new setting is not reported back.
  1990. ** </dd>
  1991. **
  1992. ** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
  1993. ** <dd> ^This option is used to change the name of the "main" database
  1994. ** schema. ^The sole argument is a pointer to a constant UTF8 string
  1995. ** which will become the new schema name in place of "main". ^SQLite
  1996. ** does not make a copy of the new main schema name string, so the application
  1997. ** must ensure that the argument passed into this DBCONFIG option is unchanged
  1998. ** until after the database connection closes.
  1999. ** </dd>
  2000. **
  2001. ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
  2002. ** <dd> Usually, when a database in wal mode is closed or detached from a
  2003. ** database handle, SQLite checks if this will mean that there are now no
  2004. ** connections at all to the database. If so, it performs a checkpoint
  2005. ** operation before closing the connection. This option may be used to
  2006. ** override this behaviour. The first parameter passed to this operation
  2007. ** is an integer - non-zero to disable checkpoints-on-close, or zero (the
  2008. ** default) to enable them. The second parameter is a pointer to an integer
  2009. ** into which is written 0 or 1 to indicate whether checkpoints-on-close
  2010. ** have been disabled - 0 if they are not disabled, 1 if they are.
  2011. ** </dd>
  2012. **
  2013. ** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
  2014. ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
  2015. ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
  2016. ** a single SQL query statement will always use the same algorithm regardless
  2017. ** of values of [bound parameters].)^ The QPSG disables some query optimizations
  2018. ** that look at the values of bound parameters, which can make some queries
  2019. ** slower. But the QPSG has the advantage of more predictable behavior. With
  2020. ** the QPSG active, SQLite will always use the same query plan in the field as
  2021. ** was used during testing in the lab.
  2022. ** </dd>
  2023. **
  2024. ** </dl>
  2025. */
  2026. #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
  2027. #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
  2028. #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
  2029. #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
  2030. #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
  2031. #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
  2032. #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
  2033. #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
  2034. /*
  2035. ** CAPI3REF: Enable Or Disable Extended Result Codes
  2036. ** METHOD: sqlite3
  2037. **
  2038. ** ^The sqlite3_extended_result_codes() routine enables or disables the
  2039. ** [extended result codes] feature of SQLite. ^The extended result
  2040. ** codes are disabled by default for historical compatibility.
  2041. */
  2042. SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
  2043. /*
  2044. ** CAPI3REF: Last Insert Rowid
  2045. ** METHOD: sqlite3
  2046. **
  2047. ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
  2048. ** has a unique 64-bit signed
  2049. ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
  2050. ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  2051. ** names are not also used by explicitly declared columns. ^If
  2052. ** the table has a column of type [INTEGER PRIMARY KEY] then that column
  2053. ** is another alias for the rowid.
  2054. **
  2055. ** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
  2056. ** the most recent successful [INSERT] into a rowid table or [virtual table]
  2057. ** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
  2058. ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
  2059. ** on the database connection D, then sqlite3_last_insert_rowid(D) returns
  2060. ** zero.
  2061. **
  2062. ** As well as being set automatically as rows are inserted into database
  2063. ** tables, the value returned by this function may be set explicitly by
  2064. ** [sqlite3_set_last_insert_rowid()]
  2065. **
  2066. ** Some virtual table implementations may INSERT rows into rowid tables as
  2067. ** part of committing a transaction (e.g. to flush data accumulated in memory
  2068. ** to disk). In this case subsequent calls to this function return the rowid
  2069. ** associated with these internal INSERT operations, which leads to
  2070. ** unintuitive results. Virtual table implementations that do write to rowid
  2071. ** tables in this way can avoid this problem by restoring the original
  2072. ** rowid value using [sqlite3_set_last_insert_rowid()] before returning
  2073. ** control to the user.
  2074. **
  2075. ** ^(If an [INSERT] occurs within a trigger then this routine will
  2076. ** return the [rowid] of the inserted row as long as the trigger is
  2077. ** running. Once the trigger program ends, the value returned
  2078. ** by this routine reverts to what it was before the trigger was fired.)^
  2079. **
  2080. ** ^An [INSERT] that fails due to a constraint violation is not a
  2081. ** successful [INSERT] and does not change the value returned by this
  2082. ** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  2083. ** and INSERT OR ABORT make no changes to the return value of this
  2084. ** routine when their insertion fails. ^(When INSERT OR REPLACE
  2085. ** encounters a constraint violation, it does not fail. The
  2086. ** INSERT continues to completion after deleting rows that caused
  2087. ** the constraint problem so INSERT OR REPLACE will always change
  2088. ** the return value of this interface.)^
  2089. **
  2090. ** ^For the purposes of this routine, an [INSERT] is considered to
  2091. ** be successful even if it is subsequently rolled back.
  2092. **
  2093. ** This function is accessible to SQL statements via the
  2094. ** [last_insert_rowid() SQL function].
  2095. **
  2096. ** If a separate thread performs a new [INSERT] on the same
  2097. ** database connection while the [sqlite3_last_insert_rowid()]
  2098. ** function is running and thus changes the last insert [rowid],
  2099. ** then the value returned by [sqlite3_last_insert_rowid()] is
  2100. ** unpredictable and might not equal either the old or the new
  2101. ** last insert [rowid].
  2102. */
  2103. SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  2104. /*
  2105. ** CAPI3REF: Set the Last Insert Rowid value.
  2106. ** METHOD: sqlite3
  2107. **
  2108. ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
  2109. ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
  2110. ** without inserting a row into the database.
  2111. */
  2112. SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
  2113. /*
  2114. ** CAPI3REF: Count The Number Of Rows Modified
  2115. ** METHOD: sqlite3
  2116. **
  2117. ** ^This function returns the number of rows modified, inserted or
  2118. ** deleted by the most recently completed INSERT, UPDATE or DELETE
  2119. ** statement on the database connection specified by the only parameter.
  2120. ** ^Executing any other type of SQL statement does not modify the value
  2121. ** returned by this function.
  2122. **
  2123. ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
  2124. ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
  2125. ** [foreign key actions] or [REPLACE] constraint resolution are not counted.
  2126. **
  2127. ** Changes to a view that are intercepted by
  2128. ** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
  2129. ** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
  2130. ** DELETE statement run on a view is always zero. Only changes made to real
  2131. ** tables are counted.
  2132. **
  2133. ** Things are more complicated if the sqlite3_changes() function is
  2134. ** executed while a trigger program is running. This may happen if the
  2135. ** program uses the [changes() SQL function], or if some other callback
  2136. ** function invokes sqlite3_changes() directly. Essentially:
  2137. **
  2138. ** <ul>
  2139. ** <li> ^(Before entering a trigger program the value returned by
  2140. ** sqlite3_changes() function is saved. After the trigger program
  2141. ** has finished, the original value is restored.)^
  2142. **
  2143. ** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
  2144. ** statement sets the value returned by sqlite3_changes()
  2145. ** upon completion as normal. Of course, this value will not include
  2146. ** any changes performed by sub-triggers, as the sqlite3_changes()
  2147. ** value will be saved and restored after each sub-trigger has run.)^
  2148. ** </ul>
  2149. **
  2150. ** ^This means that if the changes() SQL function (or similar) is used
  2151. ** by the first INSERT, UPDATE or DELETE statement within a trigger, it
  2152. ** returns the value as set when the calling statement began executing.
  2153. ** ^If it is used by the second or subsequent such statement within a trigger
  2154. ** program, the value returned reflects the number of rows modified by the
  2155. ** previous INSERT, UPDATE or DELETE statement within the same trigger.
  2156. **
  2157. ** See also the [sqlite3_total_changes()] interface, the
  2158. ** [count_changes pragma], and the [changes() SQL function].
  2159. **
  2160. ** If a separate thread makes changes on the same database connection
  2161. ** while [sqlite3_changes()] is running then the value returned
  2162. ** is unpredictable and not meaningful.
  2163. */
  2164. SQLITE_API int sqlite3_changes(sqlite3*);
  2165. /*
  2166. ** CAPI3REF: Total Number Of Rows Modified
  2167. ** METHOD: sqlite3
  2168. **
  2169. ** ^This function returns the total number of rows inserted, modified or
  2170. ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
  2171. ** since the database connection was opened, including those executed as
  2172. ** part of trigger programs. ^Executing any other type of SQL statement
  2173. ** does not affect the value returned by sqlite3_total_changes().
  2174. **
  2175. ** ^Changes made as part of [foreign key actions] are included in the
  2176. ** count, but those made as part of REPLACE constraint resolution are
  2177. ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
  2178. ** are not counted.
  2179. **
  2180. ** See also the [sqlite3_changes()] interface, the
  2181. ** [count_changes pragma], and the [total_changes() SQL function].
  2182. **
  2183. ** If a separate thread makes changes on the same database connection
  2184. ** while [sqlite3_total_changes()] is running then the value
  2185. ** returned is unpredictable and not meaningful.
  2186. */
  2187. SQLITE_API int sqlite3_total_changes(sqlite3*);
  2188. /*
  2189. ** CAPI3REF: Interrupt A Long-Running Query
  2190. ** METHOD: sqlite3
  2191. **
  2192. ** ^This function causes any pending database operation to abort and
  2193. ** return at its earliest opportunity. This routine is typically
  2194. ** called in response to a user action such as pressing "Cancel"
  2195. ** or Ctrl-C where the user wants a long query operation to halt
  2196. ** immediately.
  2197. **
  2198. ** ^It is safe to call this routine from a thread different from the
  2199. ** thread that is currently running the database operation. But it
  2200. ** is not safe to call this routine with a [database connection] that
  2201. ** is closed or might close before sqlite3_interrupt() returns.
  2202. **
  2203. ** ^If an SQL operation is very nearly finished at the time when
  2204. ** sqlite3_interrupt() is called, then it might not have an opportunity
  2205. ** to be interrupted and might continue to completion.
  2206. **
  2207. ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
  2208. ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
  2209. ** that is inside an explicit transaction, then the entire transaction
  2210. ** will be rolled back automatically.
  2211. **
  2212. ** ^The sqlite3_interrupt(D) call is in effect until all currently running
  2213. ** SQL statements on [database connection] D complete. ^Any new SQL statements
  2214. ** that are started after the sqlite3_interrupt() call and before the
  2215. ** running statements reaches zero are interrupted as if they had been
  2216. ** running prior to the sqlite3_interrupt() call. ^New SQL statements
  2217. ** that are started after the running statement count reaches zero are
  2218. ** not effected by the sqlite3_interrupt().
  2219. ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
  2220. ** SQL statements is a no-op and has no effect on SQL statements
  2221. ** that are started after the sqlite3_interrupt() call returns.
  2222. */
  2223. SQLITE_API void sqlite3_interrupt(sqlite3*);
  2224. /*
  2225. ** CAPI3REF: Determine If An SQL Statement Is Complete
  2226. **
  2227. ** These routines are useful during command-line input to determine if the
  2228. ** currently entered text seems to form a complete SQL statement or
  2229. ** if additional input is needed before sending the text into
  2230. ** SQLite for parsing. ^These routines return 1 if the input string
  2231. ** appears to be a complete SQL statement. ^A statement is judged to be
  2232. ** complete if it ends with a semicolon token and is not a prefix of a
  2233. ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
  2234. ** string literals or quoted identifier names or comments are not
  2235. ** independent tokens (they are part of the token in which they are
  2236. ** embedded) and thus do not count as a statement terminator. ^Whitespace
  2237. ** and comments that follow the final semicolon are ignored.
  2238. **
  2239. ** ^These routines return 0 if the statement is incomplete. ^If a
  2240. ** memory allocation fails, then SQLITE_NOMEM is returned.
  2241. **
  2242. ** ^These routines do not parse the SQL statements thus
  2243. ** will not detect syntactically incorrect SQL.
  2244. **
  2245. ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
  2246. ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
  2247. ** automatically by sqlite3_complete16(). If that initialization fails,
  2248. ** then the return value from sqlite3_complete16() will be non-zero
  2249. ** regardless of whether or not the input SQL is complete.)^
  2250. **
  2251. ** The input to [sqlite3_complete()] must be a zero-terminated
  2252. ** UTF-8 string.
  2253. **
  2254. ** The input to [sqlite3_complete16()] must be a zero-terminated
  2255. ** UTF-16 string in native byte order.
  2256. */
  2257. SQLITE_API int sqlite3_complete(const char *sql);
  2258. SQLITE_API int sqlite3_complete16(const void *sql);
  2259. /*
  2260. ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
  2261. ** KEYWORDS: {busy-handler callback} {busy handler}
  2262. ** METHOD: sqlite3
  2263. **
  2264. ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
  2265. ** that might be invoked with argument P whenever
  2266. ** an attempt is made to access a database table associated with
  2267. ** [database connection] D when another thread
  2268. ** or process has the table locked.
  2269. ** The sqlite3_busy_handler() interface is used to implement
  2270. ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
  2271. **
  2272. ** ^If the busy callback is NULL, then [SQLITE_BUSY]
  2273. ** is returned immediately upon encountering the lock. ^If the busy callback
  2274. ** is not NULL, then the callback might be invoked with two arguments.
  2275. **
  2276. ** ^The first argument to the busy handler is a copy of the void* pointer which
  2277. ** is the third argument to sqlite3_busy_handler(). ^The second argument to
  2278. ** the busy handler callback is the number of times that the busy handler has
  2279. ** been invoked previously for the same locking event. ^If the
  2280. ** busy callback returns 0, then no additional attempts are made to
  2281. ** access the database and [SQLITE_BUSY] is returned
  2282. ** to the application.
  2283. ** ^If the callback returns non-zero, then another attempt
  2284. ** is made to access the database and the cycle repeats.
  2285. **
  2286. ** The presence of a busy handler does not guarantee that it will be invoked
  2287. ** when there is lock contention. ^If SQLite determines that invoking the busy
  2288. ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
  2289. ** to the application instead of invoking the
  2290. ** busy handler.
  2291. ** Consider a scenario where one process is holding a read lock that
  2292. ** it is trying to promote to a reserved lock and
  2293. ** a second process is holding a reserved lock that it is trying
  2294. ** to promote to an exclusive lock. The first process cannot proceed
  2295. ** because it is blocked by the second and the second process cannot
  2296. ** proceed because it is blocked by the first. If both processes
  2297. ** invoke the busy handlers, neither will make any progress. Therefore,
  2298. ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
  2299. ** will induce the first process to release its read lock and allow
  2300. ** the second process to proceed.
  2301. **
  2302. ** ^The default busy callback is NULL.
  2303. **
  2304. ** ^(There can only be a single busy handler defined for each
  2305. ** [database connection]. Setting a new busy handler clears any
  2306. ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
  2307. ** or evaluating [PRAGMA busy_timeout=N] will change the
  2308. ** busy handler and thus clear any previously set busy handler.
  2309. **
  2310. ** The busy callback should not take any actions which modify the
  2311. ** database connection that invoked the busy handler. In other words,
  2312. ** the busy handler is not reentrant. Any such actions
  2313. ** result in undefined behavior.
  2314. **
  2315. ** A busy handler must not close the database connection
  2316. ** or [prepared statement] that invoked the busy handler.
  2317. */
  2318. SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
  2319. /*
  2320. ** CAPI3REF: Set A Busy Timeout
  2321. ** METHOD: sqlite3
  2322. **
  2323. ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
  2324. ** for a specified amount of time when a table is locked. ^The handler
  2325. ** will sleep multiple times until at least "ms" milliseconds of sleeping
  2326. ** have accumulated. ^After at least "ms" milliseconds of sleeping,
  2327. ** the handler returns 0 which causes [sqlite3_step()] to return
  2328. ** [SQLITE_BUSY].
  2329. **
  2330. ** ^Calling this routine with an argument less than or equal to zero
  2331. ** turns off all busy handlers.
  2332. **
  2333. ** ^(There can only be a single busy handler for a particular
  2334. ** [database connection] at any given moment. If another busy handler
  2335. ** was defined (using [sqlite3_busy_handler()]) prior to calling
  2336. ** this routine, that other busy handler is cleared.)^
  2337. **
  2338. ** See also: [PRAGMA busy_timeout]
  2339. */
  2340. SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
  2341. /*
  2342. ** CAPI3REF: Convenience Routines For Running Queries
  2343. ** METHOD: sqlite3
  2344. **
  2345. ** This is a legacy interface that is preserved for backwards compatibility.
  2346. ** Use of this interface is not recommended.
  2347. **
  2348. ** Definition: A <b>result table</b> is memory data structure created by the
  2349. ** [sqlite3_get_table()] interface. A result table records the
  2350. ** complete query results from one or more queries.
  2351. **
  2352. ** The table conceptually has a number of rows and columns. But
  2353. ** these numbers are not part of the result table itself. These
  2354. ** numbers are obtained separately. Let N be the number of rows
  2355. ** and M be the number of columns.
  2356. **
  2357. ** A result table is an array of pointers to zero-terminated UTF-8 strings.
  2358. ** There are (N+1)*M elements in the array. The first M pointers point
  2359. ** to zero-terminated strings that contain the names of the columns.
  2360. ** The remaining entries all point to query results. NULL values result
  2361. ** in NULL pointers. All other values are in their UTF-8 zero-terminated
  2362. ** string representation as returned by [sqlite3_column_text()].
  2363. **
  2364. ** A result table might consist of one or more memory allocations.
  2365. ** It is not safe to pass a result table directly to [sqlite3_free()].
  2366. ** A result table should be deallocated using [sqlite3_free_table()].
  2367. **
  2368. ** ^(As an example of the result table format, suppose a query result
  2369. ** is as follows:
  2370. **
  2371. ** <blockquote><pre>
  2372. ** Name | Age
  2373. ** -----------------------
  2374. ** Alice | 43
  2375. ** Bob | 28
  2376. ** Cindy | 21
  2377. ** </pre></blockquote>
  2378. **
  2379. ** There are two column (M==2) and three rows (N==3). Thus the
  2380. ** result table has 8 entries. Suppose the result table is stored
  2381. ** in an array names azResult. Then azResult holds this content:
  2382. **
  2383. ** <blockquote><pre>
  2384. ** azResult&#91;0] = "Name";
  2385. ** azResult&#91;1] = "Age";
  2386. ** azResult&#91;2] = "Alice";
  2387. ** azResult&#91;3] = "43";
  2388. ** azResult&#91;4] = "Bob";
  2389. ** azResult&#91;5] = "28";
  2390. ** azResult&#91;6] = "Cindy";
  2391. ** azResult&#91;7] = "21";
  2392. ** </pre></blockquote>)^
  2393. **
  2394. ** ^The sqlite3_get_table() function evaluates one or more
  2395. ** semicolon-separated SQL statements in the zero-terminated UTF-8
  2396. ** string of its 2nd parameter and returns a result table to the
  2397. ** pointer given in its 3rd parameter.
  2398. **
  2399. ** After the application has finished with the result from sqlite3_get_table(),
  2400. ** it must pass the result table pointer to sqlite3_free_table() in order to
  2401. ** release the memory that was malloced. Because of the way the
  2402. ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  2403. ** function must not try to call [sqlite3_free()] directly. Only
  2404. ** [sqlite3_free_table()] is able to release the memory properly and safely.
  2405. **
  2406. ** The sqlite3_get_table() interface is implemented as a wrapper around
  2407. ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
  2408. ** to any internal data structures of SQLite. It uses only the public
  2409. ** interface defined here. As a consequence, errors that occur in the
  2410. ** wrapper layer outside of the internal [sqlite3_exec()] call are not
  2411. ** reflected in subsequent calls to [sqlite3_errcode()] or
  2412. ** [sqlite3_errmsg()].
  2413. */
  2414. SQLITE_API int sqlite3_get_table(
  2415. sqlite3 *db, /* An open database */
  2416. const char *zSql, /* SQL to be evaluated */
  2417. char ***pazResult, /* Results of the query */
  2418. int *pnRow, /* Number of result rows written here */
  2419. int *pnColumn, /* Number of result columns written here */
  2420. char **pzErrmsg /* Error msg written here */
  2421. );
  2422. SQLITE_API void sqlite3_free_table(char **result);
  2423. /*
  2424. ** CAPI3REF: Formatted String Printing Functions
  2425. **
  2426. ** These routines are work-alikes of the "printf()" family of functions
  2427. ** from the standard C library.
  2428. ** These routines understand most of the common K&R formatting options,
  2429. ** plus some additional non-standard formats, detailed below.
  2430. ** Note that some of the more obscure formatting options from recent
  2431. ** C-library standards are omitted from this implementation.
  2432. **
  2433. ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2434. ** results into memory obtained from [sqlite3_malloc()].
  2435. ** The strings returned by these two routines should be
  2436. ** released by [sqlite3_free()]. ^Both routines return a
  2437. ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  2438. ** memory to hold the resulting string.
  2439. **
  2440. ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
  2441. ** the standard C library. The result is written into the
  2442. ** buffer supplied as the second parameter whose size is given by
  2443. ** the first parameter. Note that the order of the
  2444. ** first two parameters is reversed from snprintf().)^ This is an
  2445. ** historical accident that cannot be fixed without breaking
  2446. ** backwards compatibility. ^(Note also that sqlite3_snprintf()
  2447. ** returns a pointer to its buffer instead of the number of
  2448. ** characters actually written into the buffer.)^ We admit that
  2449. ** the number of characters written would be a more useful return
  2450. ** value but we cannot change the implementation of sqlite3_snprintf()
  2451. ** now without breaking compatibility.
  2452. **
  2453. ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
  2454. ** guarantees that the buffer is always zero-terminated. ^The first
  2455. ** parameter "n" is the total size of the buffer, including space for
  2456. ** the zero terminator. So the longest string that can be completely
  2457. ** written will be n-1 characters.
  2458. **
  2459. ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2460. **
  2461. ** These routines all implement some additional formatting
  2462. ** options that are useful for constructing SQL statements.
  2463. ** All of the usual printf() formatting options apply. In addition, there
  2464. ** is are "%q", "%Q", "%w" and "%z" options.
  2465. **
  2466. ** ^(The %q option works like %s in that it substitutes a nul-terminated
  2467. ** string from the argument list. But %q also doubles every '\'' character.
  2468. ** %q is designed for use inside a string literal.)^ By doubling each '\''
  2469. ** character it escapes that character and allows it to be inserted into
  2470. ** the string.
  2471. **
  2472. ** For example, assume the string variable zText contains text as follows:
  2473. **
  2474. ** <blockquote><pre>
  2475. ** char *zText = "It's a happy day!";
  2476. ** </pre></blockquote>
  2477. **
  2478. ** One can use this text in an SQL statement as follows:
  2479. **
  2480. ** <blockquote><pre>
  2481. ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
  2482. ** sqlite3_exec(db, zSQL, 0, 0, 0);
  2483. ** sqlite3_free(zSQL);
  2484. ** </pre></blockquote>
  2485. **
  2486. ** Because the %q format string is used, the '\'' character in zText
  2487. ** is escaped and the SQL generated is as follows:
  2488. **
  2489. ** <blockquote><pre>
  2490. ** INSERT INTO table1 VALUES('It''s a happy day!')
  2491. ** </pre></blockquote>
  2492. **
  2493. ** This is correct. Had we used %s instead of %q, the generated SQL
  2494. ** would have looked like this:
  2495. **
  2496. ** <blockquote><pre>
  2497. ** INSERT INTO table1 VALUES('It's a happy day!');
  2498. ** </pre></blockquote>
  2499. **
  2500. ** This second example is an SQL syntax error. As a general rule you should
  2501. ** always use %q instead of %s when inserting text into a string literal.
  2502. **
  2503. ** ^(The %Q option works like %q except it also adds single quotes around
  2504. ** the outside of the total string. Additionally, if the parameter in the
  2505. ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
  2506. ** single quotes).)^ So, for example, one could say:
  2507. **
  2508. ** <blockquote><pre>
  2509. ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  2510. ** sqlite3_exec(db, zSQL, 0, 0, 0);
  2511. ** sqlite3_free(zSQL);
  2512. ** </pre></blockquote>
  2513. **
  2514. ** The code above will render a correct SQL statement in the zSQL
  2515. ** variable even if the zText variable is a NULL pointer.
  2516. **
  2517. ** ^(The "%w" formatting option is like "%q" except that it expects to
  2518. ** be contained within double-quotes instead of single quotes, and it
  2519. ** escapes the double-quote character instead of the single-quote
  2520. ** character.)^ The "%w" formatting option is intended for safely inserting
  2521. ** table and column names into a constructed SQL statement.
  2522. **
  2523. ** ^(The "%z" formatting option works like "%s" but with the
  2524. ** addition that after the string has been read and copied into
  2525. ** the result, [sqlite3_free()] is called on the input string.)^
  2526. */
  2527. SQLITE_API char *sqlite3_mprintf(const char*,...);
  2528. SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
  2529. SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
  2530. SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
  2531. /*
  2532. ** CAPI3REF: Memory Allocation Subsystem
  2533. **
  2534. ** The SQLite core uses these three routines for all of its own
  2535. ** internal memory allocation needs. "Core" in the previous sentence
  2536. ** does not include operating-system specific VFS implementation. The
  2537. ** Windows VFS uses native malloc() and free() for some operations.
  2538. **
  2539. ** ^The sqlite3_malloc() routine returns a pointer to a block
  2540. ** of memory at least N bytes in length, where N is the parameter.
  2541. ** ^If sqlite3_malloc() is unable to obtain sufficient free
  2542. ** memory, it returns a NULL pointer. ^If the parameter N to
  2543. ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  2544. ** a NULL pointer.
  2545. **
  2546. ** ^The sqlite3_malloc64(N) routine works just like
  2547. ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
  2548. ** of a signed 32-bit integer.
  2549. **
  2550. ** ^Calling sqlite3_free() with a pointer previously returned
  2551. ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  2552. ** that it might be reused. ^The sqlite3_free() routine is
  2553. ** a no-op if is called with a NULL pointer. Passing a NULL pointer
  2554. ** to sqlite3_free() is harmless. After being freed, memory
  2555. ** should neither be read nor written. Even reading previously freed
  2556. ** memory might result in a segmentation fault or other severe error.
  2557. ** Memory corruption, a segmentation fault, or other severe error
  2558. ** might result if sqlite3_free() is called with a non-NULL pointer that
  2559. ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
  2560. **
  2561. ** ^The sqlite3_realloc(X,N) interface attempts to resize a
  2562. ** prior memory allocation X to be at least N bytes.
  2563. ** ^If the X parameter to sqlite3_realloc(X,N)
  2564. ** is a NULL pointer then its behavior is identical to calling
  2565. ** sqlite3_malloc(N).
  2566. ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
  2567. ** negative then the behavior is exactly the same as calling
  2568. ** sqlite3_free(X).
  2569. ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
  2570. ** of at least N bytes in size or NULL if insufficient memory is available.
  2571. ** ^If M is the size of the prior allocation, then min(N,M) bytes
  2572. ** of the prior allocation are copied into the beginning of buffer returned
  2573. ** by sqlite3_realloc(X,N) and the prior allocation is freed.
  2574. ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
  2575. ** prior allocation is not freed.
  2576. **
  2577. ** ^The sqlite3_realloc64(X,N) interfaces works the same as
  2578. ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
  2579. ** of a 32-bit signed integer.
  2580. **
  2581. ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
  2582. ** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
  2583. ** sqlite3_msize(X) returns the size of that memory allocation in bytes.
  2584. ** ^The value returned by sqlite3_msize(X) might be larger than the number
  2585. ** of bytes requested when X was allocated. ^If X is a NULL pointer then
  2586. ** sqlite3_msize(X) returns zero. If X points to something that is not
  2587. ** the beginning of memory allocation, or if it points to a formerly
  2588. ** valid memory allocation that has now been freed, then the behavior
  2589. ** of sqlite3_msize(X) is undefined and possibly harmful.
  2590. **
  2591. ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
  2592. ** sqlite3_malloc64(), and sqlite3_realloc64()
  2593. ** is always aligned to at least an 8 byte boundary, or to a
  2594. ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
  2595. ** option is used.
  2596. **
  2597. ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
  2598. ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
  2599. ** implementation of these routines to be omitted. That capability
  2600. ** is no longer provided. Only built-in memory allocators can be used.
  2601. **
  2602. ** Prior to SQLite version 3.7.10, the Windows OS interface layer called
  2603. ** the system malloc() and free() directly when converting
  2604. ** filenames between the UTF-8 encoding used by SQLite
  2605. ** and whatever filename encoding is used by the particular Windows
  2606. ** installation. Memory allocation errors were detected, but
  2607. ** they were reported back as [SQLITE_CANTOPEN] or
  2608. ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
  2609. **
  2610. ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
  2611. ** must be either NULL or else pointers obtained from a prior
  2612. ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
  2613. ** not yet been released.
  2614. **
  2615. ** The application must not read or write any part of
  2616. ** a block of memory after it has been released using
  2617. ** [sqlite3_free()] or [sqlite3_realloc()].
  2618. */
  2619. SQLITE_API void *sqlite3_malloc(int);
  2620. SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
  2621. SQLITE_API void *sqlite3_realloc(void*, int);
  2622. SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
  2623. SQLITE_API void sqlite3_free(void*);
  2624. SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
  2625. /*
  2626. ** CAPI3REF: Memory Allocator Statistics
  2627. **
  2628. ** SQLite provides these two interfaces for reporting on the status
  2629. ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
  2630. ** routines, which form the built-in memory allocation subsystem.
  2631. **
  2632. ** ^The [sqlite3_memory_used()] routine returns the number of bytes
  2633. ** of memory currently outstanding (malloced but not freed).
  2634. ** ^The [sqlite3_memory_highwater()] routine returns the maximum
  2635. ** value of [sqlite3_memory_used()] since the high-water mark
  2636. ** was last reset. ^The values returned by [sqlite3_memory_used()] and
  2637. ** [sqlite3_memory_highwater()] include any overhead
  2638. ** added by SQLite in its implementation of [sqlite3_malloc()],
  2639. ** but not overhead added by the any underlying system library
  2640. ** routines that [sqlite3_malloc()] may call.
  2641. **
  2642. ** ^The memory high-water mark is reset to the current value of
  2643. ** [sqlite3_memory_used()] if and only if the parameter to
  2644. ** [sqlite3_memory_highwater()] is true. ^The value returned
  2645. ** by [sqlite3_memory_highwater(1)] is the high-water mark
  2646. ** prior to the reset.
  2647. */
  2648. SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
  2649. SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  2650. /*
  2651. ** CAPI3REF: Pseudo-Random Number Generator
  2652. **
  2653. ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
  2654. ** select random [ROWID | ROWIDs] when inserting new records into a table that
  2655. ** already uses the largest possible [ROWID]. The PRNG is also used for
  2656. ** the build-in random() and randomblob() SQL functions. This interface allows
  2657. ** applications to access the same PRNG for other purposes.
  2658. **
  2659. ** ^A call to this routine stores N bytes of randomness into buffer P.
  2660. ** ^The P parameter can be a NULL pointer.
  2661. **
  2662. ** ^If this routine has not been previously called or if the previous
  2663. ** call had N less than one or a NULL pointer for P, then the PRNG is
  2664. ** seeded using randomness obtained from the xRandomness method of
  2665. ** the default [sqlite3_vfs] object.
  2666. ** ^If the previous call to this routine had an N of 1 or more and a
  2667. ** non-NULL P then the pseudo-randomness is generated
  2668. ** internally and without recourse to the [sqlite3_vfs] xRandomness
  2669. ** method.
  2670. */
  2671. SQLITE_API void sqlite3_randomness(int N, void *P);
  2672. /*
  2673. ** CAPI3REF: Compile-Time Authorization Callbacks
  2674. ** METHOD: sqlite3
  2675. ** KEYWORDS: {authorizer callback}
  2676. **
  2677. ** ^This routine registers an authorizer callback with a particular
  2678. ** [database connection], supplied in the first argument.
  2679. ** ^The authorizer callback is invoked as SQL statements are being compiled
  2680. ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  2681. ** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
  2682. ** and [sqlite3_prepare16_v3()]. ^At various
  2683. ** points during the compilation process, as logic is being created
  2684. ** to perform various actions, the authorizer callback is invoked to
  2685. ** see if those actions are allowed. ^The authorizer callback should
  2686. ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  2687. ** specific action but allow the SQL statement to continue to be
  2688. ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  2689. ** rejected with an error. ^If the authorizer callback returns
  2690. ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  2691. ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
  2692. ** the authorizer will fail with an error message.
  2693. **
  2694. ** When the callback returns [SQLITE_OK], that means the operation
  2695. ** requested is ok. ^When the callback returns [SQLITE_DENY], the
  2696. ** [sqlite3_prepare_v2()] or equivalent call that triggered the
  2697. ** authorizer will fail with an error message explaining that
  2698. ** access is denied.
  2699. **
  2700. ** ^The first parameter to the authorizer callback is a copy of the third
  2701. ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
  2702. ** to the callback is an integer [SQLITE_COPY | action code] that specifies
  2703. ** the particular action to be authorized. ^The third through sixth parameters
  2704. ** to the callback are either NULL pointers or zero-terminated strings
  2705. ** that contain additional details about the action to be authorized.
  2706. ** Applications must always be prepared to encounter a NULL pointer in any
  2707. ** of the third through the sixth parameters of the authorization callback.
  2708. **
  2709. ** ^If the action code is [SQLITE_READ]
  2710. ** and the callback returns [SQLITE_IGNORE] then the
  2711. ** [prepared statement] statement is constructed to substitute
  2712. ** a NULL value in place of the table column that would have
  2713. ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
  2714. ** return can be used to deny an untrusted user access to individual
  2715. ** columns of a table.
  2716. ** ^When a table is referenced by a [SELECT] but no column values are
  2717. ** extracted from that table (for example in a query like
  2718. ** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
  2719. ** is invoked once for that table with a column name that is an empty string.
  2720. ** ^If the action code is [SQLITE_DELETE] and the callback returns
  2721. ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
  2722. ** [truncate optimization] is disabled and all rows are deleted individually.
  2723. **
  2724. ** An authorizer is used when [sqlite3_prepare | preparing]
  2725. ** SQL statements from an untrusted source, to ensure that the SQL statements
  2726. ** do not try to access data they are not allowed to see, or that they do not
  2727. ** try to execute malicious statements that damage the database. For
  2728. ** example, an application may allow a user to enter arbitrary
  2729. ** SQL queries for evaluation by a database. But the application does
  2730. ** not want the user to be able to make arbitrary changes to the
  2731. ** database. An authorizer could then be put in place while the
  2732. ** user-entered SQL is being [sqlite3_prepare | prepared] that
  2733. ** disallows everything except [SELECT] statements.
  2734. **
  2735. ** Applications that need to process SQL from untrusted sources
  2736. ** might also consider lowering resource limits using [sqlite3_limit()]
  2737. ** and limiting database size using the [max_page_count] [PRAGMA]
  2738. ** in addition to using an authorizer.
  2739. **
  2740. ** ^(Only a single authorizer can be in place on a database connection
  2741. ** at a time. Each call to sqlite3_set_authorizer overrides the
  2742. ** previous call.)^ ^Disable the authorizer by installing a NULL callback.
  2743. ** The authorizer is disabled by default.
  2744. **
  2745. ** The authorizer callback must not do anything that will modify
  2746. ** the database connection that invoked the authorizer callback.
  2747. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  2748. ** database connections for the meaning of "modify" in this paragraph.
  2749. **
  2750. ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
  2751. ** statement might be re-prepared during [sqlite3_step()] due to a
  2752. ** schema change. Hence, the application should ensure that the
  2753. ** correct authorizer callback remains in place during the [sqlite3_step()].
  2754. **
  2755. ** ^Note that the authorizer callback is invoked only during
  2756. ** [sqlite3_prepare()] or its variants. Authorization is not
  2757. ** performed during statement evaluation in [sqlite3_step()], unless
  2758. ** as stated in the previous paragraph, sqlite3_step() invokes
  2759. ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
  2760. */
  2761. SQLITE_API int sqlite3_set_authorizer(
  2762. sqlite3*,
  2763. int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  2764. void *pUserData
  2765. );
  2766. /*
  2767. ** CAPI3REF: Authorizer Return Codes
  2768. **
  2769. ** The [sqlite3_set_authorizer | authorizer callback function] must
  2770. ** return either [SQLITE_OK] or one of these two constants in order
  2771. ** to signal SQLite whether or not the action is permitted. See the
  2772. ** [sqlite3_set_authorizer | authorizer documentation] for additional
  2773. ** information.
  2774. **
  2775. ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
  2776. ** returned from the [sqlite3_vtab_on_conflict()] interface.
  2777. */
  2778. #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
  2779. #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
  2780. /*
  2781. ** CAPI3REF: Authorizer Action Codes
  2782. **
  2783. ** The [sqlite3_set_authorizer()] interface registers a callback function
  2784. ** that is invoked to authorize certain SQL statement actions. The
  2785. ** second parameter to the callback is an integer code that specifies
  2786. ** what action is being authorized. These are the integer action codes that
  2787. ** the authorizer callback may be passed.
  2788. **
  2789. ** These action code values signify what kind of operation is to be
  2790. ** authorized. The 3rd and 4th parameters to the authorization
  2791. ** callback function will be parameters or NULL depending on which of these
  2792. ** codes is used as the second parameter. ^(The 5th parameter to the
  2793. ** authorizer callback is the name of the database ("main", "temp",
  2794. ** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
  2795. ** is the name of the inner-most trigger or view that is responsible for
  2796. ** the access attempt or NULL if this access attempt is directly from
  2797. ** top-level SQL code.
  2798. */
  2799. /******************************************* 3rd ************ 4th ***********/
  2800. #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
  2801. #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
  2802. #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
  2803. #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
  2804. #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
  2805. #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
  2806. #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
  2807. #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
  2808. #define SQLITE_DELETE 9 /* Table Name NULL */
  2809. #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
  2810. #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
  2811. #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
  2812. #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
  2813. #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
  2814. #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
  2815. #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
  2816. #define SQLITE_DROP_VIEW 17 /* View Name NULL */
  2817. #define SQLITE_INSERT 18 /* Table Name NULL */
  2818. #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
  2819. #define SQLITE_READ 20 /* Table Name Column Name */
  2820. #define SQLITE_SELECT 21 /* NULL NULL */
  2821. #define SQLITE_TRANSACTION 22 /* Operation NULL */
  2822. #define SQLITE_UPDATE 23 /* Table Name Column Name */
  2823. #define SQLITE_ATTACH 24 /* Filename NULL */
  2824. #define SQLITE_DETACH 25 /* Database Name NULL */
  2825. #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
  2826. #define SQLITE_REINDEX 27 /* Index Name NULL */
  2827. #define SQLITE_ANALYZE 28 /* Table Name NULL */
  2828. #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
  2829. #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
  2830. #define SQLITE_FUNCTION 31 /* NULL Function Name */
  2831. #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
  2832. #define SQLITE_COPY 0 /* No longer used */
  2833. #define SQLITE_RECURSIVE 33 /* NULL NULL */
  2834. /*
  2835. ** CAPI3REF: Tracing And Profiling Functions
  2836. ** METHOD: sqlite3
  2837. **
  2838. ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
  2839. ** instead of the routines described here.
  2840. **
  2841. ** These routines register callback functions that can be used for
  2842. ** tracing and profiling the execution of SQL statements.
  2843. **
  2844. ** ^The callback function registered by sqlite3_trace() is invoked at
  2845. ** various times when an SQL statement is being run by [sqlite3_step()].
  2846. ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
  2847. ** SQL statement text as the statement first begins executing.
  2848. ** ^(Additional sqlite3_trace() callbacks might occur
  2849. ** as each triggered subprogram is entered. The callbacks for triggers
  2850. ** contain a UTF-8 SQL comment that identifies the trigger.)^
  2851. **
  2852. ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
  2853. ** the length of [bound parameter] expansion in the output of sqlite3_trace().
  2854. **
  2855. ** ^The callback function registered by sqlite3_profile() is invoked
  2856. ** as each SQL statement finishes. ^The profile callback contains
  2857. ** the original statement text and an estimate of wall-clock time
  2858. ** of how long that statement took to run. ^The profile callback
  2859. ** time is in units of nanoseconds, however the current implementation
  2860. ** is only capable of millisecond resolution so the six least significant
  2861. ** digits in the time are meaningless. Future versions of SQLite
  2862. ** might provide greater resolution on the profiler callback. The
  2863. ** sqlite3_profile() function is considered experimental and is
  2864. ** subject to change in future versions of SQLite.
  2865. */
  2866. SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
  2867. void(*xTrace)(void*,const char*), void*);
  2868. SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
  2869. void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  2870. /*
  2871. ** CAPI3REF: SQL Trace Event Codes
  2872. ** KEYWORDS: SQLITE_TRACE
  2873. **
  2874. ** These constants identify classes of events that can be monitored
  2875. ** using the [sqlite3_trace_v2()] tracing logic. The third argument
  2876. ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
  2877. ** the following constants. ^The first argument to the trace callback
  2878. ** is one of the following constants.
  2879. **
  2880. ** New tracing constants may be added in future releases.
  2881. **
  2882. ** ^A trace callback has four arguments: xCallback(T,C,P,X).
  2883. ** ^The T argument is one of the integer type codes above.
  2884. ** ^The C argument is a copy of the context pointer passed in as the
  2885. ** fourth argument to [sqlite3_trace_v2()].
  2886. ** The P and X arguments are pointers whose meanings depend on T.
  2887. **
  2888. ** <dl>
  2889. ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
  2890. ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
  2891. ** first begins running and possibly at other times during the
  2892. ** execution of the prepared statement, such as at the start of each
  2893. ** trigger subprogram. ^The P argument is a pointer to the
  2894. ** [prepared statement]. ^The X argument is a pointer to a string which
  2895. ** is the unexpanded SQL text of the prepared statement or an SQL comment
  2896. ** that indicates the invocation of a trigger. ^The callback can compute
  2897. ** the same text that would have been returned by the legacy [sqlite3_trace()]
  2898. ** interface by using the X argument when X begins with "--" and invoking
  2899. ** [sqlite3_expanded_sql(P)] otherwise.
  2900. **
  2901. ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
  2902. ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
  2903. ** information as is provided by the [sqlite3_profile()] callback.
  2904. ** ^The P argument is a pointer to the [prepared statement] and the
  2905. ** X argument points to a 64-bit integer which is the estimated of
  2906. ** the number of nanosecond that the prepared statement took to run.
  2907. ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
  2908. **
  2909. ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
  2910. ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
  2911. ** statement generates a single row of result.
  2912. ** ^The P argument is a pointer to the [prepared statement] and the
  2913. ** X argument is unused.
  2914. **
  2915. ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
  2916. ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
  2917. ** connection closes.
  2918. ** ^The P argument is a pointer to the [database connection] object
  2919. ** and the X argument is unused.
  2920. ** </dl>
  2921. */
  2922. #define SQLITE_TRACE_STMT 0x01
  2923. #define SQLITE_TRACE_PROFILE 0x02
  2924. #define SQLITE_TRACE_ROW 0x04
  2925. #define SQLITE_TRACE_CLOSE 0x08
  2926. /*
  2927. ** CAPI3REF: SQL Trace Hook
  2928. ** METHOD: sqlite3
  2929. **
  2930. ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
  2931. ** function X against [database connection] D, using property mask M
  2932. ** and context pointer P. ^If the X callback is
  2933. ** NULL or if the M mask is zero, then tracing is disabled. The
  2934. ** M argument should be the bitwise OR-ed combination of
  2935. ** zero or more [SQLITE_TRACE] constants.
  2936. **
  2937. ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
  2938. ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
  2939. **
  2940. ** ^The X callback is invoked whenever any of the events identified by
  2941. ** mask M occur. ^The integer return value from the callback is currently
  2942. ** ignored, though this may change in future releases. Callback
  2943. ** implementations should return zero to ensure future compatibility.
  2944. **
  2945. ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
  2946. ** ^The T argument is one of the [SQLITE_TRACE]
  2947. ** constants to indicate why the callback was invoked.
  2948. ** ^The C argument is a copy of the context pointer.
  2949. ** The P and X arguments are pointers whose meanings depend on T.
  2950. **
  2951. ** The sqlite3_trace_v2() interface is intended to replace the legacy
  2952. ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
  2953. ** are deprecated.
  2954. */
  2955. SQLITE_API int sqlite3_trace_v2(
  2956. sqlite3*,
  2957. unsigned uMask,
  2958. int(*xCallback)(unsigned,void*,void*,void*),
  2959. void *pCtx
  2960. );
  2961. /*
  2962. ** CAPI3REF: Query Progress Callbacks
  2963. ** METHOD: sqlite3
  2964. **
  2965. ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
  2966. ** function X to be invoked periodically during long running calls to
  2967. ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
  2968. ** database connection D. An example use for this
  2969. ** interface is to keep a GUI updated during a large query.
  2970. **
  2971. ** ^The parameter P is passed through as the only parameter to the
  2972. ** callback function X. ^The parameter N is the approximate number of
  2973. ** [virtual machine instructions] that are evaluated between successive
  2974. ** invocations of the callback X. ^If N is less than one then the progress
  2975. ** handler is disabled.
  2976. **
  2977. ** ^Only a single progress handler may be defined at one time per
  2978. ** [database connection]; setting a new progress handler cancels the
  2979. ** old one. ^Setting parameter X to NULL disables the progress handler.
  2980. ** ^The progress handler is also disabled by setting N to a value less
  2981. ** than 1.
  2982. **
  2983. ** ^If the progress callback returns non-zero, the operation is
  2984. ** interrupted. This feature can be used to implement a
  2985. ** "Cancel" button on a GUI progress dialog box.
  2986. **
  2987. ** The progress handler callback must not do anything that will modify
  2988. ** the database connection that invoked the progress handler.
  2989. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  2990. ** database connections for the meaning of "modify" in this paragraph.
  2991. **
  2992. */
  2993. SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  2994. /*
  2995. ** CAPI3REF: Opening A New Database Connection
  2996. ** CONSTRUCTOR: sqlite3
  2997. **
  2998. ** ^These routines open an SQLite database file as specified by the
  2999. ** filename argument. ^The filename argument is interpreted as UTF-8 for
  3000. ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
  3001. ** order for sqlite3_open16(). ^(A [database connection] handle is usually
  3002. ** returned in *ppDb, even if an error occurs. The only exception is that
  3003. ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
  3004. ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
  3005. ** object.)^ ^(If the database is opened (and/or created) successfully, then
  3006. ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
  3007. ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
  3008. ** an English language description of the error following a failure of any
  3009. ** of the sqlite3_open() routines.
  3010. **
  3011. ** ^The default encoding will be UTF-8 for databases created using
  3012. ** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
  3013. ** created using sqlite3_open16() will be UTF-16 in the native byte order.
  3014. **
  3015. ** Whether or not an error occurs when it is opened, resources
  3016. ** associated with the [database connection] handle should be released by
  3017. ** passing it to [sqlite3_close()] when it is no longer required.
  3018. **
  3019. ** The sqlite3_open_v2() interface works like sqlite3_open()
  3020. ** except that it accepts two additional parameters for additional control
  3021. ** over the new database connection. ^(The flags parameter to
  3022. ** sqlite3_open_v2() can take one of
  3023. ** the following three values, optionally combined with the
  3024. ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
  3025. ** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
  3026. **
  3027. ** <dl>
  3028. ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
  3029. ** <dd>The database is opened in read-only mode. If the database does not
  3030. ** already exist, an error is returned.</dd>)^
  3031. **
  3032. ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
  3033. ** <dd>The database is opened for reading and writing if possible, or reading
  3034. ** only if the file is write protected by the operating system. In either
  3035. ** case the database must already exist, otherwise an error is returned.</dd>)^
  3036. **
  3037. ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
  3038. ** <dd>The database is opened for reading and writing, and is created if
  3039. ** it does not already exist. This is the behavior that is always used for
  3040. ** sqlite3_open() and sqlite3_open16().</dd>)^
  3041. ** </dl>
  3042. **
  3043. ** If the 3rd parameter to sqlite3_open_v2() is not one of the
  3044. ** combinations shown above optionally combined with other
  3045. ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
  3046. ** then the behavior is undefined.
  3047. **
  3048. ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
  3049. ** opens in the multi-thread [threading mode] as long as the single-thread
  3050. ** mode has not been set at compile-time or start-time. ^If the
  3051. ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
  3052. ** in the serialized [threading mode] unless single-thread was
  3053. ** previously selected at compile-time or start-time.
  3054. ** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
  3055. ** eligible to use [shared cache mode], regardless of whether or not shared
  3056. ** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
  3057. ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
  3058. ** participate in [shared cache mode] even if it is enabled.
  3059. **
  3060. ** ^The fourth parameter to sqlite3_open_v2() is the name of the
  3061. ** [sqlite3_vfs] object that defines the operating system interface that
  3062. ** the new database connection should use. ^If the fourth parameter is
  3063. ** a NULL pointer then the default [sqlite3_vfs] object is used.
  3064. **
  3065. ** ^If the filename is ":memory:", then a private, temporary in-memory database
  3066. ** is created for the connection. ^This in-memory database will vanish when
  3067. ** the database connection is closed. Future versions of SQLite might
  3068. ** make use of additional special filenames that begin with the ":" character.
  3069. ** It is recommended that when a database filename actually does begin with
  3070. ** a ":" character you should prefix the filename with a pathname such as
  3071. ** "./" to avoid ambiguity.
  3072. **
  3073. ** ^If the filename is an empty string, then a private, temporary
  3074. ** on-disk database will be created. ^This private database will be
  3075. ** automatically deleted as soon as the database connection is closed.
  3076. **
  3077. ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
  3078. **
  3079. ** ^If [URI filename] interpretation is enabled, and the filename argument
  3080. ** begins with "file:", then the filename is interpreted as a URI. ^URI
  3081. ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
  3082. ** set in the third argument to sqlite3_open_v2(), or if it has
  3083. ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
  3084. ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
  3085. ** URI filename interpretation is turned off
  3086. ** by default, but future releases of SQLite might enable URI filename
  3087. ** interpretation by default. See "[URI filenames]" for additional
  3088. ** information.
  3089. **
  3090. ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
  3091. ** authority, then it must be either an empty string or the string
  3092. ** "localhost". ^If the authority is not an empty string or "localhost", an
  3093. ** error is returned to the caller. ^The fragment component of a URI, if
  3094. ** present, is ignored.
  3095. **
  3096. ** ^SQLite uses the path component of the URI as the name of the disk file
  3097. ** which contains the database. ^If the path begins with a '/' character,
  3098. ** then it is interpreted as an absolute path. ^If the path does not begin
  3099. ** with a '/' (meaning that the authority section is omitted from the URI)
  3100. ** then the path is interpreted as a relative path.
  3101. ** ^(On windows, the first component of an absolute path
  3102. ** is a drive specification (e.g. "C:").)^
  3103. **
  3104. ** [[core URI query parameters]]
  3105. ** The query component of a URI may contain parameters that are interpreted
  3106. ** either by SQLite itself, or by a [VFS | custom VFS implementation].
  3107. ** SQLite and its built-in [VFSes] interpret the
  3108. ** following query parameters:
  3109. **
  3110. ** <ul>
  3111. ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
  3112. ** a VFS object that provides the operating system interface that should
  3113. ** be used to access the database file on disk. ^If this option is set to
  3114. ** an empty string the default VFS object is used. ^Specifying an unknown
  3115. ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
  3116. ** present, then the VFS specified by the option takes precedence over
  3117. ** the value passed as the fourth parameter to sqlite3_open_v2().
  3118. **
  3119. ** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
  3120. ** "rwc", or "memory". Attempting to set it to any other value is
  3121. ** an error)^.
  3122. ** ^If "ro" is specified, then the database is opened for read-only
  3123. ** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
  3124. ** third argument to sqlite3_open_v2(). ^If the mode option is set to
  3125. ** "rw", then the database is opened for read-write (but not create)
  3126. ** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
  3127. ** been set. ^Value "rwc" is equivalent to setting both
  3128. ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
  3129. ** set to "memory" then a pure [in-memory database] that never reads
  3130. ** or writes from disk is used. ^It is an error to specify a value for
  3131. ** the mode parameter that is less restrictive than that specified by
  3132. ** the flags passed in the third parameter to sqlite3_open_v2().
  3133. **
  3134. ** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
  3135. ** "private". ^Setting it to "shared" is equivalent to setting the
  3136. ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
  3137. ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
  3138. ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
  3139. ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
  3140. ** a URI filename, its value overrides any behavior requested by setting
  3141. ** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
  3142. **
  3143. ** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
  3144. ** [powersafe overwrite] property does or does not apply to the
  3145. ** storage media on which the database file resides.
  3146. **
  3147. ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
  3148. ** which if set disables file locking in rollback journal modes. This
  3149. ** is useful for accessing a database on a filesystem that does not
  3150. ** support locking. Caution: Database corruption might result if two
  3151. ** or more processes write to the same database and any one of those
  3152. ** processes uses nolock=1.
  3153. **
  3154. ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
  3155. ** parameter that indicates that the database file is stored on
  3156. ** read-only media. ^When immutable is set, SQLite assumes that the
  3157. ** database file cannot be changed, even by a process with higher
  3158. ** privilege, and so the database is opened read-only and all locking
  3159. ** and change detection is disabled. Caution: Setting the immutable
  3160. ** property on a database file that does in fact change can result
  3161. ** in incorrect query results and/or [SQLITE_CORRUPT] errors.
  3162. ** See also: [SQLITE_IOCAP_IMMUTABLE].
  3163. **
  3164. ** </ul>
  3165. **
  3166. ** ^Specifying an unknown parameter in the query component of a URI is not an
  3167. ** error. Future versions of SQLite might understand additional query
  3168. ** parameters. See "[query parameters with special meaning to SQLite]" for
  3169. ** additional information.
  3170. **
  3171. ** [[URI filename examples]] <h3>URI filename examples</h3>
  3172. **
  3173. ** <table border="1" align=center cellpadding=5>
  3174. ** <tr><th> URI filenames <th> Results
  3175. ** <tr><td> file:data.db <td>
  3176. ** Open the file "data.db" in the current directory.
  3177. ** <tr><td> file:/home/fred/data.db<br>
  3178. ** file:///home/fred/data.db <br>
  3179. ** file://localhost/home/fred/data.db <br> <td>
  3180. ** Open the database file "/home/fred/data.db".
  3181. ** <tr><td> file://darkstar/home/fred/data.db <td>
  3182. ** An error. "darkstar" is not a recognized authority.
  3183. ** <tr><td style="white-space:nowrap">
  3184. ** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
  3185. ** <td> Windows only: Open the file "data.db" on fred's desktop on drive
  3186. ** C:. Note that the %20 escaping in this example is not strictly
  3187. ** necessary - space characters can be used literally
  3188. ** in URI filenames.
  3189. ** <tr><td> file:data.db?mode=ro&cache=private <td>
  3190. ** Open file "data.db" in the current directory for read-only access.
  3191. ** Regardless of whether or not shared-cache mode is enabled by
  3192. ** default, use a private cache.
  3193. ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
  3194. ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
  3195. ** that uses dot-files in place of posix advisory locking.
  3196. ** <tr><td> file:data.db?mode=readonly <td>
  3197. ** An error. "readonly" is not a valid option for the "mode" parameter.
  3198. ** </table>
  3199. **
  3200. ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
  3201. ** query components of a URI. A hexadecimal escape sequence consists of a
  3202. ** percent sign - "%" - followed by exactly two hexadecimal digits
  3203. ** specifying an octet value. ^Before the path or query components of a
  3204. ** URI filename are interpreted, they are encoded using UTF-8 and all
  3205. ** hexadecimal escape sequences replaced by a single byte containing the
  3206. ** corresponding octet. If this process generates an invalid UTF-8 encoding,
  3207. ** the results are undefined.
  3208. **
  3209. ** <b>Note to Windows users:</b> The encoding used for the filename argument
  3210. ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
  3211. ** codepage is currently defined. Filenames containing international
  3212. ** characters must be converted to UTF-8 prior to passing them into
  3213. ** sqlite3_open() or sqlite3_open_v2().
  3214. **
  3215. ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
  3216. ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
  3217. ** features that require the use of temporary files may fail.
  3218. **
  3219. ** See also: [sqlite3_temp_directory]
  3220. */
  3221. SQLITE_API int sqlite3_open(
  3222. const char *filename, /* Database filename (UTF-8) */
  3223. sqlite3 **ppDb /* OUT: SQLite db handle */
  3224. );
  3225. SQLITE_API int sqlite3_open16(
  3226. const void *filename, /* Database filename (UTF-16) */
  3227. sqlite3 **ppDb /* OUT: SQLite db handle */
  3228. );
  3229. SQLITE_API int sqlite3_open_v2(
  3230. const char *filename, /* Database filename (UTF-8) */
  3231. sqlite3 **ppDb, /* OUT: SQLite db handle */
  3232. int flags, /* Flags */
  3233. const char *zVfs /* Name of VFS module to use */
  3234. );
  3235. /*
  3236. ** CAPI3REF: Obtain Values For URI Parameters
  3237. **
  3238. ** These are utility routines, useful to VFS implementations, that check
  3239. ** to see if a database file was a URI that contained a specific query
  3240. ** parameter, and if so obtains the value of that query parameter.
  3241. **
  3242. ** If F is the database filename pointer passed into the xOpen() method of
  3243. ** a VFS implementation when the flags parameter to xOpen() has one or
  3244. ** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
  3245. ** P is the name of the query parameter, then
  3246. ** sqlite3_uri_parameter(F,P) returns the value of the P
  3247. ** parameter if it exists or a NULL pointer if P does not appear as a
  3248. ** query parameter on F. If P is a query parameter of F
  3249. ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
  3250. ** a pointer to an empty string.
  3251. **
  3252. ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
  3253. ** parameter and returns true (1) or false (0) according to the value
  3254. ** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
  3255. ** value of query parameter P is one of "yes", "true", or "on" in any
  3256. ** case or if the value begins with a non-zero number. The
  3257. ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
  3258. ** query parameter P is one of "no", "false", or "off" in any case or
  3259. ** if the value begins with a numeric zero. If P is not a query
  3260. ** parameter on F or if the value of P is does not match any of the
  3261. ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
  3262. **
  3263. ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
  3264. ** 64-bit signed integer and returns that integer, or D if P does not
  3265. ** exist. If the value of P is something other than an integer, then
  3266. ** zero is returned.
  3267. **
  3268. ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
  3269. ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
  3270. ** is not a database file pathname pointer that SQLite passed into the xOpen
  3271. ** VFS method, then the behavior of this routine is undefined and probably
  3272. ** undesirable.
  3273. */
  3274. SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
  3275. SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
  3276. SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
  3277. /*
  3278. ** CAPI3REF: Error Codes And Messages
  3279. ** METHOD: sqlite3
  3280. **
  3281. ** ^If the most recent sqlite3_* API call associated with
  3282. ** [database connection] D failed, then the sqlite3_errcode(D) interface
  3283. ** returns the numeric [result code] or [extended result code] for that
  3284. ** API call.
  3285. ** If the most recent API call was successful,
  3286. ** then the return value from sqlite3_errcode() is undefined.
  3287. ** ^The sqlite3_extended_errcode()
  3288. ** interface is the same except that it always returns the
  3289. ** [extended result code] even when extended result codes are
  3290. ** disabled.
  3291. **
  3292. ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  3293. ** text that describes the error, as either UTF-8 or UTF-16 respectively.
  3294. ** ^(Memory to hold the error message string is managed internally.
  3295. ** The application does not need to worry about freeing the result.
  3296. ** However, the error string might be overwritten or deallocated by
  3297. ** subsequent calls to other SQLite interface functions.)^
  3298. **
  3299. ** ^The sqlite3_errstr() interface returns the English-language text
  3300. ** that describes the [result code], as UTF-8.
  3301. ** ^(Memory to hold the error message string is managed internally
  3302. ** and must not be freed by the application)^.
  3303. **
  3304. ** When the serialized [threading mode] is in use, it might be the
  3305. ** case that a second error occurs on a separate thread in between
  3306. ** the time of the first error and the call to these interfaces.
  3307. ** When that happens, the second error will be reported since these
  3308. ** interfaces always report the most recent result. To avoid
  3309. ** this, each thread can obtain exclusive use of the [database connection] D
  3310. ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
  3311. ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
  3312. ** all calls to the interfaces listed here are completed.
  3313. **
  3314. ** If an interface fails with SQLITE_MISUSE, that means the interface
  3315. ** was invoked incorrectly by the application. In that case, the
  3316. ** error code and message may or may not be set.
  3317. */
  3318. SQLITE_API int sqlite3_errcode(sqlite3 *db);
  3319. SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
  3320. SQLITE_API const char *sqlite3_errmsg(sqlite3*);
  3321. SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
  3322. SQLITE_API const char *sqlite3_errstr(int);
  3323. /*
  3324. ** CAPI3REF: Prepared Statement Object
  3325. ** KEYWORDS: {prepared statement} {prepared statements}
  3326. **
  3327. ** An instance of this object represents a single SQL statement that
  3328. ** has been compiled into binary form and is ready to be evaluated.
  3329. **
  3330. ** Think of each SQL statement as a separate computer program. The
  3331. ** original SQL text is source code. A prepared statement object
  3332. ** is the compiled object code. All SQL must be converted into a
  3333. ** prepared statement before it can be run.
  3334. **
  3335. ** The life-cycle of a prepared statement object usually goes like this:
  3336. **
  3337. ** <ol>
  3338. ** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
  3339. ** <li> Bind values to [parameters] using the sqlite3_bind_*()
  3340. ** interfaces.
  3341. ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
  3342. ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
  3343. ** to step 2. Do this zero or more times.
  3344. ** <li> Destroy the object using [sqlite3_finalize()].
  3345. ** </ol>
  3346. */
  3347. typedef struct sqlite3_stmt sqlite3_stmt;
  3348. /*
  3349. ** CAPI3REF: Run-time Limits
  3350. ** METHOD: sqlite3
  3351. **
  3352. ** ^(This interface allows the size of various constructs to be limited
  3353. ** on a connection by connection basis. The first parameter is the
  3354. ** [database connection] whose limit is to be set or queried. The
  3355. ** second parameter is one of the [limit categories] that define a
  3356. ** class of constructs to be size limited. The third parameter is the
  3357. ** new limit for that construct.)^
  3358. **
  3359. ** ^If the new limit is a negative number, the limit is unchanged.
  3360. ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
  3361. ** [limits | hard upper bound]
  3362. ** set at compile-time by a C preprocessor macro called
  3363. ** [limits | SQLITE_MAX_<i>NAME</i>].
  3364. ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
  3365. ** ^Attempts to increase a limit above its hard upper bound are
  3366. ** silently truncated to the hard upper bound.
  3367. **
  3368. ** ^Regardless of whether or not the limit was changed, the
  3369. ** [sqlite3_limit()] interface returns the prior value of the limit.
  3370. ** ^Hence, to find the current value of a limit without changing it,
  3371. ** simply invoke this interface with the third parameter set to -1.
  3372. **
  3373. ** Run-time limits are intended for use in applications that manage
  3374. ** both their own internal database and also databases that are controlled
  3375. ** by untrusted external sources. An example application might be a
  3376. ** web browser that has its own databases for storing history and
  3377. ** separate databases controlled by JavaScript applications downloaded
  3378. ** off the Internet. The internal databases can be given the
  3379. ** large, default limits. Databases managed by external sources can
  3380. ** be given much smaller limits designed to prevent a denial of service
  3381. ** attack. Developers might also want to use the [sqlite3_set_authorizer()]
  3382. ** interface to further control untrusted SQL. The size of the database
  3383. ** created by an untrusted script can be contained using the
  3384. ** [max_page_count] [PRAGMA].
  3385. **
  3386. ** New run-time limit categories may be added in future releases.
  3387. */
  3388. SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
  3389. /*
  3390. ** CAPI3REF: Run-Time Limit Categories
  3391. ** KEYWORDS: {limit category} {*limit categories}
  3392. **
  3393. ** These constants define various performance limits
  3394. ** that can be lowered at run-time using [sqlite3_limit()].
  3395. ** The synopsis of the meanings of the various limits is shown below.
  3396. ** Additional information is available at [limits | Limits in SQLite].
  3397. **
  3398. ** <dl>
  3399. ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
  3400. ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
  3401. **
  3402. ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
  3403. ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
  3404. **
  3405. ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
  3406. ** <dd>The maximum number of columns in a table definition or in the
  3407. ** result set of a [SELECT] or the maximum number of columns in an index
  3408. ** or in an ORDER BY or GROUP BY clause.</dd>)^
  3409. **
  3410. ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
  3411. ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
  3412. **
  3413. ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  3414. ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
  3415. **
  3416. ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
  3417. ** <dd>The maximum number of instructions in a virtual machine program
  3418. ** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
  3419. ** the equivalent tries to allocate space for more than this many opcodes
  3420. ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
  3421. **
  3422. ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  3423. ** <dd>The maximum number of arguments on a function.</dd>)^
  3424. **
  3425. ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
  3426. ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
  3427. **
  3428. ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
  3429. ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
  3430. ** <dd>The maximum length of the pattern argument to the [LIKE] or
  3431. ** [GLOB] operators.</dd>)^
  3432. **
  3433. ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
  3434. ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
  3435. ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
  3436. **
  3437. ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
  3438. ** <dd>The maximum depth of recursion for triggers.</dd>)^
  3439. **
  3440. ** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
  3441. ** <dd>The maximum number of auxiliary worker threads that a single
  3442. ** [prepared statement] may start.</dd>)^
  3443. ** </dl>
  3444. */
  3445. #define SQLITE_LIMIT_LENGTH 0
  3446. #define SQLITE_LIMIT_SQL_LENGTH 1
  3447. #define SQLITE_LIMIT_COLUMN 2
  3448. #define SQLITE_LIMIT_EXPR_DEPTH 3
  3449. #define SQLITE_LIMIT_COMPOUND_SELECT 4
  3450. #define SQLITE_LIMIT_VDBE_OP 5
  3451. #define SQLITE_LIMIT_FUNCTION_ARG 6
  3452. #define SQLITE_LIMIT_ATTACHED 7
  3453. #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
  3454. #define SQLITE_LIMIT_VARIABLE_NUMBER 9
  3455. #define SQLITE_LIMIT_TRIGGER_DEPTH 10
  3456. #define SQLITE_LIMIT_WORKER_THREADS 11
  3457. /*
  3458. ** CAPI3REF: Prepare Flags
  3459. **
  3460. ** These constants define various flags that can be passed into
  3461. ** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
  3462. ** [sqlite3_prepare16_v3()] interfaces.
  3463. **
  3464. ** New flags may be added in future releases of SQLite.
  3465. **
  3466. ** <dl>
  3467. ** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
  3468. ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
  3469. ** that the prepared statement will be retained for a long time and
  3470. ** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
  3471. ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
  3472. ** be used just once or at most a few times and then destroyed using
  3473. ** [sqlite3_finalize()] relatively soon. The current implementation acts
  3474. ** on this hint by avoiding the use of [lookaside memory] so as not to
  3475. ** deplete the limited store of lookaside memory. Future versions of
  3476. ** SQLite may act on this hint differently.
  3477. ** </dl>
  3478. */
  3479. #define SQLITE_PREPARE_PERSISTENT 0x01
  3480. /*
  3481. ** CAPI3REF: Compiling An SQL Statement
  3482. ** KEYWORDS: {SQL statement compiler}
  3483. ** METHOD: sqlite3
  3484. ** CONSTRUCTOR: sqlite3_stmt
  3485. **
  3486. ** To execute an SQL statement, it must first be compiled into a byte-code
  3487. ** program using one of these routines. Or, in other words, these routines
  3488. ** are constructors for the [prepared statement] object.
  3489. **
  3490. ** The preferred routine to use is [sqlite3_prepare_v2()]. The
  3491. ** [sqlite3_prepare()] interface is legacy and should be avoided.
  3492. ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
  3493. ** for special purposes.
  3494. **
  3495. ** The use of the UTF-8 interfaces is preferred, as SQLite currently
  3496. ** does all parsing using UTF-8. The UTF-16 interfaces are provided
  3497. ** as a convenience. The UTF-16 interfaces work by converting the
  3498. ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
  3499. **
  3500. ** The first argument, "db", is a [database connection] obtained from a
  3501. ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
  3502. ** [sqlite3_open16()]. The database connection must not have been closed.
  3503. **
  3504. ** The second argument, "zSql", is the statement to be compiled, encoded
  3505. ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
  3506. ** and sqlite3_prepare_v3()
  3507. ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
  3508. ** and sqlite3_prepare16_v3() use UTF-16.
  3509. **
  3510. ** ^If the nByte argument is negative, then zSql is read up to the
  3511. ** first zero terminator. ^If nByte is positive, then it is the
  3512. ** number of bytes read from zSql. ^If nByte is zero, then no prepared
  3513. ** statement is generated.
  3514. ** If the caller knows that the supplied string is nul-terminated, then
  3515. ** there is a small performance advantage to passing an nByte parameter that
  3516. ** is the number of bytes in the input string <i>including</i>
  3517. ** the nul-terminator.
  3518. **
  3519. ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
  3520. ** past the end of the first SQL statement in zSql. These routines only
  3521. ** compile the first statement in zSql, so *pzTail is left pointing to
  3522. ** what remains uncompiled.
  3523. **
  3524. ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
  3525. ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
  3526. ** to NULL. ^If the input text contains no SQL (if the input is an empty
  3527. ** string or a comment) then *ppStmt is set to NULL.
  3528. ** The calling procedure is responsible for deleting the compiled
  3529. ** SQL statement using [sqlite3_finalize()] after it has finished with it.
  3530. ** ppStmt may not be NULL.
  3531. **
  3532. ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
  3533. ** otherwise an [error code] is returned.
  3534. **
  3535. ** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
  3536. ** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
  3537. ** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
  3538. ** are retained for backwards compatibility, but their use is discouraged.
  3539. ** ^In the "vX" interfaces, the prepared statement
  3540. ** that is returned (the [sqlite3_stmt] object) contains a copy of the
  3541. ** original SQL text. This causes the [sqlite3_step()] interface to
  3542. ** behave differently in three ways:
  3543. **
  3544. ** <ol>
  3545. ** <li>
  3546. ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  3547. ** always used to do, [sqlite3_step()] will automatically recompile the SQL
  3548. ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
  3549. ** retries will occur before sqlite3_step() gives up and returns an error.
  3550. ** </li>
  3551. **
  3552. ** <li>
  3553. ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
  3554. ** [error codes] or [extended error codes]. ^The legacy behavior was that
  3555. ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
  3556. ** and the application would have to make a second call to [sqlite3_reset()]
  3557. ** in order to find the underlying cause of the problem. With the "v2" prepare
  3558. ** interfaces, the underlying reason for the error is returned immediately.
  3559. ** </li>
  3560. **
  3561. ** <li>
  3562. ** ^If the specific value bound to [parameter | host parameter] in the
  3563. ** WHERE clause might influence the choice of query plan for a statement,
  3564. ** then the statement will be automatically recompiled, as if there had been
  3565. ** a schema change, on the first [sqlite3_step()] call following any change
  3566. ** to the [sqlite3_bind_text | bindings] of that [parameter].
  3567. ** ^The specific value of WHERE-clause [parameter] might influence the
  3568. ** choice of query plan if the parameter is the left-hand side of a [LIKE]
  3569. ** or [GLOB] operator or if the parameter is compared to an indexed column
  3570. ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
  3571. ** </li>
  3572. **
  3573. ** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
  3574. ** the extra prepFlags parameter, which is a bit array consisting of zero or
  3575. ** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
  3576. ** sqlite3_prepare_v2() interface works exactly the same as
  3577. ** sqlite3_prepare_v3() with a zero prepFlags parameter.
  3578. ** </ol>
  3579. */
  3580. SQLITE_API int sqlite3_prepare(
  3581. sqlite3 *db, /* Database handle */
  3582. const char *zSql, /* SQL statement, UTF-8 encoded */
  3583. int nByte, /* Maximum length of zSql in bytes. */
  3584. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3585. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  3586. );
  3587. SQLITE_API int sqlite3_prepare_v2(
  3588. sqlite3 *db, /* Database handle */
  3589. const char *zSql, /* SQL statement, UTF-8 encoded */
  3590. int nByte, /* Maximum length of zSql in bytes. */
  3591. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3592. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  3593. );
  3594. SQLITE_API int sqlite3_prepare_v3(
  3595. sqlite3 *db, /* Database handle */
  3596. const char *zSql, /* SQL statement, UTF-8 encoded */
  3597. int nByte, /* Maximum length of zSql in bytes. */
  3598. unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  3599. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3600. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  3601. );
  3602. SQLITE_API int sqlite3_prepare16(
  3603. sqlite3 *db, /* Database handle */
  3604. const void *zSql, /* SQL statement, UTF-16 encoded */
  3605. int nByte, /* Maximum length of zSql in bytes. */
  3606. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3607. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  3608. );
  3609. SQLITE_API int sqlite3_prepare16_v2(
  3610. sqlite3 *db, /* Database handle */
  3611. const void *zSql, /* SQL statement, UTF-16 encoded */
  3612. int nByte, /* Maximum length of zSql in bytes. */
  3613. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3614. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  3615. );
  3616. SQLITE_API int sqlite3_prepare16_v3(
  3617. sqlite3 *db, /* Database handle */
  3618. const void *zSql, /* SQL statement, UTF-16 encoded */
  3619. int nByte, /* Maximum length of zSql in bytes. */
  3620. unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  3621. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  3622. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  3623. );
  3624. /*
  3625. ** CAPI3REF: Retrieving Statement SQL
  3626. ** METHOD: sqlite3_stmt
  3627. **
  3628. ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
  3629. ** SQL text used to create [prepared statement] P if P was
  3630. ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
  3631. ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  3632. ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
  3633. ** string containing the SQL text of prepared statement P with
  3634. ** [bound parameters] expanded.
  3635. **
  3636. ** ^(For example, if a prepared statement is created using the SQL
  3637. ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
  3638. ** and parameter :xyz is unbound, then sqlite3_sql() will return
  3639. ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
  3640. ** will return "SELECT 2345,NULL".)^
  3641. **
  3642. ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
  3643. ** is available to hold the result, or if the result would exceed the
  3644. ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
  3645. **
  3646. ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
  3647. ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
  3648. ** option causes sqlite3_expanded_sql() to always return NULL.
  3649. **
  3650. ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
  3651. ** automatically freed when the prepared statement is finalized.
  3652. ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
  3653. ** is obtained from [sqlite3_malloc()] and must be free by the application
  3654. ** by passing it to [sqlite3_free()].
  3655. */
  3656. SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
  3657. SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
  3658. /*
  3659. ** CAPI3REF: Determine If An SQL Statement Writes The Database
  3660. ** METHOD: sqlite3_stmt
  3661. **
  3662. ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
  3663. ** and only if the [prepared statement] X makes no direct changes to
  3664. ** the content of the database file.
  3665. **
  3666. ** Note that [application-defined SQL functions] or
  3667. ** [virtual tables] might change the database indirectly as a side effect.
  3668. ** ^(For example, if an application defines a function "eval()" that
  3669. ** calls [sqlite3_exec()], then the following SQL statement would
  3670. ** change the database file through side-effects:
  3671. **
  3672. ** <blockquote><pre>
  3673. ** SELECT eval('DELETE FROM t1') FROM t2;
  3674. ** </pre></blockquote>
  3675. **
  3676. ** But because the [SELECT] statement does not change the database file
  3677. ** directly, sqlite3_stmt_readonly() would still return true.)^
  3678. **
  3679. ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
  3680. ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
  3681. ** since the statements themselves do not actually modify the database but
  3682. ** rather they control the timing of when other statements modify the
  3683. ** database. ^The [ATTACH] and [DETACH] statements also cause
  3684. ** sqlite3_stmt_readonly() to return true since, while those statements
  3685. ** change the configuration of a database connection, they do not make
  3686. ** changes to the content of the database files on disk.
  3687. ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
  3688. ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
  3689. ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
  3690. ** sqlite3_stmt_readonly() returns false for those commands.
  3691. */
  3692. SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
  3693. /*
  3694. ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
  3695. ** METHOD: sqlite3_stmt
  3696. **
  3697. ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
  3698. ** [prepared statement] S has been stepped at least once using
  3699. ** [sqlite3_step(S)] but has neither run to completion (returned
  3700. ** [SQLITE_DONE] from [sqlite3_step(S)]) nor
  3701. ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
  3702. ** interface returns false if S is a NULL pointer. If S is not a
  3703. ** NULL pointer and is not a pointer to a valid [prepared statement]
  3704. ** object, then the behavior is undefined and probably undesirable.
  3705. **
  3706. ** This interface can be used in combination [sqlite3_next_stmt()]
  3707. ** to locate all prepared statements associated with a database
  3708. ** connection that are in need of being reset. This can be used,
  3709. ** for example, in diagnostic routines to search for prepared
  3710. ** statements that are holding a transaction open.
  3711. */
  3712. SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
  3713. /*
  3714. ** CAPI3REF: Dynamically Typed Value Object
  3715. ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  3716. **
  3717. ** SQLite uses the sqlite3_value object to represent all values
  3718. ** that can be stored in a database table. SQLite uses dynamic typing
  3719. ** for the values it stores. ^Values stored in sqlite3_value objects
  3720. ** can be integers, floating point values, strings, BLOBs, or NULL.
  3721. **
  3722. ** An sqlite3_value object may be either "protected" or "unprotected".
  3723. ** Some interfaces require a protected sqlite3_value. Other interfaces
  3724. ** will accept either a protected or an unprotected sqlite3_value.
  3725. ** Every interface that accepts sqlite3_value arguments specifies
  3726. ** whether or not it requires a protected sqlite3_value. The
  3727. ** [sqlite3_value_dup()] interface can be used to construct a new
  3728. ** protected sqlite3_value from an unprotected sqlite3_value.
  3729. **
  3730. ** The terms "protected" and "unprotected" refer to whether or not
  3731. ** a mutex is held. An internal mutex is held for a protected
  3732. ** sqlite3_value object but no mutex is held for an unprotected
  3733. ** sqlite3_value object. If SQLite is compiled to be single-threaded
  3734. ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
  3735. ** or if SQLite is run in one of reduced mutex modes
  3736. ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
  3737. ** then there is no distinction between protected and unprotected
  3738. ** sqlite3_value objects and they can be used interchangeably. However,
  3739. ** for maximum code portability it is recommended that applications
  3740. ** still make the distinction between protected and unprotected
  3741. ** sqlite3_value objects even when not strictly required.
  3742. **
  3743. ** ^The sqlite3_value objects that are passed as parameters into the
  3744. ** implementation of [application-defined SQL functions] are protected.
  3745. ** ^The sqlite3_value object returned by
  3746. ** [sqlite3_column_value()] is unprotected.
  3747. ** Unprotected sqlite3_value objects may only be used as arguments
  3748. ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
  3749. ** [sqlite3_value_dup()].
  3750. ** The [sqlite3_value_blob | sqlite3_value_type()] family of
  3751. ** interfaces require protected sqlite3_value objects.
  3752. */
  3753. typedef struct sqlite3_value sqlite3_value;
  3754. /*
  3755. ** CAPI3REF: SQL Function Context Object
  3756. **
  3757. ** The context in which an SQL function executes is stored in an
  3758. ** sqlite3_context object. ^A pointer to an sqlite3_context object
  3759. ** is always first parameter to [application-defined SQL functions].
  3760. ** The application-defined SQL function implementation will pass this
  3761. ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
  3762. ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
  3763. ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
  3764. ** and/or [sqlite3_set_auxdata()].
  3765. */
  3766. typedef struct sqlite3_context sqlite3_context;
  3767. /*
  3768. ** CAPI3REF: Binding Values To Prepared Statements
  3769. ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
  3770. ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
  3771. ** METHOD: sqlite3_stmt
  3772. **
  3773. ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
  3774. ** literals may be replaced by a [parameter] that matches one of following
  3775. ** templates:
  3776. **
  3777. ** <ul>
  3778. ** <li> ?
  3779. ** <li> ?NNN
  3780. ** <li> :VVV
  3781. ** <li> @VVV
  3782. ** <li> $VVV
  3783. ** </ul>
  3784. **
  3785. ** In the templates above, NNN represents an integer literal,
  3786. ** and VVV represents an alphanumeric identifier.)^ ^The values of these
  3787. ** parameters (also called "host parameter names" or "SQL parameters")
  3788. ** can be set using the sqlite3_bind_*() routines defined here.
  3789. **
  3790. ** ^The first argument to the sqlite3_bind_*() routines is always
  3791. ** a pointer to the [sqlite3_stmt] object returned from
  3792. ** [sqlite3_prepare_v2()] or its variants.
  3793. **
  3794. ** ^The second argument is the index of the SQL parameter to be set.
  3795. ** ^The leftmost SQL parameter has an index of 1. ^When the same named
  3796. ** SQL parameter is used more than once, second and subsequent
  3797. ** occurrences have the same index as the first occurrence.
  3798. ** ^The index for named parameters can be looked up using the
  3799. ** [sqlite3_bind_parameter_index()] API if desired. ^The index
  3800. ** for "?NNN" parameters is the value of NNN.
  3801. ** ^The NNN value must be between 1 and the [sqlite3_limit()]
  3802. ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
  3803. **
  3804. ** ^The third argument is the value to bind to the parameter.
  3805. ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  3806. ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
  3807. ** is ignored and the end result is the same as sqlite3_bind_null().
  3808. **
  3809. ** ^(In those routines that have a fourth argument, its value is the
  3810. ** number of bytes in the parameter. To be clear: the value is the
  3811. ** number of <u>bytes</u> in the value, not the number of characters.)^
  3812. ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  3813. ** is negative, then the length of the string is
  3814. ** the number of bytes up to the first zero terminator.
  3815. ** If the fourth parameter to sqlite3_bind_blob() is negative, then
  3816. ** the behavior is undefined.
  3817. ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
  3818. ** or sqlite3_bind_text16() or sqlite3_bind_text64() then
  3819. ** that parameter must be the byte offset
  3820. ** where the NUL terminator would occur assuming the string were NUL
  3821. ** terminated. If any NUL characters occur at byte offsets less than
  3822. ** the value of the fourth parameter then the resulting string value will
  3823. ** contain embedded NULs. The result of expressions involving strings
  3824. ** with embedded NULs is undefined.
  3825. **
  3826. ** ^The fifth argument to the BLOB and string binding interfaces
  3827. ** is a destructor used to dispose of the BLOB or
  3828. ** string after SQLite has finished with it. ^The destructor is called
  3829. ** to dispose of the BLOB or string even if the call to bind API fails.
  3830. ** ^If the fifth argument is
  3831. ** the special value [SQLITE_STATIC], then SQLite assumes that the
  3832. ** information is in static, unmanaged space and does not need to be freed.
  3833. ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
  3834. ** SQLite makes its own private copy of the data immediately, before
  3835. ** the sqlite3_bind_*() routine returns.
  3836. **
  3837. ** ^The sixth argument to sqlite3_bind_text64() must be one of
  3838. ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
  3839. ** to specify the encoding of the text in the third parameter. If
  3840. ** the sixth argument to sqlite3_bind_text64() is not one of the
  3841. ** allowed values shown above, or if the text encoding is different
  3842. ** from the encoding specified by the sixth parameter, then the behavior
  3843. ** is undefined.
  3844. **
  3845. ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  3846. ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
  3847. ** (just an integer to hold its size) while it is being processed.
  3848. ** Zeroblobs are intended to serve as placeholders for BLOBs whose
  3849. ** content is later written using
  3850. ** [sqlite3_blob_open | incremental BLOB I/O] routines.
  3851. ** ^A negative value for the zeroblob results in a zero-length BLOB.
  3852. **
  3853. ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
  3854. ** [prepared statement] S to have an SQL value of NULL, but to also be
  3855. ** associated with the pointer P of type T. ^D is either a NULL pointer or
  3856. ** a pointer to a destructor function for P. ^SQLite will invoke the
  3857. ** destructor D with a single argument of P when it is finished using
  3858. ** P. The T parameter should be a static string, preferably a string
  3859. ** literal. The sqlite3_bind_pointer() routine is part of the
  3860. ** [pointer passing interface] added for SQLite 3.20.0.
  3861. **
  3862. ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
  3863. ** for the [prepared statement] or with a prepared statement for which
  3864. ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
  3865. ** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
  3866. ** routine is passed a [prepared statement] that has been finalized, the
  3867. ** result is undefined and probably harmful.
  3868. **
  3869. ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
  3870. ** ^Unbound parameters are interpreted as NULL.
  3871. **
  3872. ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
  3873. ** [error code] if anything goes wrong.
  3874. ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
  3875. ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
  3876. ** [SQLITE_MAX_LENGTH].
  3877. ** ^[SQLITE_RANGE] is returned if the parameter
  3878. ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
  3879. **
  3880. ** See also: [sqlite3_bind_parameter_count()],
  3881. ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
  3882. */
  3883. SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  3884. SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
  3885. void(*)(void*));
  3886. SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
  3887. SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
  3888. SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  3889. SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
  3890. SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
  3891. SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  3892. SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
  3893. void(*)(void*), unsigned char encoding);
  3894. SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  3895. SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
  3896. SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  3897. SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
  3898. /*
  3899. ** CAPI3REF: Number Of SQL Parameters
  3900. ** METHOD: sqlite3_stmt
  3901. **
  3902. ** ^This routine can be used to find the number of [SQL parameters]
  3903. ** in a [prepared statement]. SQL parameters are tokens of the
  3904. ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
  3905. ** placeholders for values that are [sqlite3_bind_blob | bound]
  3906. ** to the parameters at a later time.
  3907. **
  3908. ** ^(This routine actually returns the index of the largest (rightmost)
  3909. ** parameter. For all forms except ?NNN, this will correspond to the
  3910. ** number of unique parameters. If parameters of the ?NNN form are used,
  3911. ** there may be gaps in the list.)^
  3912. **
  3913. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3914. ** [sqlite3_bind_parameter_name()], and
  3915. ** [sqlite3_bind_parameter_index()].
  3916. */
  3917. SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
  3918. /*
  3919. ** CAPI3REF: Name Of A Host Parameter
  3920. ** METHOD: sqlite3_stmt
  3921. **
  3922. ** ^The sqlite3_bind_parameter_name(P,N) interface returns
  3923. ** the name of the N-th [SQL parameter] in the [prepared statement] P.
  3924. ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
  3925. ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
  3926. ** respectively.
  3927. ** In other words, the initial ":" or "$" or "@" or "?"
  3928. ** is included as part of the name.)^
  3929. ** ^Parameters of the form "?" without a following integer have no name
  3930. ** and are referred to as "nameless" or "anonymous parameters".
  3931. **
  3932. ** ^The first host parameter has an index of 1, not 0.
  3933. **
  3934. ** ^If the value N is out of range or if the N-th parameter is
  3935. ** nameless, then NULL is returned. ^The returned string is
  3936. ** always in UTF-8 encoding even if the named parameter was
  3937. ** originally specified as UTF-16 in [sqlite3_prepare16()],
  3938. ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  3939. **
  3940. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3941. ** [sqlite3_bind_parameter_count()], and
  3942. ** [sqlite3_bind_parameter_index()].
  3943. */
  3944. SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  3945. /*
  3946. ** CAPI3REF: Index Of A Parameter With A Given Name
  3947. ** METHOD: sqlite3_stmt
  3948. **
  3949. ** ^Return the index of an SQL parameter given its name. ^The
  3950. ** index value returned is suitable for use as the second
  3951. ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
  3952. ** is returned if no matching parameter is found. ^The parameter
  3953. ** name must be given in UTF-8 even if the original statement
  3954. ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
  3955. ** [sqlite3_prepare16_v3()].
  3956. **
  3957. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3958. ** [sqlite3_bind_parameter_count()], and
  3959. ** [sqlite3_bind_parameter_name()].
  3960. */
  3961. SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  3962. /*
  3963. ** CAPI3REF: Reset All Bindings On A Prepared Statement
  3964. ** METHOD: sqlite3_stmt
  3965. **
  3966. ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
  3967. ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
  3968. ** ^Use this routine to reset all host parameters to NULL.
  3969. */
  3970. SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
  3971. /*
  3972. ** CAPI3REF: Number Of Columns In A Result Set
  3973. ** METHOD: sqlite3_stmt
  3974. **
  3975. ** ^Return the number of columns in the result set returned by the
  3976. ** [prepared statement]. ^If this routine returns 0, that means the
  3977. ** [prepared statement] returns no data (for example an [UPDATE]).
  3978. ** ^However, just because this routine returns a positive number does not
  3979. ** mean that one or more rows of data will be returned. ^A SELECT statement
  3980. ** will always have a positive sqlite3_column_count() but depending on the
  3981. ** WHERE clause constraints and the table content, it might return no rows.
  3982. **
  3983. ** See also: [sqlite3_data_count()]
  3984. */
  3985. SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
  3986. /*
  3987. ** CAPI3REF: Column Names In A Result Set
  3988. ** METHOD: sqlite3_stmt
  3989. **
  3990. ** ^These routines return the name assigned to a particular column
  3991. ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
  3992. ** interface returns a pointer to a zero-terminated UTF-8 string
  3993. ** and sqlite3_column_name16() returns a pointer to a zero-terminated
  3994. ** UTF-16 string. ^The first parameter is the [prepared statement]
  3995. ** that implements the [SELECT] statement. ^The second parameter is the
  3996. ** column number. ^The leftmost column is number 0.
  3997. **
  3998. ** ^The returned string pointer is valid until either the [prepared statement]
  3999. ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
  4000. ** reprepared by the first call to [sqlite3_step()] for a particular run
  4001. ** or until the next call to
  4002. ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
  4003. **
  4004. ** ^If sqlite3_malloc() fails during the processing of either routine
  4005. ** (for example during a conversion from UTF-8 to UTF-16) then a
  4006. ** NULL pointer is returned.
  4007. **
  4008. ** ^The name of a result column is the value of the "AS" clause for
  4009. ** that column, if there is an AS clause. If there is no AS clause
  4010. ** then the name of the column is unspecified and may change from
  4011. ** one release of SQLite to the next.
  4012. */
  4013. SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
  4014. SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  4015. /*
  4016. ** CAPI3REF: Source Of Data In A Query Result
  4017. ** METHOD: sqlite3_stmt
  4018. **
  4019. ** ^These routines provide a means to determine the database, table, and
  4020. ** table column that is the origin of a particular result column in
  4021. ** [SELECT] statement.
  4022. ** ^The name of the database or table or column can be returned as
  4023. ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
  4024. ** the database name, the _table_ routines return the table name, and
  4025. ** the origin_ routines return the column name.
  4026. ** ^The returned string is valid until the [prepared statement] is destroyed
  4027. ** using [sqlite3_finalize()] or until the statement is automatically
  4028. ** reprepared by the first call to [sqlite3_step()] for a particular run
  4029. ** or until the same information is requested
  4030. ** again in a different encoding.
  4031. **
  4032. ** ^The names returned are the original un-aliased names of the
  4033. ** database, table, and column.
  4034. **
  4035. ** ^The first argument to these interfaces is a [prepared statement].
  4036. ** ^These functions return information about the Nth result column returned by
  4037. ** the statement, where N is the second function argument.
  4038. ** ^The left-most column is column 0 for these routines.
  4039. **
  4040. ** ^If the Nth column returned by the statement is an expression or
  4041. ** subquery and is not a column value, then all of these functions return
  4042. ** NULL. ^These routine might also return NULL if a memory allocation error
  4043. ** occurs. ^Otherwise, they return the name of the attached database, table,
  4044. ** or column that query result column was extracted from.
  4045. **
  4046. ** ^As with all other SQLite APIs, those whose names end with "16" return
  4047. ** UTF-16 encoded strings and the other functions return UTF-8.
  4048. **
  4049. ** ^These APIs are only available if the library was compiled with the
  4050. ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
  4051. **
  4052. ** If two or more threads call one or more of these routines against the same
  4053. ** prepared statement and column at the same time then the results are
  4054. ** undefined.
  4055. **
  4056. ** If two or more threads call one or more
  4057. ** [sqlite3_column_database_name | column metadata interfaces]
  4058. ** for the same [prepared statement] and result column
  4059. ** at the same time then the results are undefined.
  4060. */
  4061. SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  4062. SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  4063. SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  4064. SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  4065. SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  4066. SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  4067. /*
  4068. ** CAPI3REF: Declared Datatype Of A Query Result
  4069. ** METHOD: sqlite3_stmt
  4070. **
  4071. ** ^(The first parameter is a [prepared statement].
  4072. ** If this statement is a [SELECT] statement and the Nth column of the
  4073. ** returned result set of that [SELECT] is a table column (not an
  4074. ** expression or subquery) then the declared type of the table
  4075. ** column is returned.)^ ^If the Nth column of the result set is an
  4076. ** expression or subquery, then a NULL pointer is returned.
  4077. ** ^The returned string is always UTF-8 encoded.
  4078. **
  4079. ** ^(For example, given the database schema:
  4080. **
  4081. ** CREATE TABLE t1(c1 VARIANT);
  4082. **
  4083. ** and the following statement to be compiled:
  4084. **
  4085. ** SELECT c1 + 1, c1 FROM t1;
  4086. **
  4087. ** this routine would return the string "VARIANT" for the second result
  4088. ** column (i==1), and a NULL pointer for the first result column (i==0).)^
  4089. **
  4090. ** ^SQLite uses dynamic run-time typing. ^So just because a column
  4091. ** is declared to contain a particular type does not mean that the
  4092. ** data stored in that column is of the declared type. SQLite is
  4093. ** strongly typed, but the typing is dynamic not static. ^Type
  4094. ** is associated with individual values, not with the containers
  4095. ** used to hold those values.
  4096. */
  4097. SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  4098. SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  4099. /*
  4100. ** CAPI3REF: Evaluate An SQL Statement
  4101. ** METHOD: sqlite3_stmt
  4102. **
  4103. ** After a [prepared statement] has been prepared using any of
  4104. ** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
  4105. ** or [sqlite3_prepare16_v3()] or one of the legacy
  4106. ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
  4107. ** must be called one or more times to evaluate the statement.
  4108. **
  4109. ** The details of the behavior of the sqlite3_step() interface depend
  4110. ** on whether the statement was prepared using the newer "vX" interfaces
  4111. ** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
  4112. ** [sqlite3_prepare16_v2()] or the older legacy
  4113. ** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
  4114. ** new "vX" interface is recommended for new applications but the legacy
  4115. ** interface will continue to be supported.
  4116. **
  4117. ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
  4118. ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  4119. ** ^With the "v2" interface, any of the other [result codes] or
  4120. ** [extended result codes] might be returned as well.
  4121. **
  4122. ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
  4123. ** database locks it needs to do its job. ^If the statement is a [COMMIT]
  4124. ** or occurs outside of an explicit transaction, then you can retry the
  4125. ** statement. If the statement is not a [COMMIT] and occurs within an
  4126. ** explicit transaction then you should rollback the transaction before
  4127. ** continuing.
  4128. **
  4129. ** ^[SQLITE_DONE] means that the statement has finished executing
  4130. ** successfully. sqlite3_step() should not be called again on this virtual
  4131. ** machine without first calling [sqlite3_reset()] to reset the virtual
  4132. ** machine back to its initial state.
  4133. **
  4134. ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
  4135. ** is returned each time a new row of data is ready for processing by the
  4136. ** caller. The values may be accessed using the [column access functions].
  4137. ** sqlite3_step() is called again to retrieve the next row of data.
  4138. **
  4139. ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
  4140. ** violation) has occurred. sqlite3_step() should not be called again on
  4141. ** the VM. More information may be found by calling [sqlite3_errmsg()].
  4142. ** ^With the legacy interface, a more specific error code (for example,
  4143. ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  4144. ** can be obtained by calling [sqlite3_reset()] on the
  4145. ** [prepared statement]. ^In the "v2" interface,
  4146. ** the more specific error code is returned directly by sqlite3_step().
  4147. **
  4148. ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  4149. ** Perhaps it was called on a [prepared statement] that has
  4150. ** already been [sqlite3_finalize | finalized] or on one that had
  4151. ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
  4152. ** be the case that the same database connection is being used by two or
  4153. ** more threads at the same moment in time.
  4154. **
  4155. ** For all versions of SQLite up to and including 3.6.23.1, a call to
  4156. ** [sqlite3_reset()] was required after sqlite3_step() returned anything
  4157. ** other than [SQLITE_ROW] before any subsequent invocation of
  4158. ** sqlite3_step(). Failure to reset the prepared statement using
  4159. ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
  4160. ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
  4161. ** sqlite3_step() began
  4162. ** calling [sqlite3_reset()] automatically in this circumstance rather
  4163. ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
  4164. ** break because any application that ever receives an SQLITE_MISUSE error
  4165. ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
  4166. ** can be used to restore the legacy behavior.
  4167. **
  4168. ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
  4169. ** API always returns a generic error code, [SQLITE_ERROR], following any
  4170. ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
  4171. ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
  4172. ** specific [error codes] that better describes the error.
  4173. ** We admit that this is a goofy design. The problem has been fixed
  4174. ** with the "v2" interface. If you prepare all of your SQL statements
  4175. ** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
  4176. ** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
  4177. ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
  4178. ** then the more specific [error codes] are returned directly
  4179. ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
  4180. */
  4181. SQLITE_API int sqlite3_step(sqlite3_stmt*);
  4182. /*
  4183. ** CAPI3REF: Number of columns in a result set
  4184. ** METHOD: sqlite3_stmt
  4185. **
  4186. ** ^The sqlite3_data_count(P) interface returns the number of columns in the
  4187. ** current row of the result set of [prepared statement] P.
  4188. ** ^If prepared statement P does not have results ready to return
  4189. ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
  4190. ** interfaces) then sqlite3_data_count(P) returns 0.
  4191. ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
  4192. ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
  4193. ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
  4194. ** will return non-zero if previous call to [sqlite3_step](P) returned
  4195. ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
  4196. ** where it always returns zero since each step of that multi-step
  4197. ** pragma returns 0 columns of data.
  4198. **
  4199. ** See also: [sqlite3_column_count()]
  4200. */
  4201. SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
  4202. /*
  4203. ** CAPI3REF: Fundamental Datatypes
  4204. ** KEYWORDS: SQLITE_TEXT
  4205. **
  4206. ** ^(Every value in SQLite has one of five fundamental datatypes:
  4207. **
  4208. ** <ul>
  4209. ** <li> 64-bit signed integer
  4210. ** <li> 64-bit IEEE floating point number
  4211. ** <li> string
  4212. ** <li> BLOB
  4213. ** <li> NULL
  4214. ** </ul>)^
  4215. **
  4216. ** These constants are codes for each of those types.
  4217. **
  4218. ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
  4219. ** for a completely different meaning. Software that links against both
  4220. ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
  4221. ** SQLITE_TEXT.
  4222. */
  4223. #define SQLITE_INTEGER 1
  4224. #define SQLITE_FLOAT 2
  4225. #define SQLITE_BLOB 4
  4226. #define SQLITE_NULL 5
  4227. #ifdef SQLITE_TEXT
  4228. # undef SQLITE_TEXT
  4229. #else
  4230. # define SQLITE_TEXT 3
  4231. #endif
  4232. #define SQLITE3_TEXT 3
  4233. /*
  4234. ** CAPI3REF: Result Values From A Query
  4235. ** KEYWORDS: {column access functions}
  4236. ** METHOD: sqlite3_stmt
  4237. **
  4238. ** <b>Summary:</b>
  4239. ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
  4240. ** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
  4241. ** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
  4242. ** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
  4243. ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
  4244. ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
  4245. ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
  4246. ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
  4247. ** [sqlite3_value|unprotected sqlite3_value] object.
  4248. ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
  4249. ** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
  4250. ** or a UTF-8 TEXT result in bytes
  4251. ** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
  4252. ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
  4253. ** TEXT in bytes
  4254. ** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
  4255. ** datatype of the result
  4256. ** </table></blockquote>
  4257. **
  4258. ** <b>Details:</b>
  4259. **
  4260. ** ^These routines return information about a single column of the current
  4261. ** result row of a query. ^In every case the first argument is a pointer
  4262. ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  4263. ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  4264. ** and the second argument is the index of the column for which information
  4265. ** should be returned. ^The leftmost column of the result set has the index 0.
  4266. ** ^The number of columns in the result can be determined using
  4267. ** [sqlite3_column_count()].
  4268. **
  4269. ** If the SQL statement does not currently point to a valid row, or if the
  4270. ** column index is out of range, the result is undefined.
  4271. ** These routines may only be called when the most recent call to
  4272. ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
  4273. ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
  4274. ** If any of these routines are called after [sqlite3_reset()] or
  4275. ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  4276. ** something other than [SQLITE_ROW], the results are undefined.
  4277. ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  4278. ** are called from a different thread while any of these routines
  4279. ** are pending, then the results are undefined.
  4280. **
  4281. ** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
  4282. ** each return the value of a result column in a specific data format. If
  4283. ** the result column is not initially in the requested format (for example,
  4284. ** if the query returns an integer but the sqlite3_column_text() interface
  4285. ** is used to extract the value) then an automatic type conversion is performed.
  4286. **
  4287. ** ^The sqlite3_column_type() routine returns the
  4288. ** [SQLITE_INTEGER | datatype code] for the initial data type
  4289. ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
  4290. ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
  4291. ** The return value of sqlite3_column_type() can be used to decide which
  4292. ** of the first six interface should be used to extract the column value.
  4293. ** The value returned by sqlite3_column_type() is only meaningful if no
  4294. ** automatic type conversions have occurred for the value in question.
  4295. ** After a type conversion, the result of calling sqlite3_column_type()
  4296. ** is undefined, though harmless. Future
  4297. ** versions of SQLite may change the behavior of sqlite3_column_type()
  4298. ** following a type conversion.
  4299. **
  4300. ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
  4301. ** or sqlite3_column_bytes16() interfaces can be used to determine the size
  4302. ** of that BLOB or string.
  4303. **
  4304. ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
  4305. ** routine returns the number of bytes in that BLOB or string.
  4306. ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  4307. ** the string to UTF-8 and then returns the number of bytes.
  4308. ** ^If the result is a numeric value then sqlite3_column_bytes() uses
  4309. ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  4310. ** the number of bytes in that string.
  4311. ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
  4312. **
  4313. ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
  4314. ** routine returns the number of bytes in that BLOB or string.
  4315. ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
  4316. ** the string to UTF-16 and then returns the number of bytes.
  4317. ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
  4318. ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
  4319. ** the number of bytes in that string.
  4320. ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
  4321. **
  4322. ** ^The values returned by [sqlite3_column_bytes()] and
  4323. ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
  4324. ** of the string. ^For clarity: the values returned by
  4325. ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
  4326. ** bytes in the string, not the number of characters.
  4327. **
  4328. ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  4329. ** even empty strings, are always zero-terminated. ^The return
  4330. ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
  4331. **
  4332. ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
  4333. ** [unprotected sqlite3_value] object. In a multithreaded environment,
  4334. ** an unprotected sqlite3_value object may only be used safely with
  4335. ** [sqlite3_bind_value()] and [sqlite3_result_value()].
  4336. ** If the [unprotected sqlite3_value] object returned by
  4337. ** [sqlite3_column_value()] is used in any other way, including calls
  4338. ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  4339. ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
  4340. ** Hence, the sqlite3_column_value() interface
  4341. ** is normally only useful within the implementation of
  4342. ** [application-defined SQL functions] or [virtual tables], not within
  4343. ** top-level application code.
  4344. **
  4345. ** The these routines may attempt to convert the datatype of the result.
  4346. ** ^For example, if the internal representation is FLOAT and a text result
  4347. ** is requested, [sqlite3_snprintf()] is used internally to perform the
  4348. ** conversion automatically. ^(The following table details the conversions
  4349. ** that are applied:
  4350. **
  4351. ** <blockquote>
  4352. ** <table border="1">
  4353. ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
  4354. **
  4355. ** <tr><td> NULL <td> INTEGER <td> Result is 0
  4356. ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
  4357. ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
  4358. ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
  4359. ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
  4360. ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
  4361. ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
  4362. ** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
  4363. ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
  4364. ** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
  4365. ** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
  4366. ** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
  4367. ** <tr><td> TEXT <td> BLOB <td> No change
  4368. ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
  4369. ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
  4370. ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
  4371. ** </table>
  4372. ** </blockquote>)^
  4373. **
  4374. ** Note that when type conversions occur, pointers returned by prior
  4375. ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  4376. ** sqlite3_column_text16() may be invalidated.
  4377. ** Type conversions and pointer invalidations might occur
  4378. ** in the following cases:
  4379. **
  4380. ** <ul>
  4381. ** <li> The initial content is a BLOB and sqlite3_column_text() or
  4382. ** sqlite3_column_text16() is called. A zero-terminator might
  4383. ** need to be added to the string.</li>
  4384. ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
  4385. ** sqlite3_column_text16() is called. The content must be converted
  4386. ** to UTF-16.</li>
  4387. ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
  4388. ** sqlite3_column_text() is called. The content must be converted
  4389. ** to UTF-8.</li>
  4390. ** </ul>
  4391. **
  4392. ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
  4393. ** not invalidate a prior pointer, though of course the content of the buffer
  4394. ** that the prior pointer references will have been modified. Other kinds
  4395. ** of conversion are done in place when it is possible, but sometimes they
  4396. ** are not possible and in those cases prior pointers are invalidated.
  4397. **
  4398. ** The safest policy is to invoke these routines
  4399. ** in one of the following ways:
  4400. **
  4401. ** <ul>
  4402. ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  4403. ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  4404. ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  4405. ** </ul>
  4406. **
  4407. ** In other words, you should call sqlite3_column_text(),
  4408. ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
  4409. ** into the desired format, then invoke sqlite3_column_bytes() or
  4410. ** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
  4411. ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  4412. ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  4413. ** with calls to sqlite3_column_bytes().
  4414. **
  4415. ** ^The pointers returned are valid until a type conversion occurs as
  4416. ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  4417. ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
  4418. ** and BLOBs is freed automatically. Do not pass the pointers returned
  4419. ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  4420. ** [sqlite3_free()].
  4421. **
  4422. ** ^(If a memory allocation error occurs during the evaluation of any
  4423. ** of these routines, a default value is returned. The default value
  4424. ** is either the integer 0, the floating point number 0.0, or a NULL
  4425. ** pointer. Subsequent calls to [sqlite3_errcode()] will return
  4426. ** [SQLITE_NOMEM].)^
  4427. */
  4428. SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  4429. SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
  4430. SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
  4431. SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  4432. SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  4433. SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  4434. SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  4435. SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  4436. SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  4437. SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  4438. /*
  4439. ** CAPI3REF: Destroy A Prepared Statement Object
  4440. ** DESTRUCTOR: sqlite3_stmt
  4441. **
  4442. ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
  4443. ** ^If the most recent evaluation of the statement encountered no errors
  4444. ** or if the statement is never been evaluated, then sqlite3_finalize() returns
  4445. ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
  4446. ** sqlite3_finalize(S) returns the appropriate [error code] or
  4447. ** [extended error code].
  4448. **
  4449. ** ^The sqlite3_finalize(S) routine can be called at any point during
  4450. ** the life cycle of [prepared statement] S:
  4451. ** before statement S is ever evaluated, after
  4452. ** one or more calls to [sqlite3_reset()], or after any call
  4453. ** to [sqlite3_step()] regardless of whether or not the statement has
  4454. ** completed execution.
  4455. **
  4456. ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
  4457. **
  4458. ** The application must finalize every [prepared statement] in order to avoid
  4459. ** resource leaks. It is a grievous error for the application to try to use
  4460. ** a prepared statement after it has been finalized. Any use of a prepared
  4461. ** statement after it has been finalized can result in undefined and
  4462. ** undesirable behavior such as segfaults and heap corruption.
  4463. */
  4464. SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
  4465. /*
  4466. ** CAPI3REF: Reset A Prepared Statement Object
  4467. ** METHOD: sqlite3_stmt
  4468. **
  4469. ** The sqlite3_reset() function is called to reset a [prepared statement]
  4470. ** object back to its initial state, ready to be re-executed.
  4471. ** ^Any SQL statement variables that had values bound to them using
  4472. ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  4473. ** Use [sqlite3_clear_bindings()] to reset the bindings.
  4474. **
  4475. ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
  4476. ** back to the beginning of its program.
  4477. **
  4478. ** ^If the most recent call to [sqlite3_step(S)] for the
  4479. ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
  4480. ** or if [sqlite3_step(S)] has never before been called on S,
  4481. ** then [sqlite3_reset(S)] returns [SQLITE_OK].
  4482. **
  4483. ** ^If the most recent call to [sqlite3_step(S)] for the
  4484. ** [prepared statement] S indicated an error, then
  4485. ** [sqlite3_reset(S)] returns an appropriate [error code].
  4486. **
  4487. ** ^The [sqlite3_reset(S)] interface does not change the values
  4488. ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
  4489. */
  4490. SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
  4491. /*
  4492. ** CAPI3REF: Create Or Redefine SQL Functions
  4493. ** KEYWORDS: {function creation routines}
  4494. ** KEYWORDS: {application-defined SQL function}
  4495. ** KEYWORDS: {application-defined SQL functions}
  4496. ** METHOD: sqlite3
  4497. **
  4498. ** ^These functions (collectively known as "function creation routines")
  4499. ** are used to add SQL functions or aggregates or to redefine the behavior
  4500. ** of existing SQL functions or aggregates. The only differences between
  4501. ** these routines are the text encoding expected for
  4502. ** the second parameter (the name of the function being created)
  4503. ** and the presence or absence of a destructor callback for
  4504. ** the application data pointer.
  4505. **
  4506. ** ^The first parameter is the [database connection] to which the SQL
  4507. ** function is to be added. ^If an application uses more than one database
  4508. ** connection then application-defined SQL functions must be added
  4509. ** to each database connection separately.
  4510. **
  4511. ** ^The second parameter is the name of the SQL function to be created or
  4512. ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
  4513. ** representation, exclusive of the zero-terminator. ^Note that the name
  4514. ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
  4515. ** ^Any attempt to create a function with a longer name
  4516. ** will result in [SQLITE_MISUSE] being returned.
  4517. **
  4518. ** ^The third parameter (nArg)
  4519. ** is the number of arguments that the SQL function or
  4520. ** aggregate takes. ^If this parameter is -1, then the SQL function or
  4521. ** aggregate may take any number of arguments between 0 and the limit
  4522. ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
  4523. ** parameter is less than -1 or greater than 127 then the behavior is
  4524. ** undefined.
  4525. **
  4526. ** ^The fourth parameter, eTextRep, specifies what
  4527. ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  4528. ** its parameters. The application should set this parameter to
  4529. ** [SQLITE_UTF16LE] if the function implementation invokes
  4530. ** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
  4531. ** implementation invokes [sqlite3_value_text16be()] on an input, or
  4532. ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
  4533. ** otherwise. ^The same SQL function may be registered multiple times using
  4534. ** different preferred text encodings, with different implementations for
  4535. ** each encoding.
  4536. ** ^When multiple implementations of the same function are available, SQLite
  4537. ** will pick the one that involves the least amount of data conversion.
  4538. **
  4539. ** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
  4540. ** to signal that the function will always return the same result given
  4541. ** the same inputs within a single SQL statement. Most SQL functions are
  4542. ** deterministic. The built-in [random()] SQL function is an example of a
  4543. ** function that is not deterministic. The SQLite query planner is able to
  4544. ** perform additional optimizations on deterministic functions, so use
  4545. ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
  4546. **
  4547. ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
  4548. ** function can gain access to this pointer using [sqlite3_user_data()].)^
  4549. **
  4550. ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
  4551. ** pointers to C-language functions that implement the SQL function or
  4552. ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
  4553. ** callback only; NULL pointers must be passed as the xStep and xFinal
  4554. ** parameters. ^An aggregate SQL function requires an implementation of xStep
  4555. ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
  4556. ** SQL function or aggregate, pass NULL pointers for all three function
  4557. ** callbacks.
  4558. **
  4559. ** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
  4560. ** then it is destructor for the application data pointer.
  4561. ** The destructor is invoked when the function is deleted, either by being
  4562. ** overloaded or when the database connection closes.)^
  4563. ** ^The destructor is also invoked if the call to
  4564. ** sqlite3_create_function_v2() fails.
  4565. ** ^When the destructor callback of the tenth parameter is invoked, it
  4566. ** is passed a single argument which is a copy of the application data
  4567. ** pointer which was the fifth parameter to sqlite3_create_function_v2().
  4568. **
  4569. ** ^It is permitted to register multiple implementations of the same
  4570. ** functions with the same name but with either differing numbers of
  4571. ** arguments or differing preferred text encodings. ^SQLite will use
  4572. ** the implementation that most closely matches the way in which the
  4573. ** SQL function is used. ^A function implementation with a non-negative
  4574. ** nArg parameter is a better match than a function implementation with
  4575. ** a negative nArg. ^A function where the preferred text encoding
  4576. ** matches the database encoding is a better
  4577. ** match than a function where the encoding is different.
  4578. ** ^A function where the encoding difference is between UTF16le and UTF16be
  4579. ** is a closer match than a function where the encoding difference is
  4580. ** between UTF8 and UTF16.
  4581. **
  4582. ** ^Built-in functions may be overloaded by new application-defined functions.
  4583. **
  4584. ** ^An application-defined function is permitted to call other
  4585. ** SQLite interfaces. However, such calls must not
  4586. ** close the database connection nor finalize or reset the prepared
  4587. ** statement in which the function is running.
  4588. */
  4589. SQLITE_API int sqlite3_create_function(
  4590. sqlite3 *db,
  4591. const char *zFunctionName,
  4592. int nArg,
  4593. int eTextRep,
  4594. void *pApp,
  4595. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4596. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4597. void (*xFinal)(sqlite3_context*)
  4598. );
  4599. SQLITE_API int sqlite3_create_function16(
  4600. sqlite3 *db,
  4601. const void *zFunctionName,
  4602. int nArg,
  4603. int eTextRep,
  4604. void *pApp,
  4605. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4606. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4607. void (*xFinal)(sqlite3_context*)
  4608. );
  4609. SQLITE_API int sqlite3_create_function_v2(
  4610. sqlite3 *db,
  4611. const char *zFunctionName,
  4612. int nArg,
  4613. int eTextRep,
  4614. void *pApp,
  4615. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4616. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4617. void (*xFinal)(sqlite3_context*),
  4618. void(*xDestroy)(void*)
  4619. );
  4620. /*
  4621. ** CAPI3REF: Text Encodings
  4622. **
  4623. ** These constant define integer codes that represent the various
  4624. ** text encodings supported by SQLite.
  4625. */
  4626. #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
  4627. #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
  4628. #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
  4629. #define SQLITE_UTF16 4 /* Use native byte order */
  4630. #define SQLITE_ANY 5 /* Deprecated */
  4631. #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
  4632. /*
  4633. ** CAPI3REF: Function Flags
  4634. **
  4635. ** These constants may be ORed together with the
  4636. ** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
  4637. ** to [sqlite3_create_function()], [sqlite3_create_function16()], or
  4638. ** [sqlite3_create_function_v2()].
  4639. */
  4640. #define SQLITE_DETERMINISTIC 0x800
  4641. /*
  4642. ** CAPI3REF: Deprecated Functions
  4643. ** DEPRECATED
  4644. **
  4645. ** These functions are [deprecated]. In order to maintain
  4646. ** backwards compatibility with older code, these functions continue
  4647. ** to be supported. However, new applications should avoid
  4648. ** the use of these functions. To encourage programmers to avoid
  4649. ** these functions, we will not explain what they do.
  4650. */
  4651. #ifndef SQLITE_OMIT_DEPRECATED
  4652. SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
  4653. SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
  4654. SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  4655. SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
  4656. SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
  4657. SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
  4658. void*,sqlite3_int64);
  4659. #endif
  4660. /*
  4661. ** CAPI3REF: Obtaining SQL Values
  4662. ** METHOD: sqlite3_value
  4663. **
  4664. ** <b>Summary:</b>
  4665. ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
  4666. ** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
  4667. ** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
  4668. ** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
  4669. ** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
  4670. ** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
  4671. ** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
  4672. ** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
  4673. ** the native byteorder
  4674. ** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
  4675. ** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
  4676. ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
  4677. ** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
  4678. ** or a UTF-8 TEXT in bytes
  4679. ** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
  4680. ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
  4681. ** TEXT in bytes
  4682. ** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
  4683. ** datatype of the value
  4684. ** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
  4685. ** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
  4686. ** </table></blockquote>
  4687. **
  4688. ** <b>Details:</b>
  4689. **
  4690. ** These routines extract type, size, and content information from
  4691. ** [protected sqlite3_value] objects. Protected sqlite3_value objects
  4692. ** are used to pass parameter information into implementation of
  4693. ** [application-defined SQL functions] and [virtual tables].
  4694. **
  4695. ** These routines work only with [protected sqlite3_value] objects.
  4696. ** Any attempt to use these routines on an [unprotected sqlite3_value]
  4697. ** is not threadsafe.
  4698. **
  4699. ** ^These routines work just like the corresponding [column access functions]
  4700. ** except that these routines take a single [protected sqlite3_value] object
  4701. ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
  4702. **
  4703. ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
  4704. ** in the native byte-order of the host machine. ^The
  4705. ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  4706. ** extract UTF-16 strings as big-endian and little-endian respectively.
  4707. **
  4708. ** ^If [sqlite3_value] object V was initialized
  4709. ** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
  4710. ** and if X and Y are strings that compare equal according to strcmp(X,Y),
  4711. ** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,
  4712. ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
  4713. ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
  4714. **
  4715. ** ^(The sqlite3_value_type(V) interface returns the
  4716. ** [SQLITE_INTEGER | datatype code] for the initial datatype of the
  4717. ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
  4718. ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
  4719. ** Other interfaces might change the datatype for an sqlite3_value object.
  4720. ** For example, if the datatype is initially SQLITE_INTEGER and
  4721. ** sqlite3_value_text(V) is called to extract a text value for that
  4722. ** integer, then subsequent calls to sqlite3_value_type(V) might return
  4723. ** SQLITE_TEXT. Whether or not a persistent internal datatype conversion
  4724. ** occurs is undefined and may change from one release of SQLite to the next.
  4725. **
  4726. ** ^(The sqlite3_value_numeric_type() interface attempts to apply
  4727. ** numeric affinity to the value. This means that an attempt is
  4728. ** made to convert the value to an integer or floating point. If
  4729. ** such a conversion is possible without loss of information (in other
  4730. ** words, if the value is a string that looks like a number)
  4731. ** then the conversion is performed. Otherwise no conversion occurs.
  4732. ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
  4733. **
  4734. ** Please pay particular attention to the fact that the pointer returned
  4735. ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  4736. ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  4737. ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  4738. ** or [sqlite3_value_text16()].
  4739. **
  4740. ** These routines must be called from the same thread as
  4741. ** the SQL function that supplied the [sqlite3_value*] parameters.
  4742. */
  4743. SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
  4744. SQLITE_API double sqlite3_value_double(sqlite3_value*);
  4745. SQLITE_API int sqlite3_value_int(sqlite3_value*);
  4746. SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
  4747. SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
  4748. SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
  4749. SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
  4750. SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
  4751. SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
  4752. SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
  4753. SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  4754. SQLITE_API int sqlite3_value_type(sqlite3_value*);
  4755. SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
  4756. /*
  4757. ** CAPI3REF: Finding The Subtype Of SQL Values
  4758. ** METHOD: sqlite3_value
  4759. **
  4760. ** The sqlite3_value_subtype(V) function returns the subtype for
  4761. ** an [application-defined SQL function] argument V. The subtype
  4762. ** information can be used to pass a limited amount of context from
  4763. ** one SQL function to another. Use the [sqlite3_result_subtype()]
  4764. ** routine to set the subtype for the return value of an SQL function.
  4765. */
  4766. SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
  4767. /*
  4768. ** CAPI3REF: Copy And Free SQL Values
  4769. ** METHOD: sqlite3_value
  4770. **
  4771. ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
  4772. ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
  4773. ** is a [protected sqlite3_value] object even if the input is not.
  4774. ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
  4775. ** memory allocation fails.
  4776. **
  4777. ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
  4778. ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
  4779. ** then sqlite3_value_free(V) is a harmless no-op.
  4780. */
  4781. SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
  4782. SQLITE_API void sqlite3_value_free(sqlite3_value*);
  4783. /*
  4784. ** CAPI3REF: Obtain Aggregate Function Context
  4785. ** METHOD: sqlite3_context
  4786. **
  4787. ** Implementations of aggregate SQL functions use this
  4788. ** routine to allocate memory for storing their state.
  4789. **
  4790. ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
  4791. ** for a particular aggregate function, SQLite
  4792. ** allocates N of memory, zeroes out that memory, and returns a pointer
  4793. ** to the new memory. ^On second and subsequent calls to
  4794. ** sqlite3_aggregate_context() for the same aggregate function instance,
  4795. ** the same buffer is returned. Sqlite3_aggregate_context() is normally
  4796. ** called once for each invocation of the xStep callback and then one
  4797. ** last time when the xFinal callback is invoked. ^(When no rows match
  4798. ** an aggregate query, the xStep() callback of the aggregate function
  4799. ** implementation is never called and xFinal() is called exactly once.
  4800. ** In those cases, sqlite3_aggregate_context() might be called for the
  4801. ** first time from within xFinal().)^
  4802. **
  4803. ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
  4804. ** when first called if N is less than or equal to zero or if a memory
  4805. ** allocate error occurs.
  4806. **
  4807. ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
  4808. ** determined by the N parameter on first successful call. Changing the
  4809. ** value of N in subsequent call to sqlite3_aggregate_context() within
  4810. ** the same aggregate function instance will not resize the memory
  4811. ** allocation.)^ Within the xFinal callback, it is customary to set
  4812. ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
  4813. ** pointless memory allocations occur.
  4814. **
  4815. ** ^SQLite automatically frees the memory allocated by
  4816. ** sqlite3_aggregate_context() when the aggregate query concludes.
  4817. **
  4818. ** The first parameter must be a copy of the
  4819. ** [sqlite3_context | SQL function context] that is the first parameter
  4820. ** to the xStep or xFinal callback routine that implements the aggregate
  4821. ** function.
  4822. **
  4823. ** This routine must be called from the same thread in which
  4824. ** the aggregate SQL function is running.
  4825. */
  4826. SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
  4827. /*
  4828. ** CAPI3REF: User Data For Functions
  4829. ** METHOD: sqlite3_context
  4830. **
  4831. ** ^The sqlite3_user_data() interface returns a copy of
  4832. ** the pointer that was the pUserData parameter (the 5th parameter)
  4833. ** of the [sqlite3_create_function()]
  4834. ** and [sqlite3_create_function16()] routines that originally
  4835. ** registered the application defined function.
  4836. **
  4837. ** This routine must be called from the same thread in which
  4838. ** the application-defined function is running.
  4839. */
  4840. SQLITE_API void *sqlite3_user_data(sqlite3_context*);
  4841. /*
  4842. ** CAPI3REF: Database Connection For Functions
  4843. ** METHOD: sqlite3_context
  4844. **
  4845. ** ^The sqlite3_context_db_handle() interface returns a copy of
  4846. ** the pointer to the [database connection] (the 1st parameter)
  4847. ** of the [sqlite3_create_function()]
  4848. ** and [sqlite3_create_function16()] routines that originally
  4849. ** registered the application defined function.
  4850. */
  4851. SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
  4852. /*
  4853. ** CAPI3REF: Function Auxiliary Data
  4854. ** METHOD: sqlite3_context
  4855. **
  4856. ** These functions may be used by (non-aggregate) SQL functions to
  4857. ** associate metadata with argument values. If the same value is passed to
  4858. ** multiple invocations of the same SQL function during query execution, under
  4859. ** some circumstances the associated metadata may be preserved. An example
  4860. ** of where this might be useful is in a regular-expression matching
  4861. ** function. The compiled version of the regular expression can be stored as
  4862. ** metadata associated with the pattern string.
  4863. ** Then as long as the pattern string remains the same,
  4864. ** the compiled regular expression can be reused on multiple
  4865. ** invocations of the same function.
  4866. **
  4867. ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
  4868. ** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
  4869. ** value to the application-defined function. ^N is zero for the left-most
  4870. ** function argument. ^If there is no metadata
  4871. ** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
  4872. ** returns a NULL pointer.
  4873. **
  4874. ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
  4875. ** argument of the application-defined function. ^Subsequent
  4876. ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
  4877. ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
  4878. ** NULL if the metadata has been discarded.
  4879. ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
  4880. ** SQLite will invoke the destructor function X with parameter P exactly
  4881. ** once, when the metadata is discarded.
  4882. ** SQLite is free to discard the metadata at any time, including: <ul>
  4883. ** <li> ^(when the corresponding function parameter changes)^, or
  4884. ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
  4885. ** SQL statement)^, or
  4886. ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
  4887. ** parameter)^, or
  4888. ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
  4889. ** allocation error occurs.)^ </ul>
  4890. **
  4891. ** Note the last bullet in particular. The destructor X in
  4892. ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
  4893. ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
  4894. ** should be called near the end of the function implementation and the
  4895. ** function implementation should not make any use of P after
  4896. ** sqlite3_set_auxdata() has been called.
  4897. **
  4898. ** ^(In practice, metadata is preserved between function calls for
  4899. ** function parameters that are compile-time constants, including literal
  4900. ** values and [parameters] and expressions composed from the same.)^
  4901. **
  4902. ** The value of the N parameter to these interfaces should be non-negative.
  4903. ** Future enhancements may make use of negative N values to define new
  4904. ** kinds of function caching behavior.
  4905. **
  4906. ** These routines must be called from the same thread in which
  4907. ** the SQL function is running.
  4908. */
  4909. SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
  4910. SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  4911. /*
  4912. ** CAPI3REF: Constants Defining Special Destructor Behavior
  4913. **
  4914. ** These are special values for the destructor that is passed in as the
  4915. ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
  4916. ** argument is SQLITE_STATIC, it means that the content pointer is constant
  4917. ** and will never change. It does not need to be destroyed. ^The
  4918. ** SQLITE_TRANSIENT value means that the content will likely change in
  4919. ** the near future and that SQLite should make its own private copy of
  4920. ** the content before returning.
  4921. **
  4922. ** The typedef is necessary to work around problems in certain
  4923. ** C++ compilers.
  4924. */
  4925. typedef void (*sqlite3_destructor_type)(void*);
  4926. #define SQLITE_STATIC ((sqlite3_destructor_type)0)
  4927. #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
  4928. /*
  4929. ** CAPI3REF: Setting The Result Of An SQL Function
  4930. ** METHOD: sqlite3_context
  4931. **
  4932. ** These routines are used by the xFunc or xFinal callbacks that
  4933. ** implement SQL functions and aggregates. See
  4934. ** [sqlite3_create_function()] and [sqlite3_create_function16()]
  4935. ** for additional information.
  4936. **
  4937. ** These functions work very much like the [parameter binding] family of
  4938. ** functions used to bind values to host parameters in prepared statements.
  4939. ** Refer to the [SQL parameter] documentation for additional information.
  4940. **
  4941. ** ^The sqlite3_result_blob() interface sets the result from
  4942. ** an application-defined function to be the BLOB whose content is pointed
  4943. ** to by the second parameter and which is N bytes long where N is the
  4944. ** third parameter.
  4945. **
  4946. ** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
  4947. ** interfaces set the result of the application-defined function to be
  4948. ** a BLOB containing all zero bytes and N bytes in size.
  4949. **
  4950. ** ^The sqlite3_result_double() interface sets the result from
  4951. ** an application-defined function to be a floating point value specified
  4952. ** by its 2nd argument.
  4953. **
  4954. ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
  4955. ** cause the implemented SQL function to throw an exception.
  4956. ** ^SQLite uses the string pointed to by the
  4957. ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
  4958. ** as the text of an error message. ^SQLite interprets the error
  4959. ** message string from sqlite3_result_error() as UTF-8. ^SQLite
  4960. ** interprets the string from sqlite3_result_error16() as UTF-16 in native
  4961. ** byte order. ^If the third parameter to sqlite3_result_error()
  4962. ** or sqlite3_result_error16() is negative then SQLite takes as the error
  4963. ** message all text up through the first zero character.
  4964. ** ^If the third parameter to sqlite3_result_error() or
  4965. ** sqlite3_result_error16() is non-negative then SQLite takes that many
  4966. ** bytes (not characters) from the 2nd parameter as the error message.
  4967. ** ^The sqlite3_result_error() and sqlite3_result_error16()
  4968. ** routines make a private copy of the error message text before
  4969. ** they return. Hence, the calling function can deallocate or
  4970. ** modify the text after they return without harm.
  4971. ** ^The sqlite3_result_error_code() function changes the error code
  4972. ** returned by SQLite as a result of an error in a function. ^By default,
  4973. ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
  4974. ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
  4975. **
  4976. ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
  4977. ** error indicating that a string or BLOB is too long to represent.
  4978. **
  4979. ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
  4980. ** error indicating that a memory allocation failed.
  4981. **
  4982. ** ^The sqlite3_result_int() interface sets the return value
  4983. ** of the application-defined function to be the 32-bit signed integer
  4984. ** value given in the 2nd argument.
  4985. ** ^The sqlite3_result_int64() interface sets the return value
  4986. ** of the application-defined function to be the 64-bit signed integer
  4987. ** value given in the 2nd argument.
  4988. **
  4989. ** ^The sqlite3_result_null() interface sets the return value
  4990. ** of the application-defined function to be NULL.
  4991. **
  4992. ** ^The sqlite3_result_text(), sqlite3_result_text16(),
  4993. ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
  4994. ** set the return value of the application-defined function to be
  4995. ** a text string which is represented as UTF-8, UTF-16 native byte order,
  4996. ** UTF-16 little endian, or UTF-16 big endian, respectively.
  4997. ** ^The sqlite3_result_text64() interface sets the return value of an
  4998. ** application-defined function to be a text string in an encoding
  4999. ** specified by the fifth (and last) parameter, which must be one
  5000. ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
  5001. ** ^SQLite takes the text result from the application from
  5002. ** the 2nd parameter of the sqlite3_result_text* interfaces.
  5003. ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  5004. ** is negative, then SQLite takes result text from the 2nd parameter
  5005. ** through the first zero character.
  5006. ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  5007. ** is non-negative, then as many bytes (not characters) of the text
  5008. ** pointed to by the 2nd parameter are taken as the application-defined
  5009. ** function result. If the 3rd parameter is non-negative, then it
  5010. ** must be the byte offset into the string where the NUL terminator would
  5011. ** appear if the string where NUL terminated. If any NUL characters occur
  5012. ** in the string at a byte offset that is less than the value of the 3rd
  5013. ** parameter, then the resulting string will contain embedded NULs and the
  5014. ** result of expressions operating on strings with embedded NULs is undefined.
  5015. ** ^If the 4th parameter to the sqlite3_result_text* interfaces
  5016. ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
  5017. ** function as the destructor on the text or BLOB result when it has
  5018. ** finished using that result.
  5019. ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
  5020. ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
  5021. ** assumes that the text or BLOB result is in constant space and does not
  5022. ** copy the content of the parameter nor call a destructor on the content
  5023. ** when it has finished using that result.
  5024. ** ^If the 4th parameter to the sqlite3_result_text* interfaces
  5025. ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  5026. ** then SQLite makes a copy of the result into space obtained
  5027. ** from [sqlite3_malloc()] before it returns.
  5028. **
  5029. ** ^The sqlite3_result_value() interface sets the result of
  5030. ** the application-defined function to be a copy of the
  5031. ** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
  5032. ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  5033. ** so that the [sqlite3_value] specified in the parameter may change or
  5034. ** be deallocated after sqlite3_result_value() returns without harm.
  5035. ** ^A [protected sqlite3_value] object may always be used where an
  5036. ** [unprotected sqlite3_value] object is required, so either
  5037. ** kind of [sqlite3_value] object can be used with this interface.
  5038. **
  5039. ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
  5040. ** SQL NULL value, just like [sqlite3_result_null(C)], except that it
  5041. ** also associates the host-language pointer P or type T with that
  5042. ** NULL value such that the pointer can be retrieved within an
  5043. ** [application-defined SQL function] using [sqlite3_value_pointer()].
  5044. ** ^If the D parameter is not NULL, then it is a pointer to a destructor
  5045. ** for the P parameter. ^SQLite invokes D with P as its only argument
  5046. ** when SQLite is finished with P. The T parameter should be a static
  5047. ** string and preferably a string literal. The sqlite3_result_pointer()
  5048. ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
  5049. **
  5050. ** If these routines are called from within the different thread
  5051. ** than the one containing the application-defined function that received
  5052. ** the [sqlite3_context] pointer, the results are undefined.
  5053. */
  5054. SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  5055. SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
  5056. sqlite3_uint64,void(*)(void*));
  5057. SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
  5058. SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
  5059. SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
  5060. SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
  5061. SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
  5062. SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
  5063. SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
  5064. SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
  5065. SQLITE_API void sqlite3_result_null(sqlite3_context*);
  5066. SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
  5067. SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
  5068. void(*)(void*), unsigned char encoding);
  5069. SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  5070. SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  5071. SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  5072. SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  5073. SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
  5074. SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
  5075. SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
  5076. /*
  5077. ** CAPI3REF: Setting The Subtype Of An SQL Function
  5078. ** METHOD: sqlite3_context
  5079. **
  5080. ** The sqlite3_result_subtype(C,T) function causes the subtype of
  5081. ** the result from the [application-defined SQL function] with
  5082. ** [sqlite3_context] C to be the value T. Only the lower 8 bits
  5083. ** of the subtype T are preserved in current versions of SQLite;
  5084. ** higher order bits are discarded.
  5085. ** The number of subtype bytes preserved by SQLite might increase
  5086. ** in future releases of SQLite.
  5087. */
  5088. SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
  5089. /*
  5090. ** CAPI3REF: Define New Collating Sequences
  5091. ** METHOD: sqlite3
  5092. **
  5093. ** ^These functions add, remove, or modify a [collation] associated
  5094. ** with the [database connection] specified as the first argument.
  5095. **
  5096. ** ^The name of the collation is a UTF-8 string
  5097. ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  5098. ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
  5099. ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
  5100. ** considered to be the same name.
  5101. **
  5102. ** ^(The third argument (eTextRep) must be one of the constants:
  5103. ** <ul>
  5104. ** <li> [SQLITE_UTF8],
  5105. ** <li> [SQLITE_UTF16LE],
  5106. ** <li> [SQLITE_UTF16BE],
  5107. ** <li> [SQLITE_UTF16], or
  5108. ** <li> [SQLITE_UTF16_ALIGNED].
  5109. ** </ul>)^
  5110. ** ^The eTextRep argument determines the encoding of strings passed
  5111. ** to the collating function callback, xCallback.
  5112. ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
  5113. ** force strings to be UTF16 with native byte order.
  5114. ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
  5115. ** on an even byte address.
  5116. **
  5117. ** ^The fourth argument, pArg, is an application data pointer that is passed
  5118. ** through as the first argument to the collating function callback.
  5119. **
  5120. ** ^The fifth argument, xCallback, is a pointer to the collating function.
  5121. ** ^Multiple collating functions can be registered using the same name but
  5122. ** with different eTextRep parameters and SQLite will use whichever
  5123. ** function requires the least amount of data transformation.
  5124. ** ^If the xCallback argument is NULL then the collating function is
  5125. ** deleted. ^When all collating functions having the same name are deleted,
  5126. ** that collation is no longer usable.
  5127. **
  5128. ** ^The collating function callback is invoked with a copy of the pArg
  5129. ** application data pointer and with two strings in the encoding specified
  5130. ** by the eTextRep argument. The collating function must return an
  5131. ** integer that is negative, zero, or positive
  5132. ** if the first string is less than, equal to, or greater than the second,
  5133. ** respectively. A collating function must always return the same answer
  5134. ** given the same inputs. If two or more collating functions are registered
  5135. ** to the same collation name (using different eTextRep values) then all
  5136. ** must give an equivalent answer when invoked with equivalent strings.
  5137. ** The collating function must obey the following properties for all
  5138. ** strings A, B, and C:
  5139. **
  5140. ** <ol>
  5141. ** <li> If A==B then B==A.
  5142. ** <li> If A==B and B==C then A==C.
  5143. ** <li> If A&lt;B THEN B&gt;A.
  5144. ** <li> If A&lt;B and B&lt;C then A&lt;C.
  5145. ** </ol>
  5146. **
  5147. ** If a collating function fails any of the above constraints and that
  5148. ** collating function is registered and used, then the behavior of SQLite
  5149. ** is undefined.
  5150. **
  5151. ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  5152. ** with the addition that the xDestroy callback is invoked on pArg when
  5153. ** the collating function is deleted.
  5154. ** ^Collating functions are deleted when they are overridden by later
  5155. ** calls to the collation creation functions or when the
  5156. ** [database connection] is closed using [sqlite3_close()].
  5157. **
  5158. ** ^The xDestroy callback is <u>not</u> called if the
  5159. ** sqlite3_create_collation_v2() function fails. Applications that invoke
  5160. ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
  5161. ** check the return code and dispose of the application data pointer
  5162. ** themselves rather than expecting SQLite to deal with it for them.
  5163. ** This is different from every other SQLite interface. The inconsistency
  5164. ** is unfortunate but cannot be changed without breaking backwards
  5165. ** compatibility.
  5166. **
  5167. ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
  5168. */
  5169. SQLITE_API int sqlite3_create_collation(
  5170. sqlite3*,
  5171. const char *zName,
  5172. int eTextRep,
  5173. void *pArg,
  5174. int(*xCompare)(void*,int,const void*,int,const void*)
  5175. );
  5176. SQLITE_API int sqlite3_create_collation_v2(
  5177. sqlite3*,
  5178. const char *zName,
  5179. int eTextRep,
  5180. void *pArg,
  5181. int(*xCompare)(void*,int,const void*,int,const void*),
  5182. void(*xDestroy)(void*)
  5183. );
  5184. SQLITE_API int sqlite3_create_collation16(
  5185. sqlite3*,
  5186. const void *zName,
  5187. int eTextRep,
  5188. void *pArg,
  5189. int(*xCompare)(void*,int,const void*,int,const void*)
  5190. );
  5191. /*
  5192. ** CAPI3REF: Collation Needed Callbacks
  5193. ** METHOD: sqlite3
  5194. **
  5195. ** ^To avoid having to register all collation sequences before a database
  5196. ** can be used, a single callback function may be registered with the
  5197. ** [database connection] to be invoked whenever an undefined collation
  5198. ** sequence is required.
  5199. **
  5200. ** ^If the function is registered using the sqlite3_collation_needed() API,
  5201. ** then it is passed the names of undefined collation sequences as strings
  5202. ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
  5203. ** the names are passed as UTF-16 in machine native byte order.
  5204. ** ^A call to either function replaces the existing collation-needed callback.
  5205. **
  5206. ** ^(When the callback is invoked, the first argument passed is a copy
  5207. ** of the second argument to sqlite3_collation_needed() or
  5208. ** sqlite3_collation_needed16(). The second argument is the database
  5209. ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
  5210. ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
  5211. ** sequence function required. The fourth parameter is the name of the
  5212. ** required collation sequence.)^
  5213. **
  5214. ** The callback function should register the desired collation using
  5215. ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
  5216. ** [sqlite3_create_collation_v2()].
  5217. */
  5218. SQLITE_API int sqlite3_collation_needed(
  5219. sqlite3*,
  5220. void*,
  5221. void(*)(void*,sqlite3*,int eTextRep,const char*)
  5222. );
  5223. SQLITE_API int sqlite3_collation_needed16(
  5224. sqlite3*,
  5225. void*,
  5226. void(*)(void*,sqlite3*,int eTextRep,const void*)
  5227. );
  5228. #ifdef SQLITE_HAS_CODEC
  5229. /*
  5230. ** Specify the key for an encrypted database. This routine should be
  5231. ** called right after sqlite3_open().
  5232. **
  5233. ** The code to implement this API is not available in the public release
  5234. ** of SQLite.
  5235. */
  5236. SQLITE_API int sqlite3_key(
  5237. sqlite3 *db, /* Database to be rekeyed */
  5238. const void *pKey, int nKey /* The key */
  5239. );
  5240. SQLITE_API int sqlite3_key_v2(
  5241. sqlite3 *db, /* Database to be rekeyed */
  5242. const char *zDbName, /* Name of the database */
  5243. const void *pKey, int nKey /* The key */
  5244. );
  5245. /*
  5246. ** Change the key on an open database. If the current database is not
  5247. ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
  5248. ** database is decrypted.
  5249. **
  5250. ** The code to implement this API is not available in the public release
  5251. ** of SQLite.
  5252. */
  5253. SQLITE_API int sqlite3_rekey(
  5254. sqlite3 *db, /* Database to be rekeyed */
  5255. const void *pKey, int nKey /* The new key */
  5256. );
  5257. SQLITE_API int sqlite3_rekey_v2(
  5258. sqlite3 *db, /* Database to be rekeyed */
  5259. const char *zDbName, /* Name of the database */
  5260. const void *pKey, int nKey /* The new key */
  5261. );
  5262. /*
  5263. ** Specify the activation key for a SEE database. Unless
  5264. ** activated, none of the SEE routines will work.
  5265. */
  5266. SQLITE_API void sqlite3_activate_see(
  5267. const char *zPassPhrase /* Activation phrase */
  5268. );
  5269. #endif
  5270. #ifdef SQLITE_ENABLE_CEROD
  5271. /*
  5272. ** Specify the activation key for a CEROD database. Unless
  5273. ** activated, none of the CEROD routines will work.
  5274. */
  5275. SQLITE_API void sqlite3_activate_cerod(
  5276. const char *zPassPhrase /* Activation phrase */
  5277. );
  5278. #endif
  5279. /*
  5280. ** CAPI3REF: Suspend Execution For A Short Time
  5281. **
  5282. ** The sqlite3_sleep() function causes the current thread to suspend execution
  5283. ** for at least a number of milliseconds specified in its parameter.
  5284. **
  5285. ** If the operating system does not support sleep requests with
  5286. ** millisecond time resolution, then the time will be rounded up to
  5287. ** the nearest second. The number of milliseconds of sleep actually
  5288. ** requested from the operating system is returned.
  5289. **
  5290. ** ^SQLite implements this interface by calling the xSleep()
  5291. ** method of the default [sqlite3_vfs] object. If the xSleep() method
  5292. ** of the default VFS is not implemented correctly, or not implemented at
  5293. ** all, then the behavior of sqlite3_sleep() may deviate from the description
  5294. ** in the previous paragraphs.
  5295. */
  5296. SQLITE_API int sqlite3_sleep(int);
  5297. /*
  5298. ** CAPI3REF: Name Of The Folder Holding Temporary Files
  5299. **
  5300. ** ^(If this global variable is made to point to a string which is
  5301. ** the name of a folder (a.k.a. directory), then all temporary files
  5302. ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
  5303. ** will be placed in that directory.)^ ^If this variable
  5304. ** is a NULL pointer, then SQLite performs a search for an appropriate
  5305. ** temporary file directory.
  5306. **
  5307. ** Applications are strongly discouraged from using this global variable.
  5308. ** It is required to set a temporary folder on Windows Runtime (WinRT).
  5309. ** But for all other platforms, it is highly recommended that applications
  5310. ** neither read nor write this variable. This global variable is a relic
  5311. ** that exists for backwards compatibility of legacy applications and should
  5312. ** be avoided in new projects.
  5313. **
  5314. ** It is not safe to read or modify this variable in more than one
  5315. ** thread at a time. It is not safe to read or modify this variable
  5316. ** if a [database connection] is being used at the same time in a separate
  5317. ** thread.
  5318. ** It is intended that this variable be set once
  5319. ** as part of process initialization and before any SQLite interface
  5320. ** routines have been called and that this variable remain unchanged
  5321. ** thereafter.
  5322. **
  5323. ** ^The [temp_store_directory pragma] may modify this variable and cause
  5324. ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
  5325. ** the [temp_store_directory pragma] always assumes that any string
  5326. ** that this variable points to is held in memory obtained from
  5327. ** [sqlite3_malloc] and the pragma may attempt to free that memory
  5328. ** using [sqlite3_free].
  5329. ** Hence, if this variable is modified directly, either it should be
  5330. ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  5331. ** or else the use of the [temp_store_directory pragma] should be avoided.
  5332. ** Except when requested by the [temp_store_directory pragma], SQLite
  5333. ** does not free the memory that sqlite3_temp_directory points to. If
  5334. ** the application wants that memory to be freed, it must do
  5335. ** so itself, taking care to only do so after all [database connection]
  5336. ** objects have been destroyed.
  5337. **
  5338. ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
  5339. ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
  5340. ** features that require the use of temporary files may fail. Here is an
  5341. ** example of how to do this using C++ with the Windows Runtime:
  5342. **
  5343. ** <blockquote><pre>
  5344. ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
  5345. ** &nbsp; TemporaryFolder->Path->Data();
  5346. ** char zPathBuf&#91;MAX_PATH + 1&#93;;
  5347. ** memset(zPathBuf, 0, sizeof(zPathBuf));
  5348. ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
  5349. ** &nbsp; NULL, NULL);
  5350. ** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
  5351. ** </pre></blockquote>
  5352. */
  5353. SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
  5354. /*
  5355. ** CAPI3REF: Name Of The Folder Holding Database Files
  5356. **
  5357. ** ^(If this global variable is made to point to a string which is
  5358. ** the name of a folder (a.k.a. directory), then all database files
  5359. ** specified with a relative pathname and created or accessed by
  5360. ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
  5361. ** to be relative to that directory.)^ ^If this variable is a NULL
  5362. ** pointer, then SQLite assumes that all database files specified
  5363. ** with a relative pathname are relative to the current directory
  5364. ** for the process. Only the windows VFS makes use of this global
  5365. ** variable; it is ignored by the unix VFS.
  5366. **
  5367. ** Changing the value of this variable while a database connection is
  5368. ** open can result in a corrupt database.
  5369. **
  5370. ** It is not safe to read or modify this variable in more than one
  5371. ** thread at a time. It is not safe to read or modify this variable
  5372. ** if a [database connection] is being used at the same time in a separate
  5373. ** thread.
  5374. ** It is intended that this variable be set once
  5375. ** as part of process initialization and before any SQLite interface
  5376. ** routines have been called and that this variable remain unchanged
  5377. ** thereafter.
  5378. **
  5379. ** ^The [data_store_directory pragma] may modify this variable and cause
  5380. ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
  5381. ** the [data_store_directory pragma] always assumes that any string
  5382. ** that this variable points to is held in memory obtained from
  5383. ** [sqlite3_malloc] and the pragma may attempt to free that memory
  5384. ** using [sqlite3_free].
  5385. ** Hence, if this variable is modified directly, either it should be
  5386. ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  5387. ** or else the use of the [data_store_directory pragma] should be avoided.
  5388. */
  5389. SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
  5390. /*
  5391. ** CAPI3REF: Test For Auto-Commit Mode
  5392. ** KEYWORDS: {autocommit mode}
  5393. ** METHOD: sqlite3
  5394. **
  5395. ** ^The sqlite3_get_autocommit() interface returns non-zero or
  5396. ** zero if the given database connection is or is not in autocommit mode,
  5397. ** respectively. ^Autocommit mode is on by default.
  5398. ** ^Autocommit mode is disabled by a [BEGIN] statement.
  5399. ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
  5400. **
  5401. ** If certain kinds of errors occur on a statement within a multi-statement
  5402. ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
  5403. ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  5404. ** transaction might be rolled back automatically. The only way to
  5405. ** find out whether SQLite automatically rolled back the transaction after
  5406. ** an error is to use this function.
  5407. **
  5408. ** If another thread changes the autocommit status of the database
  5409. ** connection while this routine is running, then the return value
  5410. ** is undefined.
  5411. */
  5412. SQLITE_API int sqlite3_get_autocommit(sqlite3*);
  5413. /*
  5414. ** CAPI3REF: Find The Database Handle Of A Prepared Statement
  5415. ** METHOD: sqlite3_stmt
  5416. **
  5417. ** ^The sqlite3_db_handle interface returns the [database connection] handle
  5418. ** to which a [prepared statement] belongs. ^The [database connection]
  5419. ** returned by sqlite3_db_handle is the same [database connection]
  5420. ** that was the first argument
  5421. ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
  5422. ** create the statement in the first place.
  5423. */
  5424. SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  5425. /*
  5426. ** CAPI3REF: Return The Filename For A Database Connection
  5427. ** METHOD: sqlite3
  5428. **
  5429. ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
  5430. ** associated with database N of connection D. ^The main database file
  5431. ** has the name "main". If there is no attached database N on the database
  5432. ** connection D, or if database N is a temporary or in-memory database, then
  5433. ** a NULL pointer is returned.
  5434. **
  5435. ** ^The filename returned by this function is the output of the
  5436. ** xFullPathname method of the [VFS]. ^In other words, the filename
  5437. ** will be an absolute pathname, even if the filename used
  5438. ** to open the database originally was a URI or relative pathname.
  5439. */
  5440. SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
  5441. /*
  5442. ** CAPI3REF: Determine if a database is read-only
  5443. ** METHOD: sqlite3
  5444. **
  5445. ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
  5446. ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
  5447. ** the name of a database on connection D.
  5448. */
  5449. SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
  5450. /*
  5451. ** CAPI3REF: Find the next prepared statement
  5452. ** METHOD: sqlite3
  5453. **
  5454. ** ^This interface returns a pointer to the next [prepared statement] after
  5455. ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
  5456. ** then this interface returns a pointer to the first prepared statement
  5457. ** associated with the database connection pDb. ^If no prepared statement
  5458. ** satisfies the conditions of this routine, it returns NULL.
  5459. **
  5460. ** The [database connection] pointer D in a call to
  5461. ** [sqlite3_next_stmt(D,S)] must refer to an open database
  5462. ** connection and in particular must not be a NULL pointer.
  5463. */
  5464. SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
  5465. /*
  5466. ** CAPI3REF: Commit And Rollback Notification Callbacks
  5467. ** METHOD: sqlite3
  5468. **
  5469. ** ^The sqlite3_commit_hook() interface registers a callback
  5470. ** function to be invoked whenever a transaction is [COMMIT | committed].
  5471. ** ^Any callback set by a previous call to sqlite3_commit_hook()
  5472. ** for the same database connection is overridden.
  5473. ** ^The sqlite3_rollback_hook() interface registers a callback
  5474. ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
  5475. ** ^Any callback set by a previous call to sqlite3_rollback_hook()
  5476. ** for the same database connection is overridden.
  5477. ** ^The pArg argument is passed through to the callback.
  5478. ** ^If the callback on a commit hook function returns non-zero,
  5479. ** then the commit is converted into a rollback.
  5480. **
  5481. ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
  5482. ** return the P argument from the previous call of the same function
  5483. ** on the same [database connection] D, or NULL for
  5484. ** the first call for each function on D.
  5485. **
  5486. ** The commit and rollback hook callbacks are not reentrant.
  5487. ** The callback implementation must not do anything that will modify
  5488. ** the database connection that invoked the callback. Any actions
  5489. ** to modify the database connection must be deferred until after the
  5490. ** completion of the [sqlite3_step()] call that triggered the commit
  5491. ** or rollback hook in the first place.
  5492. ** Note that running any other SQL statements, including SELECT statements,
  5493. ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
  5494. ** the database connections for the meaning of "modify" in this paragraph.
  5495. **
  5496. ** ^Registering a NULL function disables the callback.
  5497. **
  5498. ** ^When the commit hook callback routine returns zero, the [COMMIT]
  5499. ** operation is allowed to continue normally. ^If the commit hook
  5500. ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
  5501. ** ^The rollback hook is invoked on a rollback that results from a commit
  5502. ** hook returning non-zero, just as it would be with any other rollback.
  5503. **
  5504. ** ^For the purposes of this API, a transaction is said to have been
  5505. ** rolled back if an explicit "ROLLBACK" statement is executed, or
  5506. ** an error or constraint causes an implicit rollback to occur.
  5507. ** ^The rollback callback is not invoked if a transaction is
  5508. ** automatically rolled back because the database connection is closed.
  5509. **
  5510. ** See also the [sqlite3_update_hook()] interface.
  5511. */
  5512. SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
  5513. SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
  5514. /*
  5515. ** CAPI3REF: Data Change Notification Callbacks
  5516. ** METHOD: sqlite3
  5517. **
  5518. ** ^The sqlite3_update_hook() interface registers a callback function
  5519. ** with the [database connection] identified by the first argument
  5520. ** to be invoked whenever a row is updated, inserted or deleted in
  5521. ** a [rowid table].
  5522. ** ^Any callback set by a previous call to this function
  5523. ** for the same database connection is overridden.
  5524. **
  5525. ** ^The second argument is a pointer to the function to invoke when a
  5526. ** row is updated, inserted or deleted in a rowid table.
  5527. ** ^The first argument to the callback is a copy of the third argument
  5528. ** to sqlite3_update_hook().
  5529. ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
  5530. ** or [SQLITE_UPDATE], depending on the operation that caused the callback
  5531. ** to be invoked.
  5532. ** ^The third and fourth arguments to the callback contain pointers to the
  5533. ** database and table name containing the affected row.
  5534. ** ^The final callback parameter is the [rowid] of the row.
  5535. ** ^In the case of an update, this is the [rowid] after the update takes place.
  5536. **
  5537. ** ^(The update hook is not invoked when internal system tables are
  5538. ** modified (i.e. sqlite_master and sqlite_sequence).)^
  5539. ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
  5540. **
  5541. ** ^In the current implementation, the update hook
  5542. ** is not invoked when conflicting rows are deleted because of an
  5543. ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
  5544. ** invoked when rows are deleted using the [truncate optimization].
  5545. ** The exceptions defined in this paragraph might change in a future
  5546. ** release of SQLite.
  5547. **
  5548. ** The update hook implementation must not do anything that will modify
  5549. ** the database connection that invoked the update hook. Any actions
  5550. ** to modify the database connection must be deferred until after the
  5551. ** completion of the [sqlite3_step()] call that triggered the update hook.
  5552. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  5553. ** database connections for the meaning of "modify" in this paragraph.
  5554. **
  5555. ** ^The sqlite3_update_hook(D,C,P) function
  5556. ** returns the P argument from the previous call
  5557. ** on the same [database connection] D, or NULL for
  5558. ** the first call on D.
  5559. **
  5560. ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
  5561. ** and [sqlite3_preupdate_hook()] interfaces.
  5562. */
  5563. SQLITE_API void *sqlite3_update_hook(
  5564. sqlite3*,
  5565. void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  5566. void*
  5567. );
  5568. /*
  5569. ** CAPI3REF: Enable Or Disable Shared Pager Cache
  5570. **
  5571. ** ^(This routine enables or disables the sharing of the database cache
  5572. ** and schema data structures between [database connection | connections]
  5573. ** to the same database. Sharing is enabled if the argument is true
  5574. ** and disabled if the argument is false.)^
  5575. **
  5576. ** ^Cache sharing is enabled and disabled for an entire process.
  5577. ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
  5578. ** In prior versions of SQLite,
  5579. ** sharing was enabled or disabled for each thread separately.
  5580. **
  5581. ** ^(The cache sharing mode set by this interface effects all subsequent
  5582. ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
  5583. ** Existing database connections continue use the sharing mode
  5584. ** that was in effect at the time they were opened.)^
  5585. **
  5586. ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
  5587. ** successfully. An [error code] is returned otherwise.)^
  5588. **
  5589. ** ^Shared cache is disabled by default. But this might change in
  5590. ** future releases of SQLite. Applications that care about shared
  5591. ** cache setting should set it explicitly.
  5592. **
  5593. ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
  5594. ** and will always return SQLITE_MISUSE. On those systems,
  5595. ** shared cache mode should be enabled per-database connection via
  5596. ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
  5597. **
  5598. ** This interface is threadsafe on processors where writing a
  5599. ** 32-bit integer is atomic.
  5600. **
  5601. ** See Also: [SQLite Shared-Cache Mode]
  5602. */
  5603. SQLITE_API int sqlite3_enable_shared_cache(int);
  5604. /*
  5605. ** CAPI3REF: Attempt To Free Heap Memory
  5606. **
  5607. ** ^The sqlite3_release_memory() interface attempts to free N bytes
  5608. ** of heap memory by deallocating non-essential memory allocations
  5609. ** held by the database library. Memory used to cache database
  5610. ** pages to improve performance is an example of non-essential memory.
  5611. ** ^sqlite3_release_memory() returns the number of bytes actually freed,
  5612. ** which might be more or less than the amount requested.
  5613. ** ^The sqlite3_release_memory() routine is a no-op returning zero
  5614. ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
  5615. **
  5616. ** See also: [sqlite3_db_release_memory()]
  5617. */
  5618. SQLITE_API int sqlite3_release_memory(int);
  5619. /*
  5620. ** CAPI3REF: Free Memory Used By A Database Connection
  5621. ** METHOD: sqlite3
  5622. **
  5623. ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
  5624. ** memory as possible from database connection D. Unlike the
  5625. ** [sqlite3_release_memory()] interface, this interface is in effect even
  5626. ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
  5627. ** omitted.
  5628. **
  5629. ** See also: [sqlite3_release_memory()]
  5630. */
  5631. SQLITE_API int sqlite3_db_release_memory(sqlite3*);
  5632. /*
  5633. ** CAPI3REF: Impose A Limit On Heap Size
  5634. **
  5635. ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
  5636. ** soft limit on the amount of heap memory that may be allocated by SQLite.
  5637. ** ^SQLite strives to keep heap memory utilization below the soft heap
  5638. ** limit by reducing the number of pages held in the page cache
  5639. ** as heap memory usages approaches the limit.
  5640. ** ^The soft heap limit is "soft" because even though SQLite strives to stay
  5641. ** below the limit, it will exceed the limit rather than generate
  5642. ** an [SQLITE_NOMEM] error. In other words, the soft heap limit
  5643. ** is advisory only.
  5644. **
  5645. ** ^The return value from sqlite3_soft_heap_limit64() is the size of
  5646. ** the soft heap limit prior to the call, or negative in the case of an
  5647. ** error. ^If the argument N is negative
  5648. ** then no change is made to the soft heap limit. Hence, the current
  5649. ** size of the soft heap limit can be determined by invoking
  5650. ** sqlite3_soft_heap_limit64() with a negative argument.
  5651. **
  5652. ** ^If the argument N is zero then the soft heap limit is disabled.
  5653. **
  5654. ** ^(The soft heap limit is not enforced in the current implementation
  5655. ** if one or more of following conditions are true:
  5656. **
  5657. ** <ul>
  5658. ** <li> The soft heap limit is set to zero.
  5659. ** <li> Memory accounting is disabled using a combination of the
  5660. ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
  5661. ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
  5662. ** <li> An alternative page cache implementation is specified using
  5663. ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
  5664. ** <li> The page cache allocates from its own memory pool supplied
  5665. ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
  5666. ** from the heap.
  5667. ** </ul>)^
  5668. **
  5669. ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
  5670. ** the soft heap limit is enforced
  5671. ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
  5672. ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
  5673. ** the soft heap limit is enforced on every memory allocation. Without
  5674. ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
  5675. ** when memory is allocated by the page cache. Testing suggests that because
  5676. ** the page cache is the predominate memory user in SQLite, most
  5677. ** applications will achieve adequate soft heap limit enforcement without
  5678. ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
  5679. **
  5680. ** The circumstances under which SQLite will enforce the soft heap limit may
  5681. ** changes in future releases of SQLite.
  5682. */
  5683. SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
  5684. /*
  5685. ** CAPI3REF: Deprecated Soft Heap Limit Interface
  5686. ** DEPRECATED
  5687. **
  5688. ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
  5689. ** interface. This routine is provided for historical compatibility
  5690. ** only. All new applications should use the
  5691. ** [sqlite3_soft_heap_limit64()] interface rather than this one.
  5692. */
  5693. SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
  5694. /*
  5695. ** CAPI3REF: Extract Metadata About A Column Of A Table
  5696. ** METHOD: sqlite3
  5697. **
  5698. ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
  5699. ** information about column C of table T in database D
  5700. ** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
  5701. ** interface returns SQLITE_OK and fills in the non-NULL pointers in
  5702. ** the final five arguments with appropriate values if the specified
  5703. ** column exists. ^The sqlite3_table_column_metadata() interface returns
  5704. ** SQLITE_ERROR and if the specified column does not exist.
  5705. ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
  5706. ** NULL pointer, then this routine simply checks for the existence of the
  5707. ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
  5708. ** does not. If the table name parameter T in a call to
  5709. ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
  5710. ** undefined behavior.
  5711. **
  5712. ** ^The column is identified by the second, third and fourth parameters to
  5713. ** this function. ^(The second parameter is either the name of the database
  5714. ** (i.e. "main", "temp", or an attached database) containing the specified
  5715. ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
  5716. ** for the table using the same algorithm used by the database engine to
  5717. ** resolve unqualified table references.
  5718. **
  5719. ** ^The third and fourth parameters to this function are the table and column
  5720. ** name of the desired column, respectively.
  5721. **
  5722. ** ^Metadata is returned by writing to the memory locations passed as the 5th
  5723. ** and subsequent parameters to this function. ^Any of these arguments may be
  5724. ** NULL, in which case the corresponding element of metadata is omitted.
  5725. **
  5726. ** ^(<blockquote>
  5727. ** <table border="1">
  5728. ** <tr><th> Parameter <th> Output<br>Type <th> Description
  5729. **
  5730. ** <tr><td> 5th <td> const char* <td> Data type
  5731. ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
  5732. ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
  5733. ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
  5734. ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
  5735. ** </table>
  5736. ** </blockquote>)^
  5737. **
  5738. ** ^The memory pointed to by the character pointers returned for the
  5739. ** declaration type and collation sequence is valid until the next
  5740. ** call to any SQLite API function.
  5741. **
  5742. ** ^If the specified table is actually a view, an [error code] is returned.
  5743. **
  5744. ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
  5745. ** is not a [WITHOUT ROWID] table and an
  5746. ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
  5747. ** parameters are set for the explicitly declared column. ^(If there is no
  5748. ** [INTEGER PRIMARY KEY] column, then the outputs
  5749. ** for the [rowid] are set as follows:
  5750. **
  5751. ** <pre>
  5752. ** data type: "INTEGER"
  5753. ** collation sequence: "BINARY"
  5754. ** not null: 0
  5755. ** primary key: 1
  5756. ** auto increment: 0
  5757. ** </pre>)^
  5758. **
  5759. ** ^This function causes all database schemas to be read from disk and
  5760. ** parsed, if that has not already been done, and returns an error if
  5761. ** any errors are encountered while loading the schema.
  5762. */
  5763. SQLITE_API int sqlite3_table_column_metadata(
  5764. sqlite3 *db, /* Connection handle */
  5765. const char *zDbName, /* Database name or NULL */
  5766. const char *zTableName, /* Table name */
  5767. const char *zColumnName, /* Column name */
  5768. char const **pzDataType, /* OUTPUT: Declared data type */
  5769. char const **pzCollSeq, /* OUTPUT: Collation sequence name */
  5770. int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
  5771. int *pPrimaryKey, /* OUTPUT: True if column part of PK */
  5772. int *pAutoinc /* OUTPUT: True if column is auto-increment */
  5773. );
  5774. /*
  5775. ** CAPI3REF: Load An Extension
  5776. ** METHOD: sqlite3
  5777. **
  5778. ** ^This interface loads an SQLite extension library from the named file.
  5779. **
  5780. ** ^The sqlite3_load_extension() interface attempts to load an
  5781. ** [SQLite extension] library contained in the file zFile. If
  5782. ** the file cannot be loaded directly, attempts are made to load
  5783. ** with various operating-system specific extensions added.
  5784. ** So for example, if "samplelib" cannot be loaded, then names like
  5785. ** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
  5786. ** be tried also.
  5787. **
  5788. ** ^The entry point is zProc.
  5789. ** ^(zProc may be 0, in which case SQLite will try to come up with an
  5790. ** entry point name on its own. It first tries "sqlite3_extension_init".
  5791. ** If that does not work, it constructs a name "sqlite3_X_init" where the
  5792. ** X is consists of the lower-case equivalent of all ASCII alphabetic
  5793. ** characters in the filename from the last "/" to the first following
  5794. ** "." and omitting any initial "lib".)^
  5795. ** ^The sqlite3_load_extension() interface returns
  5796. ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
  5797. ** ^If an error occurs and pzErrMsg is not 0, then the
  5798. ** [sqlite3_load_extension()] interface shall attempt to
  5799. ** fill *pzErrMsg with error message text stored in memory
  5800. ** obtained from [sqlite3_malloc()]. The calling function
  5801. ** should free this memory by calling [sqlite3_free()].
  5802. **
  5803. ** ^Extension loading must be enabled using
  5804. ** [sqlite3_enable_load_extension()] or
  5805. ** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
  5806. ** prior to calling this API,
  5807. ** otherwise an error will be returned.
  5808. **
  5809. ** <b>Security warning:</b> It is recommended that the
  5810. ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
  5811. ** interface. The use of the [sqlite3_enable_load_extension()] interface
  5812. ** should be avoided. This will keep the SQL function [load_extension()]
  5813. ** disabled and prevent SQL injections from giving attackers
  5814. ** access to extension loading capabilities.
  5815. **
  5816. ** See also the [load_extension() SQL function].
  5817. */
  5818. SQLITE_API int sqlite3_load_extension(
  5819. sqlite3 *db, /* Load the extension into this database connection */
  5820. const char *zFile, /* Name of the shared library containing extension */
  5821. const char *zProc, /* Entry point. Derived from zFile if 0 */
  5822. char **pzErrMsg /* Put error message here if not 0 */
  5823. );
  5824. /*
  5825. ** CAPI3REF: Enable Or Disable Extension Loading
  5826. ** METHOD: sqlite3
  5827. **
  5828. ** ^So as not to open security holes in older applications that are
  5829. ** unprepared to deal with [extension loading], and as a means of disabling
  5830. ** [extension loading] while evaluating user-entered SQL, the following API
  5831. ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
  5832. **
  5833. ** ^Extension loading is off by default.
  5834. ** ^Call the sqlite3_enable_load_extension() routine with onoff==1
  5835. ** to turn extension loading on and call it with onoff==0 to turn
  5836. ** it back off again.
  5837. **
  5838. ** ^This interface enables or disables both the C-API
  5839. ** [sqlite3_load_extension()] and the SQL function [load_extension()].
  5840. ** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)
  5841. ** to enable or disable only the C-API.)^
  5842. **
  5843. ** <b>Security warning:</b> It is recommended that extension loading
  5844. ** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method
  5845. ** rather than this interface, so the [load_extension()] SQL function
  5846. ** remains disabled. This will prevent SQL injections from giving attackers
  5847. ** access to extension loading capabilities.
  5848. */
  5849. SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
  5850. /*
  5851. ** CAPI3REF: Automatically Load Statically Linked Extensions
  5852. **
  5853. ** ^This interface causes the xEntryPoint() function to be invoked for
  5854. ** each new [database connection] that is created. The idea here is that
  5855. ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
  5856. ** that is to be automatically loaded into all new database connections.
  5857. **
  5858. ** ^(Even though the function prototype shows that xEntryPoint() takes
  5859. ** no arguments and returns void, SQLite invokes xEntryPoint() with three
  5860. ** arguments and expects an integer result as if the signature of the
  5861. ** entry point where as follows:
  5862. **
  5863. ** <blockquote><pre>
  5864. ** &nbsp; int xEntryPoint(
  5865. ** &nbsp; sqlite3 *db,
  5866. ** &nbsp; const char **pzErrMsg,
  5867. ** &nbsp; const struct sqlite3_api_routines *pThunk
  5868. ** &nbsp; );
  5869. ** </pre></blockquote>)^
  5870. **
  5871. ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
  5872. ** point to an appropriate error message (obtained from [sqlite3_mprintf()])
  5873. ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
  5874. ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
  5875. ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
  5876. ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
  5877. ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
  5878. **
  5879. ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
  5880. ** on the list of automatic extensions is a harmless no-op. ^No entry point
  5881. ** will be called more than once for each database connection that is opened.
  5882. **
  5883. ** See also: [sqlite3_reset_auto_extension()]
  5884. ** and [sqlite3_cancel_auto_extension()]
  5885. */
  5886. SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
  5887. /*
  5888. ** CAPI3REF: Cancel Automatic Extension Loading
  5889. **
  5890. ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
  5891. ** initialization routine X that was registered using a prior call to
  5892. ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)]
  5893. ** routine returns 1 if initialization routine X was successfully
  5894. ** unregistered and it returns 0 if X was not on the list of initialization
  5895. ** routines.
  5896. */
  5897. SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
  5898. /*
  5899. ** CAPI3REF: Reset Automatic Extension Loading
  5900. **
  5901. ** ^This interface disables all automatic extensions previously
  5902. ** registered using [sqlite3_auto_extension()].
  5903. */
  5904. SQLITE_API void sqlite3_reset_auto_extension(void);
  5905. /*
  5906. ** The interface to the virtual-table mechanism is currently considered
  5907. ** to be experimental. The interface might change in incompatible ways.
  5908. ** If this is a problem for you, do not use the interface at this time.
  5909. **
  5910. ** When the virtual-table mechanism stabilizes, we will declare the
  5911. ** interface fixed, support it indefinitely, and remove this comment.
  5912. */
  5913. /*
  5914. ** Structures used by the virtual table interface
  5915. */
  5916. typedef struct sqlite3_vtab sqlite3_vtab;
  5917. typedef struct sqlite3_index_info sqlite3_index_info;
  5918. typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
  5919. typedef struct sqlite3_module sqlite3_module;
  5920. /*
  5921. ** CAPI3REF: Virtual Table Object
  5922. ** KEYWORDS: sqlite3_module {virtual table module}
  5923. **
  5924. ** This structure, sometimes called a "virtual table module",
  5925. ** defines the implementation of a [virtual tables].
  5926. ** This structure consists mostly of methods for the module.
  5927. **
  5928. ** ^A virtual table module is created by filling in a persistent
  5929. ** instance of this structure and passing a pointer to that instance
  5930. ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
  5931. ** ^The registration remains valid until it is replaced by a different
  5932. ** module or until the [database connection] closes. The content
  5933. ** of this structure must not change while it is registered with
  5934. ** any database connection.
  5935. */
  5936. struct sqlite3_module {
  5937. int iVersion;
  5938. int (*xCreate)(sqlite3*, void *pAux,
  5939. int argc, const char *const*argv,
  5940. sqlite3_vtab **ppVTab, char**);
  5941. int (*xConnect)(sqlite3*, void *pAux,
  5942. int argc, const char *const*argv,
  5943. sqlite3_vtab **ppVTab, char**);
  5944. int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  5945. int (*xDisconnect)(sqlite3_vtab *pVTab);
  5946. int (*xDestroy)(sqlite3_vtab *pVTab);
  5947. int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  5948. int (*xClose)(sqlite3_vtab_cursor*);
  5949. int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
  5950. int argc, sqlite3_value **argv);
  5951. int (*xNext)(sqlite3_vtab_cursor*);
  5952. int (*xEof)(sqlite3_vtab_cursor*);
  5953. int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  5954. int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  5955. int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  5956. int (*xBegin)(sqlite3_vtab *pVTab);
  5957. int (*xSync)(sqlite3_vtab *pVTab);
  5958. int (*xCommit)(sqlite3_vtab *pVTab);
  5959. int (*xRollback)(sqlite3_vtab *pVTab);
  5960. int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
  5961. void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
  5962. void **ppArg);
  5963. int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  5964. /* The methods above are in version 1 of the sqlite_module object. Those
  5965. ** below are for version 2 and greater. */
  5966. int (*xSavepoint)(sqlite3_vtab *pVTab, int);
  5967. int (*xRelease)(sqlite3_vtab *pVTab, int);
  5968. int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
  5969. };
  5970. /*
  5971. ** CAPI3REF: Virtual Table Indexing Information
  5972. ** KEYWORDS: sqlite3_index_info
  5973. **
  5974. ** The sqlite3_index_info structure and its substructures is used as part
  5975. ** of the [virtual table] interface to
  5976. ** pass information into and receive the reply from the [xBestIndex]
  5977. ** method of a [virtual table module]. The fields under **Inputs** are the
  5978. ** inputs to xBestIndex and are read-only. xBestIndex inserts its
  5979. ** results into the **Outputs** fields.
  5980. **
  5981. ** ^(The aConstraint[] array records WHERE clause constraints of the form:
  5982. **
  5983. ** <blockquote>column OP expr</blockquote>
  5984. **
  5985. ** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^ ^(The particular operator is
  5986. ** stored in aConstraint[].op using one of the
  5987. ** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
  5988. ** ^(The index of the column is stored in
  5989. ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
  5990. ** expr on the right-hand side can be evaluated (and thus the constraint
  5991. ** is usable) and false if it cannot.)^
  5992. **
  5993. ** ^The optimizer automatically inverts terms of the form "expr OP column"
  5994. ** and makes other simplifications to the WHERE clause in an attempt to
  5995. ** get as many WHERE clause terms into the form shown above as possible.
  5996. ** ^The aConstraint[] array only reports WHERE clause terms that are
  5997. ** relevant to the particular virtual table being queried.
  5998. **
  5999. ** ^Information about the ORDER BY clause is stored in aOrderBy[].
  6000. ** ^Each term of aOrderBy records a column of the ORDER BY clause.
  6001. **
  6002. ** The colUsed field indicates which columns of the virtual table may be
  6003. ** required by the current scan. Virtual table columns are numbered from
  6004. ** zero in the order in which they appear within the CREATE TABLE statement
  6005. ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
  6006. ** the corresponding bit is set within the colUsed mask if the column may be
  6007. ** required by SQLite. If the table has at least 64 columns and any column
  6008. ** to the right of the first 63 is required, then bit 63 of colUsed is also
  6009. ** set. In other words, column iCol may be required if the expression
  6010. ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
  6011. ** non-zero.
  6012. **
  6013. ** The [xBestIndex] method must fill aConstraintUsage[] with information
  6014. ** about what parameters to pass to xFilter. ^If argvIndex>0 then
  6015. ** the right-hand side of the corresponding aConstraint[] is evaluated
  6016. ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
  6017. ** is true, then the constraint is assumed to be fully handled by the
  6018. ** virtual table and is not checked again by SQLite.)^
  6019. **
  6020. ** ^The idxNum and idxPtr values are recorded and passed into the
  6021. ** [xFilter] method.
  6022. ** ^[sqlite3_free()] is used to free idxPtr if and only if
  6023. ** needToFreeIdxPtr is true.
  6024. **
  6025. ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
  6026. ** the correct order to satisfy the ORDER BY clause so that no separate
  6027. ** sorting step is required.
  6028. **
  6029. ** ^The estimatedCost value is an estimate of the cost of a particular
  6030. ** strategy. A cost of N indicates that the cost of the strategy is similar
  6031. ** to a linear scan of an SQLite table with N rows. A cost of log(N)
  6032. ** indicates that the expense of the operation is similar to that of a
  6033. ** binary search on a unique indexed field of an SQLite table with N rows.
  6034. **
  6035. ** ^The estimatedRows value is an estimate of the number of rows that
  6036. ** will be returned by the strategy.
  6037. **
  6038. ** The xBestIndex method may optionally populate the idxFlags field with a
  6039. ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
  6040. ** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
  6041. ** assumes that the strategy may visit at most one row.
  6042. **
  6043. ** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
  6044. ** SQLite also assumes that if a call to the xUpdate() method is made as
  6045. ** part of the same statement to delete or update a virtual table row and the
  6046. ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
  6047. ** any database changes. In other words, if the xUpdate() returns
  6048. ** SQLITE_CONSTRAINT, the database contents must be exactly as they were
  6049. ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
  6050. ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
  6051. ** the xUpdate method are automatically rolled back by SQLite.
  6052. **
  6053. ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
  6054. ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
  6055. ** If a virtual table extension is
  6056. ** used with an SQLite version earlier than 3.8.2, the results of attempting
  6057. ** to read or write the estimatedRows field are undefined (but are likely
  6058. ** to included crashing the application). The estimatedRows field should
  6059. ** therefore only be used if [sqlite3_libversion_number()] returns a
  6060. ** value greater than or equal to 3008002. Similarly, the idxFlags field
  6061. ** was added for [version 3.9.0] ([dateof:3.9.0]).
  6062. ** It may therefore only be used if
  6063. ** sqlite3_libversion_number() returns a value greater than or equal to
  6064. ** 3009000.
  6065. */
  6066. struct sqlite3_index_info {
  6067. /* Inputs */
  6068. int nConstraint; /* Number of entries in aConstraint */
  6069. struct sqlite3_index_constraint {
  6070. int iColumn; /* Column constrained. -1 for ROWID */
  6071. unsigned char op; /* Constraint operator */
  6072. unsigned char usable; /* True if this constraint is usable */
  6073. int iTermOffset; /* Used internally - xBestIndex should ignore */
  6074. } *aConstraint; /* Table of WHERE clause constraints */
  6075. int nOrderBy; /* Number of terms in the ORDER BY clause */
  6076. struct sqlite3_index_orderby {
  6077. int iColumn; /* Column number */
  6078. unsigned char desc; /* True for DESC. False for ASC. */
  6079. } *aOrderBy; /* The ORDER BY clause */
  6080. /* Outputs */
  6081. struct sqlite3_index_constraint_usage {
  6082. int argvIndex; /* if >0, constraint is part of argv to xFilter */
  6083. unsigned char omit; /* Do not code a test for this constraint */
  6084. } *aConstraintUsage;
  6085. int idxNum; /* Number used to identify the index */
  6086. char *idxStr; /* String, possibly obtained from sqlite3_malloc */
  6087. int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
  6088. int orderByConsumed; /* True if output is already ordered */
  6089. double estimatedCost; /* Estimated cost of using this index */
  6090. /* Fields below are only available in SQLite 3.8.2 and later */
  6091. sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
  6092. /* Fields below are only available in SQLite 3.9.0 and later */
  6093. int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
  6094. /* Fields below are only available in SQLite 3.10.0 and later */
  6095. sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
  6096. };
  6097. /*
  6098. ** CAPI3REF: Virtual Table Scan Flags
  6099. */
  6100. #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
  6101. /*
  6102. ** CAPI3REF: Virtual Table Constraint Operator Codes
  6103. **
  6104. ** These macros defined the allowed values for the
  6105. ** [sqlite3_index_info].aConstraint[].op field. Each value represents
  6106. ** an operator that is part of a constraint term in the wHERE clause of
  6107. ** a query that uses a [virtual table].
  6108. */
  6109. #define SQLITE_INDEX_CONSTRAINT_EQ 2
  6110. #define SQLITE_INDEX_CONSTRAINT_GT 4
  6111. #define SQLITE_INDEX_CONSTRAINT_LE 8
  6112. #define SQLITE_INDEX_CONSTRAINT_LT 16
  6113. #define SQLITE_INDEX_CONSTRAINT_GE 32
  6114. #define SQLITE_INDEX_CONSTRAINT_MATCH 64
  6115. #define SQLITE_INDEX_CONSTRAINT_LIKE 65
  6116. #define SQLITE_INDEX_CONSTRAINT_GLOB 66
  6117. #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
  6118. #define SQLITE_INDEX_CONSTRAINT_NE 68
  6119. #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
  6120. #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
  6121. #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
  6122. #define SQLITE_INDEX_CONSTRAINT_IS 72
  6123. /*
  6124. ** CAPI3REF: Register A Virtual Table Implementation
  6125. ** METHOD: sqlite3
  6126. **
  6127. ** ^These routines are used to register a new [virtual table module] name.
  6128. ** ^Module names must be registered before
  6129. ** creating a new [virtual table] using the module and before using a
  6130. ** preexisting [virtual table] for the module.
  6131. **
  6132. ** ^The module name is registered on the [database connection] specified
  6133. ** by the first parameter. ^The name of the module is given by the
  6134. ** second parameter. ^The third parameter is a pointer to
  6135. ** the implementation of the [virtual table module]. ^The fourth
  6136. ** parameter is an arbitrary client data pointer that is passed through
  6137. ** into the [xCreate] and [xConnect] methods of the virtual table module
  6138. ** when a new virtual table is be being created or reinitialized.
  6139. **
  6140. ** ^The sqlite3_create_module_v2() interface has a fifth parameter which
  6141. ** is a pointer to a destructor for the pClientData. ^SQLite will
  6142. ** invoke the destructor function (if it is not NULL) when SQLite
  6143. ** no longer needs the pClientData pointer. ^The destructor will also
  6144. ** be invoked if the call to sqlite3_create_module_v2() fails.
  6145. ** ^The sqlite3_create_module()
  6146. ** interface is equivalent to sqlite3_create_module_v2() with a NULL
  6147. ** destructor.
  6148. */
  6149. SQLITE_API int sqlite3_create_module(
  6150. sqlite3 *db, /* SQLite connection to register module with */
  6151. const char *zName, /* Name of the module */
  6152. const sqlite3_module *p, /* Methods for the module */
  6153. void *pClientData /* Client data for xCreate/xConnect */
  6154. );
  6155. SQLITE_API int sqlite3_create_module_v2(
  6156. sqlite3 *db, /* SQLite connection to register module with */
  6157. const char *zName, /* Name of the module */
  6158. const sqlite3_module *p, /* Methods for the module */
  6159. void *pClientData, /* Client data for xCreate/xConnect */
  6160. void(*xDestroy)(void*) /* Module destructor function */
  6161. );
  6162. /*
  6163. ** CAPI3REF: Virtual Table Instance Object
  6164. ** KEYWORDS: sqlite3_vtab
  6165. **
  6166. ** Every [virtual table module] implementation uses a subclass
  6167. ** of this object to describe a particular instance
  6168. ** of the [virtual table]. Each subclass will
  6169. ** be tailored to the specific needs of the module implementation.
  6170. ** The purpose of this superclass is to define certain fields that are
  6171. ** common to all module implementations.
  6172. **
  6173. ** ^Virtual tables methods can set an error message by assigning a
  6174. ** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
  6175. ** take care that any prior string is freed by a call to [sqlite3_free()]
  6176. ** prior to assigning a new string to zErrMsg. ^After the error message
  6177. ** is delivered up to the client application, the string will be automatically
  6178. ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
  6179. */
  6180. struct sqlite3_vtab {
  6181. const sqlite3_module *pModule; /* The module for this virtual table */
  6182. int nRef; /* Number of open cursors */
  6183. char *zErrMsg; /* Error message from sqlite3_mprintf() */
  6184. /* Virtual table implementations will typically add additional fields */
  6185. };
  6186. /*
  6187. ** CAPI3REF: Virtual Table Cursor Object
  6188. ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
  6189. **
  6190. ** Every [virtual table module] implementation uses a subclass of the
  6191. ** following structure to describe cursors that point into the
  6192. ** [virtual table] and are used
  6193. ** to loop through the virtual table. Cursors are created using the
  6194. ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
  6195. ** by the [sqlite3_module.xClose | xClose] method. Cursors are used
  6196. ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
  6197. ** of the module. Each module implementation will define
  6198. ** the content of a cursor structure to suit its own needs.
  6199. **
  6200. ** This superclass exists in order to define fields of the cursor that
  6201. ** are common to all implementations.
  6202. */
  6203. struct sqlite3_vtab_cursor {
  6204. sqlite3_vtab *pVtab; /* Virtual table of this cursor */
  6205. /* Virtual table implementations will typically add additional fields */
  6206. };
  6207. /*
  6208. ** CAPI3REF: Declare The Schema Of A Virtual Table
  6209. **
  6210. ** ^The [xCreate] and [xConnect] methods of a
  6211. ** [virtual table module] call this interface
  6212. ** to declare the format (the names and datatypes of the columns) of
  6213. ** the virtual tables they implement.
  6214. */
  6215. SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
  6216. /*
  6217. ** CAPI3REF: Overload A Function For A Virtual Table
  6218. ** METHOD: sqlite3
  6219. **
  6220. ** ^(Virtual tables can provide alternative implementations of functions
  6221. ** using the [xFindFunction] method of the [virtual table module].
  6222. ** But global versions of those functions
  6223. ** must exist in order to be overloaded.)^
  6224. **
  6225. ** ^(This API makes sure a global version of a function with a particular
  6226. ** name and number of parameters exists. If no such function exists
  6227. ** before this API is called, a new function is created.)^ ^The implementation
  6228. ** of the new function always causes an exception to be thrown. So
  6229. ** the new function is not good for anything by itself. Its only
  6230. ** purpose is to be a placeholder function that can be overloaded
  6231. ** by a [virtual table].
  6232. */
  6233. SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
  6234. /*
  6235. ** The interface to the virtual-table mechanism defined above (back up
  6236. ** to a comment remarkably similar to this one) is currently considered
  6237. ** to be experimental. The interface might change in incompatible ways.
  6238. ** If this is a problem for you, do not use the interface at this time.
  6239. **
  6240. ** When the virtual-table mechanism stabilizes, we will declare the
  6241. ** interface fixed, support it indefinitely, and remove this comment.
  6242. */
  6243. /*
  6244. ** CAPI3REF: A Handle To An Open BLOB
  6245. ** KEYWORDS: {BLOB handle} {BLOB handles}
  6246. **
  6247. ** An instance of this object represents an open BLOB on which
  6248. ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
  6249. ** ^Objects of this type are created by [sqlite3_blob_open()]
  6250. ** and destroyed by [sqlite3_blob_close()].
  6251. ** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
  6252. ** can be used to read or write small subsections of the BLOB.
  6253. ** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
  6254. */
  6255. typedef struct sqlite3_blob sqlite3_blob;
  6256. /*
  6257. ** CAPI3REF: Open A BLOB For Incremental I/O
  6258. ** METHOD: sqlite3
  6259. ** CONSTRUCTOR: sqlite3_blob
  6260. **
  6261. ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
  6262. ** in row iRow, column zColumn, table zTable in database zDb;
  6263. ** in other words, the same BLOB that would be selected by:
  6264. **
  6265. ** <pre>
  6266. ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
  6267. ** </pre>)^
  6268. **
  6269. ** ^(Parameter zDb is not the filename that contains the database, but
  6270. ** rather the symbolic name of the database. For attached databases, this is
  6271. ** the name that appears after the AS keyword in the [ATTACH] statement.
  6272. ** For the main database file, the database name is "main". For TEMP
  6273. ** tables, the database name is "temp".)^
  6274. **
  6275. ** ^If the flags parameter is non-zero, then the BLOB is opened for read
  6276. ** and write access. ^If the flags parameter is zero, the BLOB is opened for
  6277. ** read-only access.
  6278. **
  6279. ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
  6280. ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
  6281. ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
  6282. ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
  6283. ** on *ppBlob after this function it returns.
  6284. **
  6285. ** This function fails with SQLITE_ERROR if any of the following are true:
  6286. ** <ul>
  6287. ** <li> ^(Database zDb does not exist)^,
  6288. ** <li> ^(Table zTable does not exist within database zDb)^,
  6289. ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
  6290. ** <li> ^(Column zColumn does not exist)^,
  6291. ** <li> ^(Row iRow is not present in the table)^,
  6292. ** <li> ^(The specified column of row iRow contains a value that is not
  6293. ** a TEXT or BLOB value)^,
  6294. ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
  6295. ** constraint and the blob is being opened for read/write access)^,
  6296. ** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
  6297. ** column zColumn is part of a [child key] definition and the blob is
  6298. ** being opened for read/write access)^.
  6299. ** </ul>
  6300. **
  6301. ** ^Unless it returns SQLITE_MISUSE, this function sets the
  6302. ** [database connection] error code and message accessible via
  6303. ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
  6304. **
  6305. ** A BLOB referenced by sqlite3_blob_open() may be read using the
  6306. ** [sqlite3_blob_read()] interface and modified by using
  6307. ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
  6308. ** different row of the same table using the [sqlite3_blob_reopen()]
  6309. ** interface. However, the column, table, or database of a [BLOB handle]
  6310. ** cannot be changed after the [BLOB handle] is opened.
  6311. **
  6312. ** ^(If the row that a BLOB handle points to is modified by an
  6313. ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
  6314. ** then the BLOB handle is marked as "expired".
  6315. ** This is true if any column of the row is changed, even a column
  6316. ** other than the one the BLOB handle is open on.)^
  6317. ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
  6318. ** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
  6319. ** ^(Changes written into a BLOB prior to the BLOB expiring are not
  6320. ** rolled back by the expiration of the BLOB. Such changes will eventually
  6321. ** commit if the transaction continues to completion.)^
  6322. **
  6323. ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
  6324. ** the opened blob. ^The size of a blob may not be changed by this
  6325. ** interface. Use the [UPDATE] SQL command to change the size of a
  6326. ** blob.
  6327. **
  6328. ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
  6329. ** and the built-in [zeroblob] SQL function may be used to create a
  6330. ** zero-filled blob to read or write using the incremental-blob interface.
  6331. **
  6332. ** To avoid a resource leak, every open [BLOB handle] should eventually
  6333. ** be released by a call to [sqlite3_blob_close()].
  6334. **
  6335. ** See also: [sqlite3_blob_close()],
  6336. ** [sqlite3_blob_reopen()], [sqlite3_blob_read()],
  6337. ** [sqlite3_blob_bytes()], [sqlite3_blob_write()].
  6338. */
  6339. SQLITE_API int sqlite3_blob_open(
  6340. sqlite3*,
  6341. const char *zDb,
  6342. const char *zTable,
  6343. const char *zColumn,
  6344. sqlite3_int64 iRow,
  6345. int flags,
  6346. sqlite3_blob **ppBlob
  6347. );
  6348. /*
  6349. ** CAPI3REF: Move a BLOB Handle to a New Row
  6350. ** METHOD: sqlite3_blob
  6351. **
  6352. ** ^This function is used to move an existing [BLOB handle] so that it points
  6353. ** to a different row of the same database table. ^The new row is identified
  6354. ** by the rowid value passed as the second argument. Only the row can be
  6355. ** changed. ^The database, table and column on which the blob handle is open
  6356. ** remain the same. Moving an existing [BLOB handle] to a new row is
  6357. ** faster than closing the existing handle and opening a new one.
  6358. **
  6359. ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
  6360. ** it must exist and there must be either a blob or text value stored in
  6361. ** the nominated column.)^ ^If the new row is not present in the table, or if
  6362. ** it does not contain a blob or text value, or if another error occurs, an
  6363. ** SQLite error code is returned and the blob handle is considered aborted.
  6364. ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
  6365. ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
  6366. ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
  6367. ** always returns zero.
  6368. **
  6369. ** ^This function sets the database handle error code and message.
  6370. */
  6371. SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
  6372. /*
  6373. ** CAPI3REF: Close A BLOB Handle
  6374. ** DESTRUCTOR: sqlite3_blob
  6375. **
  6376. ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
  6377. ** unconditionally. Even if this routine returns an error code, the
  6378. ** handle is still closed.)^
  6379. **
  6380. ** ^If the blob handle being closed was opened for read-write access, and if
  6381. ** the database is in auto-commit mode and there are no other open read-write
  6382. ** blob handles or active write statements, the current transaction is
  6383. ** committed. ^If an error occurs while committing the transaction, an error
  6384. ** code is returned and the transaction rolled back.
  6385. **
  6386. ** Calling this function with an argument that is not a NULL pointer or an
  6387. ** open blob handle results in undefined behaviour. ^Calling this routine
  6388. ** with a null pointer (such as would be returned by a failed call to
  6389. ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
  6390. ** is passed a valid open blob handle, the values returned by the
  6391. ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
  6392. */
  6393. SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
  6394. /*
  6395. ** CAPI3REF: Return The Size Of An Open BLOB
  6396. ** METHOD: sqlite3_blob
  6397. **
  6398. ** ^Returns the size in bytes of the BLOB accessible via the
  6399. ** successfully opened [BLOB handle] in its only argument. ^The
  6400. ** incremental blob I/O routines can only read or overwriting existing
  6401. ** blob content; they cannot change the size of a blob.
  6402. **
  6403. ** This routine only works on a [BLOB handle] which has been created
  6404. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  6405. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  6406. ** to this routine results in undefined and probably undesirable behavior.
  6407. */
  6408. SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
  6409. /*
  6410. ** CAPI3REF: Read Data From A BLOB Incrementally
  6411. ** METHOD: sqlite3_blob
  6412. **
  6413. ** ^(This function is used to read data from an open [BLOB handle] into a
  6414. ** caller-supplied buffer. N bytes of data are copied into buffer Z
  6415. ** from the open BLOB, starting at offset iOffset.)^
  6416. **
  6417. ** ^If offset iOffset is less than N bytes from the end of the BLOB,
  6418. ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
  6419. ** less than zero, [SQLITE_ERROR] is returned and no data is read.
  6420. ** ^The size of the blob (and hence the maximum value of N+iOffset)
  6421. ** can be determined using the [sqlite3_blob_bytes()] interface.
  6422. **
  6423. ** ^An attempt to read from an expired [BLOB handle] fails with an
  6424. ** error code of [SQLITE_ABORT].
  6425. **
  6426. ** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
  6427. ** Otherwise, an [error code] or an [extended error code] is returned.)^
  6428. **
  6429. ** This routine only works on a [BLOB handle] which has been created
  6430. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  6431. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  6432. ** to this routine results in undefined and probably undesirable behavior.
  6433. **
  6434. ** See also: [sqlite3_blob_write()].
  6435. */
  6436. SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
  6437. /*
  6438. ** CAPI3REF: Write Data Into A BLOB Incrementally
  6439. ** METHOD: sqlite3_blob
  6440. **
  6441. ** ^(This function is used to write data into an open [BLOB handle] from a
  6442. ** caller-supplied buffer. N bytes of data are copied from the buffer Z
  6443. ** into the open BLOB, starting at offset iOffset.)^
  6444. **
  6445. ** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
  6446. ** Otherwise, an [error code] or an [extended error code] is returned.)^
  6447. ** ^Unless SQLITE_MISUSE is returned, this function sets the
  6448. ** [database connection] error code and message accessible via
  6449. ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
  6450. **
  6451. ** ^If the [BLOB handle] passed as the first argument was not opened for
  6452. ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
  6453. ** this function returns [SQLITE_READONLY].
  6454. **
  6455. ** This function may only modify the contents of the BLOB; it is
  6456. ** not possible to increase the size of a BLOB using this API.
  6457. ** ^If offset iOffset is less than N bytes from the end of the BLOB,
  6458. ** [SQLITE_ERROR] is returned and no data is written. The size of the
  6459. ** BLOB (and hence the maximum value of N+iOffset) can be determined
  6460. ** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
  6461. ** than zero [SQLITE_ERROR] is returned and no data is written.
  6462. **
  6463. ** ^An attempt to write to an expired [BLOB handle] fails with an
  6464. ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
  6465. ** before the [BLOB handle] expired are not rolled back by the
  6466. ** expiration of the handle, though of course those changes might
  6467. ** have been overwritten by the statement that expired the BLOB handle
  6468. ** or by other independent statements.
  6469. **
  6470. ** This routine only works on a [BLOB handle] which has been created
  6471. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  6472. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  6473. ** to this routine results in undefined and probably undesirable behavior.
  6474. **
  6475. ** See also: [sqlite3_blob_read()].
  6476. */
  6477. SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  6478. /*
  6479. ** CAPI3REF: Virtual File System Objects
  6480. **
  6481. ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
  6482. ** that SQLite uses to interact
  6483. ** with the underlying operating system. Most SQLite builds come with a
  6484. ** single default VFS that is appropriate for the host computer.
  6485. ** New VFSes can be registered and existing VFSes can be unregistered.
  6486. ** The following interfaces are provided.
  6487. **
  6488. ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
  6489. ** ^Names are case sensitive.
  6490. ** ^Names are zero-terminated UTF-8 strings.
  6491. ** ^If there is no match, a NULL pointer is returned.
  6492. ** ^If zVfsName is NULL then the default VFS is returned.
  6493. **
  6494. ** ^New VFSes are registered with sqlite3_vfs_register().
  6495. ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
  6496. ** ^The same VFS can be registered multiple times without injury.
  6497. ** ^To make an existing VFS into the default VFS, register it again
  6498. ** with the makeDflt flag set. If two different VFSes with the
  6499. ** same name are registered, the behavior is undefined. If a
  6500. ** VFS is registered with a name that is NULL or an empty string,
  6501. ** then the behavior is undefined.
  6502. **
  6503. ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
  6504. ** ^(If the default VFS is unregistered, another VFS is chosen as
  6505. ** the default. The choice for the new VFS is arbitrary.)^
  6506. */
  6507. SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
  6508. SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
  6509. SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
  6510. /*
  6511. ** CAPI3REF: Mutexes
  6512. **
  6513. ** The SQLite core uses these routines for thread
  6514. ** synchronization. Though they are intended for internal
  6515. ** use by SQLite, code that links against SQLite is
  6516. ** permitted to use any of these routines.
  6517. **
  6518. ** The SQLite source code contains multiple implementations
  6519. ** of these mutex routines. An appropriate implementation
  6520. ** is selected automatically at compile-time. The following
  6521. ** implementations are available in the SQLite core:
  6522. **
  6523. ** <ul>
  6524. ** <li> SQLITE_MUTEX_PTHREADS
  6525. ** <li> SQLITE_MUTEX_W32
  6526. ** <li> SQLITE_MUTEX_NOOP
  6527. ** </ul>
  6528. **
  6529. ** The SQLITE_MUTEX_NOOP implementation is a set of routines
  6530. ** that does no real locking and is appropriate for use in
  6531. ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
  6532. ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
  6533. ** and Windows.
  6534. **
  6535. ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
  6536. ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
  6537. ** implementation is included with the library. In this case the
  6538. ** application must supply a custom mutex implementation using the
  6539. ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
  6540. ** before calling sqlite3_initialize() or any other public sqlite3_
  6541. ** function that calls sqlite3_initialize().
  6542. **
  6543. ** ^The sqlite3_mutex_alloc() routine allocates a new
  6544. ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
  6545. ** routine returns NULL if it is unable to allocate the requested
  6546. ** mutex. The argument to sqlite3_mutex_alloc() must one of these
  6547. ** integer constants:
  6548. **
  6549. ** <ul>
  6550. ** <li> SQLITE_MUTEX_FAST
  6551. ** <li> SQLITE_MUTEX_RECURSIVE
  6552. ** <li> SQLITE_MUTEX_STATIC_MASTER
  6553. ** <li> SQLITE_MUTEX_STATIC_MEM
  6554. ** <li> SQLITE_MUTEX_STATIC_OPEN
  6555. ** <li> SQLITE_MUTEX_STATIC_PRNG
  6556. ** <li> SQLITE_MUTEX_STATIC_LRU
  6557. ** <li> SQLITE_MUTEX_STATIC_PMEM
  6558. ** <li> SQLITE_MUTEX_STATIC_APP1
  6559. ** <li> SQLITE_MUTEX_STATIC_APP2
  6560. ** <li> SQLITE_MUTEX_STATIC_APP3
  6561. ** <li> SQLITE_MUTEX_STATIC_VFS1
  6562. ** <li> SQLITE_MUTEX_STATIC_VFS2
  6563. ** <li> SQLITE_MUTEX_STATIC_VFS3
  6564. ** </ul>
  6565. **
  6566. ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
  6567. ** cause sqlite3_mutex_alloc() to create
  6568. ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
  6569. ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
  6570. ** The mutex implementation does not need to make a distinction
  6571. ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
  6572. ** not want to. SQLite will only request a recursive mutex in
  6573. ** cases where it really needs one. If a faster non-recursive mutex
  6574. ** implementation is available on the host platform, the mutex subsystem
  6575. ** might return such a mutex in response to SQLITE_MUTEX_FAST.
  6576. **
  6577. ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
  6578. ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
  6579. ** a pointer to a static preexisting mutex. ^Nine static mutexes are
  6580. ** used by the current version of SQLite. Future versions of SQLite
  6581. ** may add additional static mutexes. Static mutexes are for internal
  6582. ** use by SQLite only. Applications that use SQLite mutexes should
  6583. ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
  6584. ** SQLITE_MUTEX_RECURSIVE.
  6585. **
  6586. ** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
  6587. ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
  6588. ** returns a different mutex on every call. ^For the static
  6589. ** mutex types, the same mutex is returned on every call that has
  6590. ** the same type number.
  6591. **
  6592. ** ^The sqlite3_mutex_free() routine deallocates a previously
  6593. ** allocated dynamic mutex. Attempting to deallocate a static
  6594. ** mutex results in undefined behavior.
  6595. **
  6596. ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
  6597. ** to enter a mutex. ^If another thread is already within the mutex,
  6598. ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
  6599. ** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
  6600. ** upon successful entry. ^(Mutexes created using
  6601. ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
  6602. ** In such cases, the
  6603. ** mutex must be exited an equal number of times before another thread
  6604. ** can enter.)^ If the same thread tries to enter any mutex other
  6605. ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
  6606. **
  6607. ** ^(Some systems (for example, Windows 95) do not support the operation
  6608. ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
  6609. ** will always return SQLITE_BUSY. The SQLite core only ever uses
  6610. ** sqlite3_mutex_try() as an optimization so this is acceptable
  6611. ** behavior.)^
  6612. **
  6613. ** ^The sqlite3_mutex_leave() routine exits a mutex that was
  6614. ** previously entered by the same thread. The behavior
  6615. ** is undefined if the mutex is not currently entered by the
  6616. ** calling thread or is not currently allocated.
  6617. **
  6618. ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
  6619. ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
  6620. ** behave as no-ops.
  6621. **
  6622. ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
  6623. */
  6624. SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
  6625. SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
  6626. SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
  6627. SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
  6628. SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
  6629. /*
  6630. ** CAPI3REF: Mutex Methods Object
  6631. **
  6632. ** An instance of this structure defines the low-level routines
  6633. ** used to allocate and use mutexes.
  6634. **
  6635. ** Usually, the default mutex implementations provided by SQLite are
  6636. ** sufficient, however the application has the option of substituting a custom
  6637. ** implementation for specialized deployments or systems for which SQLite
  6638. ** does not provide a suitable implementation. In this case, the application
  6639. ** creates and populates an instance of this structure to pass
  6640. ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
  6641. ** Additionally, an instance of this structure can be used as an
  6642. ** output variable when querying the system for the current mutex
  6643. ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
  6644. **
  6645. ** ^The xMutexInit method defined by this structure is invoked as
  6646. ** part of system initialization by the sqlite3_initialize() function.
  6647. ** ^The xMutexInit routine is called by SQLite exactly once for each
  6648. ** effective call to [sqlite3_initialize()].
  6649. **
  6650. ** ^The xMutexEnd method defined by this structure is invoked as
  6651. ** part of system shutdown by the sqlite3_shutdown() function. The
  6652. ** implementation of this method is expected to release all outstanding
  6653. ** resources obtained by the mutex methods implementation, especially
  6654. ** those obtained by the xMutexInit method. ^The xMutexEnd()
  6655. ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
  6656. **
  6657. ** ^(The remaining seven methods defined by this structure (xMutexAlloc,
  6658. ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
  6659. ** xMutexNotheld) implement the following interfaces (respectively):
  6660. **
  6661. ** <ul>
  6662. ** <li> [sqlite3_mutex_alloc()] </li>
  6663. ** <li> [sqlite3_mutex_free()] </li>
  6664. ** <li> [sqlite3_mutex_enter()] </li>
  6665. ** <li> [sqlite3_mutex_try()] </li>
  6666. ** <li> [sqlite3_mutex_leave()] </li>
  6667. ** <li> [sqlite3_mutex_held()] </li>
  6668. ** <li> [sqlite3_mutex_notheld()] </li>
  6669. ** </ul>)^
  6670. **
  6671. ** The only difference is that the public sqlite3_XXX functions enumerated
  6672. ** above silently ignore any invocations that pass a NULL pointer instead
  6673. ** of a valid mutex handle. The implementations of the methods defined
  6674. ** by this structure are not required to handle this case, the results
  6675. ** of passing a NULL pointer instead of a valid mutex handle are undefined
  6676. ** (i.e. it is acceptable to provide an implementation that segfaults if
  6677. ** it is passed a NULL pointer).
  6678. **
  6679. ** The xMutexInit() method must be threadsafe. It must be harmless to
  6680. ** invoke xMutexInit() multiple times within the same process and without
  6681. ** intervening calls to xMutexEnd(). Second and subsequent calls to
  6682. ** xMutexInit() must be no-ops.
  6683. **
  6684. ** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
  6685. ** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
  6686. ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
  6687. ** memory allocation for a fast or recursive mutex.
  6688. **
  6689. ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
  6690. ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
  6691. ** If xMutexInit fails in any way, it is expected to clean up after itself
  6692. ** prior to returning.
  6693. */
  6694. typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
  6695. struct sqlite3_mutex_methods {
  6696. int (*xMutexInit)(void);
  6697. int (*xMutexEnd)(void);
  6698. sqlite3_mutex *(*xMutexAlloc)(int);
  6699. void (*xMutexFree)(sqlite3_mutex *);
  6700. void (*xMutexEnter)(sqlite3_mutex *);
  6701. int (*xMutexTry)(sqlite3_mutex *);
  6702. void (*xMutexLeave)(sqlite3_mutex *);
  6703. int (*xMutexHeld)(sqlite3_mutex *);
  6704. int (*xMutexNotheld)(sqlite3_mutex *);
  6705. };
  6706. /*
  6707. ** CAPI3REF: Mutex Verification Routines
  6708. **
  6709. ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
  6710. ** are intended for use inside assert() statements. The SQLite core
  6711. ** never uses these routines except inside an assert() and applications
  6712. ** are advised to follow the lead of the core. The SQLite core only
  6713. ** provides implementations for these routines when it is compiled
  6714. ** with the SQLITE_DEBUG flag. External mutex implementations
  6715. ** are only required to provide these routines if SQLITE_DEBUG is
  6716. ** defined and if NDEBUG is not defined.
  6717. **
  6718. ** These routines should return true if the mutex in their argument
  6719. ** is held or not held, respectively, by the calling thread.
  6720. **
  6721. ** The implementation is not required to provide versions of these
  6722. ** routines that actually work. If the implementation does not provide working
  6723. ** versions of these routines, it should at least provide stubs that always
  6724. ** return true so that one does not get spurious assertion failures.
  6725. **
  6726. ** If the argument to sqlite3_mutex_held() is a NULL pointer then
  6727. ** the routine should return 1. This seems counter-intuitive since
  6728. ** clearly the mutex cannot be held if it does not exist. But
  6729. ** the reason the mutex does not exist is because the build is not
  6730. ** using mutexes. And we do not want the assert() containing the
  6731. ** call to sqlite3_mutex_held() to fail, so a non-zero return is
  6732. ** the appropriate thing to do. The sqlite3_mutex_notheld()
  6733. ** interface should also return 1 when given a NULL pointer.
  6734. */
  6735. #ifndef NDEBUG
  6736. SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
  6737. SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
  6738. #endif
  6739. /*
  6740. ** CAPI3REF: Mutex Types
  6741. **
  6742. ** The [sqlite3_mutex_alloc()] interface takes a single argument
  6743. ** which is one of these integer constants.
  6744. **
  6745. ** The set of static mutexes may change from one SQLite release to the
  6746. ** next. Applications that override the built-in mutex logic must be
  6747. ** prepared to accommodate additional static mutexes.
  6748. */
  6749. #define SQLITE_MUTEX_FAST 0
  6750. #define SQLITE_MUTEX_RECURSIVE 1
  6751. #define SQLITE_MUTEX_STATIC_MASTER 2
  6752. #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
  6753. #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
  6754. #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
  6755. #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
  6756. #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
  6757. #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
  6758. #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
  6759. #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
  6760. #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
  6761. #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
  6762. #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
  6763. #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
  6764. #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
  6765. /*
  6766. ** CAPI3REF: Retrieve the mutex for a database connection
  6767. ** METHOD: sqlite3
  6768. **
  6769. ** ^This interface returns a pointer the [sqlite3_mutex] object that
  6770. ** serializes access to the [database connection] given in the argument
  6771. ** when the [threading mode] is Serialized.
  6772. ** ^If the [threading mode] is Single-thread or Multi-thread then this
  6773. ** routine returns a NULL pointer.
  6774. */
  6775. SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
  6776. /*
  6777. ** CAPI3REF: Low-Level Control Of Database Files
  6778. ** METHOD: sqlite3
  6779. **
  6780. ** ^The [sqlite3_file_control()] interface makes a direct call to the
  6781. ** xFileControl method for the [sqlite3_io_methods] object associated
  6782. ** with a particular database identified by the second argument. ^The
  6783. ** name of the database is "main" for the main database or "temp" for the
  6784. ** TEMP database, or the name that appears after the AS keyword for
  6785. ** databases that are added using the [ATTACH] SQL command.
  6786. ** ^A NULL pointer can be used in place of "main" to refer to the
  6787. ** main database file.
  6788. ** ^The third and fourth parameters to this routine
  6789. ** are passed directly through to the second and third parameters of
  6790. ** the xFileControl method. ^The return value of the xFileControl
  6791. ** method becomes the return value of this routine.
  6792. **
  6793. ** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
  6794. ** a pointer to the underlying [sqlite3_file] object to be written into
  6795. ** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER
  6796. ** case is a short-circuit path which does not actually invoke the
  6797. ** underlying sqlite3_io_methods.xFileControl method.
  6798. **
  6799. ** ^If the second parameter (zDbName) does not match the name of any
  6800. ** open database file, then SQLITE_ERROR is returned. ^This error
  6801. ** code is not remembered and will not be recalled by [sqlite3_errcode()]
  6802. ** or [sqlite3_errmsg()]. The underlying xFileControl method might
  6803. ** also return SQLITE_ERROR. There is no way to distinguish between
  6804. ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
  6805. ** xFileControl method.
  6806. **
  6807. ** See also: [SQLITE_FCNTL_LOCKSTATE]
  6808. */
  6809. SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
  6810. /*
  6811. ** CAPI3REF: Testing Interface
  6812. **
  6813. ** ^The sqlite3_test_control() interface is used to read out internal
  6814. ** state of SQLite and to inject faults into SQLite for testing
  6815. ** purposes. ^The first parameter is an operation code that determines
  6816. ** the number, meaning, and operation of all subsequent parameters.
  6817. **
  6818. ** This interface is not for use by applications. It exists solely
  6819. ** for verifying the correct operation of the SQLite library. Depending
  6820. ** on how the SQLite library is compiled, this interface might not exist.
  6821. **
  6822. ** The details of the operation codes, their meanings, the parameters
  6823. ** they take, and what they do are all subject to change without notice.
  6824. ** Unlike most of the SQLite API, this function is not guaranteed to
  6825. ** operate consistently from one release to the next.
  6826. */
  6827. SQLITE_API int sqlite3_test_control(int op, ...);
  6828. /*
  6829. ** CAPI3REF: Testing Interface Operation Codes
  6830. **
  6831. ** These constants are the valid operation code parameters used
  6832. ** as the first argument to [sqlite3_test_control()].
  6833. **
  6834. ** These parameters and their meanings are subject to change
  6835. ** without notice. These values are for testing purposes only.
  6836. ** Applications should not use any of these parameters or the
  6837. ** [sqlite3_test_control()] interface.
  6838. */
  6839. #define SQLITE_TESTCTRL_FIRST 5
  6840. #define SQLITE_TESTCTRL_PRNG_SAVE 5
  6841. #define SQLITE_TESTCTRL_PRNG_RESTORE 6
  6842. #define SQLITE_TESTCTRL_PRNG_RESET 7
  6843. #define SQLITE_TESTCTRL_BITVEC_TEST 8
  6844. #define SQLITE_TESTCTRL_FAULT_INSTALL 9
  6845. #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
  6846. #define SQLITE_TESTCTRL_PENDING_BYTE 11
  6847. #define SQLITE_TESTCTRL_ASSERT 12
  6848. #define SQLITE_TESTCTRL_ALWAYS 13
  6849. #define SQLITE_TESTCTRL_RESERVE 14
  6850. #define SQLITE_TESTCTRL_OPTIMIZATIONS 15
  6851. #define SQLITE_TESTCTRL_ISKEYWORD 16
  6852. #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
  6853. #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
  6854. #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
  6855. #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
  6856. #define SQLITE_TESTCTRL_NEVER_CORRUPT 20
  6857. #define SQLITE_TESTCTRL_VDBE_COVERAGE 21
  6858. #define SQLITE_TESTCTRL_BYTEORDER 22
  6859. #define SQLITE_TESTCTRL_ISINIT 23
  6860. #define SQLITE_TESTCTRL_SORTER_MMAP 24
  6861. #define SQLITE_TESTCTRL_IMPOSTER 25
  6862. #define SQLITE_TESTCTRL_LAST 25
  6863. /*
  6864. ** CAPI3REF: SQLite Runtime Status
  6865. **
  6866. ** ^These interfaces are used to retrieve runtime status information
  6867. ** about the performance of SQLite, and optionally to reset various
  6868. ** highwater marks. ^The first argument is an integer code for
  6869. ** the specific parameter to measure. ^(Recognized integer codes
  6870. ** are of the form [status parameters | SQLITE_STATUS_...].)^
  6871. ** ^The current value of the parameter is returned into *pCurrent.
  6872. ** ^The highest recorded value is returned in *pHighwater. ^If the
  6873. ** resetFlag is true, then the highest record value is reset after
  6874. ** *pHighwater is written. ^(Some parameters do not record the highest
  6875. ** value. For those parameters
  6876. ** nothing is written into *pHighwater and the resetFlag is ignored.)^
  6877. ** ^(Other parameters record only the highwater mark and not the current
  6878. ** value. For these latter parameters nothing is written into *pCurrent.)^
  6879. **
  6880. ** ^The sqlite3_status() and sqlite3_status64() routines return
  6881. ** SQLITE_OK on success and a non-zero [error code] on failure.
  6882. **
  6883. ** If either the current value or the highwater mark is too large to
  6884. ** be represented by a 32-bit integer, then the values returned by
  6885. ** sqlite3_status() are undefined.
  6886. **
  6887. ** See also: [sqlite3_db_status()]
  6888. */
  6889. SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
  6890. SQLITE_API int sqlite3_status64(
  6891. int op,
  6892. sqlite3_int64 *pCurrent,
  6893. sqlite3_int64 *pHighwater,
  6894. int resetFlag
  6895. );
  6896. /*
  6897. ** CAPI3REF: Status Parameters
  6898. ** KEYWORDS: {status parameters}
  6899. **
  6900. ** These integer constants designate various run-time status parameters
  6901. ** that can be returned by [sqlite3_status()].
  6902. **
  6903. ** <dl>
  6904. ** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
  6905. ** <dd>This parameter is the current amount of memory checked out
  6906. ** using [sqlite3_malloc()], either directly or indirectly. The
  6907. ** figure includes calls made to [sqlite3_malloc()] by the application
  6908. ** and internal memory usage by the SQLite library. Auxiliary page-cache
  6909. ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
  6910. ** this parameter. The amount returned is the sum of the allocation
  6911. ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
  6912. **
  6913. ** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
  6914. ** <dd>This parameter records the largest memory allocation request
  6915. ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
  6916. ** internal equivalents). Only the value returned in the
  6917. ** *pHighwater parameter to [sqlite3_status()] is of interest.
  6918. ** The value written into the *pCurrent parameter is undefined.</dd>)^
  6919. **
  6920. ** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
  6921. ** <dd>This parameter records the number of separate memory allocations
  6922. ** currently checked out.</dd>)^
  6923. **
  6924. ** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
  6925. ** <dd>This parameter returns the number of pages used out of the
  6926. ** [pagecache memory allocator] that was configured using
  6927. ** [SQLITE_CONFIG_PAGECACHE]. The
  6928. ** value returned is in pages, not in bytes.</dd>)^
  6929. **
  6930. ** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]
  6931. ** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
  6932. ** <dd>This parameter returns the number of bytes of page cache
  6933. ** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
  6934. ** buffer and where forced to overflow to [sqlite3_malloc()]. The
  6935. ** returned value includes allocations that overflowed because they
  6936. ** where too large (they were larger than the "sz" parameter to
  6937. ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
  6938. ** no space was left in the page cache.</dd>)^
  6939. **
  6940. ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
  6941. ** <dd>This parameter records the largest memory allocation request
  6942. ** handed to [pagecache memory allocator]. Only the value returned in the
  6943. ** *pHighwater parameter to [sqlite3_status()] is of interest.
  6944. ** The value written into the *pCurrent parameter is undefined.</dd>)^
  6945. **
  6946. ** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
  6947. ** <dd>No longer used.</dd>
  6948. **
  6949. ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
  6950. ** <dd>No longer used.</dd>
  6951. **
  6952. ** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
  6953. ** <dd>No longer used.</dd>
  6954. **
  6955. ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
  6956. ** <dd>The *pHighwater parameter records the deepest parser stack.
  6957. ** The *pCurrent value is undefined. The *pHighwater value is only
  6958. ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
  6959. ** </dl>
  6960. **
  6961. ** New status parameters may be added from time to time.
  6962. */
  6963. #define SQLITE_STATUS_MEMORY_USED 0
  6964. #define SQLITE_STATUS_PAGECACHE_USED 1
  6965. #define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
  6966. #define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */
  6967. #define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */
  6968. #define SQLITE_STATUS_MALLOC_SIZE 5
  6969. #define SQLITE_STATUS_PARSER_STACK 6
  6970. #define SQLITE_STATUS_PAGECACHE_SIZE 7
  6971. #define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */
  6972. #define SQLITE_STATUS_MALLOC_COUNT 9
  6973. /*
  6974. ** CAPI3REF: Database Connection Status
  6975. ** METHOD: sqlite3
  6976. **
  6977. ** ^This interface is used to retrieve runtime status information
  6978. ** about a single [database connection]. ^The first argument is the
  6979. ** database connection object to be interrogated. ^The second argument
  6980. ** is an integer constant, taken from the set of
  6981. ** [SQLITE_DBSTATUS options], that
  6982. ** determines the parameter to interrogate. The set of
  6983. ** [SQLITE_DBSTATUS options] is likely
  6984. ** to grow in future releases of SQLite.
  6985. **
  6986. ** ^The current value of the requested parameter is written into *pCur
  6987. ** and the highest instantaneous value is written into *pHiwtr. ^If
  6988. ** the resetFlg is true, then the highest instantaneous value is
  6989. ** reset back down to the current value.
  6990. **
  6991. ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
  6992. ** non-zero [error code] on failure.
  6993. **
  6994. ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
  6995. */
  6996. SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
  6997. /*
  6998. ** CAPI3REF: Status Parameters for database connections
  6999. ** KEYWORDS: {SQLITE_DBSTATUS options}
  7000. **
  7001. ** These constants are the available integer "verbs" that can be passed as
  7002. ** the second argument to the [sqlite3_db_status()] interface.
  7003. **
  7004. ** New verbs may be added in future releases of SQLite. Existing verbs
  7005. ** might be discontinued. Applications should check the return code from
  7006. ** [sqlite3_db_status()] to make sure that the call worked.
  7007. ** The [sqlite3_db_status()] interface will return a non-zero error code
  7008. ** if a discontinued or unsupported verb is invoked.
  7009. **
  7010. ** <dl>
  7011. ** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
  7012. ** <dd>This parameter returns the number of lookaside memory slots currently
  7013. ** checked out.</dd>)^
  7014. **
  7015. ** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
  7016. ** <dd>This parameter returns the number malloc attempts that were
  7017. ** satisfied using lookaside memory. Only the high-water value is meaningful;
  7018. ** the current value is always zero.)^
  7019. **
  7020. ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
  7021. ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
  7022. ** <dd>This parameter returns the number malloc attempts that might have
  7023. ** been satisfied using lookaside memory but failed due to the amount of
  7024. ** memory requested being larger than the lookaside slot size.
  7025. ** Only the high-water value is meaningful;
  7026. ** the current value is always zero.)^
  7027. **
  7028. ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
  7029. ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
  7030. ** <dd>This parameter returns the number malloc attempts that might have
  7031. ** been satisfied using lookaside memory but failed due to all lookaside
  7032. ** memory already being in use.
  7033. ** Only the high-water value is meaningful;
  7034. ** the current value is always zero.)^
  7035. **
  7036. ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
  7037. ** <dd>This parameter returns the approximate number of bytes of heap
  7038. ** memory used by all pager caches associated with the database connection.)^
  7039. ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
  7040. **
  7041. ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
  7042. ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
  7043. ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
  7044. ** pager cache is shared between two or more connections the bytes of heap
  7045. ** memory used by that pager cache is divided evenly between the attached
  7046. ** connections.)^ In other words, if none of the pager caches associated
  7047. ** with the database connection are shared, this request returns the same
  7048. ** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
  7049. ** shared, the value returned by this call will be smaller than that returned
  7050. ** by DBSTATUS_CACHE_USED. ^The highwater mark associated with
  7051. ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
  7052. **
  7053. ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
  7054. ** <dd>This parameter returns the approximate number of bytes of heap
  7055. ** memory used to store the schema for all databases associated
  7056. ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
  7057. ** ^The full amount of memory used by the schemas is reported, even if the
  7058. ** schema memory is shared with other database connections due to
  7059. ** [shared cache mode] being enabled.
  7060. ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
  7061. **
  7062. ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
  7063. ** <dd>This parameter returns the approximate number of bytes of heap
  7064. ** and lookaside memory used by all prepared statements associated with
  7065. ** the database connection.)^
  7066. ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
  7067. ** </dd>
  7068. **
  7069. ** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
  7070. ** <dd>This parameter returns the number of pager cache hits that have
  7071. ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
  7072. ** is always 0.
  7073. ** </dd>
  7074. **
  7075. ** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
  7076. ** <dd>This parameter returns the number of pager cache misses that have
  7077. ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
  7078. ** is always 0.
  7079. ** </dd>
  7080. **
  7081. ** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
  7082. ** <dd>This parameter returns the number of dirty cache entries that have
  7083. ** been written to disk. Specifically, the number of pages written to the
  7084. ** wal file in wal mode databases, or the number of pages written to the
  7085. ** database file in rollback mode databases. Any pages written as part of
  7086. ** transaction rollback or database recovery operations are not included.
  7087. ** If an IO or other error occurs while writing a page to disk, the effect
  7088. ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
  7089. ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
  7090. ** </dd>
  7091. **
  7092. ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
  7093. ** <dd>This parameter returns zero for the current value if and only if
  7094. ** all foreign key constraints (deferred or immediate) have been
  7095. ** resolved.)^ ^The highwater mark is always 0.
  7096. ** </dd>
  7097. ** </dl>
  7098. */
  7099. #define SQLITE_DBSTATUS_LOOKASIDE_USED 0
  7100. #define SQLITE_DBSTATUS_CACHE_USED 1
  7101. #define SQLITE_DBSTATUS_SCHEMA_USED 2
  7102. #define SQLITE_DBSTATUS_STMT_USED 3
  7103. #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
  7104. #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
  7105. #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
  7106. #define SQLITE_DBSTATUS_CACHE_HIT 7
  7107. #define SQLITE_DBSTATUS_CACHE_MISS 8
  7108. #define SQLITE_DBSTATUS_CACHE_WRITE 9
  7109. #define SQLITE_DBSTATUS_DEFERRED_FKS 10
  7110. #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
  7111. #define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */
  7112. /*
  7113. ** CAPI3REF: Prepared Statement Status
  7114. ** METHOD: sqlite3_stmt
  7115. **
  7116. ** ^(Each prepared statement maintains various
  7117. ** [SQLITE_STMTSTATUS counters] that measure the number
  7118. ** of times it has performed specific operations.)^ These counters can
  7119. ** be used to monitor the performance characteristics of the prepared
  7120. ** statements. For example, if the number of table steps greatly exceeds
  7121. ** the number of table searches or result rows, that would tend to indicate
  7122. ** that the prepared statement is using a full table scan rather than
  7123. ** an index.
  7124. **
  7125. ** ^(This interface is used to retrieve and reset counter values from
  7126. ** a [prepared statement]. The first argument is the prepared statement
  7127. ** object to be interrogated. The second argument
  7128. ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
  7129. ** to be interrogated.)^
  7130. ** ^The current value of the requested counter is returned.
  7131. ** ^If the resetFlg is true, then the counter is reset to zero after this
  7132. ** interface call returns.
  7133. **
  7134. ** See also: [sqlite3_status()] and [sqlite3_db_status()].
  7135. */
  7136. SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
  7137. /*
  7138. ** CAPI3REF: Status Parameters for prepared statements
  7139. ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
  7140. **
  7141. ** These preprocessor macros define integer codes that name counter
  7142. ** values associated with the [sqlite3_stmt_status()] interface.
  7143. ** The meanings of the various counters are as follows:
  7144. **
  7145. ** <dl>
  7146. ** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
  7147. ** <dd>^This is the number of times that SQLite has stepped forward in
  7148. ** a table as part of a full table scan. Large numbers for this counter
  7149. ** may indicate opportunities for performance improvement through
  7150. ** careful use of indices.</dd>
  7151. **
  7152. ** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
  7153. ** <dd>^This is the number of sort operations that have occurred.
  7154. ** A non-zero value in this counter may indicate an opportunity to
  7155. ** improvement performance through careful use of indices.</dd>
  7156. **
  7157. ** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
  7158. ** <dd>^This is the number of rows inserted into transient indices that
  7159. ** were created automatically in order to help joins run faster.
  7160. ** A non-zero value in this counter may indicate an opportunity to
  7161. ** improvement performance by adding permanent indices that do not
  7162. ** need to be reinitialized each time the statement is run.</dd>
  7163. **
  7164. ** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
  7165. ** <dd>^This is the number of virtual machine operations executed
  7166. ** by the prepared statement if that number is less than or equal
  7167. ** to 2147483647. The number of virtual machine operations can be
  7168. ** used as a proxy for the total work done by the prepared statement.
  7169. ** If the number of virtual machine operations exceeds 2147483647
  7170. ** then the value returned by this statement status code is undefined.
  7171. **
  7172. ** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
  7173. ** <dd>^This is the number of times that the prepare statement has been
  7174. ** automatically regenerated due to schema changes or change to
  7175. ** [bound parameters] that might affect the query plan.
  7176. **
  7177. ** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
  7178. ** <dd>^This is the number of times that the prepared statement has
  7179. ** been run. A single "run" for the purposes of this counter is one
  7180. ** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
  7181. ** The counter is incremented on the first [sqlite3_step()] call of each
  7182. ** cycle.
  7183. **
  7184. ** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
  7185. ** <dd>^This is the approximate number of bytes of heap memory
  7186. ** used to store the prepared statement. ^This value is not actually
  7187. ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
  7188. ** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
  7189. ** </dd>
  7190. ** </dl>
  7191. */
  7192. #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
  7193. #define SQLITE_STMTSTATUS_SORT 2
  7194. #define SQLITE_STMTSTATUS_AUTOINDEX 3
  7195. #define SQLITE_STMTSTATUS_VM_STEP 4
  7196. #define SQLITE_STMTSTATUS_REPREPARE 5
  7197. #define SQLITE_STMTSTATUS_RUN 6
  7198. #define SQLITE_STMTSTATUS_MEMUSED 99
  7199. /*
  7200. ** CAPI3REF: Custom Page Cache Object
  7201. **
  7202. ** The sqlite3_pcache type is opaque. It is implemented by
  7203. ** the pluggable module. The SQLite core has no knowledge of
  7204. ** its size or internal structure and never deals with the
  7205. ** sqlite3_pcache object except by holding and passing pointers
  7206. ** to the object.
  7207. **
  7208. ** See [sqlite3_pcache_methods2] for additional information.
  7209. */
  7210. typedef struct sqlite3_pcache sqlite3_pcache;
  7211. /*
  7212. ** CAPI3REF: Custom Page Cache Object
  7213. **
  7214. ** The sqlite3_pcache_page object represents a single page in the
  7215. ** page cache. The page cache will allocate instances of this
  7216. ** object. Various methods of the page cache use pointers to instances
  7217. ** of this object as parameters or as their return value.
  7218. **
  7219. ** See [sqlite3_pcache_methods2] for additional information.
  7220. */
  7221. typedef struct sqlite3_pcache_page sqlite3_pcache_page;
  7222. struct sqlite3_pcache_page {
  7223. void *pBuf; /* The content of the page */
  7224. void *pExtra; /* Extra information associated with the page */
  7225. };
  7226. /*
  7227. ** CAPI3REF: Application Defined Page Cache.
  7228. ** KEYWORDS: {page cache}
  7229. **
  7230. ** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
  7231. ** register an alternative page cache implementation by passing in an
  7232. ** instance of the sqlite3_pcache_methods2 structure.)^
  7233. ** In many applications, most of the heap memory allocated by
  7234. ** SQLite is used for the page cache.
  7235. ** By implementing a
  7236. ** custom page cache using this API, an application can better control
  7237. ** the amount of memory consumed by SQLite, the way in which
  7238. ** that memory is allocated and released, and the policies used to
  7239. ** determine exactly which parts of a database file are cached and for
  7240. ** how long.
  7241. **
  7242. ** The alternative page cache mechanism is an
  7243. ** extreme measure that is only needed by the most demanding applications.
  7244. ** The built-in page cache is recommended for most uses.
  7245. **
  7246. ** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
  7247. ** internal buffer by SQLite within the call to [sqlite3_config]. Hence
  7248. ** the application may discard the parameter after the call to
  7249. ** [sqlite3_config()] returns.)^
  7250. **
  7251. ** [[the xInit() page cache method]]
  7252. ** ^(The xInit() method is called once for each effective
  7253. ** call to [sqlite3_initialize()])^
  7254. ** (usually only once during the lifetime of the process). ^(The xInit()
  7255. ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
  7256. ** The intent of the xInit() method is to set up global data structures
  7257. ** required by the custom page cache implementation.
  7258. ** ^(If the xInit() method is NULL, then the
  7259. ** built-in default page cache is used instead of the application defined
  7260. ** page cache.)^
  7261. **
  7262. ** [[the xShutdown() page cache method]]
  7263. ** ^The xShutdown() method is called by [sqlite3_shutdown()].
  7264. ** It can be used to clean up
  7265. ** any outstanding resources before process shutdown, if required.
  7266. ** ^The xShutdown() method may be NULL.
  7267. **
  7268. ** ^SQLite automatically serializes calls to the xInit method,
  7269. ** so the xInit method need not be threadsafe. ^The
  7270. ** xShutdown method is only called from [sqlite3_shutdown()] so it does
  7271. ** not need to be threadsafe either. All other methods must be threadsafe
  7272. ** in multithreaded applications.
  7273. **
  7274. ** ^SQLite will never invoke xInit() more than once without an intervening
  7275. ** call to xShutdown().
  7276. **
  7277. ** [[the xCreate() page cache methods]]
  7278. ** ^SQLite invokes the xCreate() method to construct a new cache instance.
  7279. ** SQLite will typically create one cache instance for each open database file,
  7280. ** though this is not guaranteed. ^The
  7281. ** first parameter, szPage, is the size in bytes of the pages that must
  7282. ** be allocated by the cache. ^szPage will always a power of two. ^The
  7283. ** second parameter szExtra is a number of bytes of extra storage
  7284. ** associated with each page cache entry. ^The szExtra parameter will
  7285. ** a number less than 250. SQLite will use the
  7286. ** extra szExtra bytes on each page to store metadata about the underlying
  7287. ** database page on disk. The value passed into szExtra depends
  7288. ** on the SQLite version, the target platform, and how SQLite was compiled.
  7289. ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
  7290. ** created will be used to cache database pages of a file stored on disk, or
  7291. ** false if it is used for an in-memory database. The cache implementation
  7292. ** does not have to do anything special based with the value of bPurgeable;
  7293. ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
  7294. ** never invoke xUnpin() except to deliberately delete a page.
  7295. ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
  7296. ** false will always have the "discard" flag set to true.
  7297. ** ^Hence, a cache created with bPurgeable false will
  7298. ** never contain any unpinned pages.
  7299. **
  7300. ** [[the xCachesize() page cache method]]
  7301. ** ^(The xCachesize() method may be called at any time by SQLite to set the
  7302. ** suggested maximum cache-size (number of pages stored by) the cache
  7303. ** instance passed as the first argument. This is the value configured using
  7304. ** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
  7305. ** parameter, the implementation is not required to do anything with this
  7306. ** value; it is advisory only.
  7307. **
  7308. ** [[the xPagecount() page cache methods]]
  7309. ** The xPagecount() method must return the number of pages currently
  7310. ** stored in the cache, both pinned and unpinned.
  7311. **
  7312. ** [[the xFetch() page cache methods]]
  7313. ** The xFetch() method locates a page in the cache and returns a pointer to
  7314. ** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
  7315. ** The pBuf element of the returned sqlite3_pcache_page object will be a
  7316. ** pointer to a buffer of szPage bytes used to store the content of a
  7317. ** single database page. The pExtra element of sqlite3_pcache_page will be
  7318. ** a pointer to the szExtra bytes of extra storage that SQLite has requested
  7319. ** for each entry in the page cache.
  7320. **
  7321. ** The page to be fetched is determined by the key. ^The minimum key value
  7322. ** is 1. After it has been retrieved using xFetch, the page is considered
  7323. ** to be "pinned".
  7324. **
  7325. ** If the requested page is already in the page cache, then the page cache
  7326. ** implementation must return a pointer to the page buffer with its content
  7327. ** intact. If the requested page is not already in the cache, then the
  7328. ** cache implementation should use the value of the createFlag
  7329. ** parameter to help it determined what action to take:
  7330. **
  7331. ** <table border=1 width=85% align=center>
  7332. ** <tr><th> createFlag <th> Behavior when page is not already in cache
  7333. ** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
  7334. ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
  7335. ** Otherwise return NULL.
  7336. ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
  7337. ** NULL if allocating a new page is effectively impossible.
  7338. ** </table>
  7339. **
  7340. ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
  7341. ** will only use a createFlag of 2 after a prior call with a createFlag of 1
  7342. ** failed.)^ In between the to xFetch() calls, SQLite may
  7343. ** attempt to unpin one or more cache pages by spilling the content of
  7344. ** pinned pages to disk and synching the operating system disk cache.
  7345. **
  7346. ** [[the xUnpin() page cache method]]
  7347. ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
  7348. ** as its second argument. If the third parameter, discard, is non-zero,
  7349. ** then the page must be evicted from the cache.
  7350. ** ^If the discard parameter is
  7351. ** zero, then the page may be discarded or retained at the discretion of
  7352. ** page cache implementation. ^The page cache implementation
  7353. ** may choose to evict unpinned pages at any time.
  7354. **
  7355. ** The cache must not perform any reference counting. A single
  7356. ** call to xUnpin() unpins the page regardless of the number of prior calls
  7357. ** to xFetch().
  7358. **
  7359. ** [[the xRekey() page cache methods]]
  7360. ** The xRekey() method is used to change the key value associated with the
  7361. ** page passed as the second argument. If the cache
  7362. ** previously contains an entry associated with newKey, it must be
  7363. ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
  7364. ** to be pinned.
  7365. **
  7366. ** When SQLite calls the xTruncate() method, the cache must discard all
  7367. ** existing cache entries with page numbers (keys) greater than or equal
  7368. ** to the value of the iLimit parameter passed to xTruncate(). If any
  7369. ** of these pages are pinned, they are implicitly unpinned, meaning that
  7370. ** they can be safely discarded.
  7371. **
  7372. ** [[the xDestroy() page cache method]]
  7373. ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
  7374. ** All resources associated with the specified cache should be freed. ^After
  7375. ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
  7376. ** handle invalid, and will not use it with any other sqlite3_pcache_methods2
  7377. ** functions.
  7378. **
  7379. ** [[the xShrink() page cache method]]
  7380. ** ^SQLite invokes the xShrink() method when it wants the page cache to
  7381. ** free up as much of heap memory as possible. The page cache implementation
  7382. ** is not obligated to free any memory, but well-behaved implementations should
  7383. ** do their best.
  7384. */
  7385. typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
  7386. struct sqlite3_pcache_methods2 {
  7387. int iVersion;
  7388. void *pArg;
  7389. int (*xInit)(void*);
  7390. void (*xShutdown)(void*);
  7391. sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
  7392. void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  7393. int (*xPagecount)(sqlite3_pcache*);
  7394. sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  7395. void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  7396. void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
  7397. unsigned oldKey, unsigned newKey);
  7398. void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  7399. void (*xDestroy)(sqlite3_pcache*);
  7400. void (*xShrink)(sqlite3_pcache*);
  7401. };
  7402. /*
  7403. ** This is the obsolete pcache_methods object that has now been replaced
  7404. ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
  7405. ** retained in the header file for backwards compatibility only.
  7406. */
  7407. typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
  7408. struct sqlite3_pcache_methods {
  7409. void *pArg;
  7410. int (*xInit)(void*);
  7411. void (*xShutdown)(void*);
  7412. sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
  7413. void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  7414. int (*xPagecount)(sqlite3_pcache*);
  7415. void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  7416. void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  7417. void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  7418. void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  7419. void (*xDestroy)(sqlite3_pcache*);
  7420. };
  7421. /*
  7422. ** CAPI3REF: Online Backup Object
  7423. **
  7424. ** The sqlite3_backup object records state information about an ongoing
  7425. ** online backup operation. ^The sqlite3_backup object is created by
  7426. ** a call to [sqlite3_backup_init()] and is destroyed by a call to
  7427. ** [sqlite3_backup_finish()].
  7428. **
  7429. ** See Also: [Using the SQLite Online Backup API]
  7430. */
  7431. typedef struct sqlite3_backup sqlite3_backup;
  7432. /*
  7433. ** CAPI3REF: Online Backup API.
  7434. **
  7435. ** The backup API copies the content of one database into another.
  7436. ** It is useful either for creating backups of databases or
  7437. ** for copying in-memory databases to or from persistent files.
  7438. **
  7439. ** See Also: [Using the SQLite Online Backup API]
  7440. **
  7441. ** ^SQLite holds a write transaction open on the destination database file
  7442. ** for the duration of the backup operation.
  7443. ** ^The source database is read-locked only while it is being read;
  7444. ** it is not locked continuously for the entire backup operation.
  7445. ** ^Thus, the backup may be performed on a live source database without
  7446. ** preventing other database connections from
  7447. ** reading or writing to the source database while the backup is underway.
  7448. **
  7449. ** ^(To perform a backup operation:
  7450. ** <ol>
  7451. ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
  7452. ** backup,
  7453. ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
  7454. ** the data between the two databases, and finally
  7455. ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
  7456. ** associated with the backup operation.
  7457. ** </ol>)^
  7458. ** There should be exactly one call to sqlite3_backup_finish() for each
  7459. ** successful call to sqlite3_backup_init().
  7460. **
  7461. ** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
  7462. **
  7463. ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
  7464. ** [database connection] associated with the destination database
  7465. ** and the database name, respectively.
  7466. ** ^The database name is "main" for the main database, "temp" for the
  7467. ** temporary database, or the name specified after the AS keyword in
  7468. ** an [ATTACH] statement for an attached database.
  7469. ** ^The S and M arguments passed to
  7470. ** sqlite3_backup_init(D,N,S,M) identify the [database connection]
  7471. ** and database name of the source database, respectively.
  7472. ** ^The source and destination [database connections] (parameters S and D)
  7473. ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
  7474. ** an error.
  7475. **
  7476. ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
  7477. ** there is already a read or read-write transaction open on the
  7478. ** destination database.
  7479. **
  7480. ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
  7481. ** returned and an error code and error message are stored in the
  7482. ** destination [database connection] D.
  7483. ** ^The error code and message for the failed call to sqlite3_backup_init()
  7484. ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
  7485. ** [sqlite3_errmsg16()] functions.
  7486. ** ^A successful call to sqlite3_backup_init() returns a pointer to an
  7487. ** [sqlite3_backup] object.
  7488. ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
  7489. ** sqlite3_backup_finish() functions to perform the specified backup
  7490. ** operation.
  7491. **
  7492. ** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
  7493. **
  7494. ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
  7495. ** the source and destination databases specified by [sqlite3_backup] object B.
  7496. ** ^If N is negative, all remaining source pages are copied.
  7497. ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
  7498. ** are still more pages to be copied, then the function returns [SQLITE_OK].
  7499. ** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
  7500. ** from source to destination, then it returns [SQLITE_DONE].
  7501. ** ^If an error occurs while running sqlite3_backup_step(B,N),
  7502. ** then an [error code] is returned. ^As well as [SQLITE_OK] and
  7503. ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
  7504. ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
  7505. ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
  7506. **
  7507. ** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
  7508. ** <ol>
  7509. ** <li> the destination database was opened read-only, or
  7510. ** <li> the destination database is using write-ahead-log journaling
  7511. ** and the destination and source page sizes differ, or
  7512. ** <li> the destination database is an in-memory database and the
  7513. ** destination and source page sizes differ.
  7514. ** </ol>)^
  7515. **
  7516. ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
  7517. ** the [sqlite3_busy_handler | busy-handler function]
  7518. ** is invoked (if one is specified). ^If the
  7519. ** busy-handler returns non-zero before the lock is available, then
  7520. ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
  7521. ** sqlite3_backup_step() can be retried later. ^If the source
  7522. ** [database connection]
  7523. ** is being used to write to the source database when sqlite3_backup_step()
  7524. ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
  7525. ** case the call to sqlite3_backup_step() can be retried later on. ^(If
  7526. ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
  7527. ** [SQLITE_READONLY] is returned, then
  7528. ** there is no point in retrying the call to sqlite3_backup_step(). These
  7529. ** errors are considered fatal.)^ The application must accept
  7530. ** that the backup operation has failed and pass the backup operation handle
  7531. ** to the sqlite3_backup_finish() to release associated resources.
  7532. **
  7533. ** ^The first call to sqlite3_backup_step() obtains an exclusive lock
  7534. ** on the destination file. ^The exclusive lock is not released until either
  7535. ** sqlite3_backup_finish() is called or the backup operation is complete
  7536. ** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
  7537. ** sqlite3_backup_step() obtains a [shared lock] on the source database that
  7538. ** lasts for the duration of the sqlite3_backup_step() call.
  7539. ** ^Because the source database is not locked between calls to
  7540. ** sqlite3_backup_step(), the source database may be modified mid-way
  7541. ** through the backup process. ^If the source database is modified by an
  7542. ** external process or via a database connection other than the one being
  7543. ** used by the backup operation, then the backup will be automatically
  7544. ** restarted by the next call to sqlite3_backup_step(). ^If the source
  7545. ** database is modified by the using the same database connection as is used
  7546. ** by the backup operation, then the backup database is automatically
  7547. ** updated at the same time.
  7548. **
  7549. ** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
  7550. **
  7551. ** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
  7552. ** application wishes to abandon the backup operation, the application
  7553. ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
  7554. ** ^The sqlite3_backup_finish() interfaces releases all
  7555. ** resources associated with the [sqlite3_backup] object.
  7556. ** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
  7557. ** active write-transaction on the destination database is rolled back.
  7558. ** The [sqlite3_backup] object is invalid
  7559. ** and may not be used following a call to sqlite3_backup_finish().
  7560. **
  7561. ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
  7562. ** sqlite3_backup_step() errors occurred, regardless or whether or not
  7563. ** sqlite3_backup_step() completed.
  7564. ** ^If an out-of-memory condition or IO error occurred during any prior
  7565. ** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
  7566. ** sqlite3_backup_finish() returns the corresponding [error code].
  7567. **
  7568. ** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
  7569. ** is not a permanent error and does not affect the return value of
  7570. ** sqlite3_backup_finish().
  7571. **
  7572. ** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
  7573. ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
  7574. **
  7575. ** ^The sqlite3_backup_remaining() routine returns the number of pages still
  7576. ** to be backed up at the conclusion of the most recent sqlite3_backup_step().
  7577. ** ^The sqlite3_backup_pagecount() routine returns the total number of pages
  7578. ** in the source database at the conclusion of the most recent
  7579. ** sqlite3_backup_step().
  7580. ** ^(The values returned by these functions are only updated by
  7581. ** sqlite3_backup_step(). If the source database is modified in a way that
  7582. ** changes the size of the source database or the number of pages remaining,
  7583. ** those changes are not reflected in the output of sqlite3_backup_pagecount()
  7584. ** and sqlite3_backup_remaining() until after the next
  7585. ** sqlite3_backup_step().)^
  7586. **
  7587. ** <b>Concurrent Usage of Database Handles</b>
  7588. **
  7589. ** ^The source [database connection] may be used by the application for other
  7590. ** purposes while a backup operation is underway or being initialized.
  7591. ** ^If SQLite is compiled and configured to support threadsafe database
  7592. ** connections, then the source database connection may be used concurrently
  7593. ** from within other threads.
  7594. **
  7595. ** However, the application must guarantee that the destination
  7596. ** [database connection] is not passed to any other API (by any thread) after
  7597. ** sqlite3_backup_init() is called and before the corresponding call to
  7598. ** sqlite3_backup_finish(). SQLite does not currently check to see
  7599. ** if the application incorrectly accesses the destination [database connection]
  7600. ** and so no error code is reported, but the operations may malfunction
  7601. ** nevertheless. Use of the destination database connection while a
  7602. ** backup is in progress might also also cause a mutex deadlock.
  7603. **
  7604. ** If running in [shared cache mode], the application must
  7605. ** guarantee that the shared cache used by the destination database
  7606. ** is not accessed while the backup is running. In practice this means
  7607. ** that the application must guarantee that the disk file being
  7608. ** backed up to is not accessed by any connection within the process,
  7609. ** not just the specific connection that was passed to sqlite3_backup_init().
  7610. **
  7611. ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
  7612. ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
  7613. ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
  7614. ** APIs are not strictly speaking threadsafe. If they are invoked at the
  7615. ** same time as another thread is invoking sqlite3_backup_step() it is
  7616. ** possible that they return invalid values.
  7617. */
  7618. SQLITE_API sqlite3_backup *sqlite3_backup_init(
  7619. sqlite3 *pDest, /* Destination database handle */
  7620. const char *zDestName, /* Destination database name */
  7621. sqlite3 *pSource, /* Source database handle */
  7622. const char *zSourceName /* Source database name */
  7623. );
  7624. SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
  7625. SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
  7626. SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
  7627. SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
  7628. /*
  7629. ** CAPI3REF: Unlock Notification
  7630. ** METHOD: sqlite3
  7631. **
  7632. ** ^When running in shared-cache mode, a database operation may fail with
  7633. ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
  7634. ** individual tables within the shared-cache cannot be obtained. See
  7635. ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
  7636. ** ^This API may be used to register a callback that SQLite will invoke
  7637. ** when the connection currently holding the required lock relinquishes it.
  7638. ** ^This API is only available if the library was compiled with the
  7639. ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
  7640. **
  7641. ** See Also: [Using the SQLite Unlock Notification Feature].
  7642. **
  7643. ** ^Shared-cache locks are released when a database connection concludes
  7644. ** its current transaction, either by committing it or rolling it back.
  7645. **
  7646. ** ^When a connection (known as the blocked connection) fails to obtain a
  7647. ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
  7648. ** identity of the database connection (the blocking connection) that
  7649. ** has locked the required resource is stored internally. ^After an
  7650. ** application receives an SQLITE_LOCKED error, it may call the
  7651. ** sqlite3_unlock_notify() method with the blocked connection handle as
  7652. ** the first argument to register for a callback that will be invoked
  7653. ** when the blocking connections current transaction is concluded. ^The
  7654. ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
  7655. ** call that concludes the blocking connections transaction.
  7656. **
  7657. ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
  7658. ** there is a chance that the blocking connection will have already
  7659. ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
  7660. ** If this happens, then the specified callback is invoked immediately,
  7661. ** from within the call to sqlite3_unlock_notify().)^
  7662. **
  7663. ** ^If the blocked connection is attempting to obtain a write-lock on a
  7664. ** shared-cache table, and more than one other connection currently holds
  7665. ** a read-lock on the same table, then SQLite arbitrarily selects one of
  7666. ** the other connections to use as the blocking connection.
  7667. **
  7668. ** ^(There may be at most one unlock-notify callback registered by a
  7669. ** blocked connection. If sqlite3_unlock_notify() is called when the
  7670. ** blocked connection already has a registered unlock-notify callback,
  7671. ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
  7672. ** called with a NULL pointer as its second argument, then any existing
  7673. ** unlock-notify callback is canceled. ^The blocked connections
  7674. ** unlock-notify callback may also be canceled by closing the blocked
  7675. ** connection using [sqlite3_close()].
  7676. **
  7677. ** The unlock-notify callback is not reentrant. If an application invokes
  7678. ** any sqlite3_xxx API functions from within an unlock-notify callback, a
  7679. ** crash or deadlock may be the result.
  7680. **
  7681. ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
  7682. ** returns SQLITE_OK.
  7683. **
  7684. ** <b>Callback Invocation Details</b>
  7685. **
  7686. ** When an unlock-notify callback is registered, the application provides a
  7687. ** single void* pointer that is passed to the callback when it is invoked.
  7688. ** However, the signature of the callback function allows SQLite to pass
  7689. ** it an array of void* context pointers. The first argument passed to
  7690. ** an unlock-notify callback is a pointer to an array of void* pointers,
  7691. ** and the second is the number of entries in the array.
  7692. **
  7693. ** When a blocking connections transaction is concluded, there may be
  7694. ** more than one blocked connection that has registered for an unlock-notify
  7695. ** callback. ^If two or more such blocked connections have specified the
  7696. ** same callback function, then instead of invoking the callback function
  7697. ** multiple times, it is invoked once with the set of void* context pointers
  7698. ** specified by the blocked connections bundled together into an array.
  7699. ** This gives the application an opportunity to prioritize any actions
  7700. ** related to the set of unblocked database connections.
  7701. **
  7702. ** <b>Deadlock Detection</b>
  7703. **
  7704. ** Assuming that after registering for an unlock-notify callback a
  7705. ** database waits for the callback to be issued before taking any further
  7706. ** action (a reasonable assumption), then using this API may cause the
  7707. ** application to deadlock. For example, if connection X is waiting for
  7708. ** connection Y's transaction to be concluded, and similarly connection
  7709. ** Y is waiting on connection X's transaction, then neither connection
  7710. ** will proceed and the system may remain deadlocked indefinitely.
  7711. **
  7712. ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
  7713. ** detection. ^If a given call to sqlite3_unlock_notify() would put the
  7714. ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
  7715. ** unlock-notify callback is registered. The system is said to be in
  7716. ** a deadlocked state if connection A has registered for an unlock-notify
  7717. ** callback on the conclusion of connection B's transaction, and connection
  7718. ** B has itself registered for an unlock-notify callback when connection
  7719. ** A's transaction is concluded. ^Indirect deadlock is also detected, so
  7720. ** the system is also considered to be deadlocked if connection B has
  7721. ** registered for an unlock-notify callback on the conclusion of connection
  7722. ** C's transaction, where connection C is waiting on connection A. ^Any
  7723. ** number of levels of indirection are allowed.
  7724. **
  7725. ** <b>The "DROP TABLE" Exception</b>
  7726. **
  7727. ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
  7728. ** always appropriate to call sqlite3_unlock_notify(). There is however,
  7729. ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
  7730. ** SQLite checks if there are any currently executing SELECT statements
  7731. ** that belong to the same connection. If there are, SQLITE_LOCKED is
  7732. ** returned. In this case there is no "blocking connection", so invoking
  7733. ** sqlite3_unlock_notify() results in the unlock-notify callback being
  7734. ** invoked immediately. If the application then re-attempts the "DROP TABLE"
  7735. ** or "DROP INDEX" query, an infinite loop might be the result.
  7736. **
  7737. ** One way around this problem is to check the extended error code returned
  7738. ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
  7739. ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
  7740. ** the special "DROP TABLE/INDEX" case, the extended error code is just
  7741. ** SQLITE_LOCKED.)^
  7742. */
  7743. SQLITE_API int sqlite3_unlock_notify(
  7744. sqlite3 *pBlocked, /* Waiting connection */
  7745. void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
  7746. void *pNotifyArg /* Argument to pass to xNotify */
  7747. );
  7748. /*
  7749. ** CAPI3REF: String Comparison
  7750. **
  7751. ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
  7752. ** and extensions to compare the contents of two buffers containing UTF-8
  7753. ** strings in a case-independent fashion, using the same definition of "case
  7754. ** independence" that SQLite uses internally when comparing identifiers.
  7755. */
  7756. SQLITE_API int sqlite3_stricmp(const char *, const char *);
  7757. SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
  7758. /*
  7759. ** CAPI3REF: String Globbing
  7760. *
  7761. ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
  7762. ** string X matches the [GLOB] pattern P.
  7763. ** ^The definition of [GLOB] pattern matching used in
  7764. ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
  7765. ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
  7766. ** is case sensitive.
  7767. **
  7768. ** Note that this routine returns zero on a match and non-zero if the strings
  7769. ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
  7770. **
  7771. ** See also: [sqlite3_strlike()].
  7772. */
  7773. SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
  7774. /*
  7775. ** CAPI3REF: String LIKE Matching
  7776. *
  7777. ** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
  7778. ** string X matches the [LIKE] pattern P with escape character E.
  7779. ** ^The definition of [LIKE] pattern matching used in
  7780. ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
  7781. ** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
  7782. ** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
  7783. ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
  7784. ** insensitive - equivalent upper and lower case ASCII characters match
  7785. ** one another.
  7786. **
  7787. ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
  7788. ** only ASCII characters are case folded.
  7789. **
  7790. ** Note that this routine returns zero on a match and non-zero if the strings
  7791. ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
  7792. **
  7793. ** See also: [sqlite3_strglob()].
  7794. */
  7795. SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
  7796. /*
  7797. ** CAPI3REF: Error Logging Interface
  7798. **
  7799. ** ^The [sqlite3_log()] interface writes a message into the [error log]
  7800. ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
  7801. ** ^If logging is enabled, the zFormat string and subsequent arguments are
  7802. ** used with [sqlite3_snprintf()] to generate the final output string.
  7803. **
  7804. ** The sqlite3_log() interface is intended for use by extensions such as
  7805. ** virtual tables, collating functions, and SQL functions. While there is
  7806. ** nothing to prevent an application from calling sqlite3_log(), doing so
  7807. ** is considered bad form.
  7808. **
  7809. ** The zFormat string must not be NULL.
  7810. **
  7811. ** To avoid deadlocks and other threading problems, the sqlite3_log() routine
  7812. ** will not use dynamically allocated memory. The log message is stored in
  7813. ** a fixed-length buffer on the stack. If the log message is longer than
  7814. ** a few hundred characters, it will be truncated to the length of the
  7815. ** buffer.
  7816. */
  7817. SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
  7818. /*
  7819. ** CAPI3REF: Write-Ahead Log Commit Hook
  7820. ** METHOD: sqlite3
  7821. **
  7822. ** ^The [sqlite3_wal_hook()] function is used to register a callback that
  7823. ** is invoked each time data is committed to a database in wal mode.
  7824. **
  7825. ** ^(The callback is invoked by SQLite after the commit has taken place and
  7826. ** the associated write-lock on the database released)^, so the implementation
  7827. ** may read, write or [checkpoint] the database as required.
  7828. **
  7829. ** ^The first parameter passed to the callback function when it is invoked
  7830. ** is a copy of the third parameter passed to sqlite3_wal_hook() when
  7831. ** registering the callback. ^The second is a copy of the database handle.
  7832. ** ^The third parameter is the name of the database that was written to -
  7833. ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
  7834. ** is the number of pages currently in the write-ahead log file,
  7835. ** including those that were just committed.
  7836. **
  7837. ** The callback function should normally return [SQLITE_OK]. ^If an error
  7838. ** code is returned, that error will propagate back up through the
  7839. ** SQLite code base to cause the statement that provoked the callback
  7840. ** to report an error, though the commit will have still occurred. If the
  7841. ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
  7842. ** that does not correspond to any valid SQLite error code, the results
  7843. ** are undefined.
  7844. **
  7845. ** A single database handle may have at most a single write-ahead log callback
  7846. ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
  7847. ** previously registered write-ahead log callback. ^Note that the
  7848. ** [sqlite3_wal_autocheckpoint()] interface and the
  7849. ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
  7850. ** overwrite any prior [sqlite3_wal_hook()] settings.
  7851. */
  7852. SQLITE_API void *sqlite3_wal_hook(
  7853. sqlite3*,
  7854. int(*)(void *,sqlite3*,const char*,int),
  7855. void*
  7856. );
  7857. /*
  7858. ** CAPI3REF: Configure an auto-checkpoint
  7859. ** METHOD: sqlite3
  7860. **
  7861. ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
  7862. ** [sqlite3_wal_hook()] that causes any database on [database connection] D
  7863. ** to automatically [checkpoint]
  7864. ** after committing a transaction if there are N or
  7865. ** more frames in the [write-ahead log] file. ^Passing zero or
  7866. ** a negative value as the nFrame parameter disables automatic
  7867. ** checkpoints entirely.
  7868. **
  7869. ** ^The callback registered by this function replaces any existing callback
  7870. ** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
  7871. ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
  7872. ** configured by this function.
  7873. **
  7874. ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
  7875. ** from SQL.
  7876. **
  7877. ** ^Checkpoints initiated by this mechanism are
  7878. ** [sqlite3_wal_checkpoint_v2|PASSIVE].
  7879. **
  7880. ** ^Every new [database connection] defaults to having the auto-checkpoint
  7881. ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
  7882. ** pages. The use of this interface
  7883. ** is only necessary if the default setting is found to be suboptimal
  7884. ** for a particular application.
  7885. */
  7886. SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
  7887. /*
  7888. ** CAPI3REF: Checkpoint a database
  7889. ** METHOD: sqlite3
  7890. **
  7891. ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
  7892. ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
  7893. **
  7894. ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
  7895. ** [write-ahead log] for database X on [database connection] D to be
  7896. ** transferred into the database file and for the write-ahead log to
  7897. ** be reset. See the [checkpointing] documentation for addition
  7898. ** information.
  7899. **
  7900. ** This interface used to be the only way to cause a checkpoint to
  7901. ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
  7902. ** interface was added. This interface is retained for backwards
  7903. ** compatibility and as a convenience for applications that need to manually
  7904. ** start a callback but which do not need the full power (and corresponding
  7905. ** complication) of [sqlite3_wal_checkpoint_v2()].
  7906. */
  7907. SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
  7908. /*
  7909. ** CAPI3REF: Checkpoint a database
  7910. ** METHOD: sqlite3
  7911. **
  7912. ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
  7913. ** operation on database X of [database connection] D in mode M. Status
  7914. ** information is written back into integers pointed to by L and C.)^
  7915. ** ^(The M parameter must be a valid [checkpoint mode]:)^
  7916. **
  7917. ** <dl>
  7918. ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
  7919. ** ^Checkpoint as many frames as possible without waiting for any database
  7920. ** readers or writers to finish, then sync the database file if all frames
  7921. ** in the log were checkpointed. ^The [busy-handler callback]
  7922. ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
  7923. ** ^On the other hand, passive mode might leave the checkpoint unfinished
  7924. ** if there are concurrent readers or writers.
  7925. **
  7926. ** <dt>SQLITE_CHECKPOINT_FULL<dd>
  7927. ** ^This mode blocks (it invokes the
  7928. ** [sqlite3_busy_handler|busy-handler callback]) until there is no
  7929. ** database writer and all readers are reading from the most recent database
  7930. ** snapshot. ^It then checkpoints all frames in the log file and syncs the
  7931. ** database file. ^This mode blocks new database writers while it is pending,
  7932. ** but new database readers are allowed to continue unimpeded.
  7933. **
  7934. ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
  7935. ** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
  7936. ** that after checkpointing the log file it blocks (calls the
  7937. ** [busy-handler callback])
  7938. ** until all readers are reading from the database file only. ^This ensures
  7939. ** that the next writer will restart the log file from the beginning.
  7940. ** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
  7941. ** database writer attempts while it is pending, but does not impede readers.
  7942. **
  7943. ** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
  7944. ** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
  7945. ** addition that it also truncates the log file to zero bytes just prior
  7946. ** to a successful return.
  7947. ** </dl>
  7948. **
  7949. ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
  7950. ** the log file or to -1 if the checkpoint could not run because
  7951. ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
  7952. ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
  7953. ** log file (including any that were already checkpointed before the function
  7954. ** was called) or to -1 if the checkpoint could not run due to an error or
  7955. ** because the database is not in WAL mode. ^Note that upon successful
  7956. ** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
  7957. ** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
  7958. **
  7959. ** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
  7960. ** any other process is running a checkpoint operation at the same time, the
  7961. ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
  7962. ** busy-handler configured, it will not be invoked in this case.
  7963. **
  7964. ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
  7965. ** exclusive "writer" lock on the database file. ^If the writer lock cannot be
  7966. ** obtained immediately, and a busy-handler is configured, it is invoked and
  7967. ** the writer lock retried until either the busy-handler returns 0 or the lock
  7968. ** is successfully obtained. ^The busy-handler is also invoked while waiting for
  7969. ** database readers as described above. ^If the busy-handler returns 0 before
  7970. ** the writer lock is obtained or while waiting for database readers, the
  7971. ** checkpoint operation proceeds from that point in the same way as
  7972. ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
  7973. ** without blocking any further. ^SQLITE_BUSY is returned in this case.
  7974. **
  7975. ** ^If parameter zDb is NULL or points to a zero length string, then the
  7976. ** specified operation is attempted on all WAL databases [attached] to
  7977. ** [database connection] db. In this case the
  7978. ** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
  7979. ** an SQLITE_BUSY error is encountered when processing one or more of the
  7980. ** attached WAL databases, the operation is still attempted on any remaining
  7981. ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
  7982. ** error occurs while processing an attached database, processing is abandoned
  7983. ** and the error code is returned to the caller immediately. ^If no error
  7984. ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
  7985. ** databases, SQLITE_OK is returned.
  7986. **
  7987. ** ^If database zDb is the name of an attached database that is not in WAL
  7988. ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
  7989. ** zDb is not NULL (or a zero length string) and is not the name of any
  7990. ** attached database, SQLITE_ERROR is returned to the caller.
  7991. **
  7992. ** ^Unless it returns SQLITE_MISUSE,
  7993. ** the sqlite3_wal_checkpoint_v2() interface
  7994. ** sets the error information that is queried by
  7995. ** [sqlite3_errcode()] and [sqlite3_errmsg()].
  7996. **
  7997. ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
  7998. ** from SQL.
  7999. */
  8000. SQLITE_API int sqlite3_wal_checkpoint_v2(
  8001. sqlite3 *db, /* Database handle */
  8002. const char *zDb, /* Name of attached database (or NULL) */
  8003. int eMode, /* SQLITE_CHECKPOINT_* value */
  8004. int *pnLog, /* OUT: Size of WAL log in frames */
  8005. int *pnCkpt /* OUT: Total number of frames checkpointed */
  8006. );
  8007. /*
  8008. ** CAPI3REF: Checkpoint Mode Values
  8009. ** KEYWORDS: {checkpoint mode}
  8010. **
  8011. ** These constants define all valid values for the "checkpoint mode" passed
  8012. ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
  8013. ** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
  8014. ** meaning of each of these checkpoint modes.
  8015. */
  8016. #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
  8017. #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
  8018. #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
  8019. #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
  8020. /*
  8021. ** CAPI3REF: Virtual Table Interface Configuration
  8022. **
  8023. ** This function may be called by either the [xConnect] or [xCreate] method
  8024. ** of a [virtual table] implementation to configure
  8025. ** various facets of the virtual table interface.
  8026. **
  8027. ** If this interface is invoked outside the context of an xConnect or
  8028. ** xCreate virtual table method then the behavior is undefined.
  8029. **
  8030. ** At present, there is only one option that may be configured using
  8031. ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
  8032. ** may be added in the future.
  8033. */
  8034. SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
  8035. /*
  8036. ** CAPI3REF: Virtual Table Configuration Options
  8037. **
  8038. ** These macros define the various options to the
  8039. ** [sqlite3_vtab_config()] interface that [virtual table] implementations
  8040. ** can use to customize and optimize their behavior.
  8041. **
  8042. ** <dl>
  8043. ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
  8044. ** <dd>Calls of the form
  8045. ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
  8046. ** where X is an integer. If X is zero, then the [virtual table] whose
  8047. ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
  8048. ** support constraints. In this configuration (which is the default) if
  8049. ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
  8050. ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
  8051. ** specified as part of the users SQL statement, regardless of the actual
  8052. ** ON CONFLICT mode specified.
  8053. **
  8054. ** If X is non-zero, then the virtual table implementation guarantees
  8055. ** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
  8056. ** any modifications to internal or persistent data structures have been made.
  8057. ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
  8058. ** is able to roll back a statement or database transaction, and abandon
  8059. ** or continue processing the current SQL statement as appropriate.
  8060. ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
  8061. ** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
  8062. ** had been ABORT.
  8063. **
  8064. ** Virtual table implementations that are required to handle OR REPLACE
  8065. ** must do so within the [xUpdate] method. If a call to the
  8066. ** [sqlite3_vtab_on_conflict()] function indicates that the current ON
  8067. ** CONFLICT policy is REPLACE, the virtual table implementation should
  8068. ** silently replace the appropriate rows within the xUpdate callback and
  8069. ** return SQLITE_OK. Or, if this is not possible, it may return
  8070. ** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
  8071. ** constraint handling.
  8072. ** </dl>
  8073. */
  8074. #define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
  8075. /*
  8076. ** CAPI3REF: Determine The Virtual Table Conflict Policy
  8077. **
  8078. ** This function may only be called from within a call to the [xUpdate] method
  8079. ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
  8080. ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
  8081. ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
  8082. ** of the SQL statement that triggered the call to the [xUpdate] method of the
  8083. ** [virtual table].
  8084. */
  8085. SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
  8086. /*
  8087. ** CAPI3REF: Conflict resolution modes
  8088. ** KEYWORDS: {conflict resolution mode}
  8089. **
  8090. ** These constants are returned by [sqlite3_vtab_on_conflict()] to
  8091. ** inform a [virtual table] implementation what the [ON CONFLICT] mode
  8092. ** is for the SQL statement being evaluated.
  8093. **
  8094. ** Note that the [SQLITE_IGNORE] constant is also used as a potential
  8095. ** return value from the [sqlite3_set_authorizer()] callback and that
  8096. ** [SQLITE_ABORT] is also a [result code].
  8097. */
  8098. #define SQLITE_ROLLBACK 1
  8099. /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
  8100. #define SQLITE_FAIL 3
  8101. /* #define SQLITE_ABORT 4 // Also an error code */
  8102. #define SQLITE_REPLACE 5
  8103. /*
  8104. ** CAPI3REF: Prepared Statement Scan Status Opcodes
  8105. ** KEYWORDS: {scanstatus options}
  8106. **
  8107. ** The following constants can be used for the T parameter to the
  8108. ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
  8109. ** different metric for sqlite3_stmt_scanstatus() to return.
  8110. **
  8111. ** When the value returned to V is a string, space to hold that string is
  8112. ** managed by the prepared statement S and will be automatically freed when
  8113. ** S is finalized.
  8114. **
  8115. ** <dl>
  8116. ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
  8117. ** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
  8118. ** set to the total number of times that the X-th loop has run.</dd>
  8119. **
  8120. ** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
  8121. ** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
  8122. ** to the total number of rows examined by all iterations of the X-th loop.</dd>
  8123. **
  8124. ** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
  8125. ** <dd>^The "double" variable pointed to by the T parameter will be set to the
  8126. ** query planner's estimate for the average number of rows output from each
  8127. ** iteration of the X-th loop. If the query planner's estimates was accurate,
  8128. ** then this value will approximate the quotient NVISIT/NLOOP and the
  8129. ** product of this value for all prior loops with the same SELECTID will
  8130. ** be the NLOOP value for the current loop.
  8131. **
  8132. ** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
  8133. ** <dd>^The "const char *" variable pointed to by the T parameter will be set
  8134. ** to a zero-terminated UTF-8 string containing the name of the index or table
  8135. ** used for the X-th loop.
  8136. **
  8137. ** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
  8138. ** <dd>^The "const char *" variable pointed to by the T parameter will be set
  8139. ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
  8140. ** description for the X-th loop.
  8141. **
  8142. ** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
  8143. ** <dd>^The "int" variable pointed to by the T parameter will be set to the
  8144. ** "select-id" for the X-th loop. The select-id identifies which query or
  8145. ** subquery the loop is part of. The main query has a select-id of zero.
  8146. ** The select-id is the same value as is output in the first column
  8147. ** of an [EXPLAIN QUERY PLAN] query.
  8148. ** </dl>
  8149. */
  8150. #define SQLITE_SCANSTAT_NLOOP 0
  8151. #define SQLITE_SCANSTAT_NVISIT 1
  8152. #define SQLITE_SCANSTAT_EST 2
  8153. #define SQLITE_SCANSTAT_NAME 3
  8154. #define SQLITE_SCANSTAT_EXPLAIN 4
  8155. #define SQLITE_SCANSTAT_SELECTID 5
  8156. /*
  8157. ** CAPI3REF: Prepared Statement Scan Status
  8158. ** METHOD: sqlite3_stmt
  8159. **
  8160. ** This interface returns information about the predicted and measured
  8161. ** performance for pStmt. Advanced applications can use this
  8162. ** interface to compare the predicted and the measured performance and
  8163. ** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
  8164. **
  8165. ** Since this interface is expected to be rarely used, it is only
  8166. ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
  8167. ** compile-time option.
  8168. **
  8169. ** The "iScanStatusOp" parameter determines which status information to return.
  8170. ** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
  8171. ** of this interface is undefined.
  8172. ** ^The requested measurement is written into a variable pointed to by
  8173. ** the "pOut" parameter.
  8174. ** Parameter "idx" identifies the specific loop to retrieve statistics for.
  8175. ** Loops are numbered starting from zero. ^If idx is out of range - less than
  8176. ** zero or greater than or equal to the total number of loops used to implement
  8177. ** the statement - a non-zero value is returned and the variable that pOut
  8178. ** points to is unchanged.
  8179. **
  8180. ** ^Statistics might not be available for all loops in all statements. ^In cases
  8181. ** where there exist loops with no available statistics, this function behaves
  8182. ** as if the loop did not exist - it returns non-zero and leave the variable
  8183. ** that pOut points to unchanged.
  8184. **
  8185. ** See also: [sqlite3_stmt_scanstatus_reset()]
  8186. */
  8187. SQLITE_API int sqlite3_stmt_scanstatus(
  8188. sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
  8189. int idx, /* Index of loop to report on */
  8190. int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
  8191. void *pOut /* Result written here */
  8192. );
  8193. /*
  8194. ** CAPI3REF: Zero Scan-Status Counters
  8195. ** METHOD: sqlite3_stmt
  8196. **
  8197. ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
  8198. **
  8199. ** This API is only available if the library is built with pre-processor
  8200. ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
  8201. */
  8202. SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
  8203. /*
  8204. ** CAPI3REF: Flush caches to disk mid-transaction
  8205. **
  8206. ** ^If a write-transaction is open on [database connection] D when the
  8207. ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
  8208. ** pages in the pager-cache that are not currently in use are written out
  8209. ** to disk. A dirty page may be in use if a database cursor created by an
  8210. ** active SQL statement is reading from it, or if it is page 1 of a database
  8211. ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
  8212. ** interface flushes caches for all schemas - "main", "temp", and
  8213. ** any [attached] databases.
  8214. **
  8215. ** ^If this function needs to obtain extra database locks before dirty pages
  8216. ** can be flushed to disk, it does so. ^If those locks cannot be obtained
  8217. ** immediately and there is a busy-handler callback configured, it is invoked
  8218. ** in the usual manner. ^If the required lock still cannot be obtained, then
  8219. ** the database is skipped and an attempt made to flush any dirty pages
  8220. ** belonging to the next (if any) database. ^If any databases are skipped
  8221. ** because locks cannot be obtained, but no other error occurs, this
  8222. ** function returns SQLITE_BUSY.
  8223. **
  8224. ** ^If any other error occurs while flushing dirty pages to disk (for
  8225. ** example an IO error or out-of-memory condition), then processing is
  8226. ** abandoned and an SQLite [error code] is returned to the caller immediately.
  8227. **
  8228. ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
  8229. **
  8230. ** ^This function does not set the database handle error code or message
  8231. ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
  8232. */
  8233. SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
  8234. /*
  8235. ** CAPI3REF: The pre-update hook.
  8236. **
  8237. ** ^These interfaces are only available if SQLite is compiled using the
  8238. ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
  8239. **
  8240. ** ^The [sqlite3_preupdate_hook()] interface registers a callback function
  8241. ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
  8242. ** on a database table.
  8243. ** ^At most one preupdate hook may be registered at a time on a single
  8244. ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
  8245. ** the previous setting.
  8246. ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
  8247. ** with a NULL pointer as the second parameter.
  8248. ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
  8249. ** the first parameter to callbacks.
  8250. **
  8251. ** ^The preupdate hook only fires for changes to real database tables; the
  8252. ** preupdate hook is not invoked for changes to [virtual tables] or to
  8253. ** system tables like sqlite_master or sqlite_stat1.
  8254. **
  8255. ** ^The second parameter to the preupdate callback is a pointer to
  8256. ** the [database connection] that registered the preupdate hook.
  8257. ** ^The third parameter to the preupdate callback is one of the constants
  8258. ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
  8259. ** kind of update operation that is about to occur.
  8260. ** ^(The fourth parameter to the preupdate callback is the name of the
  8261. ** database within the database connection that is being modified. This
  8262. ** will be "main" for the main database or "temp" for TEMP tables or
  8263. ** the name given after the AS keyword in the [ATTACH] statement for attached
  8264. ** databases.)^
  8265. ** ^The fifth parameter to the preupdate callback is the name of the
  8266. ** table that is being modified.
  8267. **
  8268. ** For an UPDATE or DELETE operation on a [rowid table], the sixth
  8269. ** parameter passed to the preupdate callback is the initial [rowid] of the
  8270. ** row being modified or deleted. For an INSERT operation on a rowid table,
  8271. ** or any operation on a WITHOUT ROWID table, the value of the sixth
  8272. ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
  8273. ** seventh parameter is the final rowid value of the row being inserted
  8274. ** or updated. The value of the seventh parameter passed to the callback
  8275. ** function is not defined for operations on WITHOUT ROWID tables, or for
  8276. ** INSERT operations on rowid tables.
  8277. **
  8278. ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
  8279. ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
  8280. ** provide additional information about a preupdate event. These routines
  8281. ** may only be called from within a preupdate callback. Invoking any of
  8282. ** these routines from outside of a preupdate callback or with a
  8283. ** [database connection] pointer that is different from the one supplied
  8284. ** to the preupdate callback results in undefined and probably undesirable
  8285. ** behavior.
  8286. **
  8287. ** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
  8288. ** in the row that is being inserted, updated, or deleted.
  8289. **
  8290. ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
  8291. ** a [protected sqlite3_value] that contains the value of the Nth column of
  8292. ** the table row before it is updated. The N parameter must be between 0
  8293. ** and one less than the number of columns or the behavior will be
  8294. ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
  8295. ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
  8296. ** behavior is undefined. The [sqlite3_value] that P points to
  8297. ** will be destroyed when the preupdate callback returns.
  8298. **
  8299. ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
  8300. ** a [protected sqlite3_value] that contains the value of the Nth column of
  8301. ** the table row after it is updated. The N parameter must be between 0
  8302. ** and one less than the number of columns or the behavior will be
  8303. ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
  8304. ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
  8305. ** behavior is undefined. The [sqlite3_value] that P points to
  8306. ** will be destroyed when the preupdate callback returns.
  8307. **
  8308. ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
  8309. ** callback was invoked as a result of a direct insert, update, or delete
  8310. ** operation; or 1 for inserts, updates, or deletes invoked by top-level
  8311. ** triggers; or 2 for changes resulting from triggers called by top-level
  8312. ** triggers; and so forth.
  8313. **
  8314. ** See also: [sqlite3_update_hook()]
  8315. */
  8316. #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
  8317. SQLITE_API void *sqlite3_preupdate_hook(
  8318. sqlite3 *db,
  8319. void(*xPreUpdate)(
  8320. void *pCtx, /* Copy of third arg to preupdate_hook() */
  8321. sqlite3 *db, /* Database handle */
  8322. int op, /* SQLITE_UPDATE, DELETE or INSERT */
  8323. char const *zDb, /* Database name */
  8324. char const *zName, /* Table name */
  8325. sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
  8326. sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
  8327. ),
  8328. void*
  8329. );
  8330. SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
  8331. SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
  8332. SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
  8333. SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
  8334. #endif
  8335. /*
  8336. ** CAPI3REF: Low-level system error code
  8337. **
  8338. ** ^Attempt to return the underlying operating system error code or error
  8339. ** number that caused the most recent I/O error or failure to open a file.
  8340. ** The return value is OS-dependent. For example, on unix systems, after
  8341. ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
  8342. ** called to get back the underlying "errno" that caused the problem, such
  8343. ** as ENOSPC, EAUTH, EISDIR, and so forth.
  8344. */
  8345. SQLITE_API int sqlite3_system_errno(sqlite3*);
  8346. /*
  8347. ** CAPI3REF: Database Snapshot
  8348. ** KEYWORDS: {snapshot} {sqlite3_snapshot}
  8349. ** EXPERIMENTAL
  8350. **
  8351. ** An instance of the snapshot object records the state of a [WAL mode]
  8352. ** database for some specific point in history.
  8353. **
  8354. ** In [WAL mode], multiple [database connections] that are open on the
  8355. ** same database file can each be reading a different historical version
  8356. ** of the database file. When a [database connection] begins a read
  8357. ** transaction, that connection sees an unchanging copy of the database
  8358. ** as it existed for the point in time when the transaction first started.
  8359. ** Subsequent changes to the database from other connections are not seen
  8360. ** by the reader until a new read transaction is started.
  8361. **
  8362. ** The sqlite3_snapshot object records state information about an historical
  8363. ** version of the database file so that it is possible to later open a new read
  8364. ** transaction that sees that historical version of the database rather than
  8365. ** the most recent version.
  8366. **
  8367. ** The constructor for this object is [sqlite3_snapshot_get()]. The
  8368. ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
  8369. ** to an historical snapshot (if possible). The destructor for
  8370. ** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
  8371. */
  8372. typedef struct sqlite3_snapshot {
  8373. unsigned char hidden[48];
  8374. } sqlite3_snapshot;
  8375. /*
  8376. ** CAPI3REF: Record A Database Snapshot
  8377. ** EXPERIMENTAL
  8378. **
  8379. ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
  8380. ** new [sqlite3_snapshot] object that records the current state of
  8381. ** schema S in database connection D. ^On success, the
  8382. ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
  8383. ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
  8384. ** If there is not already a read-transaction open on schema S when
  8385. ** this function is called, one is opened automatically.
  8386. **
  8387. ** The following must be true for this function to succeed. If any of
  8388. ** the following statements are false when sqlite3_snapshot_get() is
  8389. ** called, SQLITE_ERROR is returned. The final value of *P is undefined
  8390. ** in this case.
  8391. **
  8392. ** <ul>
  8393. ** <li> The database handle must be in [autocommit mode].
  8394. **
  8395. ** <li> Schema S of [database connection] D must be a [WAL mode] database.
  8396. **
  8397. ** <li> There must not be a write transaction open on schema S of database
  8398. ** connection D.
  8399. **
  8400. ** <li> One or more transactions must have been written to the current wal
  8401. ** file since it was created on disk (by any connection). This means
  8402. ** that a snapshot cannot be taken on a wal mode database with no wal
  8403. ** file immediately after it is first opened. At least one transaction
  8404. ** must be written to it first.
  8405. ** </ul>
  8406. **
  8407. ** This function may also return SQLITE_NOMEM. If it is called with the
  8408. ** database handle in autocommit mode but fails for some other reason,
  8409. ** whether or not a read transaction is opened on schema S is undefined.
  8410. **
  8411. ** The [sqlite3_snapshot] object returned from a successful call to
  8412. ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
  8413. ** to avoid a memory leak.
  8414. **
  8415. ** The [sqlite3_snapshot_get()] interface is only available when the
  8416. ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
  8417. */
  8418. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
  8419. sqlite3 *db,
  8420. const char *zSchema,
  8421. sqlite3_snapshot **ppSnapshot
  8422. );
  8423. /*
  8424. ** CAPI3REF: Start a read transaction on an historical snapshot
  8425. ** EXPERIMENTAL
  8426. **
  8427. ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
  8428. ** read transaction for schema S of
  8429. ** [database connection] D such that the read transaction
  8430. ** refers to historical [snapshot] P, rather than the most
  8431. ** recent change to the database.
  8432. ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
  8433. ** or an appropriate [error code] if it fails.
  8434. **
  8435. ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
  8436. ** the first operation following the [BEGIN] that takes the schema S
  8437. ** out of [autocommit mode].
  8438. ** ^In other words, schema S must not currently be in
  8439. ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the
  8440. ** database connection D must be out of [autocommit mode].
  8441. ** ^A [snapshot] will fail to open if it has been overwritten by a
  8442. ** [checkpoint].
  8443. ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
  8444. ** database connection D does not know that the database file for
  8445. ** schema S is in [WAL mode]. A database connection might not know
  8446. ** that the database file is in [WAL mode] if there has been no prior
  8447. ** I/O on that database connection, or if the database entered [WAL mode]
  8448. ** after the most recent I/O on the database connection.)^
  8449. ** (Hint: Run "[PRAGMA application_id]" against a newly opened
  8450. ** database connection in order to make it ready to use snapshots.)
  8451. **
  8452. ** The [sqlite3_snapshot_open()] interface is only available when the
  8453. ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
  8454. */
  8455. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
  8456. sqlite3 *db,
  8457. const char *zSchema,
  8458. sqlite3_snapshot *pSnapshot
  8459. );
  8460. /*
  8461. ** CAPI3REF: Destroy a snapshot
  8462. ** EXPERIMENTAL
  8463. **
  8464. ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
  8465. ** The application must eventually free every [sqlite3_snapshot] object
  8466. ** using this routine to avoid a memory leak.
  8467. **
  8468. ** The [sqlite3_snapshot_free()] interface is only available when the
  8469. ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
  8470. */
  8471. SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
  8472. /*
  8473. ** CAPI3REF: Compare the ages of two snapshot handles.
  8474. ** EXPERIMENTAL
  8475. **
  8476. ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
  8477. ** of two valid snapshot handles.
  8478. **
  8479. ** If the two snapshot handles are not associated with the same database
  8480. ** file, the result of the comparison is undefined.
  8481. **
  8482. ** Additionally, the result of the comparison is only valid if both of the
  8483. ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
  8484. ** last time the wal file was deleted. The wal file is deleted when the
  8485. ** database is changed back to rollback mode or when the number of database
  8486. ** clients drops to zero. If either snapshot handle was obtained before the
  8487. ** wal file was last deleted, the value returned by this function
  8488. ** is undefined.
  8489. **
  8490. ** Otherwise, this API returns a negative value if P1 refers to an older
  8491. ** snapshot than P2, zero if the two handles refer to the same database
  8492. ** snapshot, and a positive value if P1 is a newer snapshot than P2.
  8493. */
  8494. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
  8495. sqlite3_snapshot *p1,
  8496. sqlite3_snapshot *p2
  8497. );
  8498. /*
  8499. ** CAPI3REF: Recover snapshots from a wal file
  8500. ** EXPERIMENTAL
  8501. **
  8502. ** If all connections disconnect from a database file but do not perform
  8503. ** a checkpoint, the existing wal file is opened along with the database
  8504. ** file the next time the database is opened. At this point it is only
  8505. ** possible to successfully call sqlite3_snapshot_open() to open the most
  8506. ** recent snapshot of the database (the one at the head of the wal file),
  8507. ** even though the wal file may contain other valid snapshots for which
  8508. ** clients have sqlite3_snapshot handles.
  8509. **
  8510. ** This function attempts to scan the wal file associated with database zDb
  8511. ** of database handle db and make all valid snapshots available to
  8512. ** sqlite3_snapshot_open(). It is an error if there is already a read
  8513. ** transaction open on the database, or if the database is not a wal mode
  8514. ** database.
  8515. **
  8516. ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
  8517. */
  8518. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
  8519. /*
  8520. ** Undo the hack that converts floating point types to integer for
  8521. ** builds on processors without floating point support.
  8522. */
  8523. #ifdef SQLITE_OMIT_FLOATING_POINT
  8524. # undef double
  8525. #endif
  8526. #ifdef __cplusplus
  8527. } /* End of the 'extern "C"' block */
  8528. #endif
  8529. #endif /* SQLITE3_H */
  8530. /******** Begin file sqlite3rtree.h *********/
  8531. /*
  8532. ** 2010 August 30
  8533. **
  8534. ** The author disclaims copyright to this source code. In place of
  8535. ** a legal notice, here is a blessing:
  8536. **
  8537. ** May you do good and not evil.
  8538. ** May you find forgiveness for yourself and forgive others.
  8539. ** May you share freely, never taking more than you give.
  8540. **
  8541. *************************************************************************
  8542. */
  8543. #ifndef _SQLITE3RTREE_H_
  8544. #define _SQLITE3RTREE_H_
  8545. #ifdef __cplusplus
  8546. extern "C" {
  8547. #endif
  8548. typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
  8549. typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
  8550. /* The double-precision datatype used by RTree depends on the
  8551. ** SQLITE_RTREE_INT_ONLY compile-time option.
  8552. */
  8553. #ifdef SQLITE_RTREE_INT_ONLY
  8554. typedef sqlite3_int64 sqlite3_rtree_dbl;
  8555. #else
  8556. typedef double sqlite3_rtree_dbl;
  8557. #endif
  8558. /*
  8559. ** Register a geometry callback named zGeom that can be used as part of an
  8560. ** R-Tree geometry query as follows:
  8561. **
  8562. ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
  8563. */
  8564. SQLITE_API int sqlite3_rtree_geometry_callback(
  8565. sqlite3 *db,
  8566. const char *zGeom,
  8567. int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
  8568. void *pContext
  8569. );
  8570. /*
  8571. ** A pointer to a structure of the following type is passed as the first
  8572. ** argument to callbacks registered using rtree_geometry_callback().
  8573. */
  8574. struct sqlite3_rtree_geometry {
  8575. void *pContext; /* Copy of pContext passed to s_r_g_c() */
  8576. int nParam; /* Size of array aParam[] */
  8577. sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
  8578. void *pUser; /* Callback implementation user data */
  8579. void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
  8580. };
  8581. /*
  8582. ** Register a 2nd-generation geometry callback named zScore that can be
  8583. ** used as part of an R-Tree geometry query as follows:
  8584. **
  8585. ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
  8586. */
  8587. SQLITE_API int sqlite3_rtree_query_callback(
  8588. sqlite3 *db,
  8589. const char *zQueryFunc,
  8590. int (*xQueryFunc)(sqlite3_rtree_query_info*),
  8591. void *pContext,
  8592. void (*xDestructor)(void*)
  8593. );
  8594. /*
  8595. ** A pointer to a structure of the following type is passed as the
  8596. ** argument to scored geometry callback registered using
  8597. ** sqlite3_rtree_query_callback().
  8598. **
  8599. ** Note that the first 5 fields of this structure are identical to
  8600. ** sqlite3_rtree_geometry. This structure is a subclass of
  8601. ** sqlite3_rtree_geometry.
  8602. */
  8603. struct sqlite3_rtree_query_info {
  8604. void *pContext; /* pContext from when function registered */
  8605. int nParam; /* Number of function parameters */
  8606. sqlite3_rtree_dbl *aParam; /* value of function parameters */
  8607. void *pUser; /* callback can use this, if desired */
  8608. void (*xDelUser)(void*); /* function to free pUser */
  8609. sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
  8610. unsigned int *anQueue; /* Number of pending entries in the queue */
  8611. int nCoord; /* Number of coordinates */
  8612. int iLevel; /* Level of current node or entry */
  8613. int mxLevel; /* The largest iLevel value in the tree */
  8614. sqlite3_int64 iRowid; /* Rowid for current entry */
  8615. sqlite3_rtree_dbl rParentScore; /* Score of parent node */
  8616. int eParentWithin; /* Visibility of parent node */
  8617. int eWithin; /* OUT: Visiblity */
  8618. sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
  8619. /* The following fields are only available in 3.8.11 and later */
  8620. sqlite3_value **apSqlParam; /* Original SQL values of parameters */
  8621. };
  8622. /*
  8623. ** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
  8624. */
  8625. #define NOT_WITHIN 0 /* Object completely outside of query region */
  8626. #define PARTLY_WITHIN 1 /* Object partially overlaps query region */
  8627. #define FULLY_WITHIN 2 /* Object fully contained within query region */
  8628. #ifdef __cplusplus
  8629. } /* end of the 'extern "C"' block */
  8630. #endif
  8631. #endif /* ifndef _SQLITE3RTREE_H_ */
  8632. /******** End of sqlite3rtree.h *********/
  8633. /******** Begin file sqlite3session.h *********/
  8634. #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
  8635. #define __SQLITESESSION_H_ 1
  8636. /*
  8637. ** Make sure we can call this stuff from C++.
  8638. */
  8639. #ifdef __cplusplus
  8640. extern "C" {
  8641. #endif
  8642. /*
  8643. ** CAPI3REF: Session Object Handle
  8644. */
  8645. typedef struct sqlite3_session sqlite3_session;
  8646. /*
  8647. ** CAPI3REF: Changeset Iterator Handle
  8648. */
  8649. typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
  8650. /*
  8651. ** CAPI3REF: Create A New Session Object
  8652. **
  8653. ** Create a new session object attached to database handle db. If successful,
  8654. ** a pointer to the new object is written to *ppSession and SQLITE_OK is
  8655. ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
  8656. ** error code (e.g. SQLITE_NOMEM) is returned.
  8657. **
  8658. ** It is possible to create multiple session objects attached to a single
  8659. ** database handle.
  8660. **
  8661. ** Session objects created using this function should be deleted using the
  8662. ** [sqlite3session_delete()] function before the database handle that they
  8663. ** are attached to is itself closed. If the database handle is closed before
  8664. ** the session object is deleted, then the results of calling any session
  8665. ** module function, including [sqlite3session_delete()] on the session object
  8666. ** are undefined.
  8667. **
  8668. ** Because the session module uses the [sqlite3_preupdate_hook()] API, it
  8669. ** is not possible for an application to register a pre-update hook on a
  8670. ** database handle that has one or more session objects attached. Nor is
  8671. ** it possible to create a session object attached to a database handle for
  8672. ** which a pre-update hook is already defined. The results of attempting
  8673. ** either of these things are undefined.
  8674. **
  8675. ** The session object will be used to create changesets for tables in
  8676. ** database zDb, where zDb is either "main", or "temp", or the name of an
  8677. ** attached database. It is not an error if database zDb is not attached
  8678. ** to the database when the session object is created.
  8679. */
  8680. SQLITE_API int sqlite3session_create(
  8681. sqlite3 *db, /* Database handle */
  8682. const char *zDb, /* Name of db (e.g. "main") */
  8683. sqlite3_session **ppSession /* OUT: New session object */
  8684. );
  8685. /*
  8686. ** CAPI3REF: Delete A Session Object
  8687. **
  8688. ** Delete a session object previously allocated using
  8689. ** [sqlite3session_create()]. Once a session object has been deleted, the
  8690. ** results of attempting to use pSession with any other session module
  8691. ** function are undefined.
  8692. **
  8693. ** Session objects must be deleted before the database handle to which they
  8694. ** are attached is closed. Refer to the documentation for
  8695. ** [sqlite3session_create()] for details.
  8696. */
  8697. SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
  8698. /*
  8699. ** CAPI3REF: Enable Or Disable A Session Object
  8700. **
  8701. ** Enable or disable the recording of changes by a session object. When
  8702. ** enabled, a session object records changes made to the database. When
  8703. ** disabled - it does not. A newly created session object is enabled.
  8704. ** Refer to the documentation for [sqlite3session_changeset()] for further
  8705. ** details regarding how enabling and disabling a session object affects
  8706. ** the eventual changesets.
  8707. **
  8708. ** Passing zero to this function disables the session. Passing a value
  8709. ** greater than zero enables it. Passing a value less than zero is a
  8710. ** no-op, and may be used to query the current state of the session.
  8711. **
  8712. ** The return value indicates the final state of the session object: 0 if
  8713. ** the session is disabled, or 1 if it is enabled.
  8714. */
  8715. SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
  8716. /*
  8717. ** CAPI3REF: Set Or Clear the Indirect Change Flag
  8718. **
  8719. ** Each change recorded by a session object is marked as either direct or
  8720. ** indirect. A change is marked as indirect if either:
  8721. **
  8722. ** <ul>
  8723. ** <li> The session object "indirect" flag is set when the change is
  8724. ** made, or
  8725. ** <li> The change is made by an SQL trigger or foreign key action
  8726. ** instead of directly as a result of a users SQL statement.
  8727. ** </ul>
  8728. **
  8729. ** If a single row is affected by more than one operation within a session,
  8730. ** then the change is considered indirect if all operations meet the criteria
  8731. ** for an indirect change above, or direct otherwise.
  8732. **
  8733. ** This function is used to set, clear or query the session object indirect
  8734. ** flag. If the second argument passed to this function is zero, then the
  8735. ** indirect flag is cleared. If it is greater than zero, the indirect flag
  8736. ** is set. Passing a value less than zero does not modify the current value
  8737. ** of the indirect flag, and may be used to query the current state of the
  8738. ** indirect flag for the specified session object.
  8739. **
  8740. ** The return value indicates the final state of the indirect flag: 0 if
  8741. ** it is clear, or 1 if it is set.
  8742. */
  8743. SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
  8744. /*
  8745. ** CAPI3REF: Attach A Table To A Session Object
  8746. **
  8747. ** If argument zTab is not NULL, then it is the name of a table to attach
  8748. ** to the session object passed as the first argument. All subsequent changes
  8749. ** made to the table while the session object is enabled will be recorded. See
  8750. ** documentation for [sqlite3session_changeset()] for further details.
  8751. **
  8752. ** Or, if argument zTab is NULL, then changes are recorded for all tables
  8753. ** in the database. If additional tables are added to the database (by
  8754. ** executing "CREATE TABLE" statements) after this call is made, changes for
  8755. ** the new tables are also recorded.
  8756. **
  8757. ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
  8758. ** defined as part of their CREATE TABLE statement. It does not matter if the
  8759. ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
  8760. ** KEY may consist of a single column, or may be a composite key.
  8761. **
  8762. ** It is not an error if the named table does not exist in the database. Nor
  8763. ** is it an error if the named table does not have a PRIMARY KEY. However,
  8764. ** no changes will be recorded in either of these scenarios.
  8765. **
  8766. ** Changes are not recorded for individual rows that have NULL values stored
  8767. ** in one or more of their PRIMARY KEY columns.
  8768. **
  8769. ** SQLITE_OK is returned if the call completes without error. Or, if an error
  8770. ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
  8771. */
  8772. SQLITE_API int sqlite3session_attach(
  8773. sqlite3_session *pSession, /* Session object */
  8774. const char *zTab /* Table name */
  8775. );
  8776. /*
  8777. ** CAPI3REF: Set a table filter on a Session Object.
  8778. **
  8779. ** The second argument (xFilter) is the "filter callback". For changes to rows
  8780. ** in tables that are not attached to the Session object, the filter is called
  8781. ** to determine whether changes to the table's rows should be tracked or not.
  8782. ** If xFilter returns 0, changes is not tracked. Note that once a table is
  8783. ** attached, xFilter will not be called again.
  8784. */
  8785. SQLITE_API void sqlite3session_table_filter(
  8786. sqlite3_session *pSession, /* Session object */
  8787. int(*xFilter)(
  8788. void *pCtx, /* Copy of third arg to _filter_table() */
  8789. const char *zTab /* Table name */
  8790. ),
  8791. void *pCtx /* First argument passed to xFilter */
  8792. );
  8793. /*
  8794. ** CAPI3REF: Generate A Changeset From A Session Object
  8795. **
  8796. ** Obtain a changeset containing changes to the tables attached to the
  8797. ** session object passed as the first argument. If successful,
  8798. ** set *ppChangeset to point to a buffer containing the changeset
  8799. ** and *pnChangeset to the size of the changeset in bytes before returning
  8800. ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
  8801. ** zero and return an SQLite error code.
  8802. **
  8803. ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
  8804. ** each representing a change to a single row of an attached table. An INSERT
  8805. ** change contains the values of each field of a new database row. A DELETE
  8806. ** contains the original values of each field of a deleted database row. An
  8807. ** UPDATE change contains the original values of each field of an updated
  8808. ** database row along with the updated values for each updated non-primary-key
  8809. ** column. It is not possible for an UPDATE change to represent a change that
  8810. ** modifies the values of primary key columns. If such a change is made, it
  8811. ** is represented in a changeset as a DELETE followed by an INSERT.
  8812. **
  8813. ** Changes are not recorded for rows that have NULL values stored in one or
  8814. ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
  8815. ** no corresponding change is present in the changesets returned by this
  8816. ** function. If an existing row with one or more NULL values stored in
  8817. ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
  8818. ** only an INSERT is appears in the changeset. Similarly, if an existing row
  8819. ** with non-NULL PRIMARY KEY values is updated so that one or more of its
  8820. ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
  8821. ** DELETE change only.
  8822. **
  8823. ** The contents of a changeset may be traversed using an iterator created
  8824. ** using the [sqlite3changeset_start()] API. A changeset may be applied to
  8825. ** a database with a compatible schema using the [sqlite3changeset_apply()]
  8826. ** API.
  8827. **
  8828. ** Within a changeset generated by this function, all changes related to a
  8829. ** single table are grouped together. In other words, when iterating through
  8830. ** a changeset or when applying a changeset to a database, all changes related
  8831. ** to a single table are processed before moving on to the next table. Tables
  8832. ** are sorted in the same order in which they were attached (or auto-attached)
  8833. ** to the sqlite3_session object. The order in which the changes related to
  8834. ** a single table are stored is undefined.
  8835. **
  8836. ** Following a successful call to this function, it is the responsibility of
  8837. ** the caller to eventually free the buffer that *ppChangeset points to using
  8838. ** [sqlite3_free()].
  8839. **
  8840. ** <h3>Changeset Generation</h3>
  8841. **
  8842. ** Once a table has been attached to a session object, the session object
  8843. ** records the primary key values of all new rows inserted into the table.
  8844. ** It also records the original primary key and other column values of any
  8845. ** deleted or updated rows. For each unique primary key value, data is only
  8846. ** recorded once - the first time a row with said primary key is inserted,
  8847. ** updated or deleted in the lifetime of the session.
  8848. **
  8849. ** There is one exception to the previous paragraph: when a row is inserted,
  8850. ** updated or deleted, if one or more of its primary key columns contain a
  8851. ** NULL value, no record of the change is made.
  8852. **
  8853. ** The session object therefore accumulates two types of records - those
  8854. ** that consist of primary key values only (created when the user inserts
  8855. ** a new record) and those that consist of the primary key values and the
  8856. ** original values of other table columns (created when the users deletes
  8857. ** or updates a record).
  8858. **
  8859. ** When this function is called, the requested changeset is created using
  8860. ** both the accumulated records and the current contents of the database
  8861. ** file. Specifically:
  8862. **
  8863. ** <ul>
  8864. ** <li> For each record generated by an insert, the database is queried
  8865. ** for a row with a matching primary key. If one is found, an INSERT
  8866. ** change is added to the changeset. If no such row is found, no change
  8867. ** is added to the changeset.
  8868. **
  8869. ** <li> For each record generated by an update or delete, the database is
  8870. ** queried for a row with a matching primary key. If such a row is
  8871. ** found and one or more of the non-primary key fields have been
  8872. ** modified from their original values, an UPDATE change is added to
  8873. ** the changeset. Or, if no such row is found in the table, a DELETE
  8874. ** change is added to the changeset. If there is a row with a matching
  8875. ** primary key in the database, but all fields contain their original
  8876. ** values, no change is added to the changeset.
  8877. ** </ul>
  8878. **
  8879. ** This means, amongst other things, that if a row is inserted and then later
  8880. ** deleted while a session object is active, neither the insert nor the delete
  8881. ** will be present in the changeset. Or if a row is deleted and then later a
  8882. ** row with the same primary key values inserted while a session object is
  8883. ** active, the resulting changeset will contain an UPDATE change instead of
  8884. ** a DELETE and an INSERT.
  8885. **
  8886. ** When a session object is disabled (see the [sqlite3session_enable()] API),
  8887. ** it does not accumulate records when rows are inserted, updated or deleted.
  8888. ** This may appear to have some counter-intuitive effects if a single row
  8889. ** is written to more than once during a session. For example, if a row
  8890. ** is inserted while a session object is enabled, then later deleted while
  8891. ** the same session object is disabled, no INSERT record will appear in the
  8892. ** changeset, even though the delete took place while the session was disabled.
  8893. ** Or, if one field of a row is updated while a session is disabled, and
  8894. ** another field of the same row is updated while the session is enabled, the
  8895. ** resulting changeset will contain an UPDATE change that updates both fields.
  8896. */
  8897. SQLITE_API int sqlite3session_changeset(
  8898. sqlite3_session *pSession, /* Session object */
  8899. int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
  8900. void **ppChangeset /* OUT: Buffer containing changeset */
  8901. );
  8902. /*
  8903. ** CAPI3REF: Load The Difference Between Tables Into A Session
  8904. **
  8905. ** If it is not already attached to the session object passed as the first
  8906. ** argument, this function attaches table zTbl in the same manner as the
  8907. ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
  8908. ** does not have a primary key, this function is a no-op (but does not return
  8909. ** an error).
  8910. **
  8911. ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
  8912. ** attached to the same database handle as the session object that contains
  8913. ** a table compatible with the table attached to the session by this function.
  8914. ** A table is considered compatible if it:
  8915. **
  8916. ** <ul>
  8917. ** <li> Has the same name,
  8918. ** <li> Has the same set of columns declared in the same order, and
  8919. ** <li> Has the same PRIMARY KEY definition.
  8920. ** </ul>
  8921. **
  8922. ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
  8923. ** are compatible but do not have any PRIMARY KEY columns, it is not an error
  8924. ** but no changes are added to the session object. As with other session
  8925. ** APIs, tables without PRIMARY KEYs are simply ignored.
  8926. **
  8927. ** This function adds a set of changes to the session object that could be
  8928. ** used to update the table in database zFrom (call this the "from-table")
  8929. ** so that its content is the same as the table attached to the session
  8930. ** object (call this the "to-table"). Specifically:
  8931. **
  8932. ** <ul>
  8933. ** <li> For each row (primary key) that exists in the to-table but not in
  8934. ** the from-table, an INSERT record is added to the session object.
  8935. **
  8936. ** <li> For each row (primary key) that exists in the to-table but not in
  8937. ** the from-table, a DELETE record is added to the session object.
  8938. **
  8939. ** <li> For each row (primary key) that exists in both tables, but features
  8940. ** different non-PK values in each, an UPDATE record is added to the
  8941. ** session.
  8942. ** </ul>
  8943. **
  8944. ** To clarify, if this function is called and then a changeset constructed
  8945. ** using [sqlite3session_changeset()], then after applying that changeset to
  8946. ** database zFrom the contents of the two compatible tables would be
  8947. ** identical.
  8948. **
  8949. ** It an error if database zFrom does not exist or does not contain the
  8950. ** required compatible table.
  8951. **
  8952. ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
  8953. ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
  8954. ** may be set to point to a buffer containing an English language error
  8955. ** message. It is the responsibility of the caller to free this buffer using
  8956. ** sqlite3_free().
  8957. */
  8958. SQLITE_API int sqlite3session_diff(
  8959. sqlite3_session *pSession,
  8960. const char *zFromDb,
  8961. const char *zTbl,
  8962. char **pzErrMsg
  8963. );
  8964. /*
  8965. ** CAPI3REF: Generate A Patchset From A Session Object
  8966. **
  8967. ** The differences between a patchset and a changeset are that:
  8968. **
  8969. ** <ul>
  8970. ** <li> DELETE records consist of the primary key fields only. The
  8971. ** original values of other fields are omitted.
  8972. ** <li> The original values of any modified fields are omitted from
  8973. ** UPDATE records.
  8974. ** </ul>
  8975. **
  8976. ** A patchset blob may be used with up to date versions of all
  8977. ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
  8978. ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
  8979. ** attempting to use a patchset blob with old versions of the
  8980. ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
  8981. **
  8982. ** Because the non-primary key "old.*" fields are omitted, no
  8983. ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
  8984. ** is passed to the sqlite3changeset_apply() API. Other conflict types work
  8985. ** in the same way as for changesets.
  8986. **
  8987. ** Changes within a patchset are ordered in the same way as for changesets
  8988. ** generated by the sqlite3session_changeset() function (i.e. all changes for
  8989. ** a single table are grouped together, tables appear in the order in which
  8990. ** they were attached to the session object).
  8991. */
  8992. SQLITE_API int sqlite3session_patchset(
  8993. sqlite3_session *pSession, /* Session object */
  8994. int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
  8995. void **ppPatchset /* OUT: Buffer containing patchset */
  8996. );
  8997. /*
  8998. ** CAPI3REF: Test if a changeset has recorded any changes.
  8999. **
  9000. ** Return non-zero if no changes to attached tables have been recorded by
  9001. ** the session object passed as the first argument. Otherwise, if one or
  9002. ** more changes have been recorded, return zero.
  9003. **
  9004. ** Even if this function returns zero, it is possible that calling
  9005. ** [sqlite3session_changeset()] on the session handle may still return a
  9006. ** changeset that contains no changes. This can happen when a row in
  9007. ** an attached table is modified and then later on the original values
  9008. ** are restored. However, if this function returns non-zero, then it is
  9009. ** guaranteed that a call to sqlite3session_changeset() will return a
  9010. ** changeset containing zero changes.
  9011. */
  9012. SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
  9013. /*
  9014. ** CAPI3REF: Create An Iterator To Traverse A Changeset
  9015. **
  9016. ** Create an iterator used to iterate through the contents of a changeset.
  9017. ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
  9018. ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
  9019. ** SQLite error code is returned.
  9020. **
  9021. ** The following functions can be used to advance and query a changeset
  9022. ** iterator created by this function:
  9023. **
  9024. ** <ul>
  9025. ** <li> [sqlite3changeset_next()]
  9026. ** <li> [sqlite3changeset_op()]
  9027. ** <li> [sqlite3changeset_new()]
  9028. ** <li> [sqlite3changeset_old()]
  9029. ** </ul>
  9030. **
  9031. ** It is the responsibility of the caller to eventually destroy the iterator
  9032. ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
  9033. ** changeset (pChangeset) must remain valid until after the iterator is
  9034. ** destroyed.
  9035. **
  9036. ** Assuming the changeset blob was created by one of the
  9037. ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
  9038. ** [sqlite3changeset_invert()] functions, all changes within the changeset
  9039. ** that apply to a single table are grouped together. This means that when
  9040. ** an application iterates through a changeset using an iterator created by
  9041. ** this function, all changes that relate to a single table are visited
  9042. ** consecutively. There is no chance that the iterator will visit a change
  9043. ** the applies to table X, then one for table Y, and then later on visit
  9044. ** another change for table X.
  9045. */
  9046. SQLITE_API int sqlite3changeset_start(
  9047. sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
  9048. int nChangeset, /* Size of changeset blob in bytes */
  9049. void *pChangeset /* Pointer to blob containing changeset */
  9050. );
  9051. /*
  9052. ** CAPI3REF: Advance A Changeset Iterator
  9053. **
  9054. ** This function may only be used with iterators created by function
  9055. ** [sqlite3changeset_start()]. If it is called on an iterator passed to
  9056. ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
  9057. ** is returned and the call has no effect.
  9058. **
  9059. ** Immediately after an iterator is created by sqlite3changeset_start(), it
  9060. ** does not point to any change in the changeset. Assuming the changeset
  9061. ** is not empty, the first call to this function advances the iterator to
  9062. ** point to the first change in the changeset. Each subsequent call advances
  9063. ** the iterator to point to the next change in the changeset (if any). If
  9064. ** no error occurs and the iterator points to a valid change after a call
  9065. ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
  9066. ** Otherwise, if all changes in the changeset have already been visited,
  9067. ** SQLITE_DONE is returned.
  9068. **
  9069. ** If an error occurs, an SQLite error code is returned. Possible error
  9070. ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
  9071. ** SQLITE_NOMEM.
  9072. */
  9073. SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
  9074. /*
  9075. ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
  9076. **
  9077. ** The pIter argument passed to this function may either be an iterator
  9078. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  9079. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  9080. ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
  9081. ** is not the case, this function returns [SQLITE_MISUSE].
  9082. **
  9083. ** If argument pzTab is not NULL, then *pzTab is set to point to a
  9084. ** nul-terminated utf-8 encoded string containing the name of the table
  9085. ** affected by the current change. The buffer remains valid until either
  9086. ** sqlite3changeset_next() is called on the iterator or until the
  9087. ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
  9088. ** set to the number of columns in the table affected by the change. If
  9089. ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
  9090. ** is an indirect change, or false (0) otherwise. See the documentation for
  9091. ** [sqlite3session_indirect()] for a description of direct and indirect
  9092. ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
  9093. ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
  9094. ** type of change that the iterator currently points to.
  9095. **
  9096. ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
  9097. ** SQLite error code is returned. The values of the output variables may not
  9098. ** be trusted in this case.
  9099. */
  9100. SQLITE_API int sqlite3changeset_op(
  9101. sqlite3_changeset_iter *pIter, /* Iterator object */
  9102. const char **pzTab, /* OUT: Pointer to table name */
  9103. int *pnCol, /* OUT: Number of columns in table */
  9104. int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
  9105. int *pbIndirect /* OUT: True for an 'indirect' change */
  9106. );
  9107. /*
  9108. ** CAPI3REF: Obtain The Primary Key Definition Of A Table
  9109. **
  9110. ** For each modified table, a changeset includes the following:
  9111. **
  9112. ** <ul>
  9113. ** <li> The number of columns in the table, and
  9114. ** <li> Which of those columns make up the tables PRIMARY KEY.
  9115. ** </ul>
  9116. **
  9117. ** This function is used to find which columns comprise the PRIMARY KEY of
  9118. ** the table modified by the change that iterator pIter currently points to.
  9119. ** If successful, *pabPK is set to point to an array of nCol entries, where
  9120. ** nCol is the number of columns in the table. Elements of *pabPK are set to
  9121. ** 0x01 if the corresponding column is part of the tables primary key, or
  9122. ** 0x00 if it is not.
  9123. **
  9124. ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
  9125. ** in the table.
  9126. **
  9127. ** If this function is called when the iterator does not point to a valid
  9128. ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
  9129. ** SQLITE_OK is returned and the output variables populated as described
  9130. ** above.
  9131. */
  9132. SQLITE_API int sqlite3changeset_pk(
  9133. sqlite3_changeset_iter *pIter, /* Iterator object */
  9134. unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
  9135. int *pnCol /* OUT: Number of entries in output array */
  9136. );
  9137. /*
  9138. ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
  9139. **
  9140. ** The pIter argument passed to this function may either be an iterator
  9141. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  9142. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  9143. ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
  9144. ** Furthermore, it may only be called if the type of change that the iterator
  9145. ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
  9146. ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
  9147. **
  9148. ** Argument iVal must be greater than or equal to 0, and less than the number
  9149. ** of columns in the table affected by the current change. Otherwise,
  9150. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  9151. **
  9152. ** If successful, this function sets *ppValue to point to a protected
  9153. ** sqlite3_value object containing the iVal'th value from the vector of
  9154. ** original row values stored as part of the UPDATE or DELETE change and
  9155. ** returns SQLITE_OK. The name of the function comes from the fact that this
  9156. ** is similar to the "old.*" columns available to update or delete triggers.
  9157. **
  9158. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9159. ** is returned and *ppValue is set to NULL.
  9160. */
  9161. SQLITE_API int sqlite3changeset_old(
  9162. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  9163. int iVal, /* Column number */
  9164. sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
  9165. );
  9166. /*
  9167. ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
  9168. **
  9169. ** The pIter argument passed to this function may either be an iterator
  9170. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  9171. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  9172. ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
  9173. ** Furthermore, it may only be called if the type of change that the iterator
  9174. ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
  9175. ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
  9176. **
  9177. ** Argument iVal must be greater than or equal to 0, and less than the number
  9178. ** of columns in the table affected by the current change. Otherwise,
  9179. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  9180. **
  9181. ** If successful, this function sets *ppValue to point to a protected
  9182. ** sqlite3_value object containing the iVal'th value from the vector of
  9183. ** new row values stored as part of the UPDATE or INSERT change and
  9184. ** returns SQLITE_OK. If the change is an UPDATE and does not include
  9185. ** a new value for the requested column, *ppValue is set to NULL and
  9186. ** SQLITE_OK returned. The name of the function comes from the fact that
  9187. ** this is similar to the "new.*" columns available to update or delete
  9188. ** triggers.
  9189. **
  9190. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9191. ** is returned and *ppValue is set to NULL.
  9192. */
  9193. SQLITE_API int sqlite3changeset_new(
  9194. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  9195. int iVal, /* Column number */
  9196. sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
  9197. );
  9198. /*
  9199. ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
  9200. **
  9201. ** This function should only be used with iterator objects passed to a
  9202. ** conflict-handler callback by [sqlite3changeset_apply()] with either
  9203. ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
  9204. ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
  9205. ** is set to NULL.
  9206. **
  9207. ** Argument iVal must be greater than or equal to 0, and less than the number
  9208. ** of columns in the table affected by the current change. Otherwise,
  9209. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  9210. **
  9211. ** If successful, this function sets *ppValue to point to a protected
  9212. ** sqlite3_value object containing the iVal'th value from the
  9213. ** "conflicting row" associated with the current conflict-handler callback
  9214. ** and returns SQLITE_OK.
  9215. **
  9216. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  9217. ** is returned and *ppValue is set to NULL.
  9218. */
  9219. SQLITE_API int sqlite3changeset_conflict(
  9220. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  9221. int iVal, /* Column number */
  9222. sqlite3_value **ppValue /* OUT: Value from conflicting row */
  9223. );
  9224. /*
  9225. ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
  9226. **
  9227. ** This function may only be called with an iterator passed to an
  9228. ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
  9229. ** it sets the output variable to the total number of known foreign key
  9230. ** violations in the destination database and returns SQLITE_OK.
  9231. **
  9232. ** In all other cases this function returns SQLITE_MISUSE.
  9233. */
  9234. SQLITE_API int sqlite3changeset_fk_conflicts(
  9235. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  9236. int *pnOut /* OUT: Number of FK violations */
  9237. );
  9238. /*
  9239. ** CAPI3REF: Finalize A Changeset Iterator
  9240. **
  9241. ** This function is used to finalize an iterator allocated with
  9242. ** [sqlite3changeset_start()].
  9243. **
  9244. ** This function should only be called on iterators created using the
  9245. ** [sqlite3changeset_start()] function. If an application calls this
  9246. ** function with an iterator passed to a conflict-handler by
  9247. ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
  9248. ** call has no effect.
  9249. **
  9250. ** If an error was encountered within a call to an sqlite3changeset_xxx()
  9251. ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
  9252. ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
  9253. ** to that error is returned by this function. Otherwise, SQLITE_OK is
  9254. ** returned. This is to allow the following pattern (pseudo-code):
  9255. **
  9256. ** sqlite3changeset_start();
  9257. ** while( SQLITE_ROW==sqlite3changeset_next() ){
  9258. ** // Do something with change.
  9259. ** }
  9260. ** rc = sqlite3changeset_finalize();
  9261. ** if( rc!=SQLITE_OK ){
  9262. ** // An error has occurred
  9263. ** }
  9264. */
  9265. SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
  9266. /*
  9267. ** CAPI3REF: Invert A Changeset
  9268. **
  9269. ** This function is used to "invert" a changeset object. Applying an inverted
  9270. ** changeset to a database reverses the effects of applying the uninverted
  9271. ** changeset. Specifically:
  9272. **
  9273. ** <ul>
  9274. ** <li> Each DELETE change is changed to an INSERT, and
  9275. ** <li> Each INSERT change is changed to a DELETE, and
  9276. ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
  9277. ** </ul>
  9278. **
  9279. ** This function does not change the order in which changes appear within
  9280. ** the changeset. It merely reverses the sense of each individual change.
  9281. **
  9282. ** If successful, a pointer to a buffer containing the inverted changeset
  9283. ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
  9284. ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
  9285. ** zeroed and an SQLite error code returned.
  9286. **
  9287. ** It is the responsibility of the caller to eventually call sqlite3_free()
  9288. ** on the *ppOut pointer to free the buffer allocation following a successful
  9289. ** call to this function.
  9290. **
  9291. ** WARNING/TODO: This function currently assumes that the input is a valid
  9292. ** changeset. If it is not, the results are undefined.
  9293. */
  9294. SQLITE_API int sqlite3changeset_invert(
  9295. int nIn, const void *pIn, /* Input changeset */
  9296. int *pnOut, void **ppOut /* OUT: Inverse of input */
  9297. );
  9298. /*
  9299. ** CAPI3REF: Concatenate Two Changeset Objects
  9300. **
  9301. ** This function is used to concatenate two changesets, A and B, into a
  9302. ** single changeset. The result is a changeset equivalent to applying
  9303. ** changeset A followed by changeset B.
  9304. **
  9305. ** This function combines the two input changesets using an
  9306. ** sqlite3_changegroup object. Calling it produces similar results as the
  9307. ** following code fragment:
  9308. **
  9309. ** sqlite3_changegroup *pGrp;
  9310. ** rc = sqlite3_changegroup_new(&pGrp);
  9311. ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
  9312. ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
  9313. ** if( rc==SQLITE_OK ){
  9314. ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
  9315. ** }else{
  9316. ** *ppOut = 0;
  9317. ** *pnOut = 0;
  9318. ** }
  9319. **
  9320. ** Refer to the sqlite3_changegroup documentation below for details.
  9321. */
  9322. SQLITE_API int sqlite3changeset_concat(
  9323. int nA, /* Number of bytes in buffer pA */
  9324. void *pA, /* Pointer to buffer containing changeset A */
  9325. int nB, /* Number of bytes in buffer pB */
  9326. void *pB, /* Pointer to buffer containing changeset B */
  9327. int *pnOut, /* OUT: Number of bytes in output changeset */
  9328. void **ppOut /* OUT: Buffer containing output changeset */
  9329. );
  9330. /*
  9331. ** CAPI3REF: Changegroup Handle
  9332. */
  9333. typedef struct sqlite3_changegroup sqlite3_changegroup;
  9334. /*
  9335. ** CAPI3REF: Create A New Changegroup Object
  9336. **
  9337. ** An sqlite3_changegroup object is used to combine two or more changesets
  9338. ** (or patchsets) into a single changeset (or patchset). A single changegroup
  9339. ** object may combine changesets or patchsets, but not both. The output is
  9340. ** always in the same format as the input.
  9341. **
  9342. ** If successful, this function returns SQLITE_OK and populates (*pp) with
  9343. ** a pointer to a new sqlite3_changegroup object before returning. The caller
  9344. ** should eventually free the returned object using a call to
  9345. ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
  9346. ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
  9347. **
  9348. ** The usual usage pattern for an sqlite3_changegroup object is as follows:
  9349. **
  9350. ** <ul>
  9351. ** <li> It is created using a call to sqlite3changegroup_new().
  9352. **
  9353. ** <li> Zero or more changesets (or patchsets) are added to the object
  9354. ** by calling sqlite3changegroup_add().
  9355. **
  9356. ** <li> The result of combining all input changesets together is obtained
  9357. ** by the application via a call to sqlite3changegroup_output().
  9358. **
  9359. ** <li> The object is deleted using a call to sqlite3changegroup_delete().
  9360. ** </ul>
  9361. **
  9362. ** Any number of calls to add() and output() may be made between the calls to
  9363. ** new() and delete(), and in any order.
  9364. **
  9365. ** As well as the regular sqlite3changegroup_add() and
  9366. ** sqlite3changegroup_output() functions, also available are the streaming
  9367. ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
  9368. */
  9369. SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
  9370. /*
  9371. ** CAPI3REF: Add A Changeset To A Changegroup
  9372. **
  9373. ** Add all changes within the changeset (or patchset) in buffer pData (size
  9374. ** nData bytes) to the changegroup.
  9375. **
  9376. ** If the buffer contains a patchset, then all prior calls to this function
  9377. ** on the same changegroup object must also have specified patchsets. Or, if
  9378. ** the buffer contains a changeset, so must have the earlier calls to this
  9379. ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
  9380. ** to the changegroup.
  9381. **
  9382. ** Rows within the changeset and changegroup are identified by the values in
  9383. ** their PRIMARY KEY columns. A change in the changeset is considered to
  9384. ** apply to the same row as a change already present in the changegroup if
  9385. ** the two rows have the same primary key.
  9386. **
  9387. ** Changes to rows that do not already appear in the changegroup are
  9388. ** simply copied into it. Or, if both the new changeset and the changegroup
  9389. ** contain changes that apply to a single row, the final contents of the
  9390. ** changegroup depends on the type of each change, as follows:
  9391. **
  9392. ** <table border=1 style="margin-left:8ex;margin-right:8ex">
  9393. ** <tr><th style="white-space:pre">Existing Change </th>
  9394. ** <th style="white-space:pre">New Change </th>
  9395. ** <th>Output Change
  9396. ** <tr><td>INSERT <td>INSERT <td>
  9397. ** The new change is ignored. This case does not occur if the new
  9398. ** changeset was recorded immediately after the changesets already
  9399. ** added to the changegroup.
  9400. ** <tr><td>INSERT <td>UPDATE <td>
  9401. ** The INSERT change remains in the changegroup. The values in the
  9402. ** INSERT change are modified as if the row was inserted by the
  9403. ** existing change and then updated according to the new change.
  9404. ** <tr><td>INSERT <td>DELETE <td>
  9405. ** The existing INSERT is removed from the changegroup. The DELETE is
  9406. ** not added.
  9407. ** <tr><td>UPDATE <td>INSERT <td>
  9408. ** The new change is ignored. This case does not occur if the new
  9409. ** changeset was recorded immediately after the changesets already
  9410. ** added to the changegroup.
  9411. ** <tr><td>UPDATE <td>UPDATE <td>
  9412. ** The existing UPDATE remains within the changegroup. It is amended
  9413. ** so that the accompanying values are as if the row was updated once
  9414. ** by the existing change and then again by the new change.
  9415. ** <tr><td>UPDATE <td>DELETE <td>
  9416. ** The existing UPDATE is replaced by the new DELETE within the
  9417. ** changegroup.
  9418. ** <tr><td>DELETE <td>INSERT <td>
  9419. ** If one or more of the column values in the row inserted by the
  9420. ** new change differ from those in the row deleted by the existing
  9421. ** change, the existing DELETE is replaced by an UPDATE within the
  9422. ** changegroup. Otherwise, if the inserted row is exactly the same
  9423. ** as the deleted row, the existing DELETE is simply discarded.
  9424. ** <tr><td>DELETE <td>UPDATE <td>
  9425. ** The new change is ignored. This case does not occur if the new
  9426. ** changeset was recorded immediately after the changesets already
  9427. ** added to the changegroup.
  9428. ** <tr><td>DELETE <td>DELETE <td>
  9429. ** The new change is ignored. This case does not occur if the new
  9430. ** changeset was recorded immediately after the changesets already
  9431. ** added to the changegroup.
  9432. ** </table>
  9433. **
  9434. ** If the new changeset contains changes to a table that is already present
  9435. ** in the changegroup, then the number of columns and the position of the
  9436. ** primary key columns for the table must be consistent. If this is not the
  9437. ** case, this function fails with SQLITE_SCHEMA. If the input changeset
  9438. ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
  9439. ** returned. Or, if an out-of-memory condition occurs during processing, this
  9440. ** function returns SQLITE_NOMEM. In all cases, if an error occurs the
  9441. ** final contents of the changegroup is undefined.
  9442. **
  9443. ** If no error occurs, SQLITE_OK is returned.
  9444. */
  9445. SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
  9446. /*
  9447. ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
  9448. **
  9449. ** Obtain a buffer containing a changeset (or patchset) representing the
  9450. ** current contents of the changegroup. If the inputs to the changegroup
  9451. ** were themselves changesets, the output is a changeset. Or, if the
  9452. ** inputs were patchsets, the output is also a patchset.
  9453. **
  9454. ** As with the output of the sqlite3session_changeset() and
  9455. ** sqlite3session_patchset() functions, all changes related to a single
  9456. ** table are grouped together in the output of this function. Tables appear
  9457. ** in the same order as for the very first changeset added to the changegroup.
  9458. ** If the second or subsequent changesets added to the changegroup contain
  9459. ** changes for tables that do not appear in the first changeset, they are
  9460. ** appended onto the end of the output changeset, again in the order in
  9461. ** which they are first encountered.
  9462. **
  9463. ** If an error occurs, an SQLite error code is returned and the output
  9464. ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
  9465. ** is returned and the output variables are set to the size of and a
  9466. ** pointer to the output buffer, respectively. In this case it is the
  9467. ** responsibility of the caller to eventually free the buffer using a
  9468. ** call to sqlite3_free().
  9469. */
  9470. SQLITE_API int sqlite3changegroup_output(
  9471. sqlite3_changegroup*,
  9472. int *pnData, /* OUT: Size of output buffer in bytes */
  9473. void **ppData /* OUT: Pointer to output buffer */
  9474. );
  9475. /*
  9476. ** CAPI3REF: Delete A Changegroup Object
  9477. */
  9478. SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
  9479. /*
  9480. ** CAPI3REF: Apply A Changeset To A Database
  9481. **
  9482. ** Apply a changeset to a database. This function attempts to update the
  9483. ** "main" database attached to handle db with the changes found in the
  9484. ** changeset passed via the second and third arguments.
  9485. **
  9486. ** The fourth argument (xFilter) passed to this function is the "filter
  9487. ** callback". If it is not NULL, then for each table affected by at least one
  9488. ** change in the changeset, the filter callback is invoked with
  9489. ** the table name as the second argument, and a copy of the context pointer
  9490. ** passed as the sixth argument to this function as the first. If the "filter
  9491. ** callback" returns zero, then no attempt is made to apply any changes to
  9492. ** the table. Otherwise, if the return value is non-zero or the xFilter
  9493. ** argument to this function is NULL, all changes related to the table are
  9494. ** attempted.
  9495. **
  9496. ** For each table that is not excluded by the filter callback, this function
  9497. ** tests that the target database contains a compatible table. A table is
  9498. ** considered compatible if all of the following are true:
  9499. **
  9500. ** <ul>
  9501. ** <li> The table has the same name as the name recorded in the
  9502. ** changeset, and
  9503. ** <li> The table has at least as many columns as recorded in the
  9504. ** changeset, and
  9505. ** <li> The table has primary key columns in the same position as
  9506. ** recorded in the changeset.
  9507. ** </ul>
  9508. **
  9509. ** If there is no compatible table, it is not an error, but none of the
  9510. ** changes associated with the table are applied. A warning message is issued
  9511. ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
  9512. ** one such warning is issued for each table in the changeset.
  9513. **
  9514. ** For each change for which there is a compatible table, an attempt is made
  9515. ** to modify the table contents according to the UPDATE, INSERT or DELETE
  9516. ** change. If a change cannot be applied cleanly, the conflict handler
  9517. ** function passed as the fifth argument to sqlite3changeset_apply() may be
  9518. ** invoked. A description of exactly when the conflict handler is invoked for
  9519. ** each type of change is below.
  9520. **
  9521. ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
  9522. ** of passing anything other than a valid function pointer as the xConflict
  9523. ** argument are undefined.
  9524. **
  9525. ** Each time the conflict handler function is invoked, it must return one
  9526. ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
  9527. ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
  9528. ** if the second argument passed to the conflict handler is either
  9529. ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
  9530. ** returns an illegal value, any changes already made are rolled back and
  9531. ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
  9532. ** actions are taken by sqlite3changeset_apply() depending on the value
  9533. ** returned by each invocation of the conflict-handler function. Refer to
  9534. ** the documentation for the three
  9535. ** [SQLITE_CHANGESET_OMIT|available return values] for details.
  9536. **
  9537. ** <dl>
  9538. ** <dt>DELETE Changes<dd>
  9539. ** For each DELETE change, this function checks if the target database
  9540. ** contains a row with the same primary key value (or values) as the
  9541. ** original row values stored in the changeset. If it does, and the values
  9542. ** stored in all non-primary key columns also match the values stored in
  9543. ** the changeset the row is deleted from the target database.
  9544. **
  9545. ** If a row with matching primary key values is found, but one or more of
  9546. ** the non-primary key fields contains a value different from the original
  9547. ** row value stored in the changeset, the conflict-handler function is
  9548. ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
  9549. ** database table has more columns than are recorded in the changeset,
  9550. ** only the values of those non-primary key fields are compared against
  9551. ** the current database contents - any trailing database table columns
  9552. ** are ignored.
  9553. **
  9554. ** If no row with matching primary key values is found in the database,
  9555. ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  9556. ** passed as the second argument.
  9557. **
  9558. ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
  9559. ** (which can only happen if a foreign key constraint is violated), the
  9560. ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
  9561. ** passed as the second argument. This includes the case where the DELETE
  9562. ** operation is attempted because an earlier call to the conflict handler
  9563. ** function returned [SQLITE_CHANGESET_REPLACE].
  9564. **
  9565. ** <dt>INSERT Changes<dd>
  9566. ** For each INSERT change, an attempt is made to insert the new row into
  9567. ** the database. If the changeset row contains fewer fields than the
  9568. ** database table, the trailing fields are populated with their default
  9569. ** values.
  9570. **
  9571. ** If the attempt to insert the row fails because the database already
  9572. ** contains a row with the same primary key values, the conflict handler
  9573. ** function is invoked with the second argument set to
  9574. ** [SQLITE_CHANGESET_CONFLICT].
  9575. **
  9576. ** If the attempt to insert the row fails because of some other constraint
  9577. ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
  9578. ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
  9579. ** This includes the case where the INSERT operation is re-attempted because
  9580. ** an earlier call to the conflict handler function returned
  9581. ** [SQLITE_CHANGESET_REPLACE].
  9582. **
  9583. ** <dt>UPDATE Changes<dd>
  9584. ** For each UPDATE change, this function checks if the target database
  9585. ** contains a row with the same primary key value (or values) as the
  9586. ** original row values stored in the changeset. If it does, and the values
  9587. ** stored in all modified non-primary key columns also match the values
  9588. ** stored in the changeset the row is updated within the target database.
  9589. **
  9590. ** If a row with matching primary key values is found, but one or more of
  9591. ** the modified non-primary key fields contains a value different from an
  9592. ** original row value stored in the changeset, the conflict-handler function
  9593. ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
  9594. ** UPDATE changes only contain values for non-primary key fields that are
  9595. ** to be modified, only those fields need to match the original values to
  9596. ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
  9597. **
  9598. ** If no row with matching primary key values is found in the database,
  9599. ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  9600. ** passed as the second argument.
  9601. **
  9602. ** If the UPDATE operation is attempted, but SQLite returns
  9603. ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
  9604. ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
  9605. ** This includes the case where the UPDATE operation is attempted after
  9606. ** an earlier call to the conflict handler function returned
  9607. ** [SQLITE_CHANGESET_REPLACE].
  9608. ** </dl>
  9609. **
  9610. ** It is safe to execute SQL statements, including those that write to the
  9611. ** table that the callback related to, from within the xConflict callback.
  9612. ** This can be used to further customize the applications conflict
  9613. ** resolution strategy.
  9614. **
  9615. ** All changes made by this function are enclosed in a savepoint transaction.
  9616. ** If any other error (aside from a constraint failure when attempting to
  9617. ** write to the target database) occurs, then the savepoint transaction is
  9618. ** rolled back, restoring the target database to its original state, and an
  9619. ** SQLite error code returned.
  9620. */
  9621. SQLITE_API int sqlite3changeset_apply(
  9622. sqlite3 *db, /* Apply change to "main" db of this handle */
  9623. int nChangeset, /* Size of changeset in bytes */
  9624. void *pChangeset, /* Changeset blob */
  9625. int(*xFilter)(
  9626. void *pCtx, /* Copy of sixth arg to _apply() */
  9627. const char *zTab /* Table name */
  9628. ),
  9629. int(*xConflict)(
  9630. void *pCtx, /* Copy of sixth arg to _apply() */
  9631. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  9632. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  9633. ),
  9634. void *pCtx /* First argument passed to xConflict */
  9635. );
  9636. /*
  9637. ** CAPI3REF: Constants Passed To The Conflict Handler
  9638. **
  9639. ** Values that may be passed as the second argument to a conflict-handler.
  9640. **
  9641. ** <dl>
  9642. ** <dt>SQLITE_CHANGESET_DATA<dd>
  9643. ** The conflict handler is invoked with CHANGESET_DATA as the second argument
  9644. ** when processing a DELETE or UPDATE change if a row with the required
  9645. ** PRIMARY KEY fields is present in the database, but one or more other
  9646. ** (non primary-key) fields modified by the update do not contain the
  9647. ** expected "before" values.
  9648. **
  9649. ** The conflicting row, in this case, is the database row with the matching
  9650. ** primary key.
  9651. **
  9652. ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
  9653. ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
  9654. ** argument when processing a DELETE or UPDATE change if a row with the
  9655. ** required PRIMARY KEY fields is not present in the database.
  9656. **
  9657. ** There is no conflicting row in this case. The results of invoking the
  9658. ** sqlite3changeset_conflict() API are undefined.
  9659. **
  9660. ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
  9661. ** CHANGESET_CONFLICT is passed as the second argument to the conflict
  9662. ** handler while processing an INSERT change if the operation would result
  9663. ** in duplicate primary key values.
  9664. **
  9665. ** The conflicting row in this case is the database row with the matching
  9666. ** primary key.
  9667. **
  9668. ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
  9669. ** If foreign key handling is enabled, and applying a changeset leaves the
  9670. ** database in a state containing foreign key violations, the conflict
  9671. ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
  9672. ** exactly once before the changeset is committed. If the conflict handler
  9673. ** returns CHANGESET_OMIT, the changes, including those that caused the
  9674. ** foreign key constraint violation, are committed. Or, if it returns
  9675. ** CHANGESET_ABORT, the changeset is rolled back.
  9676. **
  9677. ** No current or conflicting row information is provided. The only function
  9678. ** it is possible to call on the supplied sqlite3_changeset_iter handle
  9679. ** is sqlite3changeset_fk_conflicts().
  9680. **
  9681. ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
  9682. ** If any other constraint violation occurs while applying a change (i.e.
  9683. ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
  9684. ** invoked with CHANGESET_CONSTRAINT as the second argument.
  9685. **
  9686. ** There is no conflicting row in this case. The results of invoking the
  9687. ** sqlite3changeset_conflict() API are undefined.
  9688. **
  9689. ** </dl>
  9690. */
  9691. #define SQLITE_CHANGESET_DATA 1
  9692. #define SQLITE_CHANGESET_NOTFOUND 2
  9693. #define SQLITE_CHANGESET_CONFLICT 3
  9694. #define SQLITE_CHANGESET_CONSTRAINT 4
  9695. #define SQLITE_CHANGESET_FOREIGN_KEY 5
  9696. /*
  9697. ** CAPI3REF: Constants Returned By The Conflict Handler
  9698. **
  9699. ** A conflict handler callback must return one of the following three values.
  9700. **
  9701. ** <dl>
  9702. ** <dt>SQLITE_CHANGESET_OMIT<dd>
  9703. ** If a conflict handler returns this value no special action is taken. The
  9704. ** change that caused the conflict is not applied. The session module
  9705. ** continues to the next change in the changeset.
  9706. **
  9707. ** <dt>SQLITE_CHANGESET_REPLACE<dd>
  9708. ** This value may only be returned if the second argument to the conflict
  9709. ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
  9710. ** is not the case, any changes applied so far are rolled back and the
  9711. ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
  9712. **
  9713. ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
  9714. ** handler, then the conflicting row is either updated or deleted, depending
  9715. ** on the type of change.
  9716. **
  9717. ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
  9718. ** handler, then the conflicting row is removed from the database and a
  9719. ** second attempt to apply the change is made. If this second attempt fails,
  9720. ** the original row is restored to the database before continuing.
  9721. **
  9722. ** <dt>SQLITE_CHANGESET_ABORT<dd>
  9723. ** If this value is returned, any changes applied so far are rolled back
  9724. ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
  9725. ** </dl>
  9726. */
  9727. #define SQLITE_CHANGESET_OMIT 0
  9728. #define SQLITE_CHANGESET_REPLACE 1
  9729. #define SQLITE_CHANGESET_ABORT 2
  9730. /*
  9731. ** CAPI3REF: Streaming Versions of API functions.
  9732. **
  9733. ** The six streaming API xxx_strm() functions serve similar purposes to the
  9734. ** corresponding non-streaming API functions:
  9735. **
  9736. ** <table border=1 style="margin-left:8ex;margin-right:8ex">
  9737. ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
  9738. ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
  9739. ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
  9740. ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
  9741. ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
  9742. ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
  9743. ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
  9744. ** </table>
  9745. **
  9746. ** Non-streaming functions that accept changesets (or patchsets) as input
  9747. ** require that the entire changeset be stored in a single buffer in memory.
  9748. ** Similarly, those that return a changeset or patchset do so by returning
  9749. ** a pointer to a single large buffer allocated using sqlite3_malloc().
  9750. ** Normally this is convenient. However, if an application running in a
  9751. ** low-memory environment is required to handle very large changesets, the
  9752. ** large contiguous memory allocations required can become onerous.
  9753. **
  9754. ** In order to avoid this problem, instead of a single large buffer, input
  9755. ** is passed to a streaming API functions by way of a callback function that
  9756. ** the sessions module invokes to incrementally request input data as it is
  9757. ** required. In all cases, a pair of API function parameters such as
  9758. **
  9759. ** <pre>
  9760. ** &nbsp; int nChangeset,
  9761. ** &nbsp; void *pChangeset,
  9762. ** </pre>
  9763. **
  9764. ** Is replaced by:
  9765. **
  9766. ** <pre>
  9767. ** &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
  9768. ** &nbsp; void *pIn,
  9769. ** </pre>
  9770. **
  9771. ** Each time the xInput callback is invoked by the sessions module, the first
  9772. ** argument passed is a copy of the supplied pIn context pointer. The second
  9773. ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
  9774. ** error occurs the xInput method should copy up to (*pnData) bytes of data
  9775. ** into the buffer and set (*pnData) to the actual number of bytes copied
  9776. ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
  9777. ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
  9778. ** error code should be returned. In all cases, if an xInput callback returns
  9779. ** an error, all processing is abandoned and the streaming API function
  9780. ** returns a copy of the error code to the caller.
  9781. **
  9782. ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
  9783. ** invoked by the sessions module at any point during the lifetime of the
  9784. ** iterator. If such an xInput callback returns an error, the iterator enters
  9785. ** an error state, whereby all subsequent calls to iterator functions
  9786. ** immediately fail with the same error code as returned by xInput.
  9787. **
  9788. ** Similarly, streaming API functions that return changesets (or patchsets)
  9789. ** return them in chunks by way of a callback function instead of via a
  9790. ** pointer to a single large buffer. In this case, a pair of parameters such
  9791. ** as:
  9792. **
  9793. ** <pre>
  9794. ** &nbsp; int *pnChangeset,
  9795. ** &nbsp; void **ppChangeset,
  9796. ** </pre>
  9797. **
  9798. ** Is replaced by:
  9799. **
  9800. ** <pre>
  9801. ** &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
  9802. ** &nbsp; void *pOut
  9803. ** </pre>
  9804. **
  9805. ** The xOutput callback is invoked zero or more times to return data to
  9806. ** the application. The first parameter passed to each call is a copy of the
  9807. ** pOut pointer supplied by the application. The second parameter, pData,
  9808. ** points to a buffer nData bytes in size containing the chunk of output
  9809. ** data being returned. If the xOutput callback successfully processes the
  9810. ** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
  9811. ** it should return some other SQLite error code. In this case processing
  9812. ** is immediately abandoned and the streaming API function returns a copy
  9813. ** of the xOutput error code to the application.
  9814. **
  9815. ** The sessions module never invokes an xOutput callback with the third
  9816. ** parameter set to a value less than or equal to zero. Other than this,
  9817. ** no guarantees are made as to the size of the chunks of data returned.
  9818. */
  9819. SQLITE_API int sqlite3changeset_apply_strm(
  9820. sqlite3 *db, /* Apply change to "main" db of this handle */
  9821. int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  9822. void *pIn, /* First arg for xInput */
  9823. int(*xFilter)(
  9824. void *pCtx, /* Copy of sixth arg to _apply() */
  9825. const char *zTab /* Table name */
  9826. ),
  9827. int(*xConflict)(
  9828. void *pCtx, /* Copy of sixth arg to _apply() */
  9829. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  9830. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  9831. ),
  9832. void *pCtx /* First argument passed to xConflict */
  9833. );
  9834. SQLITE_API int sqlite3changeset_concat_strm(
  9835. int (*xInputA)(void *pIn, void *pData, int *pnData),
  9836. void *pInA,
  9837. int (*xInputB)(void *pIn, void *pData, int *pnData),
  9838. void *pInB,
  9839. int (*xOutput)(void *pOut, const void *pData, int nData),
  9840. void *pOut
  9841. );
  9842. SQLITE_API int sqlite3changeset_invert_strm(
  9843. int (*xInput)(void *pIn, void *pData, int *pnData),
  9844. void *pIn,
  9845. int (*xOutput)(void *pOut, const void *pData, int nData),
  9846. void *pOut
  9847. );
  9848. SQLITE_API int sqlite3changeset_start_strm(
  9849. sqlite3_changeset_iter **pp,
  9850. int (*xInput)(void *pIn, void *pData, int *pnData),
  9851. void *pIn
  9852. );
  9853. SQLITE_API int sqlite3session_changeset_strm(
  9854. sqlite3_session *pSession,
  9855. int (*xOutput)(void *pOut, const void *pData, int nData),
  9856. void *pOut
  9857. );
  9858. SQLITE_API int sqlite3session_patchset_strm(
  9859. sqlite3_session *pSession,
  9860. int (*xOutput)(void *pOut, const void *pData, int nData),
  9861. void *pOut
  9862. );
  9863. SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
  9864. int (*xInput)(void *pIn, void *pData, int *pnData),
  9865. void *pIn
  9866. );
  9867. SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
  9868. int (*xOutput)(void *pOut, const void *pData, int nData),
  9869. void *pOut
  9870. );
  9871. /*
  9872. ** Make sure we can call this stuff from C++.
  9873. */
  9874. #ifdef __cplusplus
  9875. }
  9876. #endif
  9877. #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */
  9878. /******** End of sqlite3session.h *********/
  9879. /******** Begin file fts5.h *********/
  9880. /*
  9881. ** 2014 May 31
  9882. **
  9883. ** The author disclaims copyright to this source code. In place of
  9884. ** a legal notice, here is a blessing:
  9885. **
  9886. ** May you do good and not evil.
  9887. ** May you find forgiveness for yourself and forgive others.
  9888. ** May you share freely, never taking more than you give.
  9889. **
  9890. ******************************************************************************
  9891. **
  9892. ** Interfaces to extend FTS5. Using the interfaces defined in this file,
  9893. ** FTS5 may be extended with:
  9894. **
  9895. ** * custom tokenizers, and
  9896. ** * custom auxiliary functions.
  9897. */
  9898. #ifndef _FTS5_H
  9899. #define _FTS5_H
  9900. #ifdef __cplusplus
  9901. extern "C" {
  9902. #endif
  9903. /*************************************************************************
  9904. ** CUSTOM AUXILIARY FUNCTIONS
  9905. **
  9906. ** Virtual table implementations may overload SQL functions by implementing
  9907. ** the sqlite3_module.xFindFunction() method.
  9908. */
  9909. typedef struct Fts5ExtensionApi Fts5ExtensionApi;
  9910. typedef struct Fts5Context Fts5Context;
  9911. typedef struct Fts5PhraseIter Fts5PhraseIter;
  9912. typedef void (*fts5_extension_function)(
  9913. const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
  9914. Fts5Context *pFts, /* First arg to pass to pApi functions */
  9915. sqlite3_context *pCtx, /* Context for returning result/error */
  9916. int nVal, /* Number of values in apVal[] array */
  9917. sqlite3_value **apVal /* Array of trailing arguments */
  9918. );
  9919. struct Fts5PhraseIter {
  9920. const unsigned char *a;
  9921. const unsigned char *b;
  9922. };
  9923. /*
  9924. ** EXTENSION API FUNCTIONS
  9925. **
  9926. ** xUserData(pFts):
  9927. ** Return a copy of the context pointer the extension function was
  9928. ** registered with.
  9929. **
  9930. ** xColumnTotalSize(pFts, iCol, pnToken):
  9931. ** If parameter iCol is less than zero, set output variable *pnToken
  9932. ** to the total number of tokens in the FTS5 table. Or, if iCol is
  9933. ** non-negative but less than the number of columns in the table, return
  9934. ** the total number of tokens in column iCol, considering all rows in
  9935. ** the FTS5 table.
  9936. **
  9937. ** If parameter iCol is greater than or equal to the number of columns
  9938. ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
  9939. ** an OOM condition or IO error), an appropriate SQLite error code is
  9940. ** returned.
  9941. **
  9942. ** xColumnCount(pFts):
  9943. ** Return the number of columns in the table.
  9944. **
  9945. ** xColumnSize(pFts, iCol, pnToken):
  9946. ** If parameter iCol is less than zero, set output variable *pnToken
  9947. ** to the total number of tokens in the current row. Or, if iCol is
  9948. ** non-negative but less than the number of columns in the table, set
  9949. ** *pnToken to the number of tokens in column iCol of the current row.
  9950. **
  9951. ** If parameter iCol is greater than or equal to the number of columns
  9952. ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
  9953. ** an OOM condition or IO error), an appropriate SQLite error code is
  9954. ** returned.
  9955. **
  9956. ** This function may be quite inefficient if used with an FTS5 table
  9957. ** created with the "columnsize=0" option.
  9958. **
  9959. ** xColumnText:
  9960. ** This function attempts to retrieve the text of column iCol of the
  9961. ** current document. If successful, (*pz) is set to point to a buffer
  9962. ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
  9963. ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
  9964. ** if an error occurs, an SQLite error code is returned and the final values
  9965. ** of (*pz) and (*pn) are undefined.
  9966. **
  9967. ** xPhraseCount:
  9968. ** Returns the number of phrases in the current query expression.
  9969. **
  9970. ** xPhraseSize:
  9971. ** Returns the number of tokens in phrase iPhrase of the query. Phrases
  9972. ** are numbered starting from zero.
  9973. **
  9974. ** xInstCount:
  9975. ** Set *pnInst to the total number of occurrences of all phrases within
  9976. ** the query within the current row. Return SQLITE_OK if successful, or
  9977. ** an error code (i.e. SQLITE_NOMEM) if an error occurs.
  9978. **
  9979. ** This API can be quite slow if used with an FTS5 table created with the
  9980. ** "detail=none" or "detail=column" option. If the FTS5 table is created
  9981. ** with either "detail=none" or "detail=column" and "content=" option
  9982. ** (i.e. if it is a contentless table), then this API always returns 0.
  9983. **
  9984. ** xInst:
  9985. ** Query for the details of phrase match iIdx within the current row.
  9986. ** Phrase matches are numbered starting from zero, so the iIdx argument
  9987. ** should be greater than or equal to zero and smaller than the value
  9988. ** output by xInstCount().
  9989. **
  9990. ** Usually, output parameter *piPhrase is set to the phrase number, *piCol
  9991. ** to the column in which it occurs and *piOff the token offset of the
  9992. ** first token of the phrase. The exception is if the table was created
  9993. ** with the offsets=0 option specified. In this case *piOff is always
  9994. ** set to -1.
  9995. **
  9996. ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM)
  9997. ** if an error occurs.
  9998. **
  9999. ** This API can be quite slow if used with an FTS5 table created with the
  10000. ** "detail=none" or "detail=column" option.
  10001. **
  10002. ** xRowid:
  10003. ** Returns the rowid of the current row.
  10004. **
  10005. ** xTokenize:
  10006. ** Tokenize text using the tokenizer belonging to the FTS5 table.
  10007. **
  10008. ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):
  10009. ** This API function is used to query the FTS table for phrase iPhrase
  10010. ** of the current query. Specifically, a query equivalent to:
  10011. **
  10012. ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid
  10013. **
  10014. ** with $p set to a phrase equivalent to the phrase iPhrase of the
  10015. ** current query is executed. Any column filter that applies to
  10016. ** phrase iPhrase of the current query is included in $p. For each
  10017. ** row visited, the callback function passed as the fourth argument
  10018. ** is invoked. The context and API objects passed to the callback
  10019. ** function may be used to access the properties of each matched row.
  10020. ** Invoking Api.xUserData() returns a copy of the pointer passed as
  10021. ** the third argument to pUserData.
  10022. **
  10023. ** If the callback function returns any value other than SQLITE_OK, the
  10024. ** query is abandoned and the xQueryPhrase function returns immediately.
  10025. ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
  10026. ** Otherwise, the error code is propagated upwards.
  10027. **
  10028. ** If the query runs to completion without incident, SQLITE_OK is returned.
  10029. ** Or, if some error occurs before the query completes or is aborted by
  10030. ** the callback, an SQLite error code is returned.
  10031. **
  10032. **
  10033. ** xSetAuxdata(pFts5, pAux, xDelete)
  10034. **
  10035. ** Save the pointer passed as the second argument as the extension functions
  10036. ** "auxiliary data". The pointer may then be retrieved by the current or any
  10037. ** future invocation of the same fts5 extension function made as part of
  10038. ** of the same MATCH query using the xGetAuxdata() API.
  10039. **
  10040. ** Each extension function is allocated a single auxiliary data slot for
  10041. ** each FTS query (MATCH expression). If the extension function is invoked
  10042. ** more than once for a single FTS query, then all invocations share a
  10043. ** single auxiliary data context.
  10044. **
  10045. ** If there is already an auxiliary data pointer when this function is
  10046. ** invoked, then it is replaced by the new pointer. If an xDelete callback
  10047. ** was specified along with the original pointer, it is invoked at this
  10048. ** point.
  10049. **
  10050. ** The xDelete callback, if one is specified, is also invoked on the
  10051. ** auxiliary data pointer after the FTS5 query has finished.
  10052. **
  10053. ** If an error (e.g. an OOM condition) occurs within this function, an
  10054. ** the auxiliary data is set to NULL and an error code returned. If the
  10055. ** xDelete parameter was not NULL, it is invoked on the auxiliary data
  10056. ** pointer before returning.
  10057. **
  10058. **
  10059. ** xGetAuxdata(pFts5, bClear)
  10060. **
  10061. ** Returns the current auxiliary data pointer for the fts5 extension
  10062. ** function. See the xSetAuxdata() method for details.
  10063. **
  10064. ** If the bClear argument is non-zero, then the auxiliary data is cleared
  10065. ** (set to NULL) before this function returns. In this case the xDelete,
  10066. ** if any, is not invoked.
  10067. **
  10068. **
  10069. ** xRowCount(pFts5, pnRow)
  10070. **
  10071. ** This function is used to retrieve the total number of rows in the table.
  10072. ** In other words, the same value that would be returned by:
  10073. **
  10074. ** SELECT count(*) FROM ftstable;
  10075. **
  10076. ** xPhraseFirst()
  10077. ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
  10078. ** method, to iterate through all instances of a single query phrase within
  10079. ** the current row. This is the same information as is accessible via the
  10080. ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient
  10081. ** to use, this API may be faster under some circumstances. To iterate
  10082. ** through instances of phrase iPhrase, use the following code:
  10083. **
  10084. ** Fts5PhraseIter iter;
  10085. ** int iCol, iOff;
  10086. ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
  10087. ** iCol>=0;
  10088. ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
  10089. ** ){
  10090. ** // An instance of phrase iPhrase at offset iOff of column iCol
  10091. ** }
  10092. **
  10093. ** The Fts5PhraseIter structure is defined above. Applications should not
  10094. ** modify this structure directly - it should only be used as shown above
  10095. ** with the xPhraseFirst() and xPhraseNext() API methods (and by
  10096. ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
  10097. **
  10098. ** This API can be quite slow if used with an FTS5 table created with the
  10099. ** "detail=none" or "detail=column" option. If the FTS5 table is created
  10100. ** with either "detail=none" or "detail=column" and "content=" option
  10101. ** (i.e. if it is a contentless table), then this API always iterates
  10102. ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
  10103. **
  10104. ** xPhraseNext()
  10105. ** See xPhraseFirst above.
  10106. **
  10107. ** xPhraseFirstColumn()
  10108. ** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
  10109. ** and xPhraseNext() APIs described above. The difference is that instead
  10110. ** of iterating through all instances of a phrase in the current row, these
  10111. ** APIs are used to iterate through the set of columns in the current row
  10112. ** that contain one or more instances of a specified phrase. For example:
  10113. **
  10114. ** Fts5PhraseIter iter;
  10115. ** int iCol;
  10116. ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
  10117. ** iCol>=0;
  10118. ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
  10119. ** ){
  10120. ** // Column iCol contains at least one instance of phrase iPhrase
  10121. ** }
  10122. **
  10123. ** This API can be quite slow if used with an FTS5 table created with the
  10124. ** "detail=none" option. If the FTS5 table is created with either
  10125. ** "detail=none" "content=" option (i.e. if it is a contentless table),
  10126. ** then this API always iterates through an empty set (all calls to
  10127. ** xPhraseFirstColumn() set iCol to -1).
  10128. **
  10129. ** The information accessed using this API and its companion
  10130. ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
  10131. ** (or xInst/xInstCount). The chief advantage of this API is that it is
  10132. ** significantly more efficient than those alternatives when used with
  10133. ** "detail=column" tables.
  10134. **
  10135. ** xPhraseNextColumn()
  10136. ** See xPhraseFirstColumn above.
  10137. */
  10138. struct Fts5ExtensionApi {
  10139. int iVersion; /* Currently always set to 3 */
  10140. void *(*xUserData)(Fts5Context*);
  10141. int (*xColumnCount)(Fts5Context*);
  10142. int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
  10143. int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
  10144. int (*xTokenize)(Fts5Context*,
  10145. const char *pText, int nText, /* Text to tokenize */
  10146. void *pCtx, /* Context passed to xToken() */
  10147. int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
  10148. );
  10149. int (*xPhraseCount)(Fts5Context*);
  10150. int (*xPhraseSize)(Fts5Context*, int iPhrase);
  10151. int (*xInstCount)(Fts5Context*, int *pnInst);
  10152. int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
  10153. sqlite3_int64 (*xRowid)(Fts5Context*);
  10154. int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
  10155. int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
  10156. int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
  10157. int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
  10158. );
  10159. int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
  10160. void *(*xGetAuxdata)(Fts5Context*, int bClear);
  10161. int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
  10162. void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
  10163. int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
  10164. void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
  10165. };
  10166. /*
  10167. ** CUSTOM AUXILIARY FUNCTIONS
  10168. *************************************************************************/
  10169. /*************************************************************************
  10170. ** CUSTOM TOKENIZERS
  10171. **
  10172. ** Applications may also register custom tokenizer types. A tokenizer
  10173. ** is registered by providing fts5 with a populated instance of the
  10174. ** following structure. All structure methods must be defined, setting
  10175. ** any member of the fts5_tokenizer struct to NULL leads to undefined
  10176. ** behaviour. The structure methods are expected to function as follows:
  10177. **
  10178. ** xCreate:
  10179. ** This function is used to allocate and initialize a tokenizer instance.
  10180. ** A tokenizer instance is required to actually tokenize text.
  10181. **
  10182. ** The first argument passed to this function is a copy of the (void*)
  10183. ** pointer provided by the application when the fts5_tokenizer object
  10184. ** was registered with FTS5 (the third argument to xCreateTokenizer()).
  10185. ** The second and third arguments are an array of nul-terminated strings
  10186. ** containing the tokenizer arguments, if any, specified following the
  10187. ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used
  10188. ** to create the FTS5 table.
  10189. **
  10190. ** The final argument is an output variable. If successful, (*ppOut)
  10191. ** should be set to point to the new tokenizer handle and SQLITE_OK
  10192. ** returned. If an error occurs, some value other than SQLITE_OK should
  10193. ** be returned. In this case, fts5 assumes that the final value of *ppOut
  10194. ** is undefined.
  10195. **
  10196. ** xDelete:
  10197. ** This function is invoked to delete a tokenizer handle previously
  10198. ** allocated using xCreate(). Fts5 guarantees that this function will
  10199. ** be invoked exactly once for each successful call to xCreate().
  10200. **
  10201. ** xTokenize:
  10202. ** This function is expected to tokenize the nText byte string indicated
  10203. ** by argument pText. pText may or may not be nul-terminated. The first
  10204. ** argument passed to this function is a pointer to an Fts5Tokenizer object
  10205. ** returned by an earlier call to xCreate().
  10206. **
  10207. ** The second argument indicates the reason that FTS5 is requesting
  10208. ** tokenization of the supplied text. This is always one of the following
  10209. ** four values:
  10210. **
  10211. ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
  10212. ** or removed from the FTS table. The tokenizer is being invoked to
  10213. ** determine the set of tokens to add to (or delete from) the
  10214. ** FTS index.
  10215. **
  10216. ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
  10217. ** against the FTS index. The tokenizer is being called to tokenize
  10218. ** a bareword or quoted string specified as part of the query.
  10219. **
  10220. ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
  10221. ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
  10222. ** followed by a "*" character, indicating that the last token
  10223. ** returned by the tokenizer will be treated as a token prefix.
  10224. **
  10225. ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
  10226. ** satisfy an fts5_api.xTokenize() request made by an auxiliary
  10227. ** function. Or an fts5_api.xColumnSize() request made by the same
  10228. ** on a columnsize=0 database.
  10229. ** </ul>
  10230. **
  10231. ** For each token in the input string, the supplied callback xToken() must
  10232. ** be invoked. The first argument to it should be a copy of the pointer
  10233. ** passed as the second argument to xTokenize(). The third and fourth
  10234. ** arguments are a pointer to a buffer containing the token text, and the
  10235. ** size of the token in bytes. The 4th and 5th arguments are the byte offsets
  10236. ** of the first byte of and first byte immediately following the text from
  10237. ** which the token is derived within the input.
  10238. **
  10239. ** The second argument passed to the xToken() callback ("tflags") should
  10240. ** normally be set to 0. The exception is if the tokenizer supports
  10241. ** synonyms. In this case see the discussion below for details.
  10242. **
  10243. ** FTS5 assumes the xToken() callback is invoked for each token in the
  10244. ** order that they occur within the input text.
  10245. **
  10246. ** If an xToken() callback returns any value other than SQLITE_OK, then
  10247. ** the tokenization should be abandoned and the xTokenize() method should
  10248. ** immediately return a copy of the xToken() return value. Or, if the
  10249. ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
  10250. ** if an error occurs with the xTokenize() implementation itself, it
  10251. ** may abandon the tokenization and return any error code other than
  10252. ** SQLITE_OK or SQLITE_DONE.
  10253. **
  10254. ** SYNONYM SUPPORT
  10255. **
  10256. ** Custom tokenizers may also support synonyms. Consider a case in which a
  10257. ** user wishes to query for a phrase such as "first place". Using the
  10258. ** built-in tokenizers, the FTS5 query 'first + place' will match instances
  10259. ** of "first place" within the document set, but not alternative forms
  10260. ** such as "1st place". In some applications, it would be better to match
  10261. ** all instances of "first place" or "1st place" regardless of which form
  10262. ** the user specified in the MATCH query text.
  10263. **
  10264. ** There are several ways to approach this in FTS5:
  10265. **
  10266. ** <ol><li> By mapping all synonyms to a single token. In this case, the
  10267. ** In the above example, this means that the tokenizer returns the
  10268. ** same token for inputs "first" and "1st". Say that token is in
  10269. ** fact "first", so that when the user inserts the document "I won
  10270. ** 1st place" entries are added to the index for tokens "i", "won",
  10271. ** "first" and "place". If the user then queries for '1st + place',
  10272. ** the tokenizer substitutes "first" for "1st" and the query works
  10273. ** as expected.
  10274. **
  10275. ** <li> By adding multiple synonyms for a single term to the FTS index.
  10276. ** In this case, when tokenizing query text, the tokenizer may
  10277. ** provide multiple synonyms for a single term within the document.
  10278. ** FTS5 then queries the index for each synonym individually. For
  10279. ** example, faced with the query:
  10280. **
  10281. ** <codeblock>
  10282. ** ... MATCH 'first place'</codeblock>
  10283. **
  10284. ** the tokenizer offers both "1st" and "first" as synonyms for the
  10285. ** first token in the MATCH query and FTS5 effectively runs a query
  10286. ** similar to:
  10287. **
  10288. ** <codeblock>
  10289. ** ... MATCH '(first OR 1st) place'</codeblock>
  10290. **
  10291. ** except that, for the purposes of auxiliary functions, the query
  10292. ** still appears to contain just two phrases - "(first OR 1st)"
  10293. ** being treated as a single phrase.
  10294. **
  10295. ** <li> By adding multiple synonyms for a single term to the FTS index.
  10296. ** Using this method, when tokenizing document text, the tokenizer
  10297. ** provides multiple synonyms for each token. So that when a
  10298. ** document such as "I won first place" is tokenized, entries are
  10299. ** added to the FTS index for "i", "won", "first", "1st" and
  10300. ** "place".
  10301. **
  10302. ** This way, even if the tokenizer does not provide synonyms
  10303. ** when tokenizing query text (it should not - to do would be
  10304. ** inefficient), it doesn't matter if the user queries for
  10305. ** 'first + place' or '1st + place', as there are entires in the
  10306. ** FTS index corresponding to both forms of the first token.
  10307. ** </ol>
  10308. **
  10309. ** Whether it is parsing document or query text, any call to xToken that
  10310. ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
  10311. ** is considered to supply a synonym for the previous token. For example,
  10312. ** when parsing the document "I won first place", a tokenizer that supports
  10313. ** synonyms would call xToken() 5 times, as follows:
  10314. **
  10315. ** <codeblock>
  10316. ** xToken(pCtx, 0, "i", 1, 0, 1);
  10317. ** xToken(pCtx, 0, "won", 3, 2, 5);
  10318. ** xToken(pCtx, 0, "first", 5, 6, 11);
  10319. ** xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3, 6, 11);
  10320. ** xToken(pCtx, 0, "place", 5, 12, 17);
  10321. **</codeblock>
  10322. **
  10323. ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
  10324. ** xToken() is called. Multiple synonyms may be specified for a single token
  10325. ** by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.
  10326. ** There is no limit to the number of synonyms that may be provided for a
  10327. ** single token.
  10328. **
  10329. ** In many cases, method (1) above is the best approach. It does not add
  10330. ** extra data to the FTS index or require FTS5 to query for multiple terms,
  10331. ** so it is efficient in terms of disk space and query speed. However, it
  10332. ** does not support prefix queries very well. If, as suggested above, the
  10333. ** token "first" is subsituted for "1st" by the tokenizer, then the query:
  10334. **
  10335. ** <codeblock>
  10336. ** ... MATCH '1s*'</codeblock>
  10337. **
  10338. ** will not match documents that contain the token "1st" (as the tokenizer
  10339. ** will probably not map "1s" to any prefix of "first").
  10340. **
  10341. ** For full prefix support, method (3) may be preferred. In this case,
  10342. ** because the index contains entries for both "first" and "1st", prefix
  10343. ** queries such as 'fi*' or '1s*' will match correctly. However, because
  10344. ** extra entries are added to the FTS index, this method uses more space
  10345. ** within the database.
  10346. **
  10347. ** Method (2) offers a midpoint between (1) and (3). Using this method,
  10348. ** a query such as '1s*' will match documents that contain the literal
  10349. ** token "1st", but not "first" (assuming the tokenizer is not able to
  10350. ** provide synonyms for prefixes). However, a non-prefix query like '1st'
  10351. ** will match against "1st" and "first". This method does not require
  10352. ** extra disk space, as no extra entries are added to the FTS index.
  10353. ** On the other hand, it may require more CPU cycles to run MATCH queries,
  10354. ** as separate queries of the FTS index are required for each synonym.
  10355. **
  10356. ** When using methods (2) or (3), it is important that the tokenizer only
  10357. ** provide synonyms when tokenizing document text (method (2)) or query
  10358. ** text (method (3)), not both. Doing so will not cause any errors, but is
  10359. ** inefficient.
  10360. */
  10361. typedef struct Fts5Tokenizer Fts5Tokenizer;
  10362. typedef struct fts5_tokenizer fts5_tokenizer;
  10363. struct fts5_tokenizer {
  10364. int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
  10365. void (*xDelete)(Fts5Tokenizer*);
  10366. int (*xTokenize)(Fts5Tokenizer*,
  10367. void *pCtx,
  10368. int flags, /* Mask of FTS5_TOKENIZE_* flags */
  10369. const char *pText, int nText,
  10370. int (*xToken)(
  10371. void *pCtx, /* Copy of 2nd argument to xTokenize() */
  10372. int tflags, /* Mask of FTS5_TOKEN_* flags */
  10373. const char *pToken, /* Pointer to buffer containing token */
  10374. int nToken, /* Size of token in bytes */
  10375. int iStart, /* Byte offset of token within input text */
  10376. int iEnd /* Byte offset of end of token within input text */
  10377. )
  10378. );
  10379. };
  10380. /* Flags that may be passed as the third argument to xTokenize() */
  10381. #define FTS5_TOKENIZE_QUERY 0x0001
  10382. #define FTS5_TOKENIZE_PREFIX 0x0002
  10383. #define FTS5_TOKENIZE_DOCUMENT 0x0004
  10384. #define FTS5_TOKENIZE_AUX 0x0008
  10385. /* Flags that may be passed by the tokenizer implementation back to FTS5
  10386. ** as the third argument to the supplied xToken callback. */
  10387. #define FTS5_TOKEN_COLOCATED 0x0001 /* Same position as prev. token */
  10388. /*
  10389. ** END OF CUSTOM TOKENIZERS
  10390. *************************************************************************/
  10391. /*************************************************************************
  10392. ** FTS5 EXTENSION REGISTRATION API
  10393. */
  10394. typedef struct fts5_api fts5_api;
  10395. struct fts5_api {
  10396. int iVersion; /* Currently always set to 2 */
  10397. /* Create a new tokenizer */
  10398. int (*xCreateTokenizer)(
  10399. fts5_api *pApi,
  10400. const char *zName,
  10401. void *pContext,
  10402. fts5_tokenizer *pTokenizer,
  10403. void (*xDestroy)(void*)
  10404. );
  10405. /* Find an existing tokenizer */
  10406. int (*xFindTokenizer)(
  10407. fts5_api *pApi,
  10408. const char *zName,
  10409. void **ppContext,
  10410. fts5_tokenizer *pTokenizer
  10411. );
  10412. /* Create a new auxiliary function */
  10413. int (*xCreateFunction)(
  10414. fts5_api *pApi,
  10415. const char *zName,
  10416. void *pContext,
  10417. fts5_extension_function xFunction,
  10418. void (*xDestroy)(void*)
  10419. );
  10420. };
  10421. /*
  10422. ** END OF REGISTRATION API
  10423. *************************************************************************/
  10424. #ifdef __cplusplus
  10425. } /* end of the 'extern "C"' block */
  10426. #endif
  10427. #endif /* _FTS5_H */
  10428. /******** End of fts5.h *********/