sqlite3.h 597 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828882988308831883288338834883588368837883888398840884188428843884488458846884788488849885088518852885388548855885688578858885988608861886288638864886588668867886888698870887188728873887488758876887788788879888088818882888388848885888688878888888988908891889288938894889588968897889888998900890189028903890489058906890789088909891089118912891389148915891689178918891989208921892289238924892589268927892889298930893189328933893489358936893789388939894089418942894389448945894689478948894989508951895289538954895589568957895889598960896189628963896489658966896789688969897089718972897389748975897689778978897989808981898289838984898589868987898889898990899189928993899489958996899789988999900090019002900390049005900690079008900990109011901290139014901590169017901890199020902190229023902490259026902790289029903090319032903390349035903690379038903990409041904290439044904590469047904890499050905190529053905490559056905790589059906090619062906390649065906690679068906990709071907290739074907590769077907890799080908190829083908490859086908790889089909090919092909390949095909690979098909991009101910291039104910591069107910891099110911191129113911491159116911791189119912091219122912391249125912691279128912991309131913291339134913591369137913891399140914191429143914491459146914791489149915091519152915391549155915691579158915991609161916291639164916591669167916891699170917191729173917491759176917791789179918091819182918391849185918691879188918991909191919291939194919591969197919891999200920192029203920492059206920792089209921092119212921392149215921692179218921992209221922292239224922592269227922892299230923192329233923492359236923792389239924092419242924392449245924692479248924992509251925292539254925592569257925892599260926192629263926492659266926792689269927092719272927392749275927692779278927992809281928292839284928592869287928892899290929192929293929492959296929792989299930093019302930393049305930693079308930993109311931293139314931593169317931893199320932193229323932493259326932793289329933093319332933393349335933693379338933993409341934293439344934593469347934893499350935193529353935493559356935793589359936093619362936393649365936693679368936993709371937293739374937593769377937893799380938193829383938493859386938793889389939093919392939393949395939693979398939994009401940294039404940594069407940894099410941194129413941494159416941794189419942094219422942394249425942694279428942994309431943294339434943594369437943894399440944194429443944494459446944794489449945094519452945394549455945694579458945994609461946294639464946594669467946894699470947194729473947494759476947794789479948094819482948394849485948694879488948994909491949294939494949594969497949894999500950195029503950495059506950795089509951095119512951395149515951695179518951995209521952295239524952595269527952895299530953195329533953495359536953795389539954095419542954395449545954695479548954995509551955295539554955595569557955895599560956195629563956495659566956795689569957095719572957395749575957695779578957995809581958295839584958595869587958895899590959195929593959495959596959795989599960096019602960396049605960696079608960996109611961296139614961596169617961896199620962196229623962496259626962796289629963096319632963396349635963696379638963996409641964296439644964596469647964896499650965196529653965496559656965796589659966096619662966396649665966696679668966996709671967296739674967596769677967896799680968196829683968496859686968796889689969096919692969396949695969696979698969997009701970297039704970597069707970897099710971197129713971497159716971797189719972097219722972397249725972697279728972997309731973297339734973597369737973897399740974197429743974497459746974797489749975097519752975397549755975697579758975997609761976297639764976597669767976897699770977197729773977497759776977797789779978097819782978397849785978697879788978997909791979297939794979597969797979897999800980198029803980498059806980798089809981098119812981398149815981698179818981998209821982298239824982598269827982898299830983198329833983498359836983798389839984098419842984398449845984698479848984998509851985298539854985598569857985898599860986198629863986498659866986798689869987098719872987398749875987698779878987998809881988298839884988598869887988898899890989198929893989498959896989798989899990099019902990399049905990699079908990999109911991299139914991599169917991899199920992199229923992499259926992799289929993099319932993399349935993699379938993999409941994299439944994599469947994899499950995199529953995499559956995799589959996099619962996399649965996699679968996999709971997299739974997599769977997899799980998199829983998499859986998799889989999099919992999399949995999699979998999910000100011000210003100041000510006100071000810009100101001110012100131001410015100161001710018100191002010021100221002310024100251002610027100281002910030100311003210033100341003510036100371003810039100401004110042100431004410045100461004710048100491005010051100521005310054100551005610057100581005910060100611006210063100641006510066100671006810069100701007110072100731007410075100761007710078100791008010081100821008310084100851008610087100881008910090100911009210093100941009510096100971009810099101001010110102101031010410105101061010710108101091011010111101121011310114101151011610117101181011910120101211012210123101241012510126101271012810129101301013110132101331013410135101361013710138101391014010141101421014310144101451014610147101481014910150101511015210153101541015510156101571015810159101601016110162101631016410165101661016710168101691017010171101721017310174101751017610177101781017910180101811018210183101841018510186101871018810189101901019110192101931019410195101961019710198101991020010201102021020310204102051020610207102081020910210102111021210213102141021510216102171021810219102201022110222102231022410225102261022710228102291023010231102321023310234102351023610237102381023910240102411024210243102441024510246102471024810249102501025110252102531025410255102561025710258102591026010261102621026310264102651026610267102681026910270102711027210273102741027510276102771027810279102801028110282102831028410285102861028710288102891029010291102921029310294102951029610297102981029910300103011030210303103041030510306103071030810309103101031110312103131031410315103161031710318103191032010321103221032310324103251032610327103281032910330103311033210333103341033510336103371033810339103401034110342103431034410345103461034710348103491035010351103521035310354103551035610357103581035910360103611036210363103641036510366103671036810369103701037110372103731037410375103761037710378103791038010381103821038310384103851038610387103881038910390103911039210393103941039510396103971039810399104001040110402104031040410405104061040710408104091041010411104121041310414104151041610417104181041910420104211042210423104241042510426104271042810429104301043110432104331043410435104361043710438104391044010441104421044310444104451044610447104481044910450104511045210453104541045510456104571045810459104601046110462104631046410465104661046710468104691047010471104721047310474104751047610477104781047910480104811048210483104841048510486104871048810489104901049110492104931049410495104961049710498104991050010501105021050310504105051050610507105081050910510105111051210513105141051510516105171051810519105201052110522105231052410525105261052710528105291053010531105321053310534105351053610537105381053910540105411054210543105441054510546105471054810549105501055110552105531055410555105561055710558105591056010561105621056310564105651056610567105681056910570105711057210573105741057510576105771057810579105801058110582105831058410585105861058710588105891059010591105921059310594105951059610597105981059910600106011060210603106041060510606106071060810609106101061110612106131061410615106161061710618106191062010621106221062310624106251062610627106281062910630106311063210633106341063510636106371063810639106401064110642106431064410645106461064710648106491065010651106521065310654106551065610657106581065910660106611066210663106641066510666106671066810669106701067110672106731067410675106761067710678106791068010681106821068310684106851068610687106881068910690106911069210693106941069510696106971069810699107001070110702107031070410705107061070710708107091071010711107121071310714107151071610717107181071910720107211072210723107241072510726107271072810729107301073110732107331073410735107361073710738107391074010741107421074310744107451074610747107481074910750107511075210753107541075510756107571075810759107601076110762107631076410765107661076710768107691077010771107721077310774107751077610777107781077910780107811078210783107841078510786107871078810789107901079110792107931079410795107961079710798107991080010801108021080310804108051080610807108081080910810108111081210813108141081510816108171081810819108201082110822108231082410825108261082710828108291083010831108321083310834108351083610837108381083910840108411084210843108441084510846108471084810849108501085110852108531085410855108561085710858108591086010861108621086310864108651086610867108681086910870108711087210873108741087510876108771087810879108801088110882108831088410885108861088710888108891089010891108921089310894108951089610897108981089910900109011090210903109041090510906109071090810909109101091110912109131091410915109161091710918109191092010921109221092310924109251092610927109281092910930109311093210933109341093510936109371093810939109401094110942109431094410945109461094710948109491095010951109521095310954109551095610957109581095910960109611096210963109641096510966109671096810969109701097110972109731097410975109761097710978109791098010981109821098310984109851098610987109881098910990109911099210993109941099510996109971099810999110001100111002110031100411005110061100711008110091101011011110121101311014110151101611017110181101911020110211102211023110241102511026110271102811029110301103111032110331103411035110361103711038110391104011041110421104311044110451104611047110481104911050110511105211053110541105511056110571105811059110601106111062110631106411065110661106711068110691107011071110721107311074110751107611077110781107911080110811108211083110841108511086110871108811089110901109111092110931109411095110961109711098110991110011101111021110311104111051110611107111081110911110111111111211113111141111511116111171111811119111201112111122111231112411125111261112711128111291113011131111321113311134111351113611137111381113911140111411114211143111441114511146111471114811149111501115111152111531115411155111561115711158111591116011161111621116311164111651116611167111681116911170111711117211173111741117511176111771117811179111801118111182111831118411185111861118711188111891119011191111921119311194111951119611197111981119911200112011120211203112041120511206112071120811209112101121111212112131121411215112161121711218112191122011221112221122311224112251122611227112281122911230112311123211233112341123511236112371123811239112401124111242112431124411245112461124711248112491125011251112521125311254112551125611257112581125911260112611126211263112641126511266112671126811269112701127111272112731127411275112761127711278112791128011281112821128311284112851128611287112881128911290112911129211293112941129511296112971129811299113001130111302113031130411305113061130711308113091131011311113121131311314113151131611317113181131911320113211132211323113241132511326113271132811329113301133111332113331133411335113361133711338113391134011341113421134311344113451134611347113481134911350113511135211353113541135511356113571135811359113601136111362113631136411365113661136711368113691137011371113721137311374113751137611377113781137911380113811138211383113841138511386113871138811389113901139111392113931139411395113961139711398113991140011401114021140311404114051140611407114081140911410114111141211413114141141511416114171141811419114201142111422114231142411425114261142711428114291143011431114321143311434114351143611437114381143911440114411144211443114441144511446114471144811449114501145111452114531145411455114561145711458114591146011461114621146311464114651146611467114681146911470114711147211473114741147511476114771147811479114801148111482114831148411485114861148711488114891149011491114921149311494114951149611497114981149911500115011150211503115041150511506115071150811509115101151111512115131151411515115161151711518115191152011521115221152311524115251152611527115281152911530115311153211533115341153511536115371153811539115401154111542115431154411545115461154711548115491155011551115521155311554115551155611557115581155911560115611156211563115641156511566115671156811569115701157111572115731157411575115761157711578115791158011581115821158311584115851158611587115881158911590115911159211593115941159511596115971159811599116001160111602116031160411605116061160711608116091161011611116121161311614116151161611617116181161911620116211162211623116241162511626116271162811629116301163111632116331163411635116361163711638116391164011641116421164311644116451164611647116481164911650116511165211653116541165511656116571165811659116601166111662116631166411665116661166711668116691167011671116721167311674116751167611677116781167911680116811168211683116841168511686116871168811689116901169111692116931169411695116961169711698116991170011701117021170311704117051170611707117081170911710117111171211713117141171511716117171171811719117201172111722117231172411725117261172711728117291173011731117321173311734117351173611737117381173911740117411174211743117441174511746117471174811749117501175111752117531175411755117561175711758117591176011761117621176311764117651176611767117681176911770117711177211773117741177511776117771177811779117801178111782117831178411785117861178711788117891179011791117921179311794117951179611797117981179911800118011180211803118041180511806118071180811809118101181111812118131181411815118161181711818118191182011821118221182311824118251182611827118281182911830118311183211833118341183511836118371183811839118401184111842118431184411845118461184711848118491185011851118521185311854118551185611857118581185911860118611186211863118641186511866118671186811869118701187111872118731187411875118761187711878118791188011881118821188311884118851188611887118881188911890118911189211893118941189511896118971189811899119001190111902119031190411905119061190711908119091191011911119121191311914119151191611917119181191911920119211192211923119241192511926119271192811929119301193111932119331193411935119361193711938119391194011941119421194311944119451194611947119481194911950119511195211953119541195511956119571195811959119601196111962119631196411965119661196711968119691197011971119721197311974119751197611977119781197911980119811198211983119841198511986119871198811989119901199111992119931199411995119961199711998119991200012001120021200312004120051200612007120081200912010120111201212013120141201512016120171201812019120201202112022120231202412025120261202712028120291203012031120321203312034120351203612037120381203912040120411204212043120441204512046120471204812049120501205112052120531205412055120561205712058120591206012061120621206312064120651206612067120681206912070120711207212073120741207512076120771207812079120801208112082120831208412085120861208712088120891209012091120921209312094120951209612097120981209912100121011210212103121041210512106121071210812109121101211112112121131211412115121161211712118121191212012121121221212312124121251212612127121281212912130121311213212133121341213512136121371213812139121401214112142121431214412145121461214712148121491215012151121521215312154121551215612157121581215912160121611216212163121641216512166121671216812169121701217112172121731217412175121761217712178121791218012181121821218312184121851218612187121881218912190121911219212193121941219512196121971219812199122001220112202122031220412205122061220712208122091221012211122121221312214122151221612217122181221912220122211222212223122241222512226122271222812229122301223112232122331223412235122361223712238122391224012241122421224312244122451224612247122481224912250122511225212253122541225512256122571225812259122601226112262122631226412265122661226712268122691227012271122721227312274122751227612277122781227912280122811228212283122841228512286122871228812289122901229112292122931229412295122961229712298122991230012301123021230312304123051230612307123081230912310123111231212313123141231512316123171231812319123201232112322123231232412325123261232712328123291233012331123321233312334123351233612337123381233912340123411234212343123441234512346123471234812349123501235112352123531235412355123561235712358123591236012361123621236312364123651236612367123681236912370123711237212373123741237512376123771237812379123801238112382123831238412385123861238712388123891239012391123921239312394123951239612397123981239912400124011240212403124041240512406124071240812409124101241112412124131241412415124161241712418124191242012421124221242312424124251242612427124281242912430124311243212433124341243512436124371243812439124401244112442124431244412445124461244712448124491245012451124521245312454124551245612457124581245912460124611246212463124641246512466124671246812469124701247112472124731247412475124761247712478124791248012481124821248312484124851248612487124881248912490124911249212493124941249512496124971249812499125001250112502125031250412505125061250712508125091251012511125121251312514125151251612517125181251912520125211252212523125241252512526125271252812529125301253112532125331253412535125361253712538125391254012541125421254312544125451254612547125481254912550125511255212553125541255512556125571255812559125601256112562125631256412565125661256712568125691257012571125721257312574125751257612577125781257912580125811258212583125841258512586125871258812589125901259112592125931259412595125961259712598125991260012601126021260312604126051260612607126081260912610126111261212613126141261512616126171261812619126201262112622126231262412625126261262712628126291263012631126321263312634126351263612637126381263912640126411264212643126441264512646126471264812649126501265112652126531265412655126561265712658126591266012661126621266312664126651266612667126681266912670126711267212673126741267512676126771267812679126801268112682126831268412685126861268712688126891269012691126921269312694126951269612697126981269912700127011270212703127041270512706127071270812709127101271112712127131271412715127161271712718127191272012721127221272312724127251272612727127281272912730127311273212733127341273512736127371273812739127401274112742127431274412745127461274712748127491275012751127521275312754127551275612757127581275912760127611276212763127641276512766127671276812769127701277112772127731277412775127761277712778127791278012781127821278312784127851278612787127881278912790127911279212793127941279512796127971279812799128001280112802
  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. ** Facilitate override of interface linkage and calling conventions.
  44. ** Be aware that these macros may not be used within this particular
  45. ** translation of the amalgamation and its associated header file.
  46. **
  47. ** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
  48. ** compiler that the target identifier should have external linkage.
  49. **
  50. ** The SQLITE_CDECL macro is used to set the calling convention for
  51. ** public functions that accept a variable number of arguments.
  52. **
  53. ** The SQLITE_APICALL macro is used to set the calling convention for
  54. ** public functions that accept a fixed number of arguments.
  55. **
  56. ** The SQLITE_STDCALL macro is no longer used and is now deprecated.
  57. **
  58. ** The SQLITE_CALLBACK macro is used to set the calling convention for
  59. ** function pointers.
  60. **
  61. ** The SQLITE_SYSAPI macro is used to set the calling convention for
  62. ** functions provided by the operating system.
  63. **
  64. ** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and
  65. ** SQLITE_SYSAPI macros are used only when building for environments
  66. ** that require non-default calling conventions.
  67. */
  68. #ifndef SQLITE_EXTERN
  69. # define SQLITE_EXTERN extern
  70. #endif
  71. #ifndef SQLITE_API
  72. # define SQLITE_API
  73. #endif
  74. #ifndef SQLITE_CDECL
  75. # define SQLITE_CDECL
  76. #endif
  77. #ifndef SQLITE_APICALL
  78. # define SQLITE_APICALL
  79. #endif
  80. #ifndef SQLITE_STDCALL
  81. # define SQLITE_STDCALL SQLITE_APICALL
  82. #endif
  83. #ifndef SQLITE_CALLBACK
  84. # define SQLITE_CALLBACK
  85. #endif
  86. #ifndef SQLITE_SYSAPI
  87. # define SQLITE_SYSAPI
  88. #endif
  89. /*
  90. ** These no-op macros are used in front of interfaces to mark those
  91. ** interfaces as either deprecated or experimental. New applications
  92. ** should not use deprecated interfaces - they are supported for backwards
  93. ** compatibility only. Application writers should be aware that
  94. ** experimental interfaces are subject to change in point releases.
  95. **
  96. ** These macros used to resolve to various kinds of compiler magic that
  97. ** would generate warning messages when they were used. But that
  98. ** compiler magic ended up generating such a flurry of bug reports
  99. ** that we have taken it all out and gone back to using simple
  100. ** noop macros.
  101. */
  102. #define SQLITE_DEPRECATED
  103. #define SQLITE_EXPERIMENTAL
  104. /*
  105. ** Ensure these symbols were not defined by some previous header file.
  106. */
  107. #ifdef SQLITE_VERSION
  108. # undef SQLITE_VERSION
  109. #endif
  110. #ifdef SQLITE_VERSION_NUMBER
  111. # undef SQLITE_VERSION_NUMBER
  112. #endif
  113. /*
  114. ** CAPI3REF: Compile-Time Library Version Numbers
  115. **
  116. ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
  117. ** evaluates to a string literal that is the SQLite version in the
  118. ** format "X.Y.Z" where X is the major version number (always 3 for
  119. ** SQLite3) and Y is the minor version number and Z is the release number.)^
  120. ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
  121. ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
  122. ** numbers used in [SQLITE_VERSION].)^
  123. ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
  124. ** be larger than the release from which it is derived. Either Y will
  125. ** be held constant and Z will be incremented or else Y will be incremented
  126. ** and Z will be reset to zero.
  127. **
  128. ** Since [version 3.6.18] ([dateof:3.6.18]),
  129. ** SQLite source code has been stored in the
  130. ** <a href="http://www.fossil-scm.org/">Fossil configuration management
  131. ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
  132. ** a string which identifies a particular check-in of SQLite
  133. ** within its configuration management system. ^The SQLITE_SOURCE_ID
  134. ** string contains the date and time of the check-in (UTC) and a SHA1
  135. ** or SHA3-256 hash of the entire source tree. If the source code has
  136. ** been edited in any way since it was last checked in, then the last
  137. ** four hexadecimal digits of the hash may be modified.
  138. **
  139. ** See also: [sqlite3_libversion()],
  140. ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
  141. ** [sqlite_version()] and [sqlite_source_id()].
  142. */
  143. #define SQLITE_VERSION "3.38.0"
  144. #define SQLITE_VERSION_NUMBER 3038000
  145. #define SQLITE_SOURCE_ID "2022-02-22 18:58:40 40fa792d359f84c3b9e9d6623743e1a59826274e221df1bde8f47086968aalt1"
  146. /*
  147. ** CAPI3REF: Run-Time Library Version Numbers
  148. ** KEYWORDS: sqlite3_version sqlite3_sourceid
  149. **
  150. ** These interfaces provide the same information as the [SQLITE_VERSION],
  151. ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
  152. ** but are associated with the library instead of the header file. ^(Cautious
  153. ** programmers might include assert() statements in their application to
  154. ** verify that values returned by these interfaces match the macros in
  155. ** the header, and thus ensure that the application is
  156. ** compiled with matching library and header files.
  157. **
  158. ** <blockquote><pre>
  159. ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
  160. ** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
  161. ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
  162. ** </pre></blockquote>)^
  163. **
  164. ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
  165. ** macro. ^The sqlite3_libversion() function returns a pointer to the
  166. ** to the sqlite3_version[] string constant. The sqlite3_libversion()
  167. ** function is provided for use in DLLs since DLL users usually do not have
  168. ** direct access to string constants within the DLL. ^The
  169. ** sqlite3_libversion_number() function returns an integer equal to
  170. ** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
  171. ** a pointer to a string constant whose value is the same as the
  172. ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
  173. ** using an edited copy of [the amalgamation], then the last four characters
  174. ** of the hash might be different from [SQLITE_SOURCE_ID].)^
  175. **
  176. ** See also: [sqlite_version()] and [sqlite_source_id()].
  177. */
  178. SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
  179. SQLITE_API const char *sqlite3_libversion(void);
  180. SQLITE_API const char *sqlite3_sourceid(void);
  181. SQLITE_API int sqlite3_libversion_number(void);
  182. /*
  183. ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
  184. **
  185. ** ^The sqlite3_compileoption_used() function returns 0 or 1
  186. ** indicating whether the specified option was defined at
  187. ** compile time. ^The SQLITE_ prefix may be omitted from the
  188. ** option name passed to sqlite3_compileoption_used().
  189. **
  190. ** ^The sqlite3_compileoption_get() function allows iterating
  191. ** over the list of options that were defined at compile time by
  192. ** returning the N-th compile time option string. ^If N is out of range,
  193. ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
  194. ** prefix is omitted from any strings returned by
  195. ** sqlite3_compileoption_get().
  196. **
  197. ** ^Support for the diagnostic functions sqlite3_compileoption_used()
  198. ** and sqlite3_compileoption_get() may be omitted by specifying the
  199. ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
  200. **
  201. ** See also: SQL functions [sqlite_compileoption_used()] and
  202. ** [sqlite_compileoption_get()] and the [compile_options pragma].
  203. */
  204. #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
  205. SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
  206. SQLITE_API const char *sqlite3_compileoption_get(int N);
  207. #else
  208. # define sqlite3_compileoption_used(X) 0
  209. # define sqlite3_compileoption_get(X) ((void*)0)
  210. #endif
  211. /*
  212. ** CAPI3REF: Test To See If The Library Is Threadsafe
  213. **
  214. ** ^The sqlite3_threadsafe() function returns zero if and only if
  215. ** SQLite was compiled with mutexing code omitted due to the
  216. ** [SQLITE_THREADSAFE] compile-time option being set to 0.
  217. **
  218. ** SQLite can be compiled with or without mutexes. When
  219. ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
  220. ** are enabled and SQLite is threadsafe. When the
  221. ** [SQLITE_THREADSAFE] macro is 0,
  222. ** the mutexes are omitted. Without the mutexes, it is not safe
  223. ** to use SQLite concurrently from more than one thread.
  224. **
  225. ** Enabling mutexes incurs a measurable performance penalty.
  226. ** So if speed is of utmost importance, it makes sense to disable
  227. ** the mutexes. But for maximum safety, mutexes should be enabled.
  228. ** ^The default behavior is for mutexes to be enabled.
  229. **
  230. ** This interface can be used by an application to make sure that the
  231. ** version of SQLite that it is linking against was compiled with
  232. ** the desired setting of the [SQLITE_THREADSAFE] macro.
  233. **
  234. ** This interface only reports on the compile-time mutex setting
  235. ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
  236. ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
  237. ** can be fully or partially disabled using a call to [sqlite3_config()]
  238. ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
  239. ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
  240. ** sqlite3_threadsafe() function shows only the compile-time setting of
  241. ** thread safety, not any run-time changes to that setting made by
  242. ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
  243. ** is unchanged by calls to sqlite3_config().)^
  244. **
  245. ** See the [threading mode] documentation for additional information.
  246. */
  247. SQLITE_API int sqlite3_threadsafe(void);
  248. /*
  249. ** CAPI3REF: Database Connection Handle
  250. ** KEYWORDS: {database connection} {database connections}
  251. **
  252. ** Each open SQLite database is represented by a pointer to an instance of
  253. ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
  254. ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
  255. ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
  256. ** and [sqlite3_close_v2()] are its destructors. There are many other
  257. ** interfaces (such as
  258. ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
  259. ** [sqlite3_busy_timeout()] to name but three) that are methods on an
  260. ** sqlite3 object.
  261. */
  262. typedef struct sqlite3 sqlite3;
  263. /*
  264. ** CAPI3REF: 64-Bit Integer Types
  265. ** KEYWORDS: sqlite_int64 sqlite_uint64
  266. **
  267. ** Because there is no cross-platform way to specify 64-bit integer types
  268. ** SQLite includes typedefs for 64-bit signed and unsigned integers.
  269. **
  270. ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
  271. ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
  272. ** compatibility only.
  273. **
  274. ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
  275. ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
  276. ** sqlite3_uint64 and sqlite_uint64 types can store integer values
  277. ** between 0 and +18446744073709551615 inclusive.
  278. */
  279. #ifdef SQLITE_INT64_TYPE
  280. typedef SQLITE_INT64_TYPE sqlite_int64;
  281. # ifdef SQLITE_UINT64_TYPE
  282. typedef SQLITE_UINT64_TYPE sqlite_uint64;
  283. # else
  284. typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
  285. # endif
  286. #elif defined(_MSC_VER) || defined(__BORLANDC__)
  287. typedef __int64 sqlite_int64;
  288. typedef unsigned __int64 sqlite_uint64;
  289. #else
  290. typedef long long int sqlite_int64;
  291. typedef unsigned long long int sqlite_uint64;
  292. #endif
  293. typedef sqlite_int64 sqlite3_int64;
  294. typedef sqlite_uint64 sqlite3_uint64;
  295. /*
  296. ** If compiling for a processor that lacks floating point support,
  297. ** substitute integer for floating-point.
  298. */
  299. #ifdef SQLITE_OMIT_FLOATING_POINT
  300. # define double sqlite3_int64
  301. #endif
  302. /*
  303. ** CAPI3REF: Closing A Database Connection
  304. ** DESTRUCTOR: sqlite3
  305. **
  306. ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
  307. ** for the [sqlite3] object.
  308. ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
  309. ** the [sqlite3] object is successfully destroyed and all associated
  310. ** resources are deallocated.
  311. **
  312. ** Ideally, applications should [sqlite3_finalize | finalize] all
  313. ** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and
  314. ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
  315. ** with the [sqlite3] object prior to attempting to close the object.
  316. ** ^If the database connection is associated with unfinalized prepared
  317. ** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
  318. ** sqlite3_close() will leave the database connection open and return
  319. ** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
  320. ** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
  321. ** it returns [SQLITE_OK] regardless, but instead of deallocating the database
  322. ** connection immediately, it marks the database connection as an unusable
  323. ** "zombie" and makes arrangements to automatically deallocate the database
  324. ** connection after all prepared statements are finalized, all BLOB handles
  325. ** are closed, and all backups have finished. The sqlite3_close_v2() interface
  326. ** is intended for use with host languages that are garbage collected, and
  327. ** where the order in which destructors are called is arbitrary.
  328. **
  329. ** ^If an [sqlite3] object is destroyed while a transaction is open,
  330. ** the transaction is automatically rolled back.
  331. **
  332. ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
  333. ** must be either a NULL
  334. ** pointer or an [sqlite3] object pointer obtained
  335. ** from [sqlite3_open()], [sqlite3_open16()], or
  336. ** [sqlite3_open_v2()], and not previously closed.
  337. ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
  338. ** argument is a harmless no-op.
  339. */
  340. SQLITE_API int sqlite3_close(sqlite3*);
  341. SQLITE_API int sqlite3_close_v2(sqlite3*);
  342. /*
  343. ** The type for a callback function.
  344. ** This is legacy and deprecated. It is included for historical
  345. ** compatibility and is not documented.
  346. */
  347. typedef int (*sqlite3_callback)(void*,int,char**, char**);
  348. /*
  349. ** CAPI3REF: One-Step Query Execution Interface
  350. ** METHOD: sqlite3
  351. **
  352. ** The sqlite3_exec() interface is a convenience wrapper around
  353. ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
  354. ** that allows an application to run multiple statements of SQL
  355. ** without having to use a lot of C code.
  356. **
  357. ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
  358. ** semicolon-separate SQL statements passed into its 2nd argument,
  359. ** in the context of the [database connection] passed in as its 1st
  360. ** argument. ^If the callback function of the 3rd argument to
  361. ** sqlite3_exec() is not NULL, then it is invoked for each result row
  362. ** coming out of the evaluated SQL statements. ^The 4th argument to
  363. ** sqlite3_exec() is relayed through to the 1st argument of each
  364. ** callback invocation. ^If the callback pointer to sqlite3_exec()
  365. ** is NULL, then no callback is ever invoked and result rows are
  366. ** ignored.
  367. **
  368. ** ^If an error occurs while evaluating the SQL statements passed into
  369. ** sqlite3_exec(), then execution of the current statement stops and
  370. ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
  371. ** is not NULL then any error message is written into memory obtained
  372. ** from [sqlite3_malloc()] and passed back through the 5th parameter.
  373. ** To avoid memory leaks, the application should invoke [sqlite3_free()]
  374. ** on error message strings returned through the 5th parameter of
  375. ** sqlite3_exec() after the error message string is no longer needed.
  376. ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
  377. ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
  378. ** NULL before returning.
  379. **
  380. ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
  381. ** routine returns SQLITE_ABORT without invoking the callback again and
  382. ** without running any subsequent SQL statements.
  383. **
  384. ** ^The 2nd argument to the sqlite3_exec() callback function is the
  385. ** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
  386. ** callback is an array of pointers to strings obtained as if from
  387. ** [sqlite3_column_text()], one for each column. ^If an element of a
  388. ** result row is NULL then the corresponding string pointer for the
  389. ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
  390. ** sqlite3_exec() callback is an array of pointers to strings where each
  391. ** entry represents the name of corresponding result column as obtained
  392. ** from [sqlite3_column_name()].
  393. **
  394. ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
  395. ** to an empty string, or a pointer that contains only whitespace and/or
  396. ** SQL comments, then no SQL statements are evaluated and the database
  397. ** is not changed.
  398. **
  399. ** Restrictions:
  400. **
  401. ** <ul>
  402. ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
  403. ** is a valid and open [database connection].
  404. ** <li> The application must not close the [database connection] specified by
  405. ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
  406. ** <li> The application must not modify the SQL statement text passed into
  407. ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
  408. ** </ul>
  409. */
  410. SQLITE_API int sqlite3_exec(
  411. sqlite3*, /* An open database */
  412. const char *sql, /* SQL to be evaluated */
  413. int (*callback)(void*,int,char**,char**), /* Callback function */
  414. void *, /* 1st argument to callback */
  415. char **errmsg /* Error msg written here */
  416. );
  417. /*
  418. ** CAPI3REF: Result Codes
  419. ** KEYWORDS: {result code definitions}
  420. **
  421. ** Many SQLite functions return an integer result code from the set shown
  422. ** here in order to indicate success or failure.
  423. **
  424. ** New error codes may be added in future versions of SQLite.
  425. **
  426. ** See also: [extended result code definitions]
  427. */
  428. #define SQLITE_OK 0 /* Successful result */
  429. /* beginning-of-error-codes */
  430. #define SQLITE_ERROR 1 /* Generic error */
  431. #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
  432. #define SQLITE_PERM 3 /* Access permission denied */
  433. #define SQLITE_ABORT 4 /* Callback routine requested an abort */
  434. #define SQLITE_BUSY 5 /* The database file is locked */
  435. #define SQLITE_LOCKED 6 /* A table in the database is locked */
  436. #define SQLITE_NOMEM 7 /* A malloc() failed */
  437. #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
  438. #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
  439. #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
  440. #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
  441. #define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
  442. #define SQLITE_FULL 13 /* Insertion failed because database is full */
  443. #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
  444. #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
  445. #define SQLITE_EMPTY 16 /* Internal use only */
  446. #define SQLITE_SCHEMA 17 /* The database schema changed */
  447. #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
  448. #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
  449. #define SQLITE_MISMATCH 20 /* Data type mismatch */
  450. #define SQLITE_MISUSE 21 /* Library used incorrectly */
  451. #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
  452. #define SQLITE_AUTH 23 /* Authorization denied */
  453. #define SQLITE_FORMAT 24 /* Not used */
  454. #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
  455. #define SQLITE_NOTADB 26 /* File opened that is not a database file */
  456. #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
  457. #define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
  458. #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
  459. #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
  460. /* end-of-error-codes */
  461. /*
  462. ** CAPI3REF: Extended Result Codes
  463. ** KEYWORDS: {extended result code definitions}
  464. **
  465. ** In its default configuration, SQLite API routines return one of 30 integer
  466. ** [result codes]. However, experience has shown that many of
  467. ** these result codes are too coarse-grained. They do not provide as
  468. ** much information about problems as programmers might like. In an effort to
  469. ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
  470. ** and later) include
  471. ** support for additional result codes that provide more detailed information
  472. ** about errors. These [extended result codes] are enabled or disabled
  473. ** on a per database connection basis using the
  474. ** [sqlite3_extended_result_codes()] API. Or, the extended code for
  475. ** the most recent error can be obtained using
  476. ** [sqlite3_extended_errcode()].
  477. */
  478. #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))
  479. #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8))
  480. #define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8))
  481. #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
  482. #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
  483. #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
  484. #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
  485. #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
  486. #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
  487. #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
  488. #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
  489. #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
  490. #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
  491. #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
  492. #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
  493. #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
  494. #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
  495. #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
  496. #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
  497. #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
  498. #define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
  499. #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
  500. #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
  501. #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
  502. #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
  503. #define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
  504. #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
  505. #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
  506. #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
  507. #define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
  508. #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
  509. #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
  510. #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
  511. #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
  512. #define SQLITE_IOERR_DATA (SQLITE_IOERR | (32<<8))
  513. #define SQLITE_IOERR_CORRUPTFS (SQLITE_IOERR | (33<<8))
  514. #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
  515. #define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8))
  516. #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
  517. #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
  518. #define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3<<8))
  519. #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
  520. #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
  521. #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
  522. #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
  523. #define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
  524. #define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6<<8))
  525. #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
  526. #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8))
  527. #define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3<<8))
  528. #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
  529. #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
  530. #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
  531. #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
  532. #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))
  533. #define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8))
  534. #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
  535. #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
  536. #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
  537. #define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
  538. #define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
  539. #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
  540. #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
  541. #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
  542. #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
  543. #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
  544. #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
  545. #define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
  546. #define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8))
  547. #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
  548. #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
  549. #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
  550. #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
  551. #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
  552. #define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */
  553. /*
  554. ** CAPI3REF: Flags For File Open Operations
  555. **
  556. ** These bit values are intended for use in the
  557. ** 3rd parameter to the [sqlite3_open_v2()] interface and
  558. ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
  559. **
  560. ** Only those flags marked as "Ok for sqlite3_open_v2()" may be
  561. ** used as the third argument to the [sqlite3_open_v2()] interface.
  562. ** The other flags have historically been ignored by sqlite3_open_v2(),
  563. ** though future versions of SQLite might change so that an error is
  564. ** raised if any of the disallowed bits are passed into sqlite3_open_v2().
  565. ** Applications should not depend on the historical behavior.
  566. **
  567. ** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
  568. ** [sqlite3_open_v2()] does *not* cause the underlying database file
  569. ** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
  570. ** [sqlite3_open_v2()] has historically be a no-op and might become an
  571. ** error in future versions of SQLite.
  572. */
  573. #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
  574. #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
  575. #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
  576. #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
  577. #define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
  578. #define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
  579. #define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
  580. #define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
  581. #define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
  582. #define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
  583. #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
  584. #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
  585. #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
  586. #define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
  587. #define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */
  588. #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
  589. #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
  590. #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
  591. #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
  592. #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
  593. #define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
  594. #define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
  595. /* Reserved: 0x00F00000 */
  596. /* Legacy compatibility: */
  597. #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
  598. /*
  599. ** CAPI3REF: Device Characteristics
  600. **
  601. ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
  602. ** object returns an integer which is a vector of these
  603. ** bit values expressing I/O characteristics of the mass storage
  604. ** device that holds the file that the [sqlite3_io_methods]
  605. ** refers to.
  606. **
  607. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  608. ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
  609. ** mean that writes of blocks that are nnn bytes in size and
  610. ** are aligned to an address which is an integer multiple of
  611. ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
  612. ** that when data is appended to a file, the data is appended
  613. ** first then the size of the file is extended, never the other
  614. ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
  615. ** information is written to disk in the same order as calls
  616. ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
  617. ** after reboot following a crash or power loss, the only bytes in a
  618. ** file that were written at the application level might have changed
  619. ** and that adjacent bytes, even bytes within the same sector are
  620. ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  621. ** flag indicates that a file cannot be deleted when open. The
  622. ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
  623. ** read-only media and cannot be changed even by processes with
  624. ** elevated privileges.
  625. **
  626. ** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
  627. ** filesystem supports doing multiple write operations atomically when those
  628. ** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
  629. ** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
  630. */
  631. #define SQLITE_IOCAP_ATOMIC 0x00000001
  632. #define SQLITE_IOCAP_ATOMIC512 0x00000002
  633. #define SQLITE_IOCAP_ATOMIC1K 0x00000004
  634. #define SQLITE_IOCAP_ATOMIC2K 0x00000008
  635. #define SQLITE_IOCAP_ATOMIC4K 0x00000010
  636. #define SQLITE_IOCAP_ATOMIC8K 0x00000020
  637. #define SQLITE_IOCAP_ATOMIC16K 0x00000040
  638. #define SQLITE_IOCAP_ATOMIC32K 0x00000080
  639. #define SQLITE_IOCAP_ATOMIC64K 0x00000100
  640. #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
  641. #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
  642. #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
  643. #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
  644. #define SQLITE_IOCAP_IMMUTABLE 0x00002000
  645. #define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
  646. /*
  647. ** CAPI3REF: File Locking Levels
  648. **
  649. ** SQLite uses one of these integer values as the second
  650. ** argument to calls it makes to the xLock() and xUnlock() methods
  651. ** of an [sqlite3_io_methods] object.
  652. */
  653. #define SQLITE_LOCK_NONE 0
  654. #define SQLITE_LOCK_SHARED 1
  655. #define SQLITE_LOCK_RESERVED 2
  656. #define SQLITE_LOCK_PENDING 3
  657. #define SQLITE_LOCK_EXCLUSIVE 4
  658. /*
  659. ** CAPI3REF: Synchronization Type Flags
  660. **
  661. ** When SQLite invokes the xSync() method of an
  662. ** [sqlite3_io_methods] object it uses a combination of
  663. ** these integer values as the second argument.
  664. **
  665. ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
  666. ** sync operation only needs to flush data to mass storage. Inode
  667. ** information need not be flushed. If the lower four bits of the flag
  668. ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
  669. ** If the lower four bits equal SQLITE_SYNC_FULL, that means
  670. ** to use Mac OS X style fullsync instead of fsync().
  671. **
  672. ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
  673. ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
  674. ** settings. The [synchronous pragma] determines when calls to the
  675. ** xSync VFS method occur and applies uniformly across all platforms.
  676. ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
  677. ** energetic or rigorous or forceful the sync operations are and
  678. ** only make a difference on Mac OSX for the default SQLite code.
  679. ** (Third-party VFS implementations might also make the distinction
  680. ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
  681. ** operating systems natively supported by SQLite, only Mac OSX
  682. ** cares about the difference.)
  683. */
  684. #define SQLITE_SYNC_NORMAL 0x00002
  685. #define SQLITE_SYNC_FULL 0x00003
  686. #define SQLITE_SYNC_DATAONLY 0x00010
  687. /*
  688. ** CAPI3REF: OS Interface Open File Handle
  689. **
  690. ** An [sqlite3_file] object represents an open file in the
  691. ** [sqlite3_vfs | OS interface layer]. Individual OS interface
  692. ** implementations will
  693. ** want to subclass this object by appending additional fields
  694. ** for their own use. The pMethods entry is a pointer to an
  695. ** [sqlite3_io_methods] object that defines methods for performing
  696. ** I/O operations on the open file.
  697. */
  698. typedef struct sqlite3_file sqlite3_file;
  699. struct sqlite3_file {
  700. const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
  701. };
  702. /*
  703. ** CAPI3REF: OS Interface File Virtual Methods Object
  704. **
  705. ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
  706. ** [sqlite3_file] object (or, more commonly, a subclass of the
  707. ** [sqlite3_file] object) with a pointer to an instance of this object.
  708. ** This object defines the methods used to perform various operations
  709. ** against the open file represented by the [sqlite3_file] object.
  710. **
  711. ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
  712. ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
  713. ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
  714. ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
  715. ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
  716. ** to NULL.
  717. **
  718. ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
  719. ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
  720. ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
  721. ** flag may be ORed in to indicate that only the data of the file
  722. ** and not its inode needs to be synced.
  723. **
  724. ** The integer values to xLock() and xUnlock() are one of
  725. ** <ul>
  726. ** <li> [SQLITE_LOCK_NONE],
  727. ** <li> [SQLITE_LOCK_SHARED],
  728. ** <li> [SQLITE_LOCK_RESERVED],
  729. ** <li> [SQLITE_LOCK_PENDING], or
  730. ** <li> [SQLITE_LOCK_EXCLUSIVE].
  731. ** </ul>
  732. ** xLock() increases the lock. xUnlock() decreases the lock.
  733. ** The xCheckReservedLock() method checks whether any database connection,
  734. ** either in this process or in some other process, is holding a RESERVED,
  735. ** PENDING, or EXCLUSIVE lock on the file. It returns true
  736. ** if such a lock exists and false otherwise.
  737. **
  738. ** The xFileControl() method is a generic interface that allows custom
  739. ** VFS implementations to directly control an open file using the
  740. ** [sqlite3_file_control()] interface. The second "op" argument is an
  741. ** integer opcode. The third argument is a generic pointer intended to
  742. ** point to a structure that may contain arguments or space in which to
  743. ** write return values. Potential uses for xFileControl() might be
  744. ** functions to enable blocking locks with timeouts, to change the
  745. ** locking strategy (for example to use dot-file locks), to inquire
  746. ** about the status of a lock, or to break stale locks. The SQLite
  747. ** core reserves all opcodes less than 100 for its own use.
  748. ** A [file control opcodes | list of opcodes] less than 100 is available.
  749. ** Applications that define a custom xFileControl method should use opcodes
  750. ** greater than 100 to avoid conflicts. VFS implementations should
  751. ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
  752. ** recognize.
  753. **
  754. ** The xSectorSize() method returns the sector size of the
  755. ** device that underlies the file. The sector size is the
  756. ** minimum write that can be performed without disturbing
  757. ** other bytes in the file. The xDeviceCharacteristics()
  758. ** method returns a bit vector describing behaviors of the
  759. ** underlying device:
  760. **
  761. ** <ul>
  762. ** <li> [SQLITE_IOCAP_ATOMIC]
  763. ** <li> [SQLITE_IOCAP_ATOMIC512]
  764. ** <li> [SQLITE_IOCAP_ATOMIC1K]
  765. ** <li> [SQLITE_IOCAP_ATOMIC2K]
  766. ** <li> [SQLITE_IOCAP_ATOMIC4K]
  767. ** <li> [SQLITE_IOCAP_ATOMIC8K]
  768. ** <li> [SQLITE_IOCAP_ATOMIC16K]
  769. ** <li> [SQLITE_IOCAP_ATOMIC32K]
  770. ** <li> [SQLITE_IOCAP_ATOMIC64K]
  771. ** <li> [SQLITE_IOCAP_SAFE_APPEND]
  772. ** <li> [SQLITE_IOCAP_SEQUENTIAL]
  773. ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
  774. ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
  775. ** <li> [SQLITE_IOCAP_IMMUTABLE]
  776. ** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
  777. ** </ul>
  778. **
  779. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  780. ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
  781. ** mean that writes of blocks that are nnn bytes in size and
  782. ** are aligned to an address which is an integer multiple of
  783. ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
  784. ** that when data is appended to a file, the data is appended
  785. ** first then the size of the file is extended, never the other
  786. ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
  787. ** information is written to disk in the same order as calls
  788. ** to xWrite().
  789. **
  790. ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
  791. ** in the unread portions of the buffer with zeros. A VFS that
  792. ** fails to zero-fill short reads might seem to work. However,
  793. ** failure to zero-fill short reads will eventually lead to
  794. ** database corruption.
  795. */
  796. typedef struct sqlite3_io_methods sqlite3_io_methods;
  797. struct sqlite3_io_methods {
  798. int iVersion;
  799. int (*xClose)(sqlite3_file*);
  800. int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  801. int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  802. int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  803. int (*xSync)(sqlite3_file*, int flags);
  804. int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  805. int (*xLock)(sqlite3_file*, int);
  806. int (*xUnlock)(sqlite3_file*, int);
  807. int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  808. int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  809. int (*xSectorSize)(sqlite3_file*);
  810. int (*xDeviceCharacteristics)(sqlite3_file*);
  811. /* Methods above are valid for version 1 */
  812. int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  813. int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  814. void (*xShmBarrier)(sqlite3_file*);
  815. int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  816. /* Methods above are valid for version 2 */
  817. int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  818. int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  819. /* Methods above are valid for version 3 */
  820. /* Additional methods may be added in future releases */
  821. };
  822. /*
  823. ** CAPI3REF: Standard File Control Opcodes
  824. ** KEYWORDS: {file control opcodes} {file control opcode}
  825. **
  826. ** These integer constants are opcodes for the xFileControl method
  827. ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
  828. ** interface.
  829. **
  830. ** <ul>
  831. ** <li>[[SQLITE_FCNTL_LOCKSTATE]]
  832. ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
  833. ** opcode causes the xFileControl method to write the current state of
  834. ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
  835. ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
  836. ** into an integer that the pArg argument points to. This capability
  837. ** is used during testing and is only available when the SQLITE_TEST
  838. ** compile-time option is used.
  839. **
  840. ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
  841. ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
  842. ** layer a hint of how large the database file will grow to be during the
  843. ** current transaction. This hint is not guaranteed to be accurate but it
  844. ** is often close. The underlying VFS might choose to preallocate database
  845. ** file space based on this hint in order to help writes to the database
  846. ** file run faster.
  847. **
  848. ** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
  849. ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
  850. ** implements [sqlite3_deserialize()] to set an upper bound on the size
  851. ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
  852. ** If the integer pointed to is negative, then it is filled in with the
  853. ** current limit. Otherwise the limit is set to the larger of the value
  854. ** of the integer pointed to and the current database size. The integer
  855. ** pointed to is set to the new limit.
  856. **
  857. ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
  858. ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
  859. ** extends and truncates the database file in chunks of a size specified
  860. ** by the user. The fourth argument to [sqlite3_file_control()] should
  861. ** point to an integer (type int) containing the new chunk-size to use
  862. ** for the nominated database. Allocating database file space in large
  863. ** chunks (say 1MB at a time), may reduce file-system fragmentation and
  864. ** improve performance on some systems.
  865. **
  866. ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
  867. ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
  868. ** to the [sqlite3_file] object associated with a particular database
  869. ** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
  870. **
  871. ** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
  872. ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
  873. ** to the [sqlite3_file] object associated with the journal file (either
  874. ** the [rollback journal] or the [write-ahead log]) for a particular database
  875. ** connection. See also [SQLITE_FCNTL_FILE_POINTER].
  876. **
  877. ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
  878. ** No longer in use.
  879. **
  880. ** <li>[[SQLITE_FCNTL_SYNC]]
  881. ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
  882. ** sent to the VFS immediately before the xSync method is invoked on a
  883. ** database file descriptor. Or, if the xSync method is not invoked
  884. ** because the user has configured SQLite with
  885. ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
  886. ** of the xSync method. In most cases, the pointer argument passed with
  887. ** this file-control is NULL. However, if the database file is being synced
  888. ** as part of a multi-database commit, the argument points to a nul-terminated
  889. ** string containing the transactions super-journal file name. VFSes that
  890. ** do not need this signal should silently ignore this opcode. Applications
  891. ** should not call [sqlite3_file_control()] with this opcode as doing so may
  892. ** disrupt the operation of the specialized VFSes that do require it.
  893. **
  894. ** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
  895. ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
  896. ** and sent to the VFS after a transaction has been committed immediately
  897. ** but before the database is unlocked. VFSes that do not need this signal
  898. ** should silently ignore this opcode. Applications should not call
  899. ** [sqlite3_file_control()] with this opcode as doing so may disrupt the
  900. ** operation of the specialized VFSes that do require it.
  901. **
  902. ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
  903. ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
  904. ** retry counts and intervals for certain disk I/O operations for the
  905. ** windows [VFS] in order to provide robustness in the presence of
  906. ** anti-virus programs. By default, the windows VFS will retry file read,
  907. ** file write, and file delete operations up to 10 times, with a delay
  908. ** of 25 milliseconds before the first retry and with the delay increasing
  909. ** by an additional 25 milliseconds with each subsequent retry. This
  910. ** opcode allows these two values (10 retries and 25 milliseconds of delay)
  911. ** to be adjusted. The values are changed for all database connections
  912. ** within the same process. The argument is a pointer to an array of two
  913. ** integers where the first integer is the new retry count and the second
  914. ** integer is the delay. If either integer is negative, then the setting
  915. ** is not changed but instead the prior value of that setting is written
  916. ** into the array entry, allowing the current retry settings to be
  917. ** interrogated. The zDbName parameter is ignored.
  918. **
  919. ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
  920. ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
  921. ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
  922. ** write ahead log ([WAL file]) and shared memory
  923. ** files used for transaction control
  924. ** are automatically deleted when the latest connection to the database
  925. ** closes. Setting persistent WAL mode causes those files to persist after
  926. ** close. Persisting the files is useful when other processes that do not
  927. ** have write permission on the directory containing the database file want
  928. ** to read the database file, as the WAL and shared memory files must exist
  929. ** in order for the database to be readable. The fourth parameter to
  930. ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  931. ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
  932. ** WAL mode. If the integer is -1, then it is overwritten with the current
  933. ** WAL persistence setting.
  934. **
  935. ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
  936. ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
  937. ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
  938. ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
  939. ** xDeviceCharacteristics methods. The fourth parameter to
  940. ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  941. ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
  942. ** mode. If the integer is -1, then it is overwritten with the current
  943. ** zero-damage mode setting.
  944. **
  945. ** <li>[[SQLITE_FCNTL_OVERWRITE]]
  946. ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
  947. ** a write transaction to indicate that, unless it is rolled back for some
  948. ** reason, the entire database file will be overwritten by the current
  949. ** transaction. This is used by VACUUM operations.
  950. **
  951. ** <li>[[SQLITE_FCNTL_VFSNAME]]
  952. ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
  953. ** all [VFSes] in the VFS stack. The names are of all VFS shims and the
  954. ** final bottom-level VFS are written into memory obtained from
  955. ** [sqlite3_malloc()] and the result is stored in the char* variable
  956. ** that the fourth parameter of [sqlite3_file_control()] points to.
  957. ** The caller is responsible for freeing the memory when done. As with
  958. ** all file-control actions, there is no guarantee that this will actually
  959. ** do anything. Callers should initialize the char* variable to a NULL
  960. ** pointer in case this file-control is not implemented. This file-control
  961. ** is intended for diagnostic use only.
  962. **
  963. ** <li>[[SQLITE_FCNTL_VFS_POINTER]]
  964. ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
  965. ** [VFSes] currently in use. ^(The argument X in
  966. ** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
  967. ** of type "[sqlite3_vfs] **". This opcodes will set *X
  968. ** to a pointer to the top-level VFS.)^
  969. ** ^When there are multiple VFS shims in the stack, this opcode finds the
  970. ** upper-most shim only.
  971. **
  972. ** <li>[[SQLITE_FCNTL_PRAGMA]]
  973. ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
  974. ** file control is sent to the open [sqlite3_file] object corresponding
  975. ** to the database file to which the pragma statement refers. ^The argument
  976. ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
  977. ** pointers to strings (char**) in which the second element of the array
  978. ** is the name of the pragma and the third element is the argument to the
  979. ** pragma or NULL if the pragma has no argument. ^The handler for an
  980. ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
  981. ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
  982. ** or the equivalent and that string will become the result of the pragma or
  983. ** the error message if the pragma fails. ^If the
  984. ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
  985. ** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
  986. ** file control returns [SQLITE_OK], then the parser assumes that the
  987. ** VFS has handled the PRAGMA itself and the parser generates a no-op
  988. ** prepared statement if result string is NULL, or that returns a copy
  989. ** of the result string if the string is non-NULL.
  990. ** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
  991. ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
  992. ** that the VFS encountered an error while handling the [PRAGMA] and the
  993. ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
  994. ** file control occurs at the beginning of pragma statement analysis and so
  995. ** it is able to override built-in [PRAGMA] statements.
  996. **
  997. ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
  998. ** ^The [SQLITE_FCNTL_BUSYHANDLER]
  999. ** file-control may be invoked by SQLite on the database file handle
  1000. ** shortly after it is opened in order to provide a custom VFS with access
  1001. ** to the connection's busy-handler callback. The argument is of type (void**)
  1002. ** - an array of two (void *) values. The first (void *) actually points
  1003. ** to a function of type (int (*)(void *)). In order to invoke the connection's
  1004. ** busy-handler, this function should be invoked with the second (void *) in
  1005. ** the array as the only argument. If it returns non-zero, then the operation
  1006. ** should be retried. If it returns zero, the custom VFS should abandon the
  1007. ** current operation.
  1008. **
  1009. ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
  1010. ** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
  1011. ** to have SQLite generate a
  1012. ** temporary filename using the same algorithm that is followed to generate
  1013. ** temporary filenames for TEMP tables and other internal uses. The
  1014. ** argument should be a char** which will be filled with the filename
  1015. ** written into memory obtained from [sqlite3_malloc()]. The caller should
  1016. ** invoke [sqlite3_free()] on the result to avoid a memory leak.
  1017. **
  1018. ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
  1019. ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
  1020. ** maximum number of bytes that will be used for memory-mapped I/O.
  1021. ** The argument is a pointer to a value of type sqlite3_int64 that
  1022. ** is an advisory maximum number of bytes in the file to memory map. The
  1023. ** pointer is overwritten with the old value. The limit is not changed if
  1024. ** the value originally pointed to is negative, and so the current limit
  1025. ** can be queried by passing in a pointer to a negative number. This
  1026. ** file-control is used internally to implement [PRAGMA mmap_size].
  1027. **
  1028. ** <li>[[SQLITE_FCNTL_TRACE]]
  1029. ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
  1030. ** to the VFS about what the higher layers of the SQLite stack are doing.
  1031. ** This file control is used by some VFS activity tracing [shims].
  1032. ** The argument is a zero-terminated string. Higher layers in the
  1033. ** SQLite stack may generate instances of this file control if
  1034. ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
  1035. **
  1036. ** <li>[[SQLITE_FCNTL_HAS_MOVED]]
  1037. ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
  1038. ** pointer to an integer and it writes a boolean into that integer depending
  1039. ** on whether or not the file has been renamed, moved, or deleted since it
  1040. ** was first opened.
  1041. **
  1042. ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
  1043. ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
  1044. ** underlying native file handle associated with a file handle. This file
  1045. ** control interprets its argument as a pointer to a native file handle and
  1046. ** writes the resulting value there.
  1047. **
  1048. ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
  1049. ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
  1050. ** opcode causes the xFileControl method to swap the file handle with the one
  1051. ** pointed to by the pArg argument. This capability is used during testing
  1052. ** and only needs to be supported when SQLITE_TEST is defined.
  1053. **
  1054. ** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
  1055. ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
  1056. ** be advantageous to block on the next WAL lock if the lock is not immediately
  1057. ** available. The WAL subsystem issues this signal during rare
  1058. ** circumstances in order to fix a problem with priority inversion.
  1059. ** Applications should <em>not</em> use this file-control.
  1060. **
  1061. ** <li>[[SQLITE_FCNTL_ZIPVFS]]
  1062. ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
  1063. ** VFS should return SQLITE_NOTFOUND for this opcode.
  1064. **
  1065. ** <li>[[SQLITE_FCNTL_RBU]]
  1066. ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
  1067. ** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
  1068. ** this opcode.
  1069. **
  1070. ** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
  1071. ** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
  1072. ** the file descriptor is placed in "batch write mode", which
  1073. ** means all subsequent write operations will be deferred and done
  1074. ** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
  1075. ** that do not support batch atomic writes will return SQLITE_NOTFOUND.
  1076. ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
  1077. ** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
  1078. ** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
  1079. ** no VFS interface calls on the same [sqlite3_file] file descriptor
  1080. ** except for calls to the xWrite method and the xFileControl method
  1081. ** with [SQLITE_FCNTL_SIZE_HINT].
  1082. **
  1083. ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
  1084. ** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
  1085. ** operations since the previous successful call to
  1086. ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
  1087. ** This file control returns [SQLITE_OK] if and only if the writes were
  1088. ** all performed successfully and have been committed to persistent storage.
  1089. ** ^Regardless of whether or not it is successful, this file control takes
  1090. ** the file descriptor out of batch write mode so that all subsequent
  1091. ** write operations are independent.
  1092. ** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
  1093. ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1094. **
  1095. ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
  1096. ** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
  1097. ** operations since the previous successful call to
  1098. ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
  1099. ** ^This file control takes the file descriptor out of batch write mode
  1100. ** so that all subsequent write operations are independent.
  1101. ** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
  1102. ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1103. **
  1104. ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
  1105. ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
  1106. ** to block for up to M milliseconds before failing when attempting to
  1107. ** obtain a file lock using the xLock or xShmLock methods of the VFS.
  1108. ** The parameter is a pointer to a 32-bit signed integer that contains
  1109. ** the value that M is to be set to. Before returning, the 32-bit signed
  1110. ** integer is overwritten with the previous value of M.
  1111. **
  1112. ** <li>[[SQLITE_FCNTL_DATA_VERSION]]
  1113. ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
  1114. ** a database file. The argument is a pointer to a 32-bit unsigned integer.
  1115. ** The "data version" for the pager is written into the pointer. The
  1116. ** "data version" changes whenever any change occurs to the corresponding
  1117. ** database file, either through SQL statements on the same database
  1118. ** connection or through transactions committed by separate database
  1119. ** connections possibly in other processes. The [sqlite3_total_changes()]
  1120. ** interface can be used to find if any database on the connection has changed,
  1121. ** but that interface responds to changes on TEMP as well as MAIN and does
  1122. ** not provide a mechanism to detect changes to MAIN only. Also, the
  1123. ** [sqlite3_total_changes()] interface responds to internal changes only and
  1124. ** omits changes made by other database connections. The
  1125. ** [PRAGMA data_version] command provides a mechanism to detect changes to
  1126. ** a single attached database that occur due to other database connections,
  1127. ** but omits changes implemented by the database connection on which it is
  1128. ** called. This file control is the only mechanism to detect changes that
  1129. ** happen either internally or externally and that are associated with
  1130. ** a particular attached database.
  1131. **
  1132. ** <li>[[SQLITE_FCNTL_CKPT_START]]
  1133. ** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
  1134. ** in wal mode before the client starts to copy pages from the wal
  1135. ** file to the database file.
  1136. **
  1137. ** <li>[[SQLITE_FCNTL_CKPT_DONE]]
  1138. ** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
  1139. ** in wal mode after the client has finished copying pages from the wal
  1140. ** file to the database file, but before the *-shm file is updated to
  1141. ** record the fact that the pages have been checkpointed.
  1142. ** </ul>
  1143. **
  1144. ** <li>[[SQLITE_FCNTL_EXTERNAL_READER]]
  1145. ** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
  1146. ** whether or not there is a database client in another process with a wal-mode
  1147. ** transaction open on the database or not. It is only available on unix.The
  1148. ** (void*) argument passed with this file-control should be a pointer to a
  1149. ** value of type (int). The integer value is set to 1 if the database is a wal
  1150. ** mode database and there exists at least one client in another process that
  1151. ** currently has an SQL transaction open on the database. It is set to 0 if
  1152. ** the database is not a wal-mode db, or if there is no such connection in any
  1153. ** other process. This opcode cannot be used to detect transactions opened
  1154. ** by clients within the current process, only within other processes.
  1155. ** </ul>
  1156. **
  1157. ** <li>[[SQLITE_FCNTL_CKSM_FILE]]
  1158. ** Used by the cksmvfs VFS module only.
  1159. ** </ul>
  1160. */
  1161. #define SQLITE_FCNTL_LOCKSTATE 1
  1162. #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
  1163. #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
  1164. #define SQLITE_FCNTL_LAST_ERRNO 4
  1165. #define SQLITE_FCNTL_SIZE_HINT 5
  1166. #define SQLITE_FCNTL_CHUNK_SIZE 6
  1167. #define SQLITE_FCNTL_FILE_POINTER 7
  1168. #define SQLITE_FCNTL_SYNC_OMITTED 8
  1169. #define SQLITE_FCNTL_WIN32_AV_RETRY 9
  1170. #define SQLITE_FCNTL_PERSIST_WAL 10
  1171. #define SQLITE_FCNTL_OVERWRITE 11
  1172. #define SQLITE_FCNTL_VFSNAME 12
  1173. #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
  1174. #define SQLITE_FCNTL_PRAGMA 14
  1175. #define SQLITE_FCNTL_BUSYHANDLER 15
  1176. #define SQLITE_FCNTL_TEMPFILENAME 16
  1177. #define SQLITE_FCNTL_MMAP_SIZE 18
  1178. #define SQLITE_FCNTL_TRACE 19
  1179. #define SQLITE_FCNTL_HAS_MOVED 20
  1180. #define SQLITE_FCNTL_SYNC 21
  1181. #define SQLITE_FCNTL_COMMIT_PHASETWO 22
  1182. #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
  1183. #define SQLITE_FCNTL_WAL_BLOCK 24
  1184. #define SQLITE_FCNTL_ZIPVFS 25
  1185. #define SQLITE_FCNTL_RBU 26
  1186. #define SQLITE_FCNTL_VFS_POINTER 27
  1187. #define SQLITE_FCNTL_JOURNAL_POINTER 28
  1188. #define SQLITE_FCNTL_WIN32_GET_HANDLE 29
  1189. #define SQLITE_FCNTL_PDB 30
  1190. #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
  1191. #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
  1192. #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
  1193. #define SQLITE_FCNTL_LOCK_TIMEOUT 34
  1194. #define SQLITE_FCNTL_DATA_VERSION 35
  1195. #define SQLITE_FCNTL_SIZE_LIMIT 36
  1196. #define SQLITE_FCNTL_CKPT_DONE 37
  1197. #define SQLITE_FCNTL_RESERVE_BYTES 38
  1198. #define SQLITE_FCNTL_CKPT_START 39
  1199. #define SQLITE_FCNTL_EXTERNAL_READER 40
  1200. #define SQLITE_FCNTL_CKSM_FILE 41
  1201. /* deprecated names */
  1202. #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
  1203. #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
  1204. #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
  1205. /*
  1206. ** CAPI3REF: Mutex Handle
  1207. **
  1208. ** The mutex module within SQLite defines [sqlite3_mutex] to be an
  1209. ** abstract type for a mutex object. The SQLite core never looks
  1210. ** at the internal representation of an [sqlite3_mutex]. It only
  1211. ** deals with pointers to the [sqlite3_mutex] object.
  1212. **
  1213. ** Mutexes are created using [sqlite3_mutex_alloc()].
  1214. */
  1215. typedef struct sqlite3_mutex sqlite3_mutex;
  1216. /*
  1217. ** CAPI3REF: Loadable Extension Thunk
  1218. **
  1219. ** A pointer to the opaque sqlite3_api_routines structure is passed as
  1220. ** the third parameter to entry points of [loadable extensions]. This
  1221. ** structure must be typedefed in order to work around compiler warnings
  1222. ** on some platforms.
  1223. */
  1224. typedef struct sqlite3_api_routines sqlite3_api_routines;
  1225. /*
  1226. ** CAPI3REF: OS Interface Object
  1227. **
  1228. ** An instance of the sqlite3_vfs object defines the interface between
  1229. ** the SQLite core and the underlying operating system. The "vfs"
  1230. ** in the name of the object stands for "virtual file system". See
  1231. ** the [VFS | VFS documentation] for further information.
  1232. **
  1233. ** The VFS interface is sometimes extended by adding new methods onto
  1234. ** the end. Each time such an extension occurs, the iVersion field
  1235. ** is incremented. The iVersion value started out as 1 in
  1236. ** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
  1237. ** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
  1238. ** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
  1239. ** may be appended to the sqlite3_vfs object and the iVersion value
  1240. ** may increase again in future versions of SQLite.
  1241. ** Note that due to an oversight, the structure
  1242. ** of the sqlite3_vfs object changed in the transition from
  1243. ** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
  1244. ** and yet the iVersion field was not increased.
  1245. **
  1246. ** The szOsFile field is the size of the subclassed [sqlite3_file]
  1247. ** structure used by this VFS. mxPathname is the maximum length of
  1248. ** a pathname in this VFS.
  1249. **
  1250. ** Registered sqlite3_vfs objects are kept on a linked list formed by
  1251. ** the pNext pointer. The [sqlite3_vfs_register()]
  1252. ** and [sqlite3_vfs_unregister()] interfaces manage this list
  1253. ** in a thread-safe way. The [sqlite3_vfs_find()] interface
  1254. ** searches the list. Neither the application code nor the VFS
  1255. ** implementation should use the pNext pointer.
  1256. **
  1257. ** The pNext field is the only field in the sqlite3_vfs
  1258. ** structure that SQLite will ever modify. SQLite will only access
  1259. ** or modify this field while holding a particular static mutex.
  1260. ** The application should never modify anything within the sqlite3_vfs
  1261. ** object once the object has been registered.
  1262. **
  1263. ** The zName field holds the name of the VFS module. The name must
  1264. ** be unique across all VFS modules.
  1265. **
  1266. ** [[sqlite3_vfs.xOpen]]
  1267. ** ^SQLite guarantees that the zFilename parameter to xOpen
  1268. ** is either a NULL pointer or string obtained
  1269. ** from xFullPathname() with an optional suffix added.
  1270. ** ^If a suffix is added to the zFilename parameter, it will
  1271. ** consist of a single "-" character followed by no more than
  1272. ** 11 alphanumeric and/or "-" characters.
  1273. ** ^SQLite further guarantees that
  1274. ** the string will be valid and unchanged until xClose() is
  1275. ** called. Because of the previous sentence,
  1276. ** the [sqlite3_file] can safely store a pointer to the
  1277. ** filename if it needs to remember the filename for some reason.
  1278. ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
  1279. ** must invent its own temporary name for the file. ^Whenever the
  1280. ** xFilename parameter is NULL it will also be the case that the
  1281. ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
  1282. **
  1283. ** The flags argument to xOpen() includes all bits set in
  1284. ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
  1285. ** or [sqlite3_open16()] is used, then flags includes at least
  1286. ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
  1287. ** If xOpen() opens a file read-only then it sets *pOutFlags to
  1288. ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
  1289. **
  1290. ** ^(SQLite will also add one of the following flags to the xOpen()
  1291. ** call, depending on the object being opened:
  1292. **
  1293. ** <ul>
  1294. ** <li> [SQLITE_OPEN_MAIN_DB]
  1295. ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
  1296. ** <li> [SQLITE_OPEN_TEMP_DB]
  1297. ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
  1298. ** <li> [SQLITE_OPEN_TRANSIENT_DB]
  1299. ** <li> [SQLITE_OPEN_SUBJOURNAL]
  1300. ** <li> [SQLITE_OPEN_SUPER_JOURNAL]
  1301. ** <li> [SQLITE_OPEN_WAL]
  1302. ** </ul>)^
  1303. **
  1304. ** The file I/O implementation can use the object type flags to
  1305. ** change the way it deals with files. For example, an application
  1306. ** that does not care about crash recovery or rollback might make
  1307. ** the open of a journal file a no-op. Writes to this journal would
  1308. ** also be no-ops, and any attempt to read the journal would return
  1309. ** SQLITE_IOERR. Or the implementation might recognize that a database
  1310. ** file will be doing page-aligned sector reads and writes in a random
  1311. ** order and set up its I/O subsystem accordingly.
  1312. **
  1313. ** SQLite might also add one of the following flags to the xOpen method:
  1314. **
  1315. ** <ul>
  1316. ** <li> [SQLITE_OPEN_DELETEONCLOSE]
  1317. ** <li> [SQLITE_OPEN_EXCLUSIVE]
  1318. ** </ul>
  1319. **
  1320. ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
  1321. ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
  1322. ** will be set for TEMP databases and their journals, transient
  1323. ** databases, and subjournals.
  1324. **
  1325. ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
  1326. ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
  1327. ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
  1328. ** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
  1329. ** SQLITE_OPEN_CREATE, is used to indicate that file should always
  1330. ** be created, and that it is an error if it already exists.
  1331. ** It is <i>not</i> used to indicate the file should be opened
  1332. ** for exclusive access.
  1333. **
  1334. ** ^At least szOsFile bytes of memory are allocated by SQLite
  1335. ** to hold the [sqlite3_file] structure passed as the third
  1336. ** argument to xOpen. The xOpen method does not have to
  1337. ** allocate the structure; it should just fill it in. Note that
  1338. ** the xOpen method must set the sqlite3_file.pMethods to either
  1339. ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
  1340. ** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
  1341. ** element will be valid after xOpen returns regardless of the success
  1342. ** or failure of the xOpen call.
  1343. **
  1344. ** [[sqlite3_vfs.xAccess]]
  1345. ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
  1346. ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
  1347. ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
  1348. ** to test whether a file is at least readable. The SQLITE_ACCESS_READ
  1349. ** flag is never actually used and is not implemented in the built-in
  1350. ** VFSes of SQLite. The file is named by the second argument and can be a
  1351. ** directory. The xAccess method returns [SQLITE_OK] on success or some
  1352. ** non-zero error code if there is an I/O error or if the name of
  1353. ** the file given in the second argument is illegal. If SQLITE_OK
  1354. ** is returned, then non-zero or zero is written into *pResOut to indicate
  1355. ** whether or not the file is accessible.
  1356. **
  1357. ** ^SQLite will always allocate at least mxPathname+1 bytes for the
  1358. ** output buffer xFullPathname. The exact size of the output buffer
  1359. ** is also passed as a parameter to both methods. If the output buffer
  1360. ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
  1361. ** handled as a fatal error by SQLite, vfs implementations should endeavor
  1362. ** to prevent this by setting mxPathname to a sufficiently large value.
  1363. **
  1364. ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
  1365. ** interfaces are not strictly a part of the filesystem, but they are
  1366. ** included in the VFS structure for completeness.
  1367. ** The xRandomness() function attempts to return nBytes bytes
  1368. ** of good-quality randomness into zOut. The return value is
  1369. ** the actual number of bytes of randomness obtained.
  1370. ** The xSleep() method causes the calling thread to sleep for at
  1371. ** least the number of microseconds given. ^The xCurrentTime()
  1372. ** method returns a Julian Day Number for the current date and time as
  1373. ** a floating point value.
  1374. ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
  1375. ** Day Number multiplied by 86400000 (the number of milliseconds in
  1376. ** a 24-hour day).
  1377. ** ^SQLite will use the xCurrentTimeInt64() method to get the current
  1378. ** date and time if that method is available (if iVersion is 2 or
  1379. ** greater and the function pointer is not NULL) and will fall back
  1380. ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
  1381. **
  1382. ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
  1383. ** are not used by the SQLite core. These optional interfaces are provided
  1384. ** by some VFSes to facilitate testing of the VFS code. By overriding
  1385. ** system calls with functions under its control, a test program can
  1386. ** simulate faults and error conditions that would otherwise be difficult
  1387. ** or impossible to induce. The set of system calls that can be overridden
  1388. ** varies from one VFS to another, and from one version of the same VFS to the
  1389. ** next. Applications that use these interfaces must be prepared for any
  1390. ** or all of these interfaces to be NULL or for their behavior to change
  1391. ** from one release to the next. Applications must not attempt to access
  1392. ** any of these methods if the iVersion of the VFS is less than 3.
  1393. */
  1394. typedef struct sqlite3_vfs sqlite3_vfs;
  1395. typedef void (*sqlite3_syscall_ptr)(void);
  1396. struct sqlite3_vfs {
  1397. int iVersion; /* Structure version number (currently 3) */
  1398. int szOsFile; /* Size of subclassed sqlite3_file */
  1399. int mxPathname; /* Maximum file pathname length */
  1400. sqlite3_vfs *pNext; /* Next registered VFS */
  1401. const char *zName; /* Name of this virtual file system */
  1402. void *pAppData; /* Pointer to application-specific data */
  1403. int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
  1404. int flags, int *pOutFlags);
  1405. int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  1406. int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  1407. int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  1408. void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  1409. void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  1410. void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  1411. void (*xDlClose)(sqlite3_vfs*, void*);
  1412. int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  1413. int (*xSleep)(sqlite3_vfs*, int microseconds);
  1414. int (*xCurrentTime)(sqlite3_vfs*, double*);
  1415. int (*xGetLastError)(sqlite3_vfs*, int, char *);
  1416. /*
  1417. ** The methods above are in version 1 of the sqlite_vfs object
  1418. ** definition. Those that follow are added in version 2 or later
  1419. */
  1420. int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  1421. /*
  1422. ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  1423. ** Those below are for version 3 and greater.
  1424. */
  1425. int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  1426. sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  1427. const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  1428. /*
  1429. ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  1430. ** New fields may be appended in future versions. The iVersion
  1431. ** value will increment whenever this happens.
  1432. */
  1433. };
  1434. /*
  1435. ** CAPI3REF: Flags for the xAccess VFS method
  1436. **
  1437. ** These integer constants can be used as the third parameter to
  1438. ** the xAccess method of an [sqlite3_vfs] object. They determine
  1439. ** what kind of permissions the xAccess method is looking for.
  1440. ** With SQLITE_ACCESS_EXISTS, the xAccess method
  1441. ** simply checks whether the file exists.
  1442. ** With SQLITE_ACCESS_READWRITE, the xAccess method
  1443. ** checks whether the named directory is both readable and writable
  1444. ** (in other words, if files can be added, removed, and renamed within
  1445. ** the directory).
  1446. ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
  1447. ** [temp_store_directory pragma], though this could change in a future
  1448. ** release of SQLite.
  1449. ** With SQLITE_ACCESS_READ, the xAccess method
  1450. ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
  1451. ** currently unused, though it might be used in a future release of
  1452. ** SQLite.
  1453. */
  1454. #define SQLITE_ACCESS_EXISTS 0
  1455. #define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
  1456. #define SQLITE_ACCESS_READ 2 /* Unused */
  1457. /*
  1458. ** CAPI3REF: Flags for the xShmLock VFS method
  1459. **
  1460. ** These integer constants define the various locking operations
  1461. ** allowed by the xShmLock method of [sqlite3_io_methods]. The
  1462. ** following are the only legal combinations of flags to the
  1463. ** xShmLock method:
  1464. **
  1465. ** <ul>
  1466. ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  1467. ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  1468. ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  1469. ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
  1470. ** </ul>
  1471. **
  1472. ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
  1473. ** was given on the corresponding lock.
  1474. **
  1475. ** The xShmLock method can transition between unlocked and SHARED or
  1476. ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
  1477. ** and EXCLUSIVE.
  1478. */
  1479. #define SQLITE_SHM_UNLOCK 1
  1480. #define SQLITE_SHM_LOCK 2
  1481. #define SQLITE_SHM_SHARED 4
  1482. #define SQLITE_SHM_EXCLUSIVE 8
  1483. /*
  1484. ** CAPI3REF: Maximum xShmLock index
  1485. **
  1486. ** The xShmLock method on [sqlite3_io_methods] may use values
  1487. ** between 0 and this upper bound as its "offset" argument.
  1488. ** The SQLite core will never attempt to acquire or release a
  1489. ** lock outside of this range
  1490. */
  1491. #define SQLITE_SHM_NLOCK 8
  1492. /*
  1493. ** CAPI3REF: Initialize The SQLite Library
  1494. **
  1495. ** ^The sqlite3_initialize() routine initializes the
  1496. ** SQLite library. ^The sqlite3_shutdown() routine
  1497. ** deallocates any resources that were allocated by sqlite3_initialize().
  1498. ** These routines are designed to aid in process initialization and
  1499. ** shutdown on embedded systems. Workstation applications using
  1500. ** SQLite normally do not need to invoke either of these routines.
  1501. **
  1502. ** A call to sqlite3_initialize() is an "effective" call if it is
  1503. ** the first time sqlite3_initialize() is invoked during the lifetime of
  1504. ** the process, or if it is the first time sqlite3_initialize() is invoked
  1505. ** following a call to sqlite3_shutdown(). ^(Only an effective call
  1506. ** of sqlite3_initialize() does any initialization. All other calls
  1507. ** are harmless no-ops.)^
  1508. **
  1509. ** A call to sqlite3_shutdown() is an "effective" call if it is the first
  1510. ** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
  1511. ** an effective call to sqlite3_shutdown() does any deinitialization.
  1512. ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
  1513. **
  1514. ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
  1515. ** is not. The sqlite3_shutdown() interface must only be called from a
  1516. ** single thread. All open [database connections] must be closed and all
  1517. ** other SQLite resources must be deallocated prior to invoking
  1518. ** sqlite3_shutdown().
  1519. **
  1520. ** Among other things, ^sqlite3_initialize() will invoke
  1521. ** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
  1522. ** will invoke sqlite3_os_end().
  1523. **
  1524. ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
  1525. ** ^If for some reason, sqlite3_initialize() is unable to initialize
  1526. ** the library (perhaps it is unable to allocate a needed resource such
  1527. ** as a mutex) it returns an [error code] other than [SQLITE_OK].
  1528. **
  1529. ** ^The sqlite3_initialize() routine is called internally by many other
  1530. ** SQLite interfaces so that an application usually does not need to
  1531. ** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
  1532. ** calls sqlite3_initialize() so the SQLite library will be automatically
  1533. ** initialized when [sqlite3_open()] is called if it has not be initialized
  1534. ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
  1535. ** compile-time option, then the automatic calls to sqlite3_initialize()
  1536. ** are omitted and the application must call sqlite3_initialize() directly
  1537. ** prior to using any other SQLite interface. For maximum portability,
  1538. ** it is recommended that applications always invoke sqlite3_initialize()
  1539. ** directly prior to using any other SQLite interface. Future releases
  1540. ** of SQLite may require this. In other words, the behavior exhibited
  1541. ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
  1542. ** default behavior in some future release of SQLite.
  1543. **
  1544. ** The sqlite3_os_init() routine does operating-system specific
  1545. ** initialization of the SQLite library. The sqlite3_os_end()
  1546. ** routine undoes the effect of sqlite3_os_init(). Typical tasks
  1547. ** performed by these routines include allocation or deallocation
  1548. ** of static resources, initialization of global variables,
  1549. ** setting up a default [sqlite3_vfs] module, or setting up
  1550. ** a default configuration using [sqlite3_config()].
  1551. **
  1552. ** The application should never invoke either sqlite3_os_init()
  1553. ** or sqlite3_os_end() directly. The application should only invoke
  1554. ** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
  1555. ** interface is called automatically by sqlite3_initialize() and
  1556. ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
  1557. ** implementations for sqlite3_os_init() and sqlite3_os_end()
  1558. ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
  1559. ** When [custom builds | built for other platforms]
  1560. ** (using the [SQLITE_OS_OTHER=1] compile-time
  1561. ** option) the application must supply a suitable implementation for
  1562. ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
  1563. ** implementation of sqlite3_os_init() or sqlite3_os_end()
  1564. ** must return [SQLITE_OK] on success and some other [error code] upon
  1565. ** failure.
  1566. */
  1567. SQLITE_API int sqlite3_initialize(void);
  1568. SQLITE_API int sqlite3_shutdown(void);
  1569. SQLITE_API int sqlite3_os_init(void);
  1570. SQLITE_API int sqlite3_os_end(void);
  1571. /*
  1572. ** CAPI3REF: Configuring The SQLite Library
  1573. **
  1574. ** The sqlite3_config() interface is used to make global configuration
  1575. ** changes to SQLite in order to tune SQLite to the specific needs of
  1576. ** the application. The default configuration is recommended for most
  1577. ** applications and so this routine is usually not necessary. It is
  1578. ** provided to support rare applications with unusual needs.
  1579. **
  1580. ** <b>The sqlite3_config() interface is not threadsafe. The application
  1581. ** must ensure that no other SQLite interfaces are invoked by other
  1582. ** threads while sqlite3_config() is running.</b>
  1583. **
  1584. ** The sqlite3_config() interface
  1585. ** may only be invoked prior to library initialization using
  1586. ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
  1587. ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
  1588. ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
  1589. ** Note, however, that ^sqlite3_config() can be called as part of the
  1590. ** implementation of an application-defined [sqlite3_os_init()].
  1591. **
  1592. ** The first argument to sqlite3_config() is an integer
  1593. ** [configuration option] that determines
  1594. ** what property of SQLite is to be configured. Subsequent arguments
  1595. ** vary depending on the [configuration option]
  1596. ** in the first argument.
  1597. **
  1598. ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
  1599. ** ^If the option is unknown or SQLite is unable to set the option
  1600. ** then this routine returns a non-zero [error code].
  1601. */
  1602. SQLITE_API int sqlite3_config(int, ...);
  1603. /*
  1604. ** CAPI3REF: Configure database connections
  1605. ** METHOD: sqlite3
  1606. **
  1607. ** The sqlite3_db_config() interface is used to make configuration
  1608. ** changes to a [database connection]. The interface is similar to
  1609. ** [sqlite3_config()] except that the changes apply to a single
  1610. ** [database connection] (specified in the first argument).
  1611. **
  1612. ** The second argument to sqlite3_db_config(D,V,...) is the
  1613. ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
  1614. ** that indicates what aspect of the [database connection] is being configured.
  1615. ** Subsequent arguments vary depending on the configuration verb.
  1616. **
  1617. ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
  1618. ** the call is considered successful.
  1619. */
  1620. SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
  1621. /*
  1622. ** CAPI3REF: Memory Allocation Routines
  1623. **
  1624. ** An instance of this object defines the interface between SQLite
  1625. ** and low-level memory allocation routines.
  1626. **
  1627. ** This object is used in only one place in the SQLite interface.
  1628. ** A pointer to an instance of this object is the argument to
  1629. ** [sqlite3_config()] when the configuration option is
  1630. ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
  1631. ** By creating an instance of this object
  1632. ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
  1633. ** during configuration, an application can specify an alternative
  1634. ** memory allocation subsystem for SQLite to use for all of its
  1635. ** dynamic memory needs.
  1636. **
  1637. ** Note that SQLite comes with several [built-in memory allocators]
  1638. ** that are perfectly adequate for the overwhelming majority of applications
  1639. ** and that this object is only useful to a tiny minority of applications
  1640. ** with specialized memory allocation requirements. This object is
  1641. ** also used during testing of SQLite in order to specify an alternative
  1642. ** memory allocator that simulates memory out-of-memory conditions in
  1643. ** order to verify that SQLite recovers gracefully from such
  1644. ** conditions.
  1645. **
  1646. ** The xMalloc, xRealloc, and xFree methods must work like the
  1647. ** malloc(), realloc() and free() functions from the standard C library.
  1648. ** ^SQLite guarantees that the second argument to
  1649. ** xRealloc is always a value returned by a prior call to xRoundup.
  1650. **
  1651. ** xSize should return the allocated size of a memory allocation
  1652. ** previously obtained from xMalloc or xRealloc. The allocated size
  1653. ** is always at least as big as the requested size but may be larger.
  1654. **
  1655. ** The xRoundup method returns what would be the allocated size of
  1656. ** a memory allocation given a particular requested size. Most memory
  1657. ** allocators round up memory allocations at least to the next multiple
  1658. ** of 8. Some allocators round up to a larger multiple or to a power of 2.
  1659. ** Every memory allocation request coming in through [sqlite3_malloc()]
  1660. ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
  1661. ** that causes the corresponding memory allocation to fail.
  1662. **
  1663. ** The xInit method initializes the memory allocator. For example,
  1664. ** it might allocate any required mutexes or initialize internal data
  1665. ** structures. The xShutdown method is invoked (indirectly) by
  1666. ** [sqlite3_shutdown()] and should deallocate any resources acquired
  1667. ** by xInit. The pAppData pointer is used as the only parameter to
  1668. ** xInit and xShutdown.
  1669. **
  1670. ** SQLite holds the [SQLITE_MUTEX_STATIC_MAIN] mutex when it invokes
  1671. ** the xInit method, so the xInit method need not be threadsafe. The
  1672. ** xShutdown method is only called from [sqlite3_shutdown()] so it does
  1673. ** not need to be threadsafe either. For all other methods, SQLite
  1674. ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
  1675. ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
  1676. ** it is by default) and so the methods are automatically serialized.
  1677. ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
  1678. ** methods must be threadsafe or else make their own arrangements for
  1679. ** serialization.
  1680. **
  1681. ** SQLite will never invoke xInit() more than once without an intervening
  1682. ** call to xShutdown().
  1683. */
  1684. typedef struct sqlite3_mem_methods sqlite3_mem_methods;
  1685. struct sqlite3_mem_methods {
  1686. void *(*xMalloc)(int); /* Memory allocation function */
  1687. void (*xFree)(void*); /* Free a prior allocation */
  1688. void *(*xRealloc)(void*,int); /* Resize an allocation */
  1689. int (*xSize)(void*); /* Return the size of an allocation */
  1690. int (*xRoundup)(int); /* Round up request size to allocation size */
  1691. int (*xInit)(void*); /* Initialize the memory allocator */
  1692. void (*xShutdown)(void*); /* Deinitialize the memory allocator */
  1693. void *pAppData; /* Argument to xInit() and xShutdown() */
  1694. };
  1695. /*
  1696. ** CAPI3REF: Configuration Options
  1697. ** KEYWORDS: {configuration option}
  1698. **
  1699. ** These constants are the available integer configuration options that
  1700. ** can be passed as the first argument to the [sqlite3_config()] interface.
  1701. **
  1702. ** New configuration options may be added in future releases of SQLite.
  1703. ** Existing configuration options might be discontinued. Applications
  1704. ** should check the return code from [sqlite3_config()] to make sure that
  1705. ** the call worked. The [sqlite3_config()] interface will return a
  1706. ** non-zero [error code] if a discontinued or unsupported configuration option
  1707. ** is invoked.
  1708. **
  1709. ** <dl>
  1710. ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
  1711. ** <dd>There are no arguments to this option. ^This option sets the
  1712. ** [threading mode] to Single-thread. In other words, it disables
  1713. ** all mutexing and puts SQLite into a mode where it can only be used
  1714. ** by a single thread. ^If SQLite is compiled with
  1715. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1716. ** it is not possible to change the [threading mode] from its default
  1717. ** value of Single-thread and so [sqlite3_config()] will return
  1718. ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
  1719. ** configuration option.</dd>
  1720. **
  1721. ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
  1722. ** <dd>There are no arguments to this option. ^This option sets the
  1723. ** [threading mode] to Multi-thread. In other words, it disables
  1724. ** mutexing on [database connection] and [prepared statement] objects.
  1725. ** The application is responsible for serializing access to
  1726. ** [database connections] and [prepared statements]. But other mutexes
  1727. ** are enabled so that SQLite will be safe to use in a multi-threaded
  1728. ** environment as long as no two threads attempt to use the same
  1729. ** [database connection] at the same time. ^If SQLite is compiled with
  1730. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1731. ** it is not possible to set the Multi-thread [threading mode] and
  1732. ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1733. ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
  1734. **
  1735. ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
  1736. ** <dd>There are no arguments to this option. ^This option sets the
  1737. ** [threading mode] to Serialized. In other words, this option enables
  1738. ** all mutexes including the recursive
  1739. ** mutexes on [database connection] and [prepared statement] objects.
  1740. ** In this mode (which is the default when SQLite is compiled with
  1741. ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
  1742. ** to [database connections] and [prepared statements] so that the
  1743. ** application is free to use the same [database connection] or the
  1744. ** same [prepared statement] in different threads at the same time.
  1745. ** ^If SQLite is compiled with
  1746. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1747. ** it is not possible to set the Serialized [threading mode] and
  1748. ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1749. ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
  1750. **
  1751. ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
  1752. ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
  1753. ** a pointer to an instance of the [sqlite3_mem_methods] structure.
  1754. ** The argument specifies
  1755. ** alternative low-level memory allocation routines to be used in place of
  1756. ** the memory allocation routines built into SQLite.)^ ^SQLite makes
  1757. ** its own private copy of the content of the [sqlite3_mem_methods] structure
  1758. ** before the [sqlite3_config()] call returns.</dd>
  1759. **
  1760. ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
  1761. ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
  1762. ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
  1763. ** The [sqlite3_mem_methods]
  1764. ** structure is filled with the currently defined memory allocation routines.)^
  1765. ** This option can be used to overload the default memory allocation
  1766. ** routines with a wrapper that simulations memory allocation failure or
  1767. ** tracks memory usage, for example. </dd>
  1768. **
  1769. ** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
  1770. ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
  1771. ** type int, interpreted as a boolean, which if true provides a hint to
  1772. ** SQLite that it should avoid large memory allocations if possible.
  1773. ** SQLite will run faster if it is free to make large memory allocations,
  1774. ** but some application might prefer to run slower in exchange for
  1775. ** guarantees about memory fragmentation that are possible if large
  1776. ** allocations are avoided. This hint is normally off.
  1777. ** </dd>
  1778. **
  1779. ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1780. ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
  1781. ** interpreted as a boolean, which enables or disables the collection of
  1782. ** memory allocation statistics. ^(When memory allocation statistics are
  1783. ** disabled, the following SQLite interfaces become non-operational:
  1784. ** <ul>
  1785. ** <li> [sqlite3_hard_heap_limit64()]
  1786. ** <li> [sqlite3_memory_used()]
  1787. ** <li> [sqlite3_memory_highwater()]
  1788. ** <li> [sqlite3_soft_heap_limit64()]
  1789. ** <li> [sqlite3_status64()]
  1790. ** </ul>)^
  1791. ** ^Memory allocation statistics are enabled by default unless SQLite is
  1792. ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
  1793. ** allocation statistics are disabled by default.
  1794. ** </dd>
  1795. **
  1796. ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
  1797. ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
  1798. ** </dd>
  1799. **
  1800. ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1801. ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
  1802. ** that SQLite can use for the database page cache with the default page
  1803. ** cache implementation.
  1804. ** This configuration option is a no-op if an application-defined page
  1805. ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
  1806. ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
  1807. ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
  1808. ** and the number of cache lines (N).
  1809. ** The sz argument should be the size of the largest database page
  1810. ** (a power of two between 512 and 65536) plus some extra bytes for each
  1811. ** page header. ^The number of extra bytes needed by the page header
  1812. ** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
  1813. ** ^It is harmless, apart from the wasted memory,
  1814. ** for the sz parameter to be larger than necessary. The pMem
  1815. ** argument must be either a NULL pointer or a pointer to an 8-byte
  1816. ** aligned block of memory of at least sz*N bytes, otherwise
  1817. ** subsequent behavior is undefined.
  1818. ** ^When pMem is not NULL, SQLite will strive to use the memory provided
  1819. ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
  1820. ** a page cache line is larger than sz bytes or if all of the pMem buffer
  1821. ** is exhausted.
  1822. ** ^If pMem is NULL and N is non-zero, then each database connection
  1823. ** does an initial bulk allocation for page cache memory
  1824. ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
  1825. ** of -1024*N bytes if N is negative, . ^If additional
  1826. ** page cache memory is needed beyond what is provided by the initial
  1827. ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
  1828. ** additional cache line. </dd>
  1829. **
  1830. ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
  1831. ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
  1832. ** that SQLite will use for all of its dynamic memory allocation needs
  1833. ** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
  1834. ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
  1835. ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
  1836. ** [SQLITE_ERROR] if invoked otherwise.
  1837. ** ^There are three arguments to SQLITE_CONFIG_HEAP:
  1838. ** An 8-byte aligned pointer to the memory,
  1839. ** the number of bytes in the memory buffer, and the minimum allocation size.
  1840. ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
  1841. ** to using its default memory allocator (the system malloc() implementation),
  1842. ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
  1843. ** memory pointer is not NULL then the alternative memory
  1844. ** allocator is engaged to handle all of SQLites memory allocation needs.
  1845. ** The first pointer (the memory pointer) must be aligned to an 8-byte
  1846. ** boundary or subsequent behavior of SQLite will be undefined.
  1847. ** The minimum allocation size is capped at 2**12. Reasonable values
  1848. ** for the minimum allocation size are 2**5 through 2**8.</dd>
  1849. **
  1850. ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
  1851. ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
  1852. ** pointer to an instance of the [sqlite3_mutex_methods] structure.
  1853. ** The argument specifies alternative low-level mutex routines to be used
  1854. ** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
  1855. ** the content of the [sqlite3_mutex_methods] structure before the call to
  1856. ** [sqlite3_config()] returns. ^If SQLite is compiled with
  1857. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1858. ** the entire mutexing subsystem is omitted from the build and hence calls to
  1859. ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
  1860. ** return [SQLITE_ERROR].</dd>
  1861. **
  1862. ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
  1863. ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
  1864. ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
  1865. ** [sqlite3_mutex_methods]
  1866. ** structure is filled with the currently defined mutex routines.)^
  1867. ** This option can be used to overload the default mutex allocation
  1868. ** routines with a wrapper used to track mutex usage for performance
  1869. ** profiling or testing, for example. ^If SQLite is compiled with
  1870. ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1871. ** the entire mutexing subsystem is omitted from the build and hence calls to
  1872. ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
  1873. ** return [SQLITE_ERROR].</dd>
  1874. **
  1875. ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
  1876. ** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
  1877. ** the default size of lookaside memory on each [database connection].
  1878. ** The first argument is the
  1879. ** size of each lookaside buffer slot and the second is the number of
  1880. ** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
  1881. ** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1882. ** option to [sqlite3_db_config()] can be used to change the lookaside
  1883. ** configuration on individual connections.)^ </dd>
  1884. **
  1885. ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
  1886. ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
  1887. ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
  1888. ** the interface to a custom page cache implementation.)^
  1889. ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
  1890. **
  1891. ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
  1892. ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
  1893. ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
  1894. ** the current page cache implementation into that object.)^ </dd>
  1895. **
  1896. ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
  1897. ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
  1898. ** global [error log].
  1899. ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
  1900. ** function with a call signature of void(*)(void*,int,const char*),
  1901. ** and a pointer to void. ^If the function pointer is not NULL, it is
  1902. ** invoked by [sqlite3_log()] to process each logging event. ^If the
  1903. ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
  1904. ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
  1905. ** passed through as the first parameter to the application-defined logger
  1906. ** function whenever that function is invoked. ^The second parameter to
  1907. ** the logger function is a copy of the first parameter to the corresponding
  1908. ** [sqlite3_log()] call and is intended to be a [result code] or an
  1909. ** [extended result code]. ^The third parameter passed to the logger is
  1910. ** log message after formatting via [sqlite3_snprintf()].
  1911. ** The SQLite logging interface is not reentrant; the logger function
  1912. ** supplied by the application must not invoke any SQLite interface.
  1913. ** In a multi-threaded application, the application-defined logger
  1914. ** function must be threadsafe. </dd>
  1915. **
  1916. ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
  1917. ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
  1918. ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
  1919. ** then URI handling is globally disabled.)^ ^If URI handling is globally
  1920. ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
  1921. ** [sqlite3_open16()] or
  1922. ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
  1923. ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
  1924. ** connection is opened. ^If it is globally disabled, filenames are
  1925. ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
  1926. ** database connection is opened. ^(By default, URI handling is globally
  1927. ** disabled. The default value may be changed by compiling with the
  1928. ** [SQLITE_USE_URI] symbol defined.)^
  1929. **
  1930. ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
  1931. ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
  1932. ** argument which is interpreted as a boolean in order to enable or disable
  1933. ** the use of covering indices for full table scans in the query optimizer.
  1934. ** ^The default setting is determined
  1935. ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
  1936. ** if that compile-time option is omitted.
  1937. ** The ability to disable the use of covering indices for full table scans
  1938. ** is because some incorrectly coded legacy applications might malfunction
  1939. ** when the optimization is enabled. Providing the ability to
  1940. ** disable the optimization allows the older, buggy application code to work
  1941. ** without change even with newer versions of SQLite.
  1942. **
  1943. ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
  1944. ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
  1945. ** <dd> These options are obsolete and should not be used by new code.
  1946. ** They are retained for backwards compatibility but are now no-ops.
  1947. ** </dd>
  1948. **
  1949. ** [[SQLITE_CONFIG_SQLLOG]]
  1950. ** <dt>SQLITE_CONFIG_SQLLOG
  1951. ** <dd>This option is only available if sqlite is compiled with the
  1952. ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
  1953. ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
  1954. ** The second should be of type (void*). The callback is invoked by the library
  1955. ** in three separate circumstances, identified by the value passed as the
  1956. ** fourth parameter. If the fourth parameter is 0, then the database connection
  1957. ** passed as the second argument has just been opened. The third argument
  1958. ** points to a buffer containing the name of the main database file. If the
  1959. ** fourth parameter is 1, then the SQL statement that the third parameter
  1960. ** points to has just been executed. Or, if the fourth parameter is 2, then
  1961. ** the connection being passed as the second parameter is being closed. The
  1962. ** third parameter is passed NULL In this case. An example of using this
  1963. ** configuration option can be seen in the "test_sqllog.c" source file in
  1964. ** the canonical SQLite source tree.</dd>
  1965. **
  1966. ** [[SQLITE_CONFIG_MMAP_SIZE]]
  1967. ** <dt>SQLITE_CONFIG_MMAP_SIZE
  1968. ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
  1969. ** that are the default mmap size limit (the default setting for
  1970. ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
  1971. ** ^The default setting can be overridden by each database connection using
  1972. ** either the [PRAGMA mmap_size] command, or by using the
  1973. ** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
  1974. ** will be silently truncated if necessary so that it does not exceed the
  1975. ** compile-time maximum mmap size set by the
  1976. ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
  1977. ** ^If either argument to this option is negative, then that argument is
  1978. ** changed to its compile-time default.
  1979. **
  1980. ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
  1981. ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
  1982. ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
  1983. ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
  1984. ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
  1985. ** that specifies the maximum size of the created heap.
  1986. **
  1987. ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
  1988. ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
  1989. ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
  1990. ** is a pointer to an integer and writes into that integer the number of extra
  1991. ** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
  1992. ** The amount of extra space required can change depending on the compiler,
  1993. ** target platform, and SQLite version.
  1994. **
  1995. ** [[SQLITE_CONFIG_PMASZ]]
  1996. ** <dt>SQLITE_CONFIG_PMASZ
  1997. ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
  1998. ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
  1999. ** sorter to that integer. The default minimum PMA Size is set by the
  2000. ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
  2001. ** to help with sort operations when multithreaded sorting
  2002. ** is enabled (using the [PRAGMA threads] command) and the amount of content
  2003. ** to be sorted exceeds the page size times the minimum of the
  2004. ** [PRAGMA cache_size] setting and this value.
  2005. **
  2006. ** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
  2007. ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
  2008. ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
  2009. ** becomes the [statement journal] spill-to-disk threshold.
  2010. ** [Statement journals] are held in memory until their size (in bytes)
  2011. ** exceeds this threshold, at which point they are written to disk.
  2012. ** Or if the threshold is -1, statement journals are always held
  2013. ** exclusively in memory.
  2014. ** Since many statement journals never become large, setting the spill
  2015. ** threshold to a value such as 64KiB can greatly reduce the amount of
  2016. ** I/O required to support statement rollback.
  2017. ** The default value for this setting is controlled by the
  2018. ** [SQLITE_STMTJRNL_SPILL] compile-time option.
  2019. **
  2020. ** [[SQLITE_CONFIG_SORTERREF_SIZE]]
  2021. ** <dt>SQLITE_CONFIG_SORTERREF_SIZE
  2022. ** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
  2023. ** of type (int) - the new value of the sorter-reference size threshold.
  2024. ** Usually, when SQLite uses an external sort to order records according
  2025. ** to an ORDER BY clause, all fields required by the caller are present in the
  2026. ** sorted records. However, if SQLite determines based on the declared type
  2027. ** of a table column that its values are likely to be very large - larger
  2028. ** than the configured sorter-reference size threshold - then a reference
  2029. ** is stored in each sorted record and the required column values loaded
  2030. ** from the database as records are returned in sorted order. The default
  2031. ** value for this option is to never use this optimization. Specifying a
  2032. ** negative value for this option restores the default behaviour.
  2033. ** This option is only available if SQLite is compiled with the
  2034. ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
  2035. **
  2036. ** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
  2037. ** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
  2038. ** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
  2039. ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
  2040. ** database created using [sqlite3_deserialize()]. This default maximum
  2041. ** size can be adjusted up or down for individual databases using the
  2042. ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
  2043. ** configuration setting is never used, then the default maximum is determined
  2044. ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
  2045. ** compile-time option is not set, then the default maximum is 1073741824.
  2046. ** </dl>
  2047. */
  2048. #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
  2049. #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
  2050. #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
  2051. #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
  2052. #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
  2053. #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
  2054. #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
  2055. #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
  2056. #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
  2057. #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
  2058. #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
  2059. /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
  2060. #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
  2061. #define SQLITE_CONFIG_PCACHE 14 /* no-op */
  2062. #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
  2063. #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
  2064. #define SQLITE_CONFIG_URI 17 /* int */
  2065. #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
  2066. #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
  2067. #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
  2068. #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
  2069. #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
  2070. #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
  2071. #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
  2072. #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
  2073. #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
  2074. #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
  2075. #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
  2076. #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
  2077. /*
  2078. ** CAPI3REF: Database Connection Configuration Options
  2079. **
  2080. ** These constants are the available integer configuration options that
  2081. ** can be passed as the second argument to the [sqlite3_db_config()] interface.
  2082. **
  2083. ** New configuration options may be added in future releases of SQLite.
  2084. ** Existing configuration options might be discontinued. Applications
  2085. ** should check the return code from [sqlite3_db_config()] to make sure that
  2086. ** the call worked. ^The [sqlite3_db_config()] interface will return a
  2087. ** non-zero [error code] if a discontinued or unsupported configuration option
  2088. ** is invoked.
  2089. **
  2090. ** <dl>
  2091. ** [[SQLITE_DBCONFIG_LOOKASIDE]]
  2092. ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
  2093. ** <dd> ^This option takes three additional arguments that determine the
  2094. ** [lookaside memory allocator] configuration for the [database connection].
  2095. ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
  2096. ** pointer to a memory buffer to use for lookaside memory.
  2097. ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
  2098. ** may be NULL in which case SQLite will allocate the
  2099. ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
  2100. ** size of each lookaside buffer slot. ^The third argument is the number of
  2101. ** slots. The size of the buffer in the first argument must be greater than
  2102. ** or equal to the product of the second and third arguments. The buffer
  2103. ** must be aligned to an 8-byte boundary. ^If the second argument to
  2104. ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
  2105. ** rounded down to the next smaller multiple of 8. ^(The lookaside memory
  2106. ** configuration for a database connection can only be changed when that
  2107. ** connection is not currently using lookaside memory, or in other words
  2108. ** when the "current value" returned by
  2109. ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
  2110. ** Any attempt to change the lookaside memory configuration when lookaside
  2111. ** memory is in use leaves the configuration unchanged and returns
  2112. ** [SQLITE_BUSY].)^</dd>
  2113. **
  2114. ** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
  2115. ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
  2116. ** <dd> ^This option is used to enable or disable the enforcement of
  2117. ** [foreign key constraints]. There should be two additional arguments.
  2118. ** The first argument is an integer which is 0 to disable FK enforcement,
  2119. ** positive to enable FK enforcement or negative to leave FK enforcement
  2120. ** unchanged. The second parameter is a pointer to an integer into which
  2121. ** is written 0 or 1 to indicate whether FK enforcement is off or on
  2122. ** following this call. The second parameter may be a NULL pointer, in
  2123. ** which case the FK enforcement setting is not reported back. </dd>
  2124. **
  2125. ** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
  2126. ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
  2127. ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
  2128. ** There should be two additional arguments.
  2129. ** The first argument is an integer which is 0 to disable triggers,
  2130. ** positive to enable triggers or negative to leave the setting unchanged.
  2131. ** The second parameter is a pointer to an integer into which
  2132. ** is written 0 or 1 to indicate whether triggers are disabled or enabled
  2133. ** following this call. The second parameter may be a NULL pointer, in
  2134. ** which case the trigger setting is not reported back.
  2135. **
  2136. ** <p>Originally this option disabled all triggers. ^(However, since
  2137. ** SQLite version 3.35.0, TEMP triggers are still allowed even if
  2138. ** this option is off. So, in other words, this option now only disables
  2139. ** triggers in the main database schema or in the schemas of ATTACH-ed
  2140. ** databases.)^ </dd>
  2141. **
  2142. ** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
  2143. ** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
  2144. ** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
  2145. ** There should be two additional arguments.
  2146. ** The first argument is an integer which is 0 to disable views,
  2147. ** positive to enable views or negative to leave the setting unchanged.
  2148. ** The second parameter is a pointer to an integer into which
  2149. ** is written 0 or 1 to indicate whether views are disabled or enabled
  2150. ** following this call. The second parameter may be a NULL pointer, in
  2151. ** which case the view setting is not reported back.
  2152. **
  2153. ** <p>Originally this option disabled all views. ^(However, since
  2154. ** SQLite version 3.35.0, TEMP views are still allowed even if
  2155. ** this option is off. So, in other words, this option now only disables
  2156. ** views in the main database schema or in the schemas of ATTACH-ed
  2157. ** databases.)^ </dd>
  2158. **
  2159. ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
  2160. ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
  2161. ** <dd> ^This option is used to enable or disable the
  2162. ** [fts3_tokenizer()] function which is part of the
  2163. ** [FTS3] full-text search engine extension.
  2164. ** There should be two additional arguments.
  2165. ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
  2166. ** positive to enable fts3_tokenizer() or negative to leave the setting
  2167. ** unchanged.
  2168. ** The second parameter is a pointer to an integer into which
  2169. ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
  2170. ** following this call. The second parameter may be a NULL pointer, in
  2171. ** which case the new setting is not reported back. </dd>
  2172. **
  2173. ** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
  2174. ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
  2175. ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
  2176. ** interface independently of the [load_extension()] SQL function.
  2177. ** The [sqlite3_enable_load_extension()] API enables or disables both the
  2178. ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
  2179. ** There should be two additional arguments.
  2180. ** When the first argument to this interface is 1, then only the C-API is
  2181. ** enabled and the SQL function remains disabled. If the first argument to
  2182. ** this interface is 0, then both the C-API and the SQL function are disabled.
  2183. ** If the first argument is -1, then no changes are made to state of either the
  2184. ** C-API or the SQL function.
  2185. ** The second parameter is a pointer to an integer into which
  2186. ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
  2187. ** is disabled or enabled following this call. The second parameter may
  2188. ** be a NULL pointer, in which case the new setting is not reported back.
  2189. ** </dd>
  2190. **
  2191. ** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
  2192. ** <dd> ^This option is used to change the name of the "main" database
  2193. ** schema. ^The sole argument is a pointer to a constant UTF8 string
  2194. ** which will become the new schema name in place of "main". ^SQLite
  2195. ** does not make a copy of the new main schema name string, so the application
  2196. ** must ensure that the argument passed into this DBCONFIG option is unchanged
  2197. ** until after the database connection closes.
  2198. ** </dd>
  2199. **
  2200. ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
  2201. ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
  2202. ** <dd> Usually, when a database in wal mode is closed or detached from a
  2203. ** database handle, SQLite checks if this will mean that there are now no
  2204. ** connections at all to the database. If so, it performs a checkpoint
  2205. ** operation before closing the connection. This option may be used to
  2206. ** override this behaviour. The first parameter passed to this operation
  2207. ** is an integer - positive to disable checkpoints-on-close, or zero (the
  2208. ** default) to enable them, and negative to leave the setting unchanged.
  2209. ** The second parameter is a pointer to an integer
  2210. ** into which is written 0 or 1 to indicate whether checkpoints-on-close
  2211. ** have been disabled - 0 if they are not disabled, 1 if they are.
  2212. ** </dd>
  2213. **
  2214. ** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
  2215. ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
  2216. ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
  2217. ** a single SQL query statement will always use the same algorithm regardless
  2218. ** of values of [bound parameters].)^ The QPSG disables some query optimizations
  2219. ** that look at the values of bound parameters, which can make some queries
  2220. ** slower. But the QPSG has the advantage of more predictable behavior. With
  2221. ** the QPSG active, SQLite will always use the same query plan in the field as
  2222. ** was used during testing in the lab.
  2223. ** The first argument to this setting is an integer which is 0 to disable
  2224. ** the QPSG, positive to enable QPSG, or negative to leave the setting
  2225. ** unchanged. The second parameter is a pointer to an integer into which
  2226. ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
  2227. ** following this call.
  2228. ** </dd>
  2229. **
  2230. ** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
  2231. ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
  2232. ** include output for any operations performed by trigger programs. This
  2233. ** option is used to set or clear (the default) a flag that governs this
  2234. ** behavior. The first parameter passed to this operation is an integer -
  2235. ** positive to enable output for trigger programs, or zero to disable it,
  2236. ** or negative to leave the setting unchanged.
  2237. ** The second parameter is a pointer to an integer into which is written
  2238. ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
  2239. ** it is not disabled, 1 if it is.
  2240. ** </dd>
  2241. **
  2242. ** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
  2243. ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
  2244. ** [VACUUM] in order to reset a database back to an empty database
  2245. ** with no schema and no content. The following process works even for
  2246. ** a badly corrupted database file:
  2247. ** <ol>
  2248. ** <li> If the database connection is newly opened, make sure it has read the
  2249. ** database schema by preparing then discarding some query against the
  2250. ** database, or calling sqlite3_table_column_metadata(), ignoring any
  2251. ** errors. This step is only necessary if the application desires to keep
  2252. ** the database in WAL mode after the reset if it was in WAL mode before
  2253. ** the reset.
  2254. ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
  2255. ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
  2256. ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
  2257. ** </ol>
  2258. ** Because resetting a database is destructive and irreversible, the
  2259. ** process requires the use of this obscure API and multiple steps to help
  2260. ** ensure that it does not happen by accident.
  2261. **
  2262. ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
  2263. ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
  2264. ** "defensive" flag for a database connection. When the defensive
  2265. ** flag is enabled, language features that allow ordinary SQL to
  2266. ** deliberately corrupt the database file are disabled. The disabled
  2267. ** features include but are not limited to the following:
  2268. ** <ul>
  2269. ** <li> The [PRAGMA writable_schema=ON] statement.
  2270. ** <li> The [PRAGMA journal_mode=OFF] statement.
  2271. ** <li> Writes to the [sqlite_dbpage] virtual table.
  2272. ** <li> Direct writes to [shadow tables].
  2273. ** </ul>
  2274. ** </dd>
  2275. **
  2276. ** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
  2277. ** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
  2278. ** "writable_schema" flag. This has the same effect and is logically equivalent
  2279. ** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
  2280. ** The first argument to this setting is an integer which is 0 to disable
  2281. ** the writable_schema, positive to enable writable_schema, or negative to
  2282. ** leave the setting unchanged. The second parameter is a pointer to an
  2283. ** integer into which is written 0 or 1 to indicate whether the writable_schema
  2284. ** is enabled or disabled following this call.
  2285. ** </dd>
  2286. **
  2287. ** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
  2288. ** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
  2289. ** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
  2290. ** the legacy behavior of the [ALTER TABLE RENAME] command such it
  2291. ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
  2292. ** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
  2293. ** additional information. This feature can also be turned on and off
  2294. ** using the [PRAGMA legacy_alter_table] statement.
  2295. ** </dd>
  2296. **
  2297. ** [[SQLITE_DBCONFIG_DQS_DML]]
  2298. ** <dt>SQLITE_DBCONFIG_DQS_DML</td>
  2299. ** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
  2300. ** the legacy [double-quoted string literal] misfeature for DML statements
  2301. ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
  2302. ** default value of this setting is determined by the [-DSQLITE_DQS]
  2303. ** compile-time option.
  2304. ** </dd>
  2305. **
  2306. ** [[SQLITE_DBCONFIG_DQS_DDL]]
  2307. ** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
  2308. ** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
  2309. ** the legacy [double-quoted string literal] misfeature for DDL statements,
  2310. ** such as CREATE TABLE and CREATE INDEX. The
  2311. ** default value of this setting is determined by the [-DSQLITE_DQS]
  2312. ** compile-time option.
  2313. ** </dd>
  2314. **
  2315. ** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]
  2316. ** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</td>
  2317. ** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
  2318. ** assume that database schemas are untainted by malicious content.
  2319. ** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
  2320. ** takes additional defensive steps to protect the application from harm
  2321. ** including:
  2322. ** <ul>
  2323. ** <li> Prohibit the use of SQL functions inside triggers, views,
  2324. ** CHECK constraints, DEFAULT clauses, expression indexes,
  2325. ** partial indexes, or generated columns
  2326. ** unless those functions are tagged with [SQLITE_INNOCUOUS].
  2327. ** <li> Prohibit the use of virtual tables inside of triggers or views
  2328. ** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].
  2329. ** </ul>
  2330. ** This setting defaults to "on" for legacy compatibility, however
  2331. ** all applications are advised to turn it off if possible. This setting
  2332. ** can also be controlled using the [PRAGMA trusted_schema] statement.
  2333. ** </dd>
  2334. **
  2335. ** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]
  2336. ** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</td>
  2337. ** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
  2338. ** the legacy file format flag. When activated, this flag causes all newly
  2339. ** created database file to have a schema format version number (the 4-byte
  2340. ** integer found at offset 44 into the database header) of 1. This in turn
  2341. ** means that the resulting database file will be readable and writable by
  2342. ** any SQLite version back to 3.0.0 ([dateof:3.0.0]). Without this setting,
  2343. ** newly created databases are generally not understandable by SQLite versions
  2344. ** prior to 3.3.0 ([dateof:3.3.0]). As these words are written, there
  2345. ** is now scarcely any need to generated database files that are compatible
  2346. ** all the way back to version 3.0.0, and so this setting is of little
  2347. ** practical use, but is provided so that SQLite can continue to claim the
  2348. ** ability to generate new database files that are compatible with version
  2349. ** 3.0.0.
  2350. ** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
  2351. ** the [VACUUM] command will fail with an obscure error when attempting to
  2352. ** process a table with generated columns and a descending index. This is
  2353. ** not considered a bug since SQLite versions 3.3.0 and earlier do not support
  2354. ** either generated columns or decending indexes.
  2355. ** </dd>
  2356. ** </dl>
  2357. */
  2358. #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
  2359. #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
  2360. #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
  2361. #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
  2362. #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
  2363. #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
  2364. #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
  2365. #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
  2366. #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
  2367. #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
  2368. #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
  2369. #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
  2370. #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
  2371. #define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
  2372. #define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
  2373. #define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
  2374. #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
  2375. #define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
  2376. #define SQLITE_DBCONFIG_MAX 1017 /* Largest DBCONFIG */
  2377. /*
  2378. ** CAPI3REF: Enable Or Disable Extended Result Codes
  2379. ** METHOD: sqlite3
  2380. **
  2381. ** ^The sqlite3_extended_result_codes() routine enables or disables the
  2382. ** [extended result codes] feature of SQLite. ^The extended result
  2383. ** codes are disabled by default for historical compatibility.
  2384. */
  2385. SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
  2386. /*
  2387. ** CAPI3REF: Last Insert Rowid
  2388. ** METHOD: sqlite3
  2389. **
  2390. ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
  2391. ** has a unique 64-bit signed
  2392. ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
  2393. ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  2394. ** names are not also used by explicitly declared columns. ^If
  2395. ** the table has a column of type [INTEGER PRIMARY KEY] then that column
  2396. ** is another alias for the rowid.
  2397. **
  2398. ** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
  2399. ** the most recent successful [INSERT] into a rowid table or [virtual table]
  2400. ** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
  2401. ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
  2402. ** on the database connection D, then sqlite3_last_insert_rowid(D) returns
  2403. ** zero.
  2404. **
  2405. ** As well as being set automatically as rows are inserted into database
  2406. ** tables, the value returned by this function may be set explicitly by
  2407. ** [sqlite3_set_last_insert_rowid()]
  2408. **
  2409. ** Some virtual table implementations may INSERT rows into rowid tables as
  2410. ** part of committing a transaction (e.g. to flush data accumulated in memory
  2411. ** to disk). In this case subsequent calls to this function return the rowid
  2412. ** associated with these internal INSERT operations, which leads to
  2413. ** unintuitive results. Virtual table implementations that do write to rowid
  2414. ** tables in this way can avoid this problem by restoring the original
  2415. ** rowid value using [sqlite3_set_last_insert_rowid()] before returning
  2416. ** control to the user.
  2417. **
  2418. ** ^(If an [INSERT] occurs within a trigger then this routine will
  2419. ** return the [rowid] of the inserted row as long as the trigger is
  2420. ** running. Once the trigger program ends, the value returned
  2421. ** by this routine reverts to what it was before the trigger was fired.)^
  2422. **
  2423. ** ^An [INSERT] that fails due to a constraint violation is not a
  2424. ** successful [INSERT] and does not change the value returned by this
  2425. ** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  2426. ** and INSERT OR ABORT make no changes to the return value of this
  2427. ** routine when their insertion fails. ^(When INSERT OR REPLACE
  2428. ** encounters a constraint violation, it does not fail. The
  2429. ** INSERT continues to completion after deleting rows that caused
  2430. ** the constraint problem so INSERT OR REPLACE will always change
  2431. ** the return value of this interface.)^
  2432. **
  2433. ** ^For the purposes of this routine, an [INSERT] is considered to
  2434. ** be successful even if it is subsequently rolled back.
  2435. **
  2436. ** This function is accessible to SQL statements via the
  2437. ** [last_insert_rowid() SQL function].
  2438. **
  2439. ** If a separate thread performs a new [INSERT] on the same
  2440. ** database connection while the [sqlite3_last_insert_rowid()]
  2441. ** function is running and thus changes the last insert [rowid],
  2442. ** then the value returned by [sqlite3_last_insert_rowid()] is
  2443. ** unpredictable and might not equal either the old or the new
  2444. ** last insert [rowid].
  2445. */
  2446. SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  2447. /*
  2448. ** CAPI3REF: Set the Last Insert Rowid value.
  2449. ** METHOD: sqlite3
  2450. **
  2451. ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
  2452. ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
  2453. ** without inserting a row into the database.
  2454. */
  2455. SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
  2456. /*
  2457. ** CAPI3REF: Count The Number Of Rows Modified
  2458. ** METHOD: sqlite3
  2459. **
  2460. ** ^These functions return the number of rows modified, inserted or
  2461. ** deleted by the most recently completed INSERT, UPDATE or DELETE
  2462. ** statement on the database connection specified by the only parameter.
  2463. ** The two functions are identical except for the type of the return value
  2464. ** and that if the number of rows modified by the most recent INSERT, UPDATE
  2465. ** or DELETE is greater than the maximum value supported by type "int", then
  2466. ** the return value of sqlite3_changes() is undefined. ^Executing any other
  2467. ** type of SQL statement does not modify the value returned by these functions.
  2468. **
  2469. ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
  2470. ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
  2471. ** [foreign key actions] or [REPLACE] constraint resolution are not counted.
  2472. **
  2473. ** Changes to a view that are intercepted by
  2474. ** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
  2475. ** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
  2476. ** DELETE statement run on a view is always zero. Only changes made to real
  2477. ** tables are counted.
  2478. **
  2479. ** Things are more complicated if the sqlite3_changes() function is
  2480. ** executed while a trigger program is running. This may happen if the
  2481. ** program uses the [changes() SQL function], or if some other callback
  2482. ** function invokes sqlite3_changes() directly. Essentially:
  2483. **
  2484. ** <ul>
  2485. ** <li> ^(Before entering a trigger program the value returned by
  2486. ** sqlite3_changes() function is saved. After the trigger program
  2487. ** has finished, the original value is restored.)^
  2488. **
  2489. ** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
  2490. ** statement sets the value returned by sqlite3_changes()
  2491. ** upon completion as normal. Of course, this value will not include
  2492. ** any changes performed by sub-triggers, as the sqlite3_changes()
  2493. ** value will be saved and restored after each sub-trigger has run.)^
  2494. ** </ul>
  2495. **
  2496. ** ^This means that if the changes() SQL function (or similar) is used
  2497. ** by the first INSERT, UPDATE or DELETE statement within a trigger, it
  2498. ** returns the value as set when the calling statement began executing.
  2499. ** ^If it is used by the second or subsequent such statement within a trigger
  2500. ** program, the value returned reflects the number of rows modified by the
  2501. ** previous INSERT, UPDATE or DELETE statement within the same trigger.
  2502. **
  2503. ** If a separate thread makes changes on the same database connection
  2504. ** while [sqlite3_changes()] is running then the value returned
  2505. ** is unpredictable and not meaningful.
  2506. **
  2507. ** See also:
  2508. ** <ul>
  2509. ** <li> the [sqlite3_total_changes()] interface
  2510. ** <li> the [count_changes pragma]
  2511. ** <li> the [changes() SQL function]
  2512. ** <li> the [data_version pragma]
  2513. ** </ul>
  2514. */
  2515. SQLITE_API int sqlite3_changes(sqlite3*);
  2516. SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*);
  2517. /*
  2518. ** CAPI3REF: Total Number Of Rows Modified
  2519. ** METHOD: sqlite3
  2520. **
  2521. ** ^These functions return the total number of rows inserted, modified or
  2522. ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
  2523. ** since the database connection was opened, including those executed as
  2524. ** part of trigger programs. The two functions are identical except for the
  2525. ** type of the return value and that if the number of rows modified by the
  2526. ** connection exceeds the maximum value supported by type "int", then
  2527. ** the return value of sqlite3_total_changes() is undefined. ^Executing
  2528. ** any other type of SQL statement does not affect the value returned by
  2529. ** sqlite3_total_changes().
  2530. **
  2531. ** ^Changes made as part of [foreign key actions] are included in the
  2532. ** count, but those made as part of REPLACE constraint resolution are
  2533. ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
  2534. ** are not counted.
  2535. **
  2536. ** The [sqlite3_total_changes(D)] interface only reports the number
  2537. ** of rows that changed due to SQL statement run against database
  2538. ** connection D. Any changes by other database connections are ignored.
  2539. ** To detect changes against a database file from other database
  2540. ** connections use the [PRAGMA data_version] command or the
  2541. ** [SQLITE_FCNTL_DATA_VERSION] [file control].
  2542. **
  2543. ** If a separate thread makes changes on the same database connection
  2544. ** while [sqlite3_total_changes()] is running then the value
  2545. ** returned is unpredictable and not meaningful.
  2546. **
  2547. ** See also:
  2548. ** <ul>
  2549. ** <li> the [sqlite3_changes()] interface
  2550. ** <li> the [count_changes pragma]
  2551. ** <li> the [changes() SQL function]
  2552. ** <li> the [data_version pragma]
  2553. ** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
  2554. ** </ul>
  2555. */
  2556. SQLITE_API int sqlite3_total_changes(sqlite3*);
  2557. SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*);
  2558. /*
  2559. ** CAPI3REF: Interrupt A Long-Running Query
  2560. ** METHOD: sqlite3
  2561. **
  2562. ** ^This function causes any pending database operation to abort and
  2563. ** return at its earliest opportunity. This routine is typically
  2564. ** called in response to a user action such as pressing "Cancel"
  2565. ** or Ctrl-C where the user wants a long query operation to halt
  2566. ** immediately.
  2567. **
  2568. ** ^It is safe to call this routine from a thread different from the
  2569. ** thread that is currently running the database operation. But it
  2570. ** is not safe to call this routine with a [database connection] that
  2571. ** is closed or might close before sqlite3_interrupt() returns.
  2572. **
  2573. ** ^If an SQL operation is very nearly finished at the time when
  2574. ** sqlite3_interrupt() is called, then it might not have an opportunity
  2575. ** to be interrupted and might continue to completion.
  2576. **
  2577. ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
  2578. ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
  2579. ** that is inside an explicit transaction, then the entire transaction
  2580. ** will be rolled back automatically.
  2581. **
  2582. ** ^The sqlite3_interrupt(D) call is in effect until all currently running
  2583. ** SQL statements on [database connection] D complete. ^Any new SQL statements
  2584. ** that are started after the sqlite3_interrupt() call and before the
  2585. ** running statement count reaches zero are interrupted as if they had been
  2586. ** running prior to the sqlite3_interrupt() call. ^New SQL statements
  2587. ** that are started after the running statement count reaches zero are
  2588. ** not effected by the sqlite3_interrupt().
  2589. ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
  2590. ** SQL statements is a no-op and has no effect on SQL statements
  2591. ** that are started after the sqlite3_interrupt() call returns.
  2592. */
  2593. SQLITE_API void sqlite3_interrupt(sqlite3*);
  2594. /*
  2595. ** CAPI3REF: Determine If An SQL Statement Is Complete
  2596. **
  2597. ** These routines are useful during command-line input to determine if the
  2598. ** currently entered text seems to form a complete SQL statement or
  2599. ** if additional input is needed before sending the text into
  2600. ** SQLite for parsing. ^These routines return 1 if the input string
  2601. ** appears to be a complete SQL statement. ^A statement is judged to be
  2602. ** complete if it ends with a semicolon token and is not a prefix of a
  2603. ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
  2604. ** string literals or quoted identifier names or comments are not
  2605. ** independent tokens (they are part of the token in which they are
  2606. ** embedded) and thus do not count as a statement terminator. ^Whitespace
  2607. ** and comments that follow the final semicolon are ignored.
  2608. **
  2609. ** ^These routines return 0 if the statement is incomplete. ^If a
  2610. ** memory allocation fails, then SQLITE_NOMEM is returned.
  2611. **
  2612. ** ^These routines do not parse the SQL statements thus
  2613. ** will not detect syntactically incorrect SQL.
  2614. **
  2615. ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
  2616. ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
  2617. ** automatically by sqlite3_complete16(). If that initialization fails,
  2618. ** then the return value from sqlite3_complete16() will be non-zero
  2619. ** regardless of whether or not the input SQL is complete.)^
  2620. **
  2621. ** The input to [sqlite3_complete()] must be a zero-terminated
  2622. ** UTF-8 string.
  2623. **
  2624. ** The input to [sqlite3_complete16()] must be a zero-terminated
  2625. ** UTF-16 string in native byte order.
  2626. */
  2627. SQLITE_API int sqlite3_complete(const char *sql);
  2628. SQLITE_API int sqlite3_complete16(const void *sql);
  2629. /*
  2630. ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
  2631. ** KEYWORDS: {busy-handler callback} {busy handler}
  2632. ** METHOD: sqlite3
  2633. **
  2634. ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
  2635. ** that might be invoked with argument P whenever
  2636. ** an attempt is made to access a database table associated with
  2637. ** [database connection] D when another thread
  2638. ** or process has the table locked.
  2639. ** The sqlite3_busy_handler() interface is used to implement
  2640. ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
  2641. **
  2642. ** ^If the busy callback is NULL, then [SQLITE_BUSY]
  2643. ** is returned immediately upon encountering the lock. ^If the busy callback
  2644. ** is not NULL, then the callback might be invoked with two arguments.
  2645. **
  2646. ** ^The first argument to the busy handler is a copy of the void* pointer which
  2647. ** is the third argument to sqlite3_busy_handler(). ^The second argument to
  2648. ** the busy handler callback is the number of times that the busy handler has
  2649. ** been invoked previously for the same locking event. ^If the
  2650. ** busy callback returns 0, then no additional attempts are made to
  2651. ** access the database and [SQLITE_BUSY] is returned
  2652. ** to the application.
  2653. ** ^If the callback returns non-zero, then another attempt
  2654. ** is made to access the database and the cycle repeats.
  2655. **
  2656. ** The presence of a busy handler does not guarantee that it will be invoked
  2657. ** when there is lock contention. ^If SQLite determines that invoking the busy
  2658. ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
  2659. ** to the application instead of invoking the
  2660. ** busy handler.
  2661. ** Consider a scenario where one process is holding a read lock that
  2662. ** it is trying to promote to a reserved lock and
  2663. ** a second process is holding a reserved lock that it is trying
  2664. ** to promote to an exclusive lock. The first process cannot proceed
  2665. ** because it is blocked by the second and the second process cannot
  2666. ** proceed because it is blocked by the first. If both processes
  2667. ** invoke the busy handlers, neither will make any progress. Therefore,
  2668. ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
  2669. ** will induce the first process to release its read lock and allow
  2670. ** the second process to proceed.
  2671. **
  2672. ** ^The default busy callback is NULL.
  2673. **
  2674. ** ^(There can only be a single busy handler defined for each
  2675. ** [database connection]. Setting a new busy handler clears any
  2676. ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
  2677. ** or evaluating [PRAGMA busy_timeout=N] will change the
  2678. ** busy handler and thus clear any previously set busy handler.
  2679. **
  2680. ** The busy callback should not take any actions which modify the
  2681. ** database connection that invoked the busy handler. In other words,
  2682. ** the busy handler is not reentrant. Any such actions
  2683. ** result in undefined behavior.
  2684. **
  2685. ** A busy handler must not close the database connection
  2686. ** or [prepared statement] that invoked the busy handler.
  2687. */
  2688. SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
  2689. /*
  2690. ** CAPI3REF: Set A Busy Timeout
  2691. ** METHOD: sqlite3
  2692. **
  2693. ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
  2694. ** for a specified amount of time when a table is locked. ^The handler
  2695. ** will sleep multiple times until at least "ms" milliseconds of sleeping
  2696. ** have accumulated. ^After at least "ms" milliseconds of sleeping,
  2697. ** the handler returns 0 which causes [sqlite3_step()] to return
  2698. ** [SQLITE_BUSY].
  2699. **
  2700. ** ^Calling this routine with an argument less than or equal to zero
  2701. ** turns off all busy handlers.
  2702. **
  2703. ** ^(There can only be a single busy handler for a particular
  2704. ** [database connection] at any given moment. If another busy handler
  2705. ** was defined (using [sqlite3_busy_handler()]) prior to calling
  2706. ** this routine, that other busy handler is cleared.)^
  2707. **
  2708. ** See also: [PRAGMA busy_timeout]
  2709. */
  2710. SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
  2711. /*
  2712. ** CAPI3REF: Convenience Routines For Running Queries
  2713. ** METHOD: sqlite3
  2714. **
  2715. ** This is a legacy interface that is preserved for backwards compatibility.
  2716. ** Use of this interface is not recommended.
  2717. **
  2718. ** Definition: A <b>result table</b> is memory data structure created by the
  2719. ** [sqlite3_get_table()] interface. A result table records the
  2720. ** complete query results from one or more queries.
  2721. **
  2722. ** The table conceptually has a number of rows and columns. But
  2723. ** these numbers are not part of the result table itself. These
  2724. ** numbers are obtained separately. Let N be the number of rows
  2725. ** and M be the number of columns.
  2726. **
  2727. ** A result table is an array of pointers to zero-terminated UTF-8 strings.
  2728. ** There are (N+1)*M elements in the array. The first M pointers point
  2729. ** to zero-terminated strings that contain the names of the columns.
  2730. ** The remaining entries all point to query results. NULL values result
  2731. ** in NULL pointers. All other values are in their UTF-8 zero-terminated
  2732. ** string representation as returned by [sqlite3_column_text()].
  2733. **
  2734. ** A result table might consist of one or more memory allocations.
  2735. ** It is not safe to pass a result table directly to [sqlite3_free()].
  2736. ** A result table should be deallocated using [sqlite3_free_table()].
  2737. **
  2738. ** ^(As an example of the result table format, suppose a query result
  2739. ** is as follows:
  2740. **
  2741. ** <blockquote><pre>
  2742. ** Name | Age
  2743. ** -----------------------
  2744. ** Alice | 43
  2745. ** Bob | 28
  2746. ** Cindy | 21
  2747. ** </pre></blockquote>
  2748. **
  2749. ** There are two columns (M==2) and three rows (N==3). Thus the
  2750. ** result table has 8 entries. Suppose the result table is stored
  2751. ** in an array named azResult. Then azResult holds this content:
  2752. **
  2753. ** <blockquote><pre>
  2754. ** azResult&#91;0] = "Name";
  2755. ** azResult&#91;1] = "Age";
  2756. ** azResult&#91;2] = "Alice";
  2757. ** azResult&#91;3] = "43";
  2758. ** azResult&#91;4] = "Bob";
  2759. ** azResult&#91;5] = "28";
  2760. ** azResult&#91;6] = "Cindy";
  2761. ** azResult&#91;7] = "21";
  2762. ** </pre></blockquote>)^
  2763. **
  2764. ** ^The sqlite3_get_table() function evaluates one or more
  2765. ** semicolon-separated SQL statements in the zero-terminated UTF-8
  2766. ** string of its 2nd parameter and returns a result table to the
  2767. ** pointer given in its 3rd parameter.
  2768. **
  2769. ** After the application has finished with the result from sqlite3_get_table(),
  2770. ** it must pass the result table pointer to sqlite3_free_table() in order to
  2771. ** release the memory that was malloced. Because of the way the
  2772. ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  2773. ** function must not try to call [sqlite3_free()] directly. Only
  2774. ** [sqlite3_free_table()] is able to release the memory properly and safely.
  2775. **
  2776. ** The sqlite3_get_table() interface is implemented as a wrapper around
  2777. ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
  2778. ** to any internal data structures of SQLite. It uses only the public
  2779. ** interface defined here. As a consequence, errors that occur in the
  2780. ** wrapper layer outside of the internal [sqlite3_exec()] call are not
  2781. ** reflected in subsequent calls to [sqlite3_errcode()] or
  2782. ** [sqlite3_errmsg()].
  2783. */
  2784. SQLITE_API int sqlite3_get_table(
  2785. sqlite3 *db, /* An open database */
  2786. const char *zSql, /* SQL to be evaluated */
  2787. char ***pazResult, /* Results of the query */
  2788. int *pnRow, /* Number of result rows written here */
  2789. int *pnColumn, /* Number of result columns written here */
  2790. char **pzErrmsg /* Error msg written here */
  2791. );
  2792. SQLITE_API void sqlite3_free_table(char **result);
  2793. /*
  2794. ** CAPI3REF: Formatted String Printing Functions
  2795. **
  2796. ** These routines are work-alikes of the "printf()" family of functions
  2797. ** from the standard C library.
  2798. ** These routines understand most of the common formatting options from
  2799. ** the standard library printf()
  2800. ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
  2801. ** See the [built-in printf()] documentation for details.
  2802. **
  2803. ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2804. ** results into memory obtained from [sqlite3_malloc64()].
  2805. ** The strings returned by these two routines should be
  2806. ** released by [sqlite3_free()]. ^Both routines return a
  2807. ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
  2808. ** memory to hold the resulting string.
  2809. **
  2810. ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
  2811. ** the standard C library. The result is written into the
  2812. ** buffer supplied as the second parameter whose size is given by
  2813. ** the first parameter. Note that the order of the
  2814. ** first two parameters is reversed from snprintf().)^ This is an
  2815. ** historical accident that cannot be fixed without breaking
  2816. ** backwards compatibility. ^(Note also that sqlite3_snprintf()
  2817. ** returns a pointer to its buffer instead of the number of
  2818. ** characters actually written into the buffer.)^ We admit that
  2819. ** the number of characters written would be a more useful return
  2820. ** value but we cannot change the implementation of sqlite3_snprintf()
  2821. ** now without breaking compatibility.
  2822. **
  2823. ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
  2824. ** guarantees that the buffer is always zero-terminated. ^The first
  2825. ** parameter "n" is the total size of the buffer, including space for
  2826. ** the zero terminator. So the longest string that can be completely
  2827. ** written will be n-1 characters.
  2828. **
  2829. ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2830. **
  2831. ** See also: [built-in printf()], [printf() SQL function]
  2832. */
  2833. SQLITE_API char *sqlite3_mprintf(const char*,...);
  2834. SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
  2835. SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
  2836. SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
  2837. /*
  2838. ** CAPI3REF: Memory Allocation Subsystem
  2839. **
  2840. ** The SQLite core uses these three routines for all of its own
  2841. ** internal memory allocation needs. "Core" in the previous sentence
  2842. ** does not include operating-system specific [VFS] implementation. The
  2843. ** Windows VFS uses native malloc() and free() for some operations.
  2844. **
  2845. ** ^The sqlite3_malloc() routine returns a pointer to a block
  2846. ** of memory at least N bytes in length, where N is the parameter.
  2847. ** ^If sqlite3_malloc() is unable to obtain sufficient free
  2848. ** memory, it returns a NULL pointer. ^If the parameter N to
  2849. ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  2850. ** a NULL pointer.
  2851. **
  2852. ** ^The sqlite3_malloc64(N) routine works just like
  2853. ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
  2854. ** of a signed 32-bit integer.
  2855. **
  2856. ** ^Calling sqlite3_free() with a pointer previously returned
  2857. ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  2858. ** that it might be reused. ^The sqlite3_free() routine is
  2859. ** a no-op if is called with a NULL pointer. Passing a NULL pointer
  2860. ** to sqlite3_free() is harmless. After being freed, memory
  2861. ** should neither be read nor written. Even reading previously freed
  2862. ** memory might result in a segmentation fault or other severe error.
  2863. ** Memory corruption, a segmentation fault, or other severe error
  2864. ** might result if sqlite3_free() is called with a non-NULL pointer that
  2865. ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
  2866. **
  2867. ** ^The sqlite3_realloc(X,N) interface attempts to resize a
  2868. ** prior memory allocation X to be at least N bytes.
  2869. ** ^If the X parameter to sqlite3_realloc(X,N)
  2870. ** is a NULL pointer then its behavior is identical to calling
  2871. ** sqlite3_malloc(N).
  2872. ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
  2873. ** negative then the behavior is exactly the same as calling
  2874. ** sqlite3_free(X).
  2875. ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
  2876. ** of at least N bytes in size or NULL if insufficient memory is available.
  2877. ** ^If M is the size of the prior allocation, then min(N,M) bytes
  2878. ** of the prior allocation are copied into the beginning of buffer returned
  2879. ** by sqlite3_realloc(X,N) and the prior allocation is freed.
  2880. ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
  2881. ** prior allocation is not freed.
  2882. **
  2883. ** ^The sqlite3_realloc64(X,N) interfaces works the same as
  2884. ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
  2885. ** of a 32-bit signed integer.
  2886. **
  2887. ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
  2888. ** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
  2889. ** sqlite3_msize(X) returns the size of that memory allocation in bytes.
  2890. ** ^The value returned by sqlite3_msize(X) might be larger than the number
  2891. ** of bytes requested when X was allocated. ^If X is a NULL pointer then
  2892. ** sqlite3_msize(X) returns zero. If X points to something that is not
  2893. ** the beginning of memory allocation, or if it points to a formerly
  2894. ** valid memory allocation that has now been freed, then the behavior
  2895. ** of sqlite3_msize(X) is undefined and possibly harmful.
  2896. **
  2897. ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
  2898. ** sqlite3_malloc64(), and sqlite3_realloc64()
  2899. ** is always aligned to at least an 8 byte boundary, or to a
  2900. ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
  2901. ** option is used.
  2902. **
  2903. ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
  2904. ** must be either NULL or else pointers obtained from a prior
  2905. ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
  2906. ** not yet been released.
  2907. **
  2908. ** The application must not read or write any part of
  2909. ** a block of memory after it has been released using
  2910. ** [sqlite3_free()] or [sqlite3_realloc()].
  2911. */
  2912. SQLITE_API void *sqlite3_malloc(int);
  2913. SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
  2914. SQLITE_API void *sqlite3_realloc(void*, int);
  2915. SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
  2916. SQLITE_API void sqlite3_free(void*);
  2917. SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
  2918. /*
  2919. ** CAPI3REF: Memory Allocator Statistics
  2920. **
  2921. ** SQLite provides these two interfaces for reporting on the status
  2922. ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
  2923. ** routines, which form the built-in memory allocation subsystem.
  2924. **
  2925. ** ^The [sqlite3_memory_used()] routine returns the number of bytes
  2926. ** of memory currently outstanding (malloced but not freed).
  2927. ** ^The [sqlite3_memory_highwater()] routine returns the maximum
  2928. ** value of [sqlite3_memory_used()] since the high-water mark
  2929. ** was last reset. ^The values returned by [sqlite3_memory_used()] and
  2930. ** [sqlite3_memory_highwater()] include any overhead
  2931. ** added by SQLite in its implementation of [sqlite3_malloc()],
  2932. ** but not overhead added by the any underlying system library
  2933. ** routines that [sqlite3_malloc()] may call.
  2934. **
  2935. ** ^The memory high-water mark is reset to the current value of
  2936. ** [sqlite3_memory_used()] if and only if the parameter to
  2937. ** [sqlite3_memory_highwater()] is true. ^The value returned
  2938. ** by [sqlite3_memory_highwater(1)] is the high-water mark
  2939. ** prior to the reset.
  2940. */
  2941. SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
  2942. SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  2943. /*
  2944. ** CAPI3REF: Pseudo-Random Number Generator
  2945. **
  2946. ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
  2947. ** select random [ROWID | ROWIDs] when inserting new records into a table that
  2948. ** already uses the largest possible [ROWID]. The PRNG is also used for
  2949. ** the built-in random() and randomblob() SQL functions. This interface allows
  2950. ** applications to access the same PRNG for other purposes.
  2951. **
  2952. ** ^A call to this routine stores N bytes of randomness into buffer P.
  2953. ** ^The P parameter can be a NULL pointer.
  2954. **
  2955. ** ^If this routine has not been previously called or if the previous
  2956. ** call had N less than one or a NULL pointer for P, then the PRNG is
  2957. ** seeded using randomness obtained from the xRandomness method of
  2958. ** the default [sqlite3_vfs] object.
  2959. ** ^If the previous call to this routine had an N of 1 or more and a
  2960. ** non-NULL P then the pseudo-randomness is generated
  2961. ** internally and without recourse to the [sqlite3_vfs] xRandomness
  2962. ** method.
  2963. */
  2964. SQLITE_API void sqlite3_randomness(int N, void *P);
  2965. /*
  2966. ** CAPI3REF: Compile-Time Authorization Callbacks
  2967. ** METHOD: sqlite3
  2968. ** KEYWORDS: {authorizer callback}
  2969. **
  2970. ** ^This routine registers an authorizer callback with a particular
  2971. ** [database connection], supplied in the first argument.
  2972. ** ^The authorizer callback is invoked as SQL statements are being compiled
  2973. ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  2974. ** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
  2975. ** and [sqlite3_prepare16_v3()]. ^At various
  2976. ** points during the compilation process, as logic is being created
  2977. ** to perform various actions, the authorizer callback is invoked to
  2978. ** see if those actions are allowed. ^The authorizer callback should
  2979. ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  2980. ** specific action but allow the SQL statement to continue to be
  2981. ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  2982. ** rejected with an error. ^If the authorizer callback returns
  2983. ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  2984. ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
  2985. ** the authorizer will fail with an error message.
  2986. **
  2987. ** When the callback returns [SQLITE_OK], that means the operation
  2988. ** requested is ok. ^When the callback returns [SQLITE_DENY], the
  2989. ** [sqlite3_prepare_v2()] or equivalent call that triggered the
  2990. ** authorizer will fail with an error message explaining that
  2991. ** access is denied.
  2992. **
  2993. ** ^The first parameter to the authorizer callback is a copy of the third
  2994. ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
  2995. ** to the callback is an integer [SQLITE_COPY | action code] that specifies
  2996. ** the particular action to be authorized. ^The third through sixth parameters
  2997. ** to the callback are either NULL pointers or zero-terminated strings
  2998. ** that contain additional details about the action to be authorized.
  2999. ** Applications must always be prepared to encounter a NULL pointer in any
  3000. ** of the third through the sixth parameters of the authorization callback.
  3001. **
  3002. ** ^If the action code is [SQLITE_READ]
  3003. ** and the callback returns [SQLITE_IGNORE] then the
  3004. ** [prepared statement] statement is constructed to substitute
  3005. ** a NULL value in place of the table column that would have
  3006. ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
  3007. ** return can be used to deny an untrusted user access to individual
  3008. ** columns of a table.
  3009. ** ^When a table is referenced by a [SELECT] but no column values are
  3010. ** extracted from that table (for example in a query like
  3011. ** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
  3012. ** is invoked once for that table with a column name that is an empty string.
  3013. ** ^If the action code is [SQLITE_DELETE] and the callback returns
  3014. ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
  3015. ** [truncate optimization] is disabled and all rows are deleted individually.
  3016. **
  3017. ** An authorizer is used when [sqlite3_prepare | preparing]
  3018. ** SQL statements from an untrusted source, to ensure that the SQL statements
  3019. ** do not try to access data they are not allowed to see, or that they do not
  3020. ** try to execute malicious statements that damage the database. For
  3021. ** example, an application may allow a user to enter arbitrary
  3022. ** SQL queries for evaluation by a database. But the application does
  3023. ** not want the user to be able to make arbitrary changes to the
  3024. ** database. An authorizer could then be put in place while the
  3025. ** user-entered SQL is being [sqlite3_prepare | prepared] that
  3026. ** disallows everything except [SELECT] statements.
  3027. **
  3028. ** Applications that need to process SQL from untrusted sources
  3029. ** might also consider lowering resource limits using [sqlite3_limit()]
  3030. ** and limiting database size using the [max_page_count] [PRAGMA]
  3031. ** in addition to using an authorizer.
  3032. **
  3033. ** ^(Only a single authorizer can be in place on a database connection
  3034. ** at a time. Each call to sqlite3_set_authorizer overrides the
  3035. ** previous call.)^ ^Disable the authorizer by installing a NULL callback.
  3036. ** The authorizer is disabled by default.
  3037. **
  3038. ** The authorizer callback must not do anything that will modify
  3039. ** the database connection that invoked the authorizer callback.
  3040. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3041. ** database connections for the meaning of "modify" in this paragraph.
  3042. **
  3043. ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
  3044. ** statement might be re-prepared during [sqlite3_step()] due to a
  3045. ** schema change. Hence, the application should ensure that the
  3046. ** correct authorizer callback remains in place during the [sqlite3_step()].
  3047. **
  3048. ** ^Note that the authorizer callback is invoked only during
  3049. ** [sqlite3_prepare()] or its variants. Authorization is not
  3050. ** performed during statement evaluation in [sqlite3_step()], unless
  3051. ** as stated in the previous paragraph, sqlite3_step() invokes
  3052. ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
  3053. */
  3054. SQLITE_API int sqlite3_set_authorizer(
  3055. sqlite3*,
  3056. int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  3057. void *pUserData
  3058. );
  3059. /*
  3060. ** CAPI3REF: Authorizer Return Codes
  3061. **
  3062. ** The [sqlite3_set_authorizer | authorizer callback function] must
  3063. ** return either [SQLITE_OK] or one of these two constants in order
  3064. ** to signal SQLite whether or not the action is permitted. See the
  3065. ** [sqlite3_set_authorizer | authorizer documentation] for additional
  3066. ** information.
  3067. **
  3068. ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
  3069. ** returned from the [sqlite3_vtab_on_conflict()] interface.
  3070. */
  3071. #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
  3072. #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
  3073. /*
  3074. ** CAPI3REF: Authorizer Action Codes
  3075. **
  3076. ** The [sqlite3_set_authorizer()] interface registers a callback function
  3077. ** that is invoked to authorize certain SQL statement actions. The
  3078. ** second parameter to the callback is an integer code that specifies
  3079. ** what action is being authorized. These are the integer action codes that
  3080. ** the authorizer callback may be passed.
  3081. **
  3082. ** These action code values signify what kind of operation is to be
  3083. ** authorized. The 3rd and 4th parameters to the authorization
  3084. ** callback function will be parameters or NULL depending on which of these
  3085. ** codes is used as the second parameter. ^(The 5th parameter to the
  3086. ** authorizer callback is the name of the database ("main", "temp",
  3087. ** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
  3088. ** is the name of the inner-most trigger or view that is responsible for
  3089. ** the access attempt or NULL if this access attempt is directly from
  3090. ** top-level SQL code.
  3091. */
  3092. /******************************************* 3rd ************ 4th ***********/
  3093. #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
  3094. #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
  3095. #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
  3096. #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
  3097. #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
  3098. #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
  3099. #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
  3100. #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
  3101. #define SQLITE_DELETE 9 /* Table Name NULL */
  3102. #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
  3103. #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
  3104. #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
  3105. #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
  3106. #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
  3107. #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
  3108. #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
  3109. #define SQLITE_DROP_VIEW 17 /* View Name NULL */
  3110. #define SQLITE_INSERT 18 /* Table Name NULL */
  3111. #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
  3112. #define SQLITE_READ 20 /* Table Name Column Name */
  3113. #define SQLITE_SELECT 21 /* NULL NULL */
  3114. #define SQLITE_TRANSACTION 22 /* Operation NULL */
  3115. #define SQLITE_UPDATE 23 /* Table Name Column Name */
  3116. #define SQLITE_ATTACH 24 /* Filename NULL */
  3117. #define SQLITE_DETACH 25 /* Database Name NULL */
  3118. #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
  3119. #define SQLITE_REINDEX 27 /* Index Name NULL */
  3120. #define SQLITE_ANALYZE 28 /* Table Name NULL */
  3121. #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
  3122. #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
  3123. #define SQLITE_FUNCTION 31 /* NULL Function Name */
  3124. #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
  3125. #define SQLITE_COPY 0 /* No longer used */
  3126. #define SQLITE_RECURSIVE 33 /* NULL NULL */
  3127. /*
  3128. ** CAPI3REF: Tracing And Profiling Functions
  3129. ** METHOD: sqlite3
  3130. **
  3131. ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
  3132. ** instead of the routines described here.
  3133. **
  3134. ** These routines register callback functions that can be used for
  3135. ** tracing and profiling the execution of SQL statements.
  3136. **
  3137. ** ^The callback function registered by sqlite3_trace() is invoked at
  3138. ** various times when an SQL statement is being run by [sqlite3_step()].
  3139. ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
  3140. ** SQL statement text as the statement first begins executing.
  3141. ** ^(Additional sqlite3_trace() callbacks might occur
  3142. ** as each triggered subprogram is entered. The callbacks for triggers
  3143. ** contain a UTF-8 SQL comment that identifies the trigger.)^
  3144. **
  3145. ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
  3146. ** the length of [bound parameter] expansion in the output of sqlite3_trace().
  3147. **
  3148. ** ^The callback function registered by sqlite3_profile() is invoked
  3149. ** as each SQL statement finishes. ^The profile callback contains
  3150. ** the original statement text and an estimate of wall-clock time
  3151. ** of how long that statement took to run. ^The profile callback
  3152. ** time is in units of nanoseconds, however the current implementation
  3153. ** is only capable of millisecond resolution so the six least significant
  3154. ** digits in the time are meaningless. Future versions of SQLite
  3155. ** might provide greater resolution on the profiler callback. Invoking
  3156. ** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
  3157. ** profile callback.
  3158. */
  3159. SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
  3160. void(*xTrace)(void*,const char*), void*);
  3161. SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
  3162. void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  3163. /*
  3164. ** CAPI3REF: SQL Trace Event Codes
  3165. ** KEYWORDS: SQLITE_TRACE
  3166. **
  3167. ** These constants identify classes of events that can be monitored
  3168. ** using the [sqlite3_trace_v2()] tracing logic. The M argument
  3169. ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
  3170. ** the following constants. ^The first argument to the trace callback
  3171. ** is one of the following constants.
  3172. **
  3173. ** New tracing constants may be added in future releases.
  3174. **
  3175. ** ^A trace callback has four arguments: xCallback(T,C,P,X).
  3176. ** ^The T argument is one of the integer type codes above.
  3177. ** ^The C argument is a copy of the context pointer passed in as the
  3178. ** fourth argument to [sqlite3_trace_v2()].
  3179. ** The P and X arguments are pointers whose meanings depend on T.
  3180. **
  3181. ** <dl>
  3182. ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
  3183. ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
  3184. ** first begins running and possibly at other times during the
  3185. ** execution of the prepared statement, such as at the start of each
  3186. ** trigger subprogram. ^The P argument is a pointer to the
  3187. ** [prepared statement]. ^The X argument is a pointer to a string which
  3188. ** is the unexpanded SQL text of the prepared statement or an SQL comment
  3189. ** that indicates the invocation of a trigger. ^The callback can compute
  3190. ** the same text that would have been returned by the legacy [sqlite3_trace()]
  3191. ** interface by using the X argument when X begins with "--" and invoking
  3192. ** [sqlite3_expanded_sql(P)] otherwise.
  3193. **
  3194. ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
  3195. ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
  3196. ** information as is provided by the [sqlite3_profile()] callback.
  3197. ** ^The P argument is a pointer to the [prepared statement] and the
  3198. ** X argument points to a 64-bit integer which is the estimated of
  3199. ** the number of nanosecond that the prepared statement took to run.
  3200. ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
  3201. **
  3202. ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
  3203. ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
  3204. ** statement generates a single row of result.
  3205. ** ^The P argument is a pointer to the [prepared statement] and the
  3206. ** X argument is unused.
  3207. **
  3208. ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
  3209. ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
  3210. ** connection closes.
  3211. ** ^The P argument is a pointer to the [database connection] object
  3212. ** and the X argument is unused.
  3213. ** </dl>
  3214. */
  3215. #define SQLITE_TRACE_STMT 0x01
  3216. #define SQLITE_TRACE_PROFILE 0x02
  3217. #define SQLITE_TRACE_ROW 0x04
  3218. #define SQLITE_TRACE_CLOSE 0x08
  3219. /*
  3220. ** CAPI3REF: SQL Trace Hook
  3221. ** METHOD: sqlite3
  3222. **
  3223. ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
  3224. ** function X against [database connection] D, using property mask M
  3225. ** and context pointer P. ^If the X callback is
  3226. ** NULL or if the M mask is zero, then tracing is disabled. The
  3227. ** M argument should be the bitwise OR-ed combination of
  3228. ** zero or more [SQLITE_TRACE] constants.
  3229. **
  3230. ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
  3231. ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
  3232. **
  3233. ** ^The X callback is invoked whenever any of the events identified by
  3234. ** mask M occur. ^The integer return value from the callback is currently
  3235. ** ignored, though this may change in future releases. Callback
  3236. ** implementations should return zero to ensure future compatibility.
  3237. **
  3238. ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
  3239. ** ^The T argument is one of the [SQLITE_TRACE]
  3240. ** constants to indicate why the callback was invoked.
  3241. ** ^The C argument is a copy of the context pointer.
  3242. ** The P and X arguments are pointers whose meanings depend on T.
  3243. **
  3244. ** The sqlite3_trace_v2() interface is intended to replace the legacy
  3245. ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
  3246. ** are deprecated.
  3247. */
  3248. SQLITE_API int sqlite3_trace_v2(
  3249. sqlite3*,
  3250. unsigned uMask,
  3251. int(*xCallback)(unsigned,void*,void*,void*),
  3252. void *pCtx
  3253. );
  3254. /*
  3255. ** CAPI3REF: Query Progress Callbacks
  3256. ** METHOD: sqlite3
  3257. **
  3258. ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
  3259. ** function X to be invoked periodically during long running calls to
  3260. ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
  3261. ** database connection D. An example use for this
  3262. ** interface is to keep a GUI updated during a large query.
  3263. **
  3264. ** ^The parameter P is passed through as the only parameter to the
  3265. ** callback function X. ^The parameter N is the approximate number of
  3266. ** [virtual machine instructions] that are evaluated between successive
  3267. ** invocations of the callback X. ^If N is less than one then the progress
  3268. ** handler is disabled.
  3269. **
  3270. ** ^Only a single progress handler may be defined at one time per
  3271. ** [database connection]; setting a new progress handler cancels the
  3272. ** old one. ^Setting parameter X to NULL disables the progress handler.
  3273. ** ^The progress handler is also disabled by setting N to a value less
  3274. ** than 1.
  3275. **
  3276. ** ^If the progress callback returns non-zero, the operation is
  3277. ** interrupted. This feature can be used to implement a
  3278. ** "Cancel" button on a GUI progress dialog box.
  3279. **
  3280. ** The progress handler callback must not do anything that will modify
  3281. ** the database connection that invoked the progress handler.
  3282. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3283. ** database connections for the meaning of "modify" in this paragraph.
  3284. **
  3285. */
  3286. SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  3287. /*
  3288. ** CAPI3REF: Opening A New Database Connection
  3289. ** CONSTRUCTOR: sqlite3
  3290. **
  3291. ** ^These routines open an SQLite database file as specified by the
  3292. ** filename argument. ^The filename argument is interpreted as UTF-8 for
  3293. ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
  3294. ** order for sqlite3_open16(). ^(A [database connection] handle is usually
  3295. ** returned in *ppDb, even if an error occurs. The only exception is that
  3296. ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
  3297. ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
  3298. ** object.)^ ^(If the database is opened (and/or created) successfully, then
  3299. ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
  3300. ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
  3301. ** an English language description of the error following a failure of any
  3302. ** of the sqlite3_open() routines.
  3303. **
  3304. ** ^The default encoding will be UTF-8 for databases created using
  3305. ** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
  3306. ** created using sqlite3_open16() will be UTF-16 in the native byte order.
  3307. **
  3308. ** Whether or not an error occurs when it is opened, resources
  3309. ** associated with the [database connection] handle should be released by
  3310. ** passing it to [sqlite3_close()] when it is no longer required.
  3311. **
  3312. ** The sqlite3_open_v2() interface works like sqlite3_open()
  3313. ** except that it accepts two additional parameters for additional control
  3314. ** over the new database connection. ^(The flags parameter to
  3315. ** sqlite3_open_v2() must include, at a minimum, one of the following
  3316. ** three flag combinations:)^
  3317. **
  3318. ** <dl>
  3319. ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
  3320. ** <dd>The database is opened in read-only mode. If the database does not
  3321. ** already exist, an error is returned.</dd>)^
  3322. **
  3323. ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
  3324. ** <dd>The database is opened for reading and writing if possible, or reading
  3325. ** only if the file is write protected by the operating system. In either
  3326. ** case the database must already exist, otherwise an error is returned.</dd>)^
  3327. **
  3328. ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
  3329. ** <dd>The database is opened for reading and writing, and is created if
  3330. ** it does not already exist. This is the behavior that is always used for
  3331. ** sqlite3_open() and sqlite3_open16().</dd>)^
  3332. ** </dl>
  3333. **
  3334. ** In addition to the required flags, the following optional flags are
  3335. ** also supported:
  3336. **
  3337. ** <dl>
  3338. ** ^(<dt>[SQLITE_OPEN_URI]</dt>
  3339. ** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
  3340. **
  3341. ** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>
  3342. ** <dd>The database will be opened as an in-memory database. The database
  3343. ** is named by the "filename" argument for the purposes of cache-sharing,
  3344. ** if shared cache mode is enabled, but the "filename" is otherwise ignored.
  3345. ** </dd>)^
  3346. **
  3347. ** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>
  3348. ** <dd>The new database connection will use the "multi-thread"
  3349. ** [threading mode].)^ This means that separate threads are allowed
  3350. ** to use SQLite at the same time, as long as each thread is using
  3351. ** a different [database connection].
  3352. **
  3353. ** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>
  3354. ** <dd>The new database connection will use the "serialized"
  3355. ** [threading mode].)^ This means the multiple threads can safely
  3356. ** attempt to use the same database connection at the same time.
  3357. ** (Mutexes will block any actual concurrency, but in this mode
  3358. ** there is no harm in trying.)
  3359. **
  3360. ** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>
  3361. ** <dd>The database is opened [shared cache] enabled, overriding
  3362. ** the default shared cache setting provided by
  3363. ** [sqlite3_enable_shared_cache()].)^
  3364. **
  3365. ** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
  3366. ** <dd>The database is opened [shared cache] disabled, overriding
  3367. ** the default shared cache setting provided by
  3368. ** [sqlite3_enable_shared_cache()].)^
  3369. **
  3370. ** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt>
  3371. ** <dd>The database connection comes up in "extended result code mode".
  3372. ** In other words, the database behaves has if
  3373. ** [sqlite3_extended_result_codes(db,1)] where called on the database
  3374. ** connection as soon as the connection is created. In addition to setting
  3375. ** the extended result code mode, this flag also causes [sqlite3_open_v2()]
  3376. ** to return an extended result code.</dd>
  3377. **
  3378. ** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
  3379. ** <dd>The database filename is not allowed to be a symbolic link</dd>
  3380. ** </dl>)^
  3381. **
  3382. ** If the 3rd parameter to sqlite3_open_v2() is not one of the
  3383. ** required combinations shown above optionally combined with other
  3384. ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
  3385. ** then the behavior is undefined. Historic versions of SQLite
  3386. ** have silently ignored surplus bits in the flags parameter to
  3387. ** sqlite3_open_v2(), however that behavior might not be carried through
  3388. ** into future versions of SQLite and so applications should not rely
  3389. ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
  3390. ** for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
  3391. ** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
  3392. ** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
  3393. ** by sqlite3_open_v2().
  3394. **
  3395. ** ^The fourth parameter to sqlite3_open_v2() is the name of the
  3396. ** [sqlite3_vfs] object that defines the operating system interface that
  3397. ** the new database connection should use. ^If the fourth parameter is
  3398. ** a NULL pointer then the default [sqlite3_vfs] object is used.
  3399. **
  3400. ** ^If the filename is ":memory:", then a private, temporary in-memory database
  3401. ** is created for the connection. ^This in-memory database will vanish when
  3402. ** the database connection is closed. Future versions of SQLite might
  3403. ** make use of additional special filenames that begin with the ":" character.
  3404. ** It is recommended that when a database filename actually does begin with
  3405. ** a ":" character you should prefix the filename with a pathname such as
  3406. ** "./" to avoid ambiguity.
  3407. **
  3408. ** ^If the filename is an empty string, then a private, temporary
  3409. ** on-disk database will be created. ^This private database will be
  3410. ** automatically deleted as soon as the database connection is closed.
  3411. **
  3412. ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
  3413. **
  3414. ** ^If [URI filename] interpretation is enabled, and the filename argument
  3415. ** begins with "file:", then the filename is interpreted as a URI. ^URI
  3416. ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
  3417. ** set in the third argument to sqlite3_open_v2(), or if it has
  3418. ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
  3419. ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
  3420. ** URI filename interpretation is turned off
  3421. ** by default, but future releases of SQLite might enable URI filename
  3422. ** interpretation by default. See "[URI filenames]" for additional
  3423. ** information.
  3424. **
  3425. ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
  3426. ** authority, then it must be either an empty string or the string
  3427. ** "localhost". ^If the authority is not an empty string or "localhost", an
  3428. ** error is returned to the caller. ^The fragment component of a URI, if
  3429. ** present, is ignored.
  3430. **
  3431. ** ^SQLite uses the path component of the URI as the name of the disk file
  3432. ** which contains the database. ^If the path begins with a '/' character,
  3433. ** then it is interpreted as an absolute path. ^If the path does not begin
  3434. ** with a '/' (meaning that the authority section is omitted from the URI)
  3435. ** then the path is interpreted as a relative path.
  3436. ** ^(On windows, the first component of an absolute path
  3437. ** is a drive specification (e.g. "C:").)^
  3438. **
  3439. ** [[core URI query parameters]]
  3440. ** The query component of a URI may contain parameters that are interpreted
  3441. ** either by SQLite itself, or by a [VFS | custom VFS implementation].
  3442. ** SQLite and its built-in [VFSes] interpret the
  3443. ** following query parameters:
  3444. **
  3445. ** <ul>
  3446. ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
  3447. ** a VFS object that provides the operating system interface that should
  3448. ** be used to access the database file on disk. ^If this option is set to
  3449. ** an empty string the default VFS object is used. ^Specifying an unknown
  3450. ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
  3451. ** present, then the VFS specified by the option takes precedence over
  3452. ** the value passed as the fourth parameter to sqlite3_open_v2().
  3453. **
  3454. ** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
  3455. ** "rwc", or "memory". Attempting to set it to any other value is
  3456. ** an error)^.
  3457. ** ^If "ro" is specified, then the database is opened for read-only
  3458. ** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
  3459. ** third argument to sqlite3_open_v2(). ^If the mode option is set to
  3460. ** "rw", then the database is opened for read-write (but not create)
  3461. ** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
  3462. ** been set. ^Value "rwc" is equivalent to setting both
  3463. ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
  3464. ** set to "memory" then a pure [in-memory database] that never reads
  3465. ** or writes from disk is used. ^It is an error to specify a value for
  3466. ** the mode parameter that is less restrictive than that specified by
  3467. ** the flags passed in the third parameter to sqlite3_open_v2().
  3468. **
  3469. ** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
  3470. ** "private". ^Setting it to "shared" is equivalent to setting the
  3471. ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
  3472. ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
  3473. ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
  3474. ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
  3475. ** a URI filename, its value overrides any behavior requested by setting
  3476. ** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
  3477. **
  3478. ** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
  3479. ** [powersafe overwrite] property does or does not apply to the
  3480. ** storage media on which the database file resides.
  3481. **
  3482. ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
  3483. ** which if set disables file locking in rollback journal modes. This
  3484. ** is useful for accessing a database on a filesystem that does not
  3485. ** support locking. Caution: Database corruption might result if two
  3486. ** or more processes write to the same database and any one of those
  3487. ** processes uses nolock=1.
  3488. **
  3489. ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
  3490. ** parameter that indicates that the database file is stored on
  3491. ** read-only media. ^When immutable is set, SQLite assumes that the
  3492. ** database file cannot be changed, even by a process with higher
  3493. ** privilege, and so the database is opened read-only and all locking
  3494. ** and change detection is disabled. Caution: Setting the immutable
  3495. ** property on a database file that does in fact change can result
  3496. ** in incorrect query results and/or [SQLITE_CORRUPT] errors.
  3497. ** See also: [SQLITE_IOCAP_IMMUTABLE].
  3498. **
  3499. ** </ul>
  3500. **
  3501. ** ^Specifying an unknown parameter in the query component of a URI is not an
  3502. ** error. Future versions of SQLite might understand additional query
  3503. ** parameters. See "[query parameters with special meaning to SQLite]" for
  3504. ** additional information.
  3505. **
  3506. ** [[URI filename examples]] <h3>URI filename examples</h3>
  3507. **
  3508. ** <table border="1" align=center cellpadding=5>
  3509. ** <tr><th> URI filenames <th> Results
  3510. ** <tr><td> file:data.db <td>
  3511. ** Open the file "data.db" in the current directory.
  3512. ** <tr><td> file:/home/fred/data.db<br>
  3513. ** file:///home/fred/data.db <br>
  3514. ** file://localhost/home/fred/data.db <br> <td>
  3515. ** Open the database file "/home/fred/data.db".
  3516. ** <tr><td> file://darkstar/home/fred/data.db <td>
  3517. ** An error. "darkstar" is not a recognized authority.
  3518. ** <tr><td style="white-space:nowrap">
  3519. ** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
  3520. ** <td> Windows only: Open the file "data.db" on fred's desktop on drive
  3521. ** C:. Note that the %20 escaping in this example is not strictly
  3522. ** necessary - space characters can be used literally
  3523. ** in URI filenames.
  3524. ** <tr><td> file:data.db?mode=ro&cache=private <td>
  3525. ** Open file "data.db" in the current directory for read-only access.
  3526. ** Regardless of whether or not shared-cache mode is enabled by
  3527. ** default, use a private cache.
  3528. ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
  3529. ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
  3530. ** that uses dot-files in place of posix advisory locking.
  3531. ** <tr><td> file:data.db?mode=readonly <td>
  3532. ** An error. "readonly" is not a valid option for the "mode" parameter.
  3533. ** Use "ro" instead: "file:data.db?mode=ro".
  3534. ** </table>
  3535. **
  3536. ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
  3537. ** query components of a URI. A hexadecimal escape sequence consists of a
  3538. ** percent sign - "%" - followed by exactly two hexadecimal digits
  3539. ** specifying an octet value. ^Before the path or query components of a
  3540. ** URI filename are interpreted, they are encoded using UTF-8 and all
  3541. ** hexadecimal escape sequences replaced by a single byte containing the
  3542. ** corresponding octet. If this process generates an invalid UTF-8 encoding,
  3543. ** the results are undefined.
  3544. **
  3545. ** <b>Note to Windows users:</b> The encoding used for the filename argument
  3546. ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
  3547. ** codepage is currently defined. Filenames containing international
  3548. ** characters must be converted to UTF-8 prior to passing them into
  3549. ** sqlite3_open() or sqlite3_open_v2().
  3550. **
  3551. ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
  3552. ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
  3553. ** features that require the use of temporary files may fail.
  3554. **
  3555. ** See also: [sqlite3_temp_directory]
  3556. */
  3557. SQLITE_API int sqlite3_open(
  3558. const char *filename, /* Database filename (UTF-8) */
  3559. sqlite3 **ppDb /* OUT: SQLite db handle */
  3560. );
  3561. SQLITE_API int sqlite3_open16(
  3562. const void *filename, /* Database filename (UTF-16) */
  3563. sqlite3 **ppDb /* OUT: SQLite db handle */
  3564. );
  3565. SQLITE_API int sqlite3_open_v2(
  3566. const char *filename, /* Database filename (UTF-8) */
  3567. sqlite3 **ppDb, /* OUT: SQLite db handle */
  3568. int flags, /* Flags */
  3569. const char *zVfs /* Name of VFS module to use */
  3570. );
  3571. /*
  3572. ** CAPI3REF: Obtain Values For URI Parameters
  3573. **
  3574. ** These are utility routines, useful to [VFS|custom VFS implementations],
  3575. ** that check if a database file was a URI that contained a specific query
  3576. ** parameter, and if so obtains the value of that query parameter.
  3577. **
  3578. ** The first parameter to these interfaces (hereafter referred to
  3579. ** as F) must be one of:
  3580. ** <ul>
  3581. ** <li> A database filename pointer created by the SQLite core and
  3582. ** passed into the xOpen() method of a VFS implemention, or
  3583. ** <li> A filename obtained from [sqlite3_db_filename()], or
  3584. ** <li> A new filename constructed using [sqlite3_create_filename()].
  3585. ** </ul>
  3586. ** If the F parameter is not one of the above, then the behavior is
  3587. ** undefined and probably undesirable. Older versions of SQLite were
  3588. ** more tolerant of invalid F parameters than newer versions.
  3589. **
  3590. ** If F is a suitable filename (as described in the previous paragraph)
  3591. ** and if P is the name of the query parameter, then
  3592. ** sqlite3_uri_parameter(F,P) returns the value of the P
  3593. ** parameter if it exists or a NULL pointer if P does not appear as a
  3594. ** query parameter on F. If P is a query parameter of F and it
  3595. ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
  3596. ** a pointer to an empty string.
  3597. **
  3598. ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
  3599. ** parameter and returns true (1) or false (0) according to the value
  3600. ** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
  3601. ** value of query parameter P is one of "yes", "true", or "on" in any
  3602. ** case or if the value begins with a non-zero number. The
  3603. ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
  3604. ** query parameter P is one of "no", "false", or "off" in any case or
  3605. ** if the value begins with a numeric zero. If P is not a query
  3606. ** parameter on F or if the value of P does not match any of the
  3607. ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
  3608. **
  3609. ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
  3610. ** 64-bit signed integer and returns that integer, or D if P does not
  3611. ** exist. If the value of P is something other than an integer, then
  3612. ** zero is returned.
  3613. **
  3614. ** The sqlite3_uri_key(F,N) returns a pointer to the name (not
  3615. ** the value) of the N-th query parameter for filename F, or a NULL
  3616. ** pointer if N is less than zero or greater than the number of query
  3617. ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
  3618. ** the name of the first query parameter, 1 for the second parameter, and
  3619. ** so forth.
  3620. **
  3621. ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
  3622. ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
  3623. ** is not a database file pathname pointer that the SQLite core passed
  3624. ** into the xOpen VFS method, then the behavior of this routine is undefined
  3625. ** and probably undesirable.
  3626. **
  3627. ** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F
  3628. ** parameter can also be the name of a rollback journal file or WAL file
  3629. ** in addition to the main database file. Prior to version 3.31.0, these
  3630. ** routines would only work if F was the name of the main database file.
  3631. ** When the F parameter is the name of the rollback journal or WAL file,
  3632. ** it has access to all the same query parameters as were found on the
  3633. ** main database file.
  3634. **
  3635. ** See the [URI filename] documentation for additional information.
  3636. */
  3637. SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
  3638. SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
  3639. SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
  3640. SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
  3641. /*
  3642. ** CAPI3REF: Translate filenames
  3643. **
  3644. ** These routines are available to [VFS|custom VFS implementations] for
  3645. ** translating filenames between the main database file, the journal file,
  3646. ** and the WAL file.
  3647. **
  3648. ** If F is the name of an sqlite database file, journal file, or WAL file
  3649. ** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
  3650. ** returns the name of the corresponding database file.
  3651. **
  3652. ** If F is the name of an sqlite database file, journal file, or WAL file
  3653. ** passed by the SQLite core into the VFS, or if F is a database filename
  3654. ** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)
  3655. ** returns the name of the corresponding rollback journal file.
  3656. **
  3657. ** If F is the name of an sqlite database file, journal file, or WAL file
  3658. ** that was passed by the SQLite core into the VFS, or if F is a database
  3659. ** filename obtained from [sqlite3_db_filename()], then
  3660. ** sqlite3_filename_wal(F) returns the name of the corresponding
  3661. ** WAL file.
  3662. **
  3663. ** In all of the above, if F is not the name of a database, journal or WAL
  3664. ** filename passed into the VFS from the SQLite core and F is not the
  3665. ** return value from [sqlite3_db_filename()], then the result is
  3666. ** undefined and is likely a memory access violation.
  3667. */
  3668. SQLITE_API const char *sqlite3_filename_database(const char*);
  3669. SQLITE_API const char *sqlite3_filename_journal(const char*);
  3670. SQLITE_API const char *sqlite3_filename_wal(const char*);
  3671. /*
  3672. ** CAPI3REF: Database File Corresponding To A Journal
  3673. **
  3674. ** ^If X is the name of a rollback or WAL-mode journal file that is
  3675. ** passed into the xOpen method of [sqlite3_vfs], then
  3676. ** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
  3677. ** object that represents the main database file.
  3678. **
  3679. ** This routine is intended for use in custom [VFS] implementations
  3680. ** only. It is not a general-purpose interface.
  3681. ** The argument sqlite3_file_object(X) must be a filename pointer that
  3682. ** has been passed into [sqlite3_vfs].xOpen method where the
  3683. ** flags parameter to xOpen contains one of the bits
  3684. ** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL]. Any other use
  3685. ** of this routine results in undefined and probably undesirable
  3686. ** behavior.
  3687. */
  3688. SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
  3689. /*
  3690. ** CAPI3REF: Create and Destroy VFS Filenames
  3691. **
  3692. ** These interfces are provided for use by [VFS shim] implementations and
  3693. ** are not useful outside of that context.
  3694. **
  3695. ** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
  3696. ** database filename D with corresponding journal file J and WAL file W and
  3697. ** with N URI parameters key/values pairs in the array P. The result from
  3698. ** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
  3699. ** is safe to pass to routines like:
  3700. ** <ul>
  3701. ** <li> [sqlite3_uri_parameter()],
  3702. ** <li> [sqlite3_uri_boolean()],
  3703. ** <li> [sqlite3_uri_int64()],
  3704. ** <li> [sqlite3_uri_key()],
  3705. ** <li> [sqlite3_filename_database()],
  3706. ** <li> [sqlite3_filename_journal()], or
  3707. ** <li> [sqlite3_filename_wal()].
  3708. ** </ul>
  3709. ** If a memory allocation error occurs, sqlite3_create_filename() might
  3710. ** return a NULL pointer. The memory obtained from sqlite3_create_filename(X)
  3711. ** must be released by a corresponding call to sqlite3_free_filename(Y).
  3712. **
  3713. ** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
  3714. ** of 2*N pointers to strings. Each pair of pointers in this array corresponds
  3715. ** to a key and value for a query parameter. The P parameter may be a NULL
  3716. ** pointer if N is zero. None of the 2*N pointers in the P array may be
  3717. ** NULL pointers and key pointers should not be empty strings.
  3718. ** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
  3719. ** be NULL pointers, though they can be empty strings.
  3720. **
  3721. ** The sqlite3_free_filename(Y) routine releases a memory allocation
  3722. ** previously obtained from sqlite3_create_filename(). Invoking
  3723. ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
  3724. **
  3725. ** If the Y parameter to sqlite3_free_filename(Y) is anything other
  3726. ** than a NULL pointer or a pointer previously acquired from
  3727. ** sqlite3_create_filename(), then bad things such as heap
  3728. ** corruption or segfaults may occur. The value Y should not be
  3729. ** used again after sqlite3_free_filename(Y) has been called. This means
  3730. ** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
  3731. ** then the corresponding [sqlite3_module.xClose() method should also be
  3732. ** invoked prior to calling sqlite3_free_filename(Y).
  3733. */
  3734. SQLITE_API char *sqlite3_create_filename(
  3735. const char *zDatabase,
  3736. const char *zJournal,
  3737. const char *zWal,
  3738. int nParam,
  3739. const char **azParam
  3740. );
  3741. SQLITE_API void sqlite3_free_filename(char*);
  3742. /*
  3743. ** CAPI3REF: Error Codes And Messages
  3744. ** METHOD: sqlite3
  3745. **
  3746. ** ^If the most recent sqlite3_* API call associated with
  3747. ** [database connection] D failed, then the sqlite3_errcode(D) interface
  3748. ** returns the numeric [result code] or [extended result code] for that
  3749. ** API call.
  3750. ** ^The sqlite3_extended_errcode()
  3751. ** interface is the same except that it always returns the
  3752. ** [extended result code] even when extended result codes are
  3753. ** disabled.
  3754. **
  3755. ** The values returned by sqlite3_errcode() and/or
  3756. ** sqlite3_extended_errcode() might change with each API call.
  3757. ** Except, there are some interfaces that are guaranteed to never
  3758. ** change the value of the error code. The error-code preserving
  3759. ** interfaces include the following:
  3760. **
  3761. ** <ul>
  3762. ** <li> sqlite3_errcode()
  3763. ** <li> sqlite3_extended_errcode()
  3764. ** <li> sqlite3_errmsg()
  3765. ** <li> sqlite3_errmsg16()
  3766. ** <li> sqlite3_error_offset()
  3767. ** </ul>
  3768. **
  3769. ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  3770. ** text that describes the error, as either UTF-8 or UTF-16 respectively.
  3771. ** ^(Memory to hold the error message string is managed internally.
  3772. ** The application does not need to worry about freeing the result.
  3773. ** However, the error string might be overwritten or deallocated by
  3774. ** subsequent calls to other SQLite interface functions.)^
  3775. **
  3776. ** ^The sqlite3_errstr() interface returns the English-language text
  3777. ** that describes the [result code], as UTF-8.
  3778. ** ^(Memory to hold the error message string is managed internally
  3779. ** and must not be freed by the application)^.
  3780. **
  3781. ** ^If the most recent error references a specific token in the input
  3782. ** SQL, the sqlite3_error_offset() interface returns the byte offset
  3783. ** of the start of that token. ^The byte offset returned by
  3784. ** sqlite3_error_offset() assumes that the input SQL is UTF8.
  3785. ** ^If the most recent error does not reference a specific token in the input
  3786. ** SQL, then the sqlite3_error_offset() function returns -1.
  3787. **
  3788. ** When the serialized [threading mode] is in use, it might be the
  3789. ** case that a second error occurs on a separate thread in between
  3790. ** the time of the first error and the call to these interfaces.
  3791. ** When that happens, the second error will be reported since these
  3792. ** interfaces always report the most recent result. To avoid
  3793. ** this, each thread can obtain exclusive use of the [database connection] D
  3794. ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
  3795. ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
  3796. ** all calls to the interfaces listed here are completed.
  3797. **
  3798. ** If an interface fails with SQLITE_MISUSE, that means the interface
  3799. ** was invoked incorrectly by the application. In that case, the
  3800. ** error code and message may or may not be set.
  3801. */
  3802. SQLITE_API int sqlite3_errcode(sqlite3 *db);
  3803. SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
  3804. SQLITE_API const char *sqlite3_errmsg(sqlite3*);
  3805. SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
  3806. SQLITE_API const char *sqlite3_errstr(int);
  3807. SQLITE_API int sqlite3_error_offset(sqlite3 *db);
  3808. /*
  3809. ** CAPI3REF: Prepared Statement Object
  3810. ** KEYWORDS: {prepared statement} {prepared statements}
  3811. **
  3812. ** An instance of this object represents a single SQL statement that
  3813. ** has been compiled into binary form and is ready to be evaluated.
  3814. **
  3815. ** Think of each SQL statement as a separate computer program. The
  3816. ** original SQL text is source code. A prepared statement object
  3817. ** is the compiled object code. All SQL must be converted into a
  3818. ** prepared statement before it can be run.
  3819. **
  3820. ** The life-cycle of a prepared statement object usually goes like this:
  3821. **
  3822. ** <ol>
  3823. ** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
  3824. ** <li> Bind values to [parameters] using the sqlite3_bind_*()
  3825. ** interfaces.
  3826. ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
  3827. ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
  3828. ** to step 2. Do this zero or more times.
  3829. ** <li> Destroy the object using [sqlite3_finalize()].
  3830. ** </ol>
  3831. */
  3832. typedef struct sqlite3_stmt sqlite3_stmt;
  3833. /*
  3834. ** CAPI3REF: Run-time Limits
  3835. ** METHOD: sqlite3
  3836. **
  3837. ** ^(This interface allows the size of various constructs to be limited
  3838. ** on a connection by connection basis. The first parameter is the
  3839. ** [database connection] whose limit is to be set or queried. The
  3840. ** second parameter is one of the [limit categories] that define a
  3841. ** class of constructs to be size limited. The third parameter is the
  3842. ** new limit for that construct.)^
  3843. **
  3844. ** ^If the new limit is a negative number, the limit is unchanged.
  3845. ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
  3846. ** [limits | hard upper bound]
  3847. ** set at compile-time by a C preprocessor macro called
  3848. ** [limits | SQLITE_MAX_<i>NAME</i>].
  3849. ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
  3850. ** ^Attempts to increase a limit above its hard upper bound are
  3851. ** silently truncated to the hard upper bound.
  3852. **
  3853. ** ^Regardless of whether or not the limit was changed, the
  3854. ** [sqlite3_limit()] interface returns the prior value of the limit.
  3855. ** ^Hence, to find the current value of a limit without changing it,
  3856. ** simply invoke this interface with the third parameter set to -1.
  3857. **
  3858. ** Run-time limits are intended for use in applications that manage
  3859. ** both their own internal database and also databases that are controlled
  3860. ** by untrusted external sources. An example application might be a
  3861. ** web browser that has its own databases for storing history and
  3862. ** separate databases controlled by JavaScript applications downloaded
  3863. ** off the Internet. The internal databases can be given the
  3864. ** large, default limits. Databases managed by external sources can
  3865. ** be given much smaller limits designed to prevent a denial of service
  3866. ** attack. Developers might also want to use the [sqlite3_set_authorizer()]
  3867. ** interface to further control untrusted SQL. The size of the database
  3868. ** created by an untrusted script can be contained using the
  3869. ** [max_page_count] [PRAGMA].
  3870. **
  3871. ** New run-time limit categories may be added in future releases.
  3872. */
  3873. SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
  3874. /*
  3875. ** CAPI3REF: Run-Time Limit Categories
  3876. ** KEYWORDS: {limit category} {*limit categories}
  3877. **
  3878. ** These constants define various performance limits
  3879. ** that can be lowered at run-time using [sqlite3_limit()].
  3880. ** The synopsis of the meanings of the various limits is shown below.
  3881. ** Additional information is available at [limits | Limits in SQLite].
  3882. **
  3883. ** <dl>
  3884. ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
  3885. ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
  3886. **
  3887. ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
  3888. ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
  3889. **
  3890. ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
  3891. ** <dd>The maximum number of columns in a table definition or in the
  3892. ** result set of a [SELECT] or the maximum number of columns in an index
  3893. ** or in an ORDER BY or GROUP BY clause.</dd>)^
  3894. **
  3895. ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
  3896. ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
  3897. **
  3898. ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  3899. ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
  3900. **
  3901. ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
  3902. ** <dd>The maximum number of instructions in a virtual machine program
  3903. ** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
  3904. ** the equivalent tries to allocate space for more than this many opcodes
  3905. ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
  3906. **
  3907. ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  3908. ** <dd>The maximum number of arguments on a function.</dd>)^
  3909. **
  3910. ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
  3911. ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
  3912. **
  3913. ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
  3914. ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
  3915. ** <dd>The maximum length of the pattern argument to the [LIKE] or
  3916. ** [GLOB] operators.</dd>)^
  3917. **
  3918. ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
  3919. ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
  3920. ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
  3921. **
  3922. ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
  3923. ** <dd>The maximum depth of recursion for triggers.</dd>)^
  3924. **
  3925. ** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
  3926. ** <dd>The maximum number of auxiliary worker threads that a single
  3927. ** [prepared statement] may start.</dd>)^
  3928. ** </dl>
  3929. */
  3930. #define SQLITE_LIMIT_LENGTH 0
  3931. #define SQLITE_LIMIT_SQL_LENGTH 1
  3932. #define SQLITE_LIMIT_COLUMN 2
  3933. #define SQLITE_LIMIT_EXPR_DEPTH 3
  3934. #define SQLITE_LIMIT_COMPOUND_SELECT 4
  3935. #define SQLITE_LIMIT_VDBE_OP 5
  3936. #define SQLITE_LIMIT_FUNCTION_ARG 6
  3937. #define SQLITE_LIMIT_ATTACHED 7
  3938. #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
  3939. #define SQLITE_LIMIT_VARIABLE_NUMBER 9
  3940. #define SQLITE_LIMIT_TRIGGER_DEPTH 10
  3941. #define SQLITE_LIMIT_WORKER_THREADS 11
  3942. /*
  3943. ** CAPI3REF: Prepare Flags
  3944. **
  3945. ** These constants define various flags that can be passed into
  3946. ** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
  3947. ** [sqlite3_prepare16_v3()] interfaces.
  3948. **
  3949. ** New flags may be added in future releases of SQLite.
  3950. **
  3951. ** <dl>
  3952. ** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
  3953. ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
  3954. ** that the prepared statement will be retained for a long time and
  3955. ** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
  3956. ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
  3957. ** be used just once or at most a few times and then destroyed using
  3958. ** [sqlite3_finalize()] relatively soon. The current implementation acts
  3959. ** on this hint by avoiding the use of [lookaside memory] so as not to
  3960. ** deplete the limited store of lookaside memory. Future versions of
  3961. ** SQLite may act on this hint differently.
  3962. **
  3963. ** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
  3964. ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
  3965. ** to be required for any prepared statement that wanted to use the
  3966. ** [sqlite3_normalized_sql()] interface. However, the
  3967. ** [sqlite3_normalized_sql()] interface is now available to all
  3968. ** prepared statements, regardless of whether or not they use this
  3969. ** flag.
  3970. **
  3971. ** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
  3972. ** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
  3973. ** to return an error (error code SQLITE_ERROR) if the statement uses
  3974. ** any virtual tables.
  3975. ** </dl>
  3976. */
  3977. #define SQLITE_PREPARE_PERSISTENT 0x01
  3978. #define SQLITE_PREPARE_NORMALIZE 0x02
  3979. #define SQLITE_PREPARE_NO_VTAB 0x04
  3980. /*
  3981. ** CAPI3REF: Compiling An SQL Statement
  3982. ** KEYWORDS: {SQL statement compiler}
  3983. ** METHOD: sqlite3
  3984. ** CONSTRUCTOR: sqlite3_stmt
  3985. **
  3986. ** To execute an SQL statement, it must first be compiled into a byte-code
  3987. ** program using one of these routines. Or, in other words, these routines
  3988. ** are constructors for the [prepared statement] object.
  3989. **
  3990. ** The preferred routine to use is [sqlite3_prepare_v2()]. The
  3991. ** [sqlite3_prepare()] interface is legacy and should be avoided.
  3992. ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
  3993. ** for special purposes.
  3994. **
  3995. ** The use of the UTF-8 interfaces is preferred, as SQLite currently
  3996. ** does all parsing using UTF-8. The UTF-16 interfaces are provided
  3997. ** as a convenience. The UTF-16 interfaces work by converting the
  3998. ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
  3999. **
  4000. ** The first argument, "db", is a [database connection] obtained from a
  4001. ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
  4002. ** [sqlite3_open16()]. The database connection must not have been closed.
  4003. **
  4004. ** The second argument, "zSql", is the statement to be compiled, encoded
  4005. ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
  4006. ** and sqlite3_prepare_v3()
  4007. ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
  4008. ** and sqlite3_prepare16_v3() use UTF-16.
  4009. **
  4010. ** ^If the nByte argument is negative, then zSql is read up to the
  4011. ** first zero terminator. ^If nByte is positive, then it is the
  4012. ** number of bytes read from zSql. ^If nByte is zero, then no prepared
  4013. ** statement is generated.
  4014. ** If the caller knows that the supplied string is nul-terminated, then
  4015. ** there is a small performance advantage to passing an nByte parameter that
  4016. ** is the number of bytes in the input string <i>including</i>
  4017. ** the nul-terminator.
  4018. **
  4019. ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
  4020. ** past the end of the first SQL statement in zSql. These routines only
  4021. ** compile the first statement in zSql, so *pzTail is left pointing to
  4022. ** what remains uncompiled.
  4023. **
  4024. ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
  4025. ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
  4026. ** to NULL. ^If the input text contains no SQL (if the input is an empty
  4027. ** string or a comment) then *ppStmt is set to NULL.
  4028. ** The calling procedure is responsible for deleting the compiled
  4029. ** SQL statement using [sqlite3_finalize()] after it has finished with it.
  4030. ** ppStmt may not be NULL.
  4031. **
  4032. ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
  4033. ** otherwise an [error code] is returned.
  4034. **
  4035. ** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
  4036. ** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
  4037. ** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
  4038. ** are retained for backwards compatibility, but their use is discouraged.
  4039. ** ^In the "vX" interfaces, the prepared statement
  4040. ** that is returned (the [sqlite3_stmt] object) contains a copy of the
  4041. ** original SQL text. This causes the [sqlite3_step()] interface to
  4042. ** behave differently in three ways:
  4043. **
  4044. ** <ol>
  4045. ** <li>
  4046. ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  4047. ** always used to do, [sqlite3_step()] will automatically recompile the SQL
  4048. ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
  4049. ** retries will occur before sqlite3_step() gives up and returns an error.
  4050. ** </li>
  4051. **
  4052. ** <li>
  4053. ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
  4054. ** [error codes] or [extended error codes]. ^The legacy behavior was that
  4055. ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
  4056. ** and the application would have to make a second call to [sqlite3_reset()]
  4057. ** in order to find the underlying cause of the problem. With the "v2" prepare
  4058. ** interfaces, the underlying reason for the error is returned immediately.
  4059. ** </li>
  4060. **
  4061. ** <li>
  4062. ** ^If the specific value bound to a [parameter | host parameter] in the
  4063. ** WHERE clause might influence the choice of query plan for a statement,
  4064. ** then the statement will be automatically recompiled, as if there had been
  4065. ** a schema change, on the first [sqlite3_step()] call following any change
  4066. ** to the [sqlite3_bind_text | bindings] of that [parameter].
  4067. ** ^The specific value of a WHERE-clause [parameter] might influence the
  4068. ** choice of query plan if the parameter is the left-hand side of a [LIKE]
  4069. ** or [GLOB] operator or if the parameter is compared to an indexed column
  4070. ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
  4071. ** </li>
  4072. ** </ol>
  4073. **
  4074. ** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
  4075. ** the extra prepFlags parameter, which is a bit array consisting of zero or
  4076. ** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
  4077. ** sqlite3_prepare_v2() interface works exactly the same as
  4078. ** sqlite3_prepare_v3() with a zero prepFlags parameter.
  4079. */
  4080. SQLITE_API int sqlite3_prepare(
  4081. sqlite3 *db, /* Database handle */
  4082. const char *zSql, /* SQL statement, UTF-8 encoded */
  4083. int nByte, /* Maximum length of zSql in bytes. */
  4084. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4085. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  4086. );
  4087. SQLITE_API int sqlite3_prepare_v2(
  4088. sqlite3 *db, /* Database handle */
  4089. const char *zSql, /* SQL statement, UTF-8 encoded */
  4090. int nByte, /* Maximum length of zSql in bytes. */
  4091. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4092. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  4093. );
  4094. SQLITE_API int sqlite3_prepare_v3(
  4095. sqlite3 *db, /* Database handle */
  4096. const char *zSql, /* SQL statement, UTF-8 encoded */
  4097. int nByte, /* Maximum length of zSql in bytes. */
  4098. unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  4099. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4100. const char **pzTail /* OUT: Pointer to unused portion of zSql */
  4101. );
  4102. SQLITE_API int sqlite3_prepare16(
  4103. sqlite3 *db, /* Database handle */
  4104. const void *zSql, /* SQL statement, UTF-16 encoded */
  4105. int nByte, /* Maximum length of zSql in bytes. */
  4106. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4107. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  4108. );
  4109. SQLITE_API int sqlite3_prepare16_v2(
  4110. sqlite3 *db, /* Database handle */
  4111. const void *zSql, /* SQL statement, UTF-16 encoded */
  4112. int nByte, /* Maximum length of zSql in bytes. */
  4113. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4114. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  4115. );
  4116. SQLITE_API int sqlite3_prepare16_v3(
  4117. sqlite3 *db, /* Database handle */
  4118. const void *zSql, /* SQL statement, UTF-16 encoded */
  4119. int nByte, /* Maximum length of zSql in bytes. */
  4120. unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  4121. sqlite3_stmt **ppStmt, /* OUT: Statement handle */
  4122. const void **pzTail /* OUT: Pointer to unused portion of zSql */
  4123. );
  4124. /*
  4125. ** CAPI3REF: Retrieving Statement SQL
  4126. ** METHOD: sqlite3_stmt
  4127. **
  4128. ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
  4129. ** SQL text used to create [prepared statement] P if P was
  4130. ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
  4131. ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  4132. ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
  4133. ** string containing the SQL text of prepared statement P with
  4134. ** [bound parameters] expanded.
  4135. ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
  4136. ** string containing the normalized SQL text of prepared statement P. The
  4137. ** semantics used to normalize a SQL statement are unspecified and subject
  4138. ** to change. At a minimum, literal values will be replaced with suitable
  4139. ** placeholders.
  4140. **
  4141. ** ^(For example, if a prepared statement is created using the SQL
  4142. ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
  4143. ** and parameter :xyz is unbound, then sqlite3_sql() will return
  4144. ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
  4145. ** will return "SELECT 2345,NULL".)^
  4146. **
  4147. ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
  4148. ** is available to hold the result, or if the result would exceed the
  4149. ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
  4150. **
  4151. ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
  4152. ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
  4153. ** option causes sqlite3_expanded_sql() to always return NULL.
  4154. **
  4155. ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
  4156. ** are managed by SQLite and are automatically freed when the prepared
  4157. ** statement is finalized.
  4158. ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
  4159. ** is obtained from [sqlite3_malloc()] and must be freed by the application
  4160. ** by passing it to [sqlite3_free()].
  4161. **
  4162. ** ^The sqlite3_normalized_sql() interface is only available if
  4163. ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
  4164. */
  4165. SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
  4166. SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
  4167. #ifdef SQLITE_ENABLE_NORMALIZE
  4168. SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
  4169. #endif
  4170. /*
  4171. ** CAPI3REF: Determine If An SQL Statement Writes The Database
  4172. ** METHOD: sqlite3_stmt
  4173. **
  4174. ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
  4175. ** and only if the [prepared statement] X makes no direct changes to
  4176. ** the content of the database file.
  4177. **
  4178. ** Note that [application-defined SQL functions] or
  4179. ** [virtual tables] might change the database indirectly as a side effect.
  4180. ** ^(For example, if an application defines a function "eval()" that
  4181. ** calls [sqlite3_exec()], then the following SQL statement would
  4182. ** change the database file through side-effects:
  4183. **
  4184. ** <blockquote><pre>
  4185. ** SELECT eval('DELETE FROM t1') FROM t2;
  4186. ** </pre></blockquote>
  4187. **
  4188. ** But because the [SELECT] statement does not change the database file
  4189. ** directly, sqlite3_stmt_readonly() would still return true.)^
  4190. **
  4191. ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
  4192. ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
  4193. ** since the statements themselves do not actually modify the database but
  4194. ** rather they control the timing of when other statements modify the
  4195. ** database. ^The [ATTACH] and [DETACH] statements also cause
  4196. ** sqlite3_stmt_readonly() to return true since, while those statements
  4197. ** change the configuration of a database connection, they do not make
  4198. ** changes to the content of the database files on disk.
  4199. ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
  4200. ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
  4201. ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
  4202. ** sqlite3_stmt_readonly() returns false for those commands.
  4203. **
  4204. ** ^This routine returns false if there is any possibility that the
  4205. ** statement might change the database file. ^A false return does
  4206. ** not guarantee that the statement will change the database file.
  4207. ** ^For example, an UPDATE statement might have a WHERE clause that
  4208. ** makes it a no-op, but the sqlite3_stmt_readonly() result would still
  4209. ** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
  4210. ** read-only no-op if the table already exists, but
  4211. ** sqlite3_stmt_readonly() still returns false for such a statement.
  4212. **
  4213. ** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
  4214. ** statement, then sqlite3_stmt_readonly(X) returns the same value as
  4215. ** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
  4216. */
  4217. SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
  4218. /*
  4219. ** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
  4220. ** METHOD: sqlite3_stmt
  4221. **
  4222. ** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
  4223. ** prepared statement S is an EXPLAIN statement, or 2 if the
  4224. ** statement S is an EXPLAIN QUERY PLAN.
  4225. ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
  4226. ** an ordinary statement or a NULL pointer.
  4227. */
  4228. SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
  4229. /*
  4230. ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
  4231. ** METHOD: sqlite3_stmt
  4232. **
  4233. ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
  4234. ** [prepared statement] S has been stepped at least once using
  4235. ** [sqlite3_step(S)] but has neither run to completion (returned
  4236. ** [SQLITE_DONE] from [sqlite3_step(S)]) nor
  4237. ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
  4238. ** interface returns false if S is a NULL pointer. If S is not a
  4239. ** NULL pointer and is not a pointer to a valid [prepared statement]
  4240. ** object, then the behavior is undefined and probably undesirable.
  4241. **
  4242. ** This interface can be used in combination [sqlite3_next_stmt()]
  4243. ** to locate all prepared statements associated with a database
  4244. ** connection that are in need of being reset. This can be used,
  4245. ** for example, in diagnostic routines to search for prepared
  4246. ** statements that are holding a transaction open.
  4247. */
  4248. SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
  4249. /*
  4250. ** CAPI3REF: Dynamically Typed Value Object
  4251. ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  4252. **
  4253. ** SQLite uses the sqlite3_value object to represent all values
  4254. ** that can be stored in a database table. SQLite uses dynamic typing
  4255. ** for the values it stores. ^Values stored in sqlite3_value objects
  4256. ** can be integers, floating point values, strings, BLOBs, or NULL.
  4257. **
  4258. ** An sqlite3_value object may be either "protected" or "unprotected".
  4259. ** Some interfaces require a protected sqlite3_value. Other interfaces
  4260. ** will accept either a protected or an unprotected sqlite3_value.
  4261. ** Every interface that accepts sqlite3_value arguments specifies
  4262. ** whether or not it requires a protected sqlite3_value. The
  4263. ** [sqlite3_value_dup()] interface can be used to construct a new
  4264. ** protected sqlite3_value from an unprotected sqlite3_value.
  4265. **
  4266. ** The terms "protected" and "unprotected" refer to whether or not
  4267. ** a mutex is held. An internal mutex is held for a protected
  4268. ** sqlite3_value object but no mutex is held for an unprotected
  4269. ** sqlite3_value object. If SQLite is compiled to be single-threaded
  4270. ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
  4271. ** or if SQLite is run in one of reduced mutex modes
  4272. ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
  4273. ** then there is no distinction between protected and unprotected
  4274. ** sqlite3_value objects and they can be used interchangeably. However,
  4275. ** for maximum code portability it is recommended that applications
  4276. ** still make the distinction between protected and unprotected
  4277. ** sqlite3_value objects even when not strictly required.
  4278. **
  4279. ** ^The sqlite3_value objects that are passed as parameters into the
  4280. ** implementation of [application-defined SQL functions] are protected.
  4281. ** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()]
  4282. ** are protected.
  4283. ** ^The sqlite3_value object returned by
  4284. ** [sqlite3_column_value()] is unprotected.
  4285. ** Unprotected sqlite3_value objects may only be used as arguments
  4286. ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
  4287. ** [sqlite3_value_dup()].
  4288. ** The [sqlite3_value_blob | sqlite3_value_type()] family of
  4289. ** interfaces require protected sqlite3_value objects.
  4290. */
  4291. typedef struct sqlite3_value sqlite3_value;
  4292. /*
  4293. ** CAPI3REF: SQL Function Context Object
  4294. **
  4295. ** The context in which an SQL function executes is stored in an
  4296. ** sqlite3_context object. ^A pointer to an sqlite3_context object
  4297. ** is always first parameter to [application-defined SQL functions].
  4298. ** The application-defined SQL function implementation will pass this
  4299. ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
  4300. ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
  4301. ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
  4302. ** and/or [sqlite3_set_auxdata()].
  4303. */
  4304. typedef struct sqlite3_context sqlite3_context;
  4305. /*
  4306. ** CAPI3REF: Binding Values To Prepared Statements
  4307. ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
  4308. ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
  4309. ** METHOD: sqlite3_stmt
  4310. **
  4311. ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
  4312. ** literals may be replaced by a [parameter] that matches one of following
  4313. ** templates:
  4314. **
  4315. ** <ul>
  4316. ** <li> ?
  4317. ** <li> ?NNN
  4318. ** <li> :VVV
  4319. ** <li> @VVV
  4320. ** <li> $VVV
  4321. ** </ul>
  4322. **
  4323. ** In the templates above, NNN represents an integer literal,
  4324. ** and VVV represents an alphanumeric identifier.)^ ^The values of these
  4325. ** parameters (also called "host parameter names" or "SQL parameters")
  4326. ** can be set using the sqlite3_bind_*() routines defined here.
  4327. **
  4328. ** ^The first argument to the sqlite3_bind_*() routines is always
  4329. ** a pointer to the [sqlite3_stmt] object returned from
  4330. ** [sqlite3_prepare_v2()] or its variants.
  4331. **
  4332. ** ^The second argument is the index of the SQL parameter to be set.
  4333. ** ^The leftmost SQL parameter has an index of 1. ^When the same named
  4334. ** SQL parameter is used more than once, second and subsequent
  4335. ** occurrences have the same index as the first occurrence.
  4336. ** ^The index for named parameters can be looked up using the
  4337. ** [sqlite3_bind_parameter_index()] API if desired. ^The index
  4338. ** for "?NNN" parameters is the value of NNN.
  4339. ** ^The NNN value must be between 1 and the [sqlite3_limit()]
  4340. ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 32766).
  4341. **
  4342. ** ^The third argument is the value to bind to the parameter.
  4343. ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  4344. ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
  4345. ** is ignored and the end result is the same as sqlite3_bind_null().
  4346. ** ^If the third parameter to sqlite3_bind_text() is not NULL, then
  4347. ** it should be a pointer to well-formed UTF8 text.
  4348. ** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
  4349. ** it should be a pointer to well-formed UTF16 text.
  4350. ** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
  4351. ** it should be a pointer to a well-formed unicode string that is
  4352. ** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
  4353. ** otherwise.
  4354. **
  4355. ** [[byte-order determination rules]] ^The byte-order of
  4356. ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
  4357. ** found in first character, which is removed, or in the absence of a BOM
  4358. ** the byte order is the native byte order of the host
  4359. ** machine for sqlite3_bind_text16() or the byte order specified in
  4360. ** the 6th parameter for sqlite3_bind_text64().)^
  4361. ** ^If UTF16 input text contains invalid unicode
  4362. ** characters, then SQLite might change those invalid characters
  4363. ** into the unicode replacement character: U+FFFD.
  4364. **
  4365. ** ^(In those routines that have a fourth argument, its value is the
  4366. ** number of bytes in the parameter. To be clear: the value is the
  4367. ** number of <u>bytes</u> in the value, not the number of characters.)^
  4368. ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  4369. ** is negative, then the length of the string is
  4370. ** the number of bytes up to the first zero terminator.
  4371. ** If the fourth parameter to sqlite3_bind_blob() is negative, then
  4372. ** the behavior is undefined.
  4373. ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
  4374. ** or sqlite3_bind_text16() or sqlite3_bind_text64() then
  4375. ** that parameter must be the byte offset
  4376. ** where the NUL terminator would occur assuming the string were NUL
  4377. ** terminated. If any NUL characters occurs at byte offsets less than
  4378. ** the value of the fourth parameter then the resulting string value will
  4379. ** contain embedded NULs. The result of expressions involving strings
  4380. ** with embedded NULs is undefined.
  4381. **
  4382. ** ^The fifth argument to the BLOB and string binding interfaces controls
  4383. ** or indicates the lifetime of the object referenced by the third parameter.
  4384. ** These three options exist:
  4385. ** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished
  4386. ** with it may be passed. ^It is called to dispose of the BLOB or string even
  4387. ** if the call to the bind API fails, except the destructor is not called if
  4388. ** the third parameter is a NULL pointer or the fourth parameter is negative.
  4389. ** ^ (2) The special constant, [SQLITE_STATIC], may be passsed to indicate that
  4390. ** the application remains responsible for disposing of the object. ^In this
  4391. ** case, the object and the provided pointer to it must remain valid until
  4392. ** either the prepared statement is finalized or the same SQL parameter is
  4393. ** bound to something else, whichever occurs sooner.
  4394. ** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the
  4395. ** object is to be copied prior to the return from sqlite3_bind_*(). ^The
  4396. ** object and pointer to it must remain valid until then. ^SQLite will then
  4397. ** manage the lifetime of its private copy.
  4398. **
  4399. ** ^The sixth argument to sqlite3_bind_text64() must be one of
  4400. ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
  4401. ** to specify the encoding of the text in the third parameter. If
  4402. ** the sixth argument to sqlite3_bind_text64() is not one of the
  4403. ** allowed values shown above, or if the text encoding is different
  4404. ** from the encoding specified by the sixth parameter, then the behavior
  4405. ** is undefined.
  4406. **
  4407. ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  4408. ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
  4409. ** (just an integer to hold its size) while it is being processed.
  4410. ** Zeroblobs are intended to serve as placeholders for BLOBs whose
  4411. ** content is later written using
  4412. ** [sqlite3_blob_open | incremental BLOB I/O] routines.
  4413. ** ^A negative value for the zeroblob results in a zero-length BLOB.
  4414. **
  4415. ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
  4416. ** [prepared statement] S to have an SQL value of NULL, but to also be
  4417. ** associated with the pointer P of type T. ^D is either a NULL pointer or
  4418. ** a pointer to a destructor function for P. ^SQLite will invoke the
  4419. ** destructor D with a single argument of P when it is finished using
  4420. ** P. The T parameter should be a static string, preferably a string
  4421. ** literal. The sqlite3_bind_pointer() routine is part of the
  4422. ** [pointer passing interface] added for SQLite 3.20.0.
  4423. **
  4424. ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
  4425. ** for the [prepared statement] or with a prepared statement for which
  4426. ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
  4427. ** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
  4428. ** routine is passed a [prepared statement] that has been finalized, the
  4429. ** result is undefined and probably harmful.
  4430. **
  4431. ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
  4432. ** ^Unbound parameters are interpreted as NULL.
  4433. **
  4434. ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
  4435. ** [error code] if anything goes wrong.
  4436. ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
  4437. ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
  4438. ** [SQLITE_MAX_LENGTH].
  4439. ** ^[SQLITE_RANGE] is returned if the parameter
  4440. ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
  4441. **
  4442. ** See also: [sqlite3_bind_parameter_count()],
  4443. ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
  4444. */
  4445. SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  4446. SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
  4447. void(*)(void*));
  4448. SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
  4449. SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
  4450. SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  4451. SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
  4452. SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
  4453. SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  4454. SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
  4455. void(*)(void*), unsigned char encoding);
  4456. SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  4457. SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
  4458. SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  4459. SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
  4460. /*
  4461. ** CAPI3REF: Number Of SQL Parameters
  4462. ** METHOD: sqlite3_stmt
  4463. **
  4464. ** ^This routine can be used to find the number of [SQL parameters]
  4465. ** in a [prepared statement]. SQL parameters are tokens of the
  4466. ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
  4467. ** placeholders for values that are [sqlite3_bind_blob | bound]
  4468. ** to the parameters at a later time.
  4469. **
  4470. ** ^(This routine actually returns the index of the largest (rightmost)
  4471. ** parameter. For all forms except ?NNN, this will correspond to the
  4472. ** number of unique parameters. If parameters of the ?NNN form are used,
  4473. ** there may be gaps in the list.)^
  4474. **
  4475. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  4476. ** [sqlite3_bind_parameter_name()], and
  4477. ** [sqlite3_bind_parameter_index()].
  4478. */
  4479. SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
  4480. /*
  4481. ** CAPI3REF: Name Of A Host Parameter
  4482. ** METHOD: sqlite3_stmt
  4483. **
  4484. ** ^The sqlite3_bind_parameter_name(P,N) interface returns
  4485. ** the name of the N-th [SQL parameter] in the [prepared statement] P.
  4486. ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
  4487. ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
  4488. ** respectively.
  4489. ** In other words, the initial ":" or "$" or "@" or "?"
  4490. ** is included as part of the name.)^
  4491. ** ^Parameters of the form "?" without a following integer have no name
  4492. ** and are referred to as "nameless" or "anonymous parameters".
  4493. **
  4494. ** ^The first host parameter has an index of 1, not 0.
  4495. **
  4496. ** ^If the value N is out of range or if the N-th parameter is
  4497. ** nameless, then NULL is returned. ^The returned string is
  4498. ** always in UTF-8 encoding even if the named parameter was
  4499. ** originally specified as UTF-16 in [sqlite3_prepare16()],
  4500. ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
  4501. **
  4502. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  4503. ** [sqlite3_bind_parameter_count()], and
  4504. ** [sqlite3_bind_parameter_index()].
  4505. */
  4506. SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  4507. /*
  4508. ** CAPI3REF: Index Of A Parameter With A Given Name
  4509. ** METHOD: sqlite3_stmt
  4510. **
  4511. ** ^Return the index of an SQL parameter given its name. ^The
  4512. ** index value returned is suitable for use as the second
  4513. ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
  4514. ** is returned if no matching parameter is found. ^The parameter
  4515. ** name must be given in UTF-8 even if the original statement
  4516. ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
  4517. ** [sqlite3_prepare16_v3()].
  4518. **
  4519. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  4520. ** [sqlite3_bind_parameter_count()], and
  4521. ** [sqlite3_bind_parameter_name()].
  4522. */
  4523. SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  4524. /*
  4525. ** CAPI3REF: Reset All Bindings On A Prepared Statement
  4526. ** METHOD: sqlite3_stmt
  4527. **
  4528. ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
  4529. ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
  4530. ** ^Use this routine to reset all host parameters to NULL.
  4531. */
  4532. SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
  4533. /*
  4534. ** CAPI3REF: Number Of Columns In A Result Set
  4535. ** METHOD: sqlite3_stmt
  4536. **
  4537. ** ^Return the number of columns in the result set returned by the
  4538. ** [prepared statement]. ^If this routine returns 0, that means the
  4539. ** [prepared statement] returns no data (for example an [UPDATE]).
  4540. ** ^However, just because this routine returns a positive number does not
  4541. ** mean that one or more rows of data will be returned. ^A SELECT statement
  4542. ** will always have a positive sqlite3_column_count() but depending on the
  4543. ** WHERE clause constraints and the table content, it might return no rows.
  4544. **
  4545. ** See also: [sqlite3_data_count()]
  4546. */
  4547. SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
  4548. /*
  4549. ** CAPI3REF: Column Names In A Result Set
  4550. ** METHOD: sqlite3_stmt
  4551. **
  4552. ** ^These routines return the name assigned to a particular column
  4553. ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
  4554. ** interface returns a pointer to a zero-terminated UTF-8 string
  4555. ** and sqlite3_column_name16() returns a pointer to a zero-terminated
  4556. ** UTF-16 string. ^The first parameter is the [prepared statement]
  4557. ** that implements the [SELECT] statement. ^The second parameter is the
  4558. ** column number. ^The leftmost column is number 0.
  4559. **
  4560. ** ^The returned string pointer is valid until either the [prepared statement]
  4561. ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
  4562. ** reprepared by the first call to [sqlite3_step()] for a particular run
  4563. ** or until the next call to
  4564. ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
  4565. **
  4566. ** ^If sqlite3_malloc() fails during the processing of either routine
  4567. ** (for example during a conversion from UTF-8 to UTF-16) then a
  4568. ** NULL pointer is returned.
  4569. **
  4570. ** ^The name of a result column is the value of the "AS" clause for
  4571. ** that column, if there is an AS clause. If there is no AS clause
  4572. ** then the name of the column is unspecified and may change from
  4573. ** one release of SQLite to the next.
  4574. */
  4575. SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
  4576. SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  4577. /*
  4578. ** CAPI3REF: Source Of Data In A Query Result
  4579. ** METHOD: sqlite3_stmt
  4580. **
  4581. ** ^These routines provide a means to determine the database, table, and
  4582. ** table column that is the origin of a particular result column in
  4583. ** [SELECT] statement.
  4584. ** ^The name of the database or table or column can be returned as
  4585. ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
  4586. ** the database name, the _table_ routines return the table name, and
  4587. ** the origin_ routines return the column name.
  4588. ** ^The returned string is valid until the [prepared statement] is destroyed
  4589. ** using [sqlite3_finalize()] or until the statement is automatically
  4590. ** reprepared by the first call to [sqlite3_step()] for a particular run
  4591. ** or until the same information is requested
  4592. ** again in a different encoding.
  4593. **
  4594. ** ^The names returned are the original un-aliased names of the
  4595. ** database, table, and column.
  4596. **
  4597. ** ^The first argument to these interfaces is a [prepared statement].
  4598. ** ^These functions return information about the Nth result column returned by
  4599. ** the statement, where N is the second function argument.
  4600. ** ^The left-most column is column 0 for these routines.
  4601. **
  4602. ** ^If the Nth column returned by the statement is an expression or
  4603. ** subquery and is not a column value, then all of these functions return
  4604. ** NULL. ^These routines might also return NULL if a memory allocation error
  4605. ** occurs. ^Otherwise, they return the name of the attached database, table,
  4606. ** or column that query result column was extracted from.
  4607. **
  4608. ** ^As with all other SQLite APIs, those whose names end with "16" return
  4609. ** UTF-16 encoded strings and the other functions return UTF-8.
  4610. **
  4611. ** ^These APIs are only available if the library was compiled with the
  4612. ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
  4613. **
  4614. ** If two or more threads call one or more
  4615. ** [sqlite3_column_database_name | column metadata interfaces]
  4616. ** for the same [prepared statement] and result column
  4617. ** at the same time then the results are undefined.
  4618. */
  4619. SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  4620. SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  4621. SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  4622. SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  4623. SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  4624. SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  4625. /*
  4626. ** CAPI3REF: Declared Datatype Of A Query Result
  4627. ** METHOD: sqlite3_stmt
  4628. **
  4629. ** ^(The first parameter is a [prepared statement].
  4630. ** If this statement is a [SELECT] statement and the Nth column of the
  4631. ** returned result set of that [SELECT] is a table column (not an
  4632. ** expression or subquery) then the declared type of the table
  4633. ** column is returned.)^ ^If the Nth column of the result set is an
  4634. ** expression or subquery, then a NULL pointer is returned.
  4635. ** ^The returned string is always UTF-8 encoded.
  4636. **
  4637. ** ^(For example, given the database schema:
  4638. **
  4639. ** CREATE TABLE t1(c1 VARIANT);
  4640. **
  4641. ** and the following statement to be compiled:
  4642. **
  4643. ** SELECT c1 + 1, c1 FROM t1;
  4644. **
  4645. ** this routine would return the string "VARIANT" for the second result
  4646. ** column (i==1), and a NULL pointer for the first result column (i==0).)^
  4647. **
  4648. ** ^SQLite uses dynamic run-time typing. ^So just because a column
  4649. ** is declared to contain a particular type does not mean that the
  4650. ** data stored in that column is of the declared type. SQLite is
  4651. ** strongly typed, but the typing is dynamic not static. ^Type
  4652. ** is associated with individual values, not with the containers
  4653. ** used to hold those values.
  4654. */
  4655. SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  4656. SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  4657. /*
  4658. ** CAPI3REF: Evaluate An SQL Statement
  4659. ** METHOD: sqlite3_stmt
  4660. **
  4661. ** After a [prepared statement] has been prepared using any of
  4662. ** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
  4663. ** or [sqlite3_prepare16_v3()] or one of the legacy
  4664. ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
  4665. ** must be called one or more times to evaluate the statement.
  4666. **
  4667. ** The details of the behavior of the sqlite3_step() interface depend
  4668. ** on whether the statement was prepared using the newer "vX" interfaces
  4669. ** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
  4670. ** [sqlite3_prepare16_v2()] or the older legacy
  4671. ** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
  4672. ** new "vX" interface is recommended for new applications but the legacy
  4673. ** interface will continue to be supported.
  4674. **
  4675. ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
  4676. ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  4677. ** ^With the "v2" interface, any of the other [result codes] or
  4678. ** [extended result codes] might be returned as well.
  4679. **
  4680. ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
  4681. ** database locks it needs to do its job. ^If the statement is a [COMMIT]
  4682. ** or occurs outside of an explicit transaction, then you can retry the
  4683. ** statement. If the statement is not a [COMMIT] and occurs within an
  4684. ** explicit transaction then you should rollback the transaction before
  4685. ** continuing.
  4686. **
  4687. ** ^[SQLITE_DONE] means that the statement has finished executing
  4688. ** successfully. sqlite3_step() should not be called again on this virtual
  4689. ** machine without first calling [sqlite3_reset()] to reset the virtual
  4690. ** machine back to its initial state.
  4691. **
  4692. ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
  4693. ** is returned each time a new row of data is ready for processing by the
  4694. ** caller. The values may be accessed using the [column access functions].
  4695. ** sqlite3_step() is called again to retrieve the next row of data.
  4696. **
  4697. ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
  4698. ** violation) has occurred. sqlite3_step() should not be called again on
  4699. ** the VM. More information may be found by calling [sqlite3_errmsg()].
  4700. ** ^With the legacy interface, a more specific error code (for example,
  4701. ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  4702. ** can be obtained by calling [sqlite3_reset()] on the
  4703. ** [prepared statement]. ^In the "v2" interface,
  4704. ** the more specific error code is returned directly by sqlite3_step().
  4705. **
  4706. ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  4707. ** Perhaps it was called on a [prepared statement] that has
  4708. ** already been [sqlite3_finalize | finalized] or on one that had
  4709. ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
  4710. ** be the case that the same database connection is being used by two or
  4711. ** more threads at the same moment in time.
  4712. **
  4713. ** For all versions of SQLite up to and including 3.6.23.1, a call to
  4714. ** [sqlite3_reset()] was required after sqlite3_step() returned anything
  4715. ** other than [SQLITE_ROW] before any subsequent invocation of
  4716. ** sqlite3_step(). Failure to reset the prepared statement using
  4717. ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
  4718. ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
  4719. ** sqlite3_step() began
  4720. ** calling [sqlite3_reset()] automatically in this circumstance rather
  4721. ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
  4722. ** break because any application that ever receives an SQLITE_MISUSE error
  4723. ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
  4724. ** can be used to restore the legacy behavior.
  4725. **
  4726. ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
  4727. ** API always returns a generic error code, [SQLITE_ERROR], following any
  4728. ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
  4729. ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
  4730. ** specific [error codes] that better describes the error.
  4731. ** We admit that this is a goofy design. The problem has been fixed
  4732. ** with the "v2" interface. If you prepare all of your SQL statements
  4733. ** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
  4734. ** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
  4735. ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
  4736. ** then the more specific [error codes] are returned directly
  4737. ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
  4738. */
  4739. SQLITE_API int sqlite3_step(sqlite3_stmt*);
  4740. /*
  4741. ** CAPI3REF: Number of columns in a result set
  4742. ** METHOD: sqlite3_stmt
  4743. **
  4744. ** ^The sqlite3_data_count(P) interface returns the number of columns in the
  4745. ** current row of the result set of [prepared statement] P.
  4746. ** ^If prepared statement P does not have results ready to return
  4747. ** (via calls to the [sqlite3_column_int | sqlite3_column()] family of
  4748. ** interfaces) then sqlite3_data_count(P) returns 0.
  4749. ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
  4750. ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
  4751. ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
  4752. ** will return non-zero if previous call to [sqlite3_step](P) returned
  4753. ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
  4754. ** where it always returns zero since each step of that multi-step
  4755. ** pragma returns 0 columns of data.
  4756. **
  4757. ** See also: [sqlite3_column_count()]
  4758. */
  4759. SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
  4760. /*
  4761. ** CAPI3REF: Fundamental Datatypes
  4762. ** KEYWORDS: SQLITE_TEXT
  4763. **
  4764. ** ^(Every value in SQLite has one of five fundamental datatypes:
  4765. **
  4766. ** <ul>
  4767. ** <li> 64-bit signed integer
  4768. ** <li> 64-bit IEEE floating point number
  4769. ** <li> string
  4770. ** <li> BLOB
  4771. ** <li> NULL
  4772. ** </ul>)^
  4773. **
  4774. ** These constants are codes for each of those types.
  4775. **
  4776. ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
  4777. ** for a completely different meaning. Software that links against both
  4778. ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
  4779. ** SQLITE_TEXT.
  4780. */
  4781. #define SQLITE_INTEGER 1
  4782. #define SQLITE_FLOAT 2
  4783. #define SQLITE_BLOB 4
  4784. #define SQLITE_NULL 5
  4785. #ifdef SQLITE_TEXT
  4786. # undef SQLITE_TEXT
  4787. #else
  4788. # define SQLITE_TEXT 3
  4789. #endif
  4790. #define SQLITE3_TEXT 3
  4791. /*
  4792. ** CAPI3REF: Result Values From A Query
  4793. ** KEYWORDS: {column access functions}
  4794. ** METHOD: sqlite3_stmt
  4795. **
  4796. ** <b>Summary:</b>
  4797. ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
  4798. ** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
  4799. ** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
  4800. ** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
  4801. ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
  4802. ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
  4803. ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
  4804. ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
  4805. ** [sqlite3_value|unprotected sqlite3_value] object.
  4806. ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
  4807. ** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
  4808. ** or a UTF-8 TEXT result in bytes
  4809. ** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
  4810. ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
  4811. ** TEXT in bytes
  4812. ** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
  4813. ** datatype of the result
  4814. ** </table></blockquote>
  4815. **
  4816. ** <b>Details:</b>
  4817. **
  4818. ** ^These routines return information about a single column of the current
  4819. ** result row of a query. ^In every case the first argument is a pointer
  4820. ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  4821. ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  4822. ** and the second argument is the index of the column for which information
  4823. ** should be returned. ^The leftmost column of the result set has the index 0.
  4824. ** ^The number of columns in the result can be determined using
  4825. ** [sqlite3_column_count()].
  4826. **
  4827. ** If the SQL statement does not currently point to a valid row, or if the
  4828. ** column index is out of range, the result is undefined.
  4829. ** These routines may only be called when the most recent call to
  4830. ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
  4831. ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
  4832. ** If any of these routines are called after [sqlite3_reset()] or
  4833. ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  4834. ** something other than [SQLITE_ROW], the results are undefined.
  4835. ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  4836. ** are called from a different thread while any of these routines
  4837. ** are pending, then the results are undefined.
  4838. **
  4839. ** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
  4840. ** each return the value of a result column in a specific data format. If
  4841. ** the result column is not initially in the requested format (for example,
  4842. ** if the query returns an integer but the sqlite3_column_text() interface
  4843. ** is used to extract the value) then an automatic type conversion is performed.
  4844. **
  4845. ** ^The sqlite3_column_type() routine returns the
  4846. ** [SQLITE_INTEGER | datatype code] for the initial data type
  4847. ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
  4848. ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
  4849. ** The return value of sqlite3_column_type() can be used to decide which
  4850. ** of the first six interface should be used to extract the column value.
  4851. ** The value returned by sqlite3_column_type() is only meaningful if no
  4852. ** automatic type conversions have occurred for the value in question.
  4853. ** After a type conversion, the result of calling sqlite3_column_type()
  4854. ** is undefined, though harmless. Future
  4855. ** versions of SQLite may change the behavior of sqlite3_column_type()
  4856. ** following a type conversion.
  4857. **
  4858. ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
  4859. ** or sqlite3_column_bytes16() interfaces can be used to determine the size
  4860. ** of that BLOB or string.
  4861. **
  4862. ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
  4863. ** routine returns the number of bytes in that BLOB or string.
  4864. ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  4865. ** the string to UTF-8 and then returns the number of bytes.
  4866. ** ^If the result is a numeric value then sqlite3_column_bytes() uses
  4867. ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  4868. ** the number of bytes in that string.
  4869. ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
  4870. **
  4871. ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
  4872. ** routine returns the number of bytes in that BLOB or string.
  4873. ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
  4874. ** the string to UTF-16 and then returns the number of bytes.
  4875. ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
  4876. ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
  4877. ** the number of bytes in that string.
  4878. ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
  4879. **
  4880. ** ^The values returned by [sqlite3_column_bytes()] and
  4881. ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
  4882. ** of the string. ^For clarity: the values returned by
  4883. ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
  4884. ** bytes in the string, not the number of characters.
  4885. **
  4886. ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  4887. ** even empty strings, are always zero-terminated. ^The return
  4888. ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
  4889. **
  4890. ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
  4891. ** [unprotected sqlite3_value] object. In a multithreaded environment,
  4892. ** an unprotected sqlite3_value object may only be used safely with
  4893. ** [sqlite3_bind_value()] and [sqlite3_result_value()].
  4894. ** If the [unprotected sqlite3_value] object returned by
  4895. ** [sqlite3_column_value()] is used in any other way, including calls
  4896. ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  4897. ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
  4898. ** Hence, the sqlite3_column_value() interface
  4899. ** is normally only useful within the implementation of
  4900. ** [application-defined SQL functions] or [virtual tables], not within
  4901. ** top-level application code.
  4902. **
  4903. ** The these routines may attempt to convert the datatype of the result.
  4904. ** ^For example, if the internal representation is FLOAT and a text result
  4905. ** is requested, [sqlite3_snprintf()] is used internally to perform the
  4906. ** conversion automatically. ^(The following table details the conversions
  4907. ** that are applied:
  4908. **
  4909. ** <blockquote>
  4910. ** <table border="1">
  4911. ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
  4912. **
  4913. ** <tr><td> NULL <td> INTEGER <td> Result is 0
  4914. ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
  4915. ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
  4916. ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
  4917. ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
  4918. ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
  4919. ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
  4920. ** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
  4921. ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
  4922. ** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
  4923. ** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
  4924. ** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
  4925. ** <tr><td> TEXT <td> BLOB <td> No change
  4926. ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
  4927. ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
  4928. ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
  4929. ** </table>
  4930. ** </blockquote>)^
  4931. **
  4932. ** Note that when type conversions occur, pointers returned by prior
  4933. ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  4934. ** sqlite3_column_text16() may be invalidated.
  4935. ** Type conversions and pointer invalidations might occur
  4936. ** in the following cases:
  4937. **
  4938. ** <ul>
  4939. ** <li> The initial content is a BLOB and sqlite3_column_text() or
  4940. ** sqlite3_column_text16() is called. A zero-terminator might
  4941. ** need to be added to the string.</li>
  4942. ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
  4943. ** sqlite3_column_text16() is called. The content must be converted
  4944. ** to UTF-16.</li>
  4945. ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
  4946. ** sqlite3_column_text() is called. The content must be converted
  4947. ** to UTF-8.</li>
  4948. ** </ul>
  4949. **
  4950. ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
  4951. ** not invalidate a prior pointer, though of course the content of the buffer
  4952. ** that the prior pointer references will have been modified. Other kinds
  4953. ** of conversion are done in place when it is possible, but sometimes they
  4954. ** are not possible and in those cases prior pointers are invalidated.
  4955. **
  4956. ** The safest policy is to invoke these routines
  4957. ** in one of the following ways:
  4958. **
  4959. ** <ul>
  4960. ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  4961. ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  4962. ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  4963. ** </ul>
  4964. **
  4965. ** In other words, you should call sqlite3_column_text(),
  4966. ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
  4967. ** into the desired format, then invoke sqlite3_column_bytes() or
  4968. ** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
  4969. ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  4970. ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  4971. ** with calls to sqlite3_column_bytes().
  4972. **
  4973. ** ^The pointers returned are valid until a type conversion occurs as
  4974. ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  4975. ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
  4976. ** and BLOBs is freed automatically. Do not pass the pointers returned
  4977. ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  4978. ** [sqlite3_free()].
  4979. **
  4980. ** As long as the input parameters are correct, these routines will only
  4981. ** fail if an out-of-memory error occurs during a format conversion.
  4982. ** Only the following subset of interfaces are subject to out-of-memory
  4983. ** errors:
  4984. **
  4985. ** <ul>
  4986. ** <li> sqlite3_column_blob()
  4987. ** <li> sqlite3_column_text()
  4988. ** <li> sqlite3_column_text16()
  4989. ** <li> sqlite3_column_bytes()
  4990. ** <li> sqlite3_column_bytes16()
  4991. ** </ul>
  4992. **
  4993. ** If an out-of-memory error occurs, then the return value from these
  4994. ** routines is the same as if the column had contained an SQL NULL value.
  4995. ** Valid SQL NULL returns can be distinguished from out-of-memory errors
  4996. ** by invoking the [sqlite3_errcode()] immediately after the suspect
  4997. ** return value is obtained and before any
  4998. ** other SQLite interface is called on the same [database connection].
  4999. */
  5000. SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  5001. SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
  5002. SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
  5003. SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  5004. SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  5005. SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  5006. SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  5007. SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  5008. SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  5009. SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  5010. /*
  5011. ** CAPI3REF: Destroy A Prepared Statement Object
  5012. ** DESTRUCTOR: sqlite3_stmt
  5013. **
  5014. ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
  5015. ** ^If the most recent evaluation of the statement encountered no errors
  5016. ** or if the statement is never been evaluated, then sqlite3_finalize() returns
  5017. ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
  5018. ** sqlite3_finalize(S) returns the appropriate [error code] or
  5019. ** [extended error code].
  5020. **
  5021. ** ^The sqlite3_finalize(S) routine can be called at any point during
  5022. ** the life cycle of [prepared statement] S:
  5023. ** before statement S is ever evaluated, after
  5024. ** one or more calls to [sqlite3_reset()], or after any call
  5025. ** to [sqlite3_step()] regardless of whether or not the statement has
  5026. ** completed execution.
  5027. **
  5028. ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
  5029. **
  5030. ** The application must finalize every [prepared statement] in order to avoid
  5031. ** resource leaks. It is a grievous error for the application to try to use
  5032. ** a prepared statement after it has been finalized. Any use of a prepared
  5033. ** statement after it has been finalized can result in undefined and
  5034. ** undesirable behavior such as segfaults and heap corruption.
  5035. */
  5036. SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
  5037. /*
  5038. ** CAPI3REF: Reset A Prepared Statement Object
  5039. ** METHOD: sqlite3_stmt
  5040. **
  5041. ** The sqlite3_reset() function is called to reset a [prepared statement]
  5042. ** object back to its initial state, ready to be re-executed.
  5043. ** ^Any SQL statement variables that had values bound to them using
  5044. ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  5045. ** Use [sqlite3_clear_bindings()] to reset the bindings.
  5046. **
  5047. ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
  5048. ** back to the beginning of its program.
  5049. **
  5050. ** ^If the most recent call to [sqlite3_step(S)] for the
  5051. ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
  5052. ** or if [sqlite3_step(S)] has never before been called on S,
  5053. ** then [sqlite3_reset(S)] returns [SQLITE_OK].
  5054. **
  5055. ** ^If the most recent call to [sqlite3_step(S)] for the
  5056. ** [prepared statement] S indicated an error, then
  5057. ** [sqlite3_reset(S)] returns an appropriate [error code].
  5058. **
  5059. ** ^The [sqlite3_reset(S)] interface does not change the values
  5060. ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
  5061. */
  5062. SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
  5063. /*
  5064. ** CAPI3REF: Create Or Redefine SQL Functions
  5065. ** KEYWORDS: {function creation routines}
  5066. ** METHOD: sqlite3
  5067. **
  5068. ** ^These functions (collectively known as "function creation routines")
  5069. ** are used to add SQL functions or aggregates or to redefine the behavior
  5070. ** of existing SQL functions or aggregates. The only differences between
  5071. ** the three "sqlite3_create_function*" routines are the text encoding
  5072. ** expected for the second parameter (the name of the function being
  5073. ** created) and the presence or absence of a destructor callback for
  5074. ** the application data pointer. Function sqlite3_create_window_function()
  5075. ** is similar, but allows the user to supply the extra callback functions
  5076. ** needed by [aggregate window functions].
  5077. **
  5078. ** ^The first parameter is the [database connection] to which the SQL
  5079. ** function is to be added. ^If an application uses more than one database
  5080. ** connection then application-defined SQL functions must be added
  5081. ** to each database connection separately.
  5082. **
  5083. ** ^The second parameter is the name of the SQL function to be created or
  5084. ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
  5085. ** representation, exclusive of the zero-terminator. ^Note that the name
  5086. ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
  5087. ** ^Any attempt to create a function with a longer name
  5088. ** will result in [SQLITE_MISUSE] being returned.
  5089. **
  5090. ** ^The third parameter (nArg)
  5091. ** is the number of arguments that the SQL function or
  5092. ** aggregate takes. ^If this parameter is -1, then the SQL function or
  5093. ** aggregate may take any number of arguments between 0 and the limit
  5094. ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
  5095. ** parameter is less than -1 or greater than 127 then the behavior is
  5096. ** undefined.
  5097. **
  5098. ** ^The fourth parameter, eTextRep, specifies what
  5099. ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  5100. ** its parameters. The application should set this parameter to
  5101. ** [SQLITE_UTF16LE] if the function implementation invokes
  5102. ** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
  5103. ** implementation invokes [sqlite3_value_text16be()] on an input, or
  5104. ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
  5105. ** otherwise. ^The same SQL function may be registered multiple times using
  5106. ** different preferred text encodings, with different implementations for
  5107. ** each encoding.
  5108. ** ^When multiple implementations of the same function are available, SQLite
  5109. ** will pick the one that involves the least amount of data conversion.
  5110. **
  5111. ** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
  5112. ** to signal that the function will always return the same result given
  5113. ** the same inputs within a single SQL statement. Most SQL functions are
  5114. ** deterministic. The built-in [random()] SQL function is an example of a
  5115. ** function that is not deterministic. The SQLite query planner is able to
  5116. ** perform additional optimizations on deterministic functions, so use
  5117. ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
  5118. **
  5119. ** ^The fourth parameter may also optionally include the [SQLITE_DIRECTONLY]
  5120. ** flag, which if present prevents the function from being invoked from
  5121. ** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
  5122. ** index expressions, or the WHERE clause of partial indexes.
  5123. **
  5124. ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
  5125. ** all application-defined SQL functions that do not need to be
  5126. ** used inside of triggers, view, CHECK constraints, or other elements of
  5127. ** the database schema. This flags is especially recommended for SQL
  5128. ** functions that have side effects or reveal internal application state.
  5129. ** Without this flag, an attacker might be able to modify the schema of
  5130. ** a database file to include invocations of the function with parameters
  5131. ** chosen by the attacker, which the application will then execute when
  5132. ** the database file is opened and read.
  5133. **
  5134. ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
  5135. ** function can gain access to this pointer using [sqlite3_user_data()].)^
  5136. **
  5137. ** ^The sixth, seventh and eighth parameters passed to the three
  5138. ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
  5139. ** pointers to C-language functions that implement the SQL function or
  5140. ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
  5141. ** callback only; NULL pointers must be passed as the xStep and xFinal
  5142. ** parameters. ^An aggregate SQL function requires an implementation of xStep
  5143. ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
  5144. ** SQL function or aggregate, pass NULL pointers for all three function
  5145. ** callbacks.
  5146. **
  5147. ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
  5148. ** and xInverse) passed to sqlite3_create_window_function are pointers to
  5149. ** C-language callbacks that implement the new function. xStep and xFinal
  5150. ** must both be non-NULL. xValue and xInverse may either both be NULL, in
  5151. ** which case a regular aggregate function is created, or must both be
  5152. ** non-NULL, in which case the new function may be used as either an aggregate
  5153. ** or aggregate window function. More details regarding the implementation
  5154. ** of aggregate window functions are
  5155. ** [user-defined window functions|available here].
  5156. **
  5157. ** ^(If the final parameter to sqlite3_create_function_v2() or
  5158. ** sqlite3_create_window_function() is not NULL, then it is destructor for
  5159. ** the application data pointer. The destructor is invoked when the function
  5160. ** is deleted, either by being overloaded or when the database connection
  5161. ** closes.)^ ^The destructor is also invoked if the call to
  5162. ** sqlite3_create_function_v2() fails. ^When the destructor callback is
  5163. ** invoked, it is passed a single argument which is a copy of the application
  5164. ** data pointer which was the fifth parameter to sqlite3_create_function_v2().
  5165. **
  5166. ** ^It is permitted to register multiple implementations of the same
  5167. ** functions with the same name but with either differing numbers of
  5168. ** arguments or differing preferred text encodings. ^SQLite will use
  5169. ** the implementation that most closely matches the way in which the
  5170. ** SQL function is used. ^A function implementation with a non-negative
  5171. ** nArg parameter is a better match than a function implementation with
  5172. ** a negative nArg. ^A function where the preferred text encoding
  5173. ** matches the database encoding is a better
  5174. ** match than a function where the encoding is different.
  5175. ** ^A function where the encoding difference is between UTF16le and UTF16be
  5176. ** is a closer match than a function where the encoding difference is
  5177. ** between UTF8 and UTF16.
  5178. **
  5179. ** ^Built-in functions may be overloaded by new application-defined functions.
  5180. **
  5181. ** ^An application-defined function is permitted to call other
  5182. ** SQLite interfaces. However, such calls must not
  5183. ** close the database connection nor finalize or reset the prepared
  5184. ** statement in which the function is running.
  5185. */
  5186. SQLITE_API int sqlite3_create_function(
  5187. sqlite3 *db,
  5188. const char *zFunctionName,
  5189. int nArg,
  5190. int eTextRep,
  5191. void *pApp,
  5192. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  5193. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  5194. void (*xFinal)(sqlite3_context*)
  5195. );
  5196. SQLITE_API int sqlite3_create_function16(
  5197. sqlite3 *db,
  5198. const void *zFunctionName,
  5199. int nArg,
  5200. int eTextRep,
  5201. void *pApp,
  5202. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  5203. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  5204. void (*xFinal)(sqlite3_context*)
  5205. );
  5206. SQLITE_API int sqlite3_create_function_v2(
  5207. sqlite3 *db,
  5208. const char *zFunctionName,
  5209. int nArg,
  5210. int eTextRep,
  5211. void *pApp,
  5212. void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  5213. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  5214. void (*xFinal)(sqlite3_context*),
  5215. void(*xDestroy)(void*)
  5216. );
  5217. SQLITE_API int sqlite3_create_window_function(
  5218. sqlite3 *db,
  5219. const char *zFunctionName,
  5220. int nArg,
  5221. int eTextRep,
  5222. void *pApp,
  5223. void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  5224. void (*xFinal)(sqlite3_context*),
  5225. void (*xValue)(sqlite3_context*),
  5226. void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
  5227. void(*xDestroy)(void*)
  5228. );
  5229. /*
  5230. ** CAPI3REF: Text Encodings
  5231. **
  5232. ** These constant define integer codes that represent the various
  5233. ** text encodings supported by SQLite.
  5234. */
  5235. #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
  5236. #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
  5237. #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
  5238. #define SQLITE_UTF16 4 /* Use native byte order */
  5239. #define SQLITE_ANY 5 /* Deprecated */
  5240. #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
  5241. /*
  5242. ** CAPI3REF: Function Flags
  5243. **
  5244. ** These constants may be ORed together with the
  5245. ** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
  5246. ** to [sqlite3_create_function()], [sqlite3_create_function16()], or
  5247. ** [sqlite3_create_function_v2()].
  5248. **
  5249. ** <dl>
  5250. ** [[SQLITE_DETERMINISTIC]] <dt>SQLITE_DETERMINISTIC</dt><dd>
  5251. ** The SQLITE_DETERMINISTIC flag means that the new function always gives
  5252. ** the same output when the input parameters are the same.
  5253. ** The [abs|abs() function] is deterministic, for example, but
  5254. ** [randomblob|randomblob()] is not. Functions must
  5255. ** be deterministic in order to be used in certain contexts such as
  5256. ** with the WHERE clause of [partial indexes] or in [generated columns].
  5257. ** SQLite might also optimize deterministic functions by factoring them
  5258. ** out of inner loops.
  5259. ** </dd>
  5260. **
  5261. ** [[SQLITE_DIRECTONLY]] <dt>SQLITE_DIRECTONLY</dt><dd>
  5262. ** The SQLITE_DIRECTONLY flag means that the function may only be invoked
  5263. ** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
  5264. ** schema structures such as [CHECK constraints], [DEFAULT clauses],
  5265. ** [expression indexes], [partial indexes], or [generated columns].
  5266. ** The SQLITE_DIRECTONLY flags is a security feature which is recommended
  5267. ** for all [application-defined SQL functions], and especially for functions
  5268. ** that have side-effects or that could potentially leak sensitive
  5269. ** information.
  5270. ** </dd>
  5271. **
  5272. ** [[SQLITE_INNOCUOUS]] <dt>SQLITE_INNOCUOUS</dt><dd>
  5273. ** The SQLITE_INNOCUOUS flag means that the function is unlikely
  5274. ** to cause problems even if misused. An innocuous function should have
  5275. ** no side effects and should not depend on any values other than its
  5276. ** input parameters. The [abs|abs() function] is an example of an
  5277. ** innocuous function.
  5278. ** The [load_extension() SQL function] is not innocuous because of its
  5279. ** side effects.
  5280. ** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
  5281. ** exactly the same. The [random|random() function] is an example of a
  5282. ** function that is innocuous but not deterministic.
  5283. ** <p>Some heightened security settings
  5284. ** ([SQLITE_DBCONFIG_TRUSTED_SCHEMA] and [PRAGMA trusted_schema=OFF])
  5285. ** disable the use of SQL functions inside views and triggers and in
  5286. ** schema structures such as [CHECK constraints], [DEFAULT clauses],
  5287. ** [expression indexes], [partial indexes], and [generated columns] unless
  5288. ** the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
  5289. ** are innocuous. Developers are advised to avoid using the
  5290. ** SQLITE_INNOCUOUS flag for application-defined functions unless the
  5291. ** function has been carefully audited and found to be free of potentially
  5292. ** security-adverse side-effects and information-leaks.
  5293. ** </dd>
  5294. **
  5295. ** [[SQLITE_SUBTYPE]] <dt>SQLITE_SUBTYPE</dt><dd>
  5296. ** The SQLITE_SUBTYPE flag indicates to SQLite that a function may call
  5297. ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
  5298. ** Specifying this flag makes no difference for scalar or aggregate user
  5299. ** functions. However, if it is not specified for a user-defined window
  5300. ** function, then any sub-types belonging to arguments passed to the window
  5301. ** function may be discarded before the window function is called (i.e.
  5302. ** sqlite3_value_subtype() will always return 0).
  5303. ** </dd>
  5304. ** </dl>
  5305. */
  5306. #define SQLITE_DETERMINISTIC 0x000000800
  5307. #define SQLITE_DIRECTONLY 0x000080000
  5308. #define SQLITE_SUBTYPE 0x000100000
  5309. #define SQLITE_INNOCUOUS 0x000200000
  5310. /*
  5311. ** CAPI3REF: Deprecated Functions
  5312. ** DEPRECATED
  5313. **
  5314. ** These functions are [deprecated]. In order to maintain
  5315. ** backwards compatibility with older code, these functions continue
  5316. ** to be supported. However, new applications should avoid
  5317. ** the use of these functions. To encourage programmers to avoid
  5318. ** these functions, we will not explain what they do.
  5319. */
  5320. #ifndef SQLITE_OMIT_DEPRECATED
  5321. SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
  5322. SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
  5323. SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  5324. SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
  5325. SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
  5326. SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
  5327. void*,sqlite3_int64);
  5328. #endif
  5329. /*
  5330. ** CAPI3REF: Obtaining SQL Values
  5331. ** METHOD: sqlite3_value
  5332. **
  5333. ** <b>Summary:</b>
  5334. ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
  5335. ** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
  5336. ** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
  5337. ** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
  5338. ** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
  5339. ** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
  5340. ** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
  5341. ** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
  5342. ** the native byteorder
  5343. ** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
  5344. ** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
  5345. ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
  5346. ** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
  5347. ** or a UTF-8 TEXT in bytes
  5348. ** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
  5349. ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
  5350. ** TEXT in bytes
  5351. ** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
  5352. ** datatype of the value
  5353. ** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
  5354. ** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
  5355. ** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
  5356. ** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
  5357. ** against a virtual table.
  5358. ** <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>
  5359. ** <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a [bound parameter]
  5360. ** </table></blockquote>
  5361. **
  5362. ** <b>Details:</b>
  5363. **
  5364. ** These routines extract type, size, and content information from
  5365. ** [protected sqlite3_value] objects. Protected sqlite3_value objects
  5366. ** are used to pass parameter information into the functions that
  5367. ** implement [application-defined SQL functions] and [virtual tables].
  5368. **
  5369. ** These routines work only with [protected sqlite3_value] objects.
  5370. ** Any attempt to use these routines on an [unprotected sqlite3_value]
  5371. ** is not threadsafe.
  5372. **
  5373. ** ^These routines work just like the corresponding [column access functions]
  5374. ** except that these routines take a single [protected sqlite3_value] object
  5375. ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
  5376. **
  5377. ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
  5378. ** in the native byte-order of the host machine. ^The
  5379. ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  5380. ** extract UTF-16 strings as big-endian and little-endian respectively.
  5381. **
  5382. ** ^If [sqlite3_value] object V was initialized
  5383. ** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
  5384. ** and if X and Y are strings that compare equal according to strcmp(X,Y),
  5385. ** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,
  5386. ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
  5387. ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
  5388. **
  5389. ** ^(The sqlite3_value_type(V) interface returns the
  5390. ** [SQLITE_INTEGER | datatype code] for the initial datatype of the
  5391. ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
  5392. ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
  5393. ** Other interfaces might change the datatype for an sqlite3_value object.
  5394. ** For example, if the datatype is initially SQLITE_INTEGER and
  5395. ** sqlite3_value_text(V) is called to extract a text value for that
  5396. ** integer, then subsequent calls to sqlite3_value_type(V) might return
  5397. ** SQLITE_TEXT. Whether or not a persistent internal datatype conversion
  5398. ** occurs is undefined and may change from one release of SQLite to the next.
  5399. **
  5400. ** ^(The sqlite3_value_numeric_type() interface attempts to apply
  5401. ** numeric affinity to the value. This means that an attempt is
  5402. ** made to convert the value to an integer or floating point. If
  5403. ** such a conversion is possible without loss of information (in other
  5404. ** words, if the value is a string that looks like a number)
  5405. ** then the conversion is performed. Otherwise no conversion occurs.
  5406. ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
  5407. **
  5408. ** ^Within the [xUpdate] method of a [virtual table], the
  5409. ** sqlite3_value_nochange(X) interface returns true if and only if
  5410. ** the column corresponding to X is unchanged by the UPDATE operation
  5411. ** that the xUpdate method call was invoked to implement and if
  5412. ** and the prior [xColumn] method call that was invoked to extracted
  5413. ** the value for that column returned without setting a result (probably
  5414. ** because it queried [sqlite3_vtab_nochange()] and found that the column
  5415. ** was unchanging). ^Within an [xUpdate] method, any value for which
  5416. ** sqlite3_value_nochange(X) is true will in all other respects appear
  5417. ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
  5418. ** than within an [xUpdate] method call for an UPDATE statement, then
  5419. ** the return value is arbitrary and meaningless.
  5420. **
  5421. ** ^The sqlite3_value_frombind(X) interface returns non-zero if the
  5422. ** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()]
  5423. ** interfaces. ^If X comes from an SQL literal value, or a table column,
  5424. ** or an expression, then sqlite3_value_frombind(X) returns zero.
  5425. **
  5426. ** Please pay particular attention to the fact that the pointer returned
  5427. ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  5428. ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  5429. ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  5430. ** or [sqlite3_value_text16()].
  5431. **
  5432. ** These routines must be called from the same thread as
  5433. ** the SQL function that supplied the [sqlite3_value*] parameters.
  5434. **
  5435. ** As long as the input parameter is correct, these routines can only
  5436. ** fail if an out-of-memory error occurs during a format conversion.
  5437. ** Only the following subset of interfaces are subject to out-of-memory
  5438. ** errors:
  5439. **
  5440. ** <ul>
  5441. ** <li> sqlite3_value_blob()
  5442. ** <li> sqlite3_value_text()
  5443. ** <li> sqlite3_value_text16()
  5444. ** <li> sqlite3_value_text16le()
  5445. ** <li> sqlite3_value_text16be()
  5446. ** <li> sqlite3_value_bytes()
  5447. ** <li> sqlite3_value_bytes16()
  5448. ** </ul>
  5449. **
  5450. ** If an out-of-memory error occurs, then the return value from these
  5451. ** routines is the same as if the column had contained an SQL NULL value.
  5452. ** Valid SQL NULL returns can be distinguished from out-of-memory errors
  5453. ** by invoking the [sqlite3_errcode()] immediately after the suspect
  5454. ** return value is obtained and before any
  5455. ** other SQLite interface is called on the same [database connection].
  5456. */
  5457. SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
  5458. SQLITE_API double sqlite3_value_double(sqlite3_value*);
  5459. SQLITE_API int sqlite3_value_int(sqlite3_value*);
  5460. SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
  5461. SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
  5462. SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
  5463. SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
  5464. SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
  5465. SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
  5466. SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
  5467. SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  5468. SQLITE_API int sqlite3_value_type(sqlite3_value*);
  5469. SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
  5470. SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
  5471. SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
  5472. /*
  5473. ** CAPI3REF: Finding The Subtype Of SQL Values
  5474. ** METHOD: sqlite3_value
  5475. **
  5476. ** The sqlite3_value_subtype(V) function returns the subtype for
  5477. ** an [application-defined SQL function] argument V. The subtype
  5478. ** information can be used to pass a limited amount of context from
  5479. ** one SQL function to another. Use the [sqlite3_result_subtype()]
  5480. ** routine to set the subtype for the return value of an SQL function.
  5481. */
  5482. SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
  5483. /*
  5484. ** CAPI3REF: Copy And Free SQL Values
  5485. ** METHOD: sqlite3_value
  5486. **
  5487. ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
  5488. ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
  5489. ** is a [protected sqlite3_value] object even if the input is not.
  5490. ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
  5491. ** memory allocation fails.
  5492. **
  5493. ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
  5494. ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
  5495. ** then sqlite3_value_free(V) is a harmless no-op.
  5496. */
  5497. SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
  5498. SQLITE_API void sqlite3_value_free(sqlite3_value*);
  5499. /*
  5500. ** CAPI3REF: Obtain Aggregate Function Context
  5501. ** METHOD: sqlite3_context
  5502. **
  5503. ** Implementations of aggregate SQL functions use this
  5504. ** routine to allocate memory for storing their state.
  5505. **
  5506. ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
  5507. ** for a particular aggregate function, SQLite allocates
  5508. ** N bytes of memory, zeroes out that memory, and returns a pointer
  5509. ** to the new memory. ^On second and subsequent calls to
  5510. ** sqlite3_aggregate_context() for the same aggregate function instance,
  5511. ** the same buffer is returned. Sqlite3_aggregate_context() is normally
  5512. ** called once for each invocation of the xStep callback and then one
  5513. ** last time when the xFinal callback is invoked. ^(When no rows match
  5514. ** an aggregate query, the xStep() callback of the aggregate function
  5515. ** implementation is never called and xFinal() is called exactly once.
  5516. ** In those cases, sqlite3_aggregate_context() might be called for the
  5517. ** first time from within xFinal().)^
  5518. **
  5519. ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
  5520. ** when first called if N is less than or equal to zero or if a memory
  5521. ** allocate error occurs.
  5522. **
  5523. ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
  5524. ** determined by the N parameter on first successful call. Changing the
  5525. ** value of N in any subsequent call to sqlite3_aggregate_context() within
  5526. ** the same aggregate function instance will not resize the memory
  5527. ** allocation.)^ Within the xFinal callback, it is customary to set
  5528. ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
  5529. ** pointless memory allocations occur.
  5530. **
  5531. ** ^SQLite automatically frees the memory allocated by
  5532. ** sqlite3_aggregate_context() when the aggregate query concludes.
  5533. **
  5534. ** The first parameter must be a copy of the
  5535. ** [sqlite3_context | SQL function context] that is the first parameter
  5536. ** to the xStep or xFinal callback routine that implements the aggregate
  5537. ** function.
  5538. **
  5539. ** This routine must be called from the same thread in which
  5540. ** the aggregate SQL function is running.
  5541. */
  5542. SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
  5543. /*
  5544. ** CAPI3REF: User Data For Functions
  5545. ** METHOD: sqlite3_context
  5546. **
  5547. ** ^The sqlite3_user_data() interface returns a copy of
  5548. ** the pointer that was the pUserData parameter (the 5th parameter)
  5549. ** of the [sqlite3_create_function()]
  5550. ** and [sqlite3_create_function16()] routines that originally
  5551. ** registered the application defined function.
  5552. **
  5553. ** This routine must be called from the same thread in which
  5554. ** the application-defined function is running.
  5555. */
  5556. SQLITE_API void *sqlite3_user_data(sqlite3_context*);
  5557. /*
  5558. ** CAPI3REF: Database Connection For Functions
  5559. ** METHOD: sqlite3_context
  5560. **
  5561. ** ^The sqlite3_context_db_handle() interface returns a copy of
  5562. ** the pointer to the [database connection] (the 1st parameter)
  5563. ** of the [sqlite3_create_function()]
  5564. ** and [sqlite3_create_function16()] routines that originally
  5565. ** registered the application defined function.
  5566. */
  5567. SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
  5568. /*
  5569. ** CAPI3REF: Function Auxiliary Data
  5570. ** METHOD: sqlite3_context
  5571. **
  5572. ** These functions may be used by (non-aggregate) SQL functions to
  5573. ** associate metadata with argument values. If the same value is passed to
  5574. ** multiple invocations of the same SQL function during query execution, under
  5575. ** some circumstances the associated metadata may be preserved. An example
  5576. ** of where this might be useful is in a regular-expression matching
  5577. ** function. The compiled version of the regular expression can be stored as
  5578. ** metadata associated with the pattern string.
  5579. ** Then as long as the pattern string remains the same,
  5580. ** the compiled regular expression can be reused on multiple
  5581. ** invocations of the same function.
  5582. **
  5583. ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
  5584. ** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
  5585. ** value to the application-defined function. ^N is zero for the left-most
  5586. ** function argument. ^If there is no metadata
  5587. ** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
  5588. ** returns a NULL pointer.
  5589. **
  5590. ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
  5591. ** argument of the application-defined function. ^Subsequent
  5592. ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
  5593. ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
  5594. ** NULL if the metadata has been discarded.
  5595. ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
  5596. ** SQLite will invoke the destructor function X with parameter P exactly
  5597. ** once, when the metadata is discarded.
  5598. ** SQLite is free to discard the metadata at any time, including: <ul>
  5599. ** <li> ^(when the corresponding function parameter changes)^, or
  5600. ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
  5601. ** SQL statement)^, or
  5602. ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
  5603. ** parameter)^, or
  5604. ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
  5605. ** allocation error occurs.)^ </ul>
  5606. **
  5607. ** Note the last bullet in particular. The destructor X in
  5608. ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
  5609. ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
  5610. ** should be called near the end of the function implementation and the
  5611. ** function implementation should not make any use of P after
  5612. ** sqlite3_set_auxdata() has been called.
  5613. **
  5614. ** ^(In practice, metadata is preserved between function calls for
  5615. ** function parameters that are compile-time constants, including literal
  5616. ** values and [parameters] and expressions composed from the same.)^
  5617. **
  5618. ** The value of the N parameter to these interfaces should be non-negative.
  5619. ** Future enhancements may make use of negative N values to define new
  5620. ** kinds of function caching behavior.
  5621. **
  5622. ** These routines must be called from the same thread in which
  5623. ** the SQL function is running.
  5624. */
  5625. SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
  5626. SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  5627. /*
  5628. ** CAPI3REF: Constants Defining Special Destructor Behavior
  5629. **
  5630. ** These are special values for the destructor that is passed in as the
  5631. ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
  5632. ** argument is SQLITE_STATIC, it means that the content pointer is constant
  5633. ** and will never change. It does not need to be destroyed. ^The
  5634. ** SQLITE_TRANSIENT value means that the content will likely change in
  5635. ** the near future and that SQLite should make its own private copy of
  5636. ** the content before returning.
  5637. **
  5638. ** The typedef is necessary to work around problems in certain
  5639. ** C++ compilers.
  5640. */
  5641. typedef void (*sqlite3_destructor_type)(void*);
  5642. #define SQLITE_STATIC ((sqlite3_destructor_type)0)
  5643. #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
  5644. /*
  5645. ** CAPI3REF: Setting The Result Of An SQL Function
  5646. ** METHOD: sqlite3_context
  5647. **
  5648. ** These routines are used by the xFunc or xFinal callbacks that
  5649. ** implement SQL functions and aggregates. See
  5650. ** [sqlite3_create_function()] and [sqlite3_create_function16()]
  5651. ** for additional information.
  5652. **
  5653. ** These functions work very much like the [parameter binding] family of
  5654. ** functions used to bind values to host parameters in prepared statements.
  5655. ** Refer to the [SQL parameter] documentation for additional information.
  5656. **
  5657. ** ^The sqlite3_result_blob() interface sets the result from
  5658. ** an application-defined function to be the BLOB whose content is pointed
  5659. ** to by the second parameter and which is N bytes long where N is the
  5660. ** third parameter.
  5661. **
  5662. ** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
  5663. ** interfaces set the result of the application-defined function to be
  5664. ** a BLOB containing all zero bytes and N bytes in size.
  5665. **
  5666. ** ^The sqlite3_result_double() interface sets the result from
  5667. ** an application-defined function to be a floating point value specified
  5668. ** by its 2nd argument.
  5669. **
  5670. ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
  5671. ** cause the implemented SQL function to throw an exception.
  5672. ** ^SQLite uses the string pointed to by the
  5673. ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
  5674. ** as the text of an error message. ^SQLite interprets the error
  5675. ** message string from sqlite3_result_error() as UTF-8. ^SQLite
  5676. ** interprets the string from sqlite3_result_error16() as UTF-16 using
  5677. ** the same [byte-order determination rules] as [sqlite3_bind_text16()].
  5678. ** ^If the third parameter to sqlite3_result_error()
  5679. ** or sqlite3_result_error16() is negative then SQLite takes as the error
  5680. ** message all text up through the first zero character.
  5681. ** ^If the third parameter to sqlite3_result_error() or
  5682. ** sqlite3_result_error16() is non-negative then SQLite takes that many
  5683. ** bytes (not characters) from the 2nd parameter as the error message.
  5684. ** ^The sqlite3_result_error() and sqlite3_result_error16()
  5685. ** routines make a private copy of the error message text before
  5686. ** they return. Hence, the calling function can deallocate or
  5687. ** modify the text after they return without harm.
  5688. ** ^The sqlite3_result_error_code() function changes the error code
  5689. ** returned by SQLite as a result of an error in a function. ^By default,
  5690. ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
  5691. ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
  5692. **
  5693. ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
  5694. ** error indicating that a string or BLOB is too long to represent.
  5695. **
  5696. ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
  5697. ** error indicating that a memory allocation failed.
  5698. **
  5699. ** ^The sqlite3_result_int() interface sets the return value
  5700. ** of the application-defined function to be the 32-bit signed integer
  5701. ** value given in the 2nd argument.
  5702. ** ^The sqlite3_result_int64() interface sets the return value
  5703. ** of the application-defined function to be the 64-bit signed integer
  5704. ** value given in the 2nd argument.
  5705. **
  5706. ** ^The sqlite3_result_null() interface sets the return value
  5707. ** of the application-defined function to be NULL.
  5708. **
  5709. ** ^The sqlite3_result_text(), sqlite3_result_text16(),
  5710. ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
  5711. ** set the return value of the application-defined function to be
  5712. ** a text string which is represented as UTF-8, UTF-16 native byte order,
  5713. ** UTF-16 little endian, or UTF-16 big endian, respectively.
  5714. ** ^The sqlite3_result_text64() interface sets the return value of an
  5715. ** application-defined function to be a text string in an encoding
  5716. ** specified by the fifth (and last) parameter, which must be one
  5717. ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
  5718. ** ^SQLite takes the text result from the application from
  5719. ** the 2nd parameter of the sqlite3_result_text* interfaces.
  5720. ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  5721. ** is negative, then SQLite takes result text from the 2nd parameter
  5722. ** through the first zero character.
  5723. ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  5724. ** is non-negative, then as many bytes (not characters) of the text
  5725. ** pointed to by the 2nd parameter are taken as the application-defined
  5726. ** function result. If the 3rd parameter is non-negative, then it
  5727. ** must be the byte offset into the string where the NUL terminator would
  5728. ** appear if the string where NUL terminated. If any NUL characters occur
  5729. ** in the string at a byte offset that is less than the value of the 3rd
  5730. ** parameter, then the resulting string will contain embedded NULs and the
  5731. ** result of expressions operating on strings with embedded NULs is undefined.
  5732. ** ^If the 4th parameter to the sqlite3_result_text* interfaces
  5733. ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
  5734. ** function as the destructor on the text or BLOB result when it has
  5735. ** finished using that result.
  5736. ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
  5737. ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
  5738. ** assumes that the text or BLOB result is in constant space and does not
  5739. ** copy the content of the parameter nor call a destructor on the content
  5740. ** when it has finished using that result.
  5741. ** ^If the 4th parameter to the sqlite3_result_text* interfaces
  5742. ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  5743. ** then SQLite makes a copy of the result into space obtained
  5744. ** from [sqlite3_malloc()] before it returns.
  5745. **
  5746. ** ^For the sqlite3_result_text16(), sqlite3_result_text16le(), and
  5747. ** sqlite3_result_text16be() routines, and for sqlite3_result_text64()
  5748. ** when the encoding is not UTF8, if the input UTF16 begins with a
  5749. ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
  5750. ** string and the rest of the string is interpreted according to the
  5751. ** byte-order specified by the BOM. ^The byte-order specified by
  5752. ** the BOM at the beginning of the text overrides the byte-order
  5753. ** specified by the interface procedure. ^So, for example, if
  5754. ** sqlite3_result_text16le() is invoked with text that begins
  5755. ** with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
  5756. ** first two bytes of input are skipped and the remaining input
  5757. ** is interpreted as UTF16BE text.
  5758. **
  5759. ** ^For UTF16 input text to the sqlite3_result_text16(),
  5760. ** sqlite3_result_text16be(), sqlite3_result_text16le(), and
  5761. ** sqlite3_result_text64() routines, if the text contains invalid
  5762. ** UTF16 characters, the invalid characters might be converted
  5763. ** into the unicode replacement character, U+FFFD.
  5764. **
  5765. ** ^The sqlite3_result_value() interface sets the result of
  5766. ** the application-defined function to be a copy of the
  5767. ** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
  5768. ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  5769. ** so that the [sqlite3_value] specified in the parameter may change or
  5770. ** be deallocated after sqlite3_result_value() returns without harm.
  5771. ** ^A [protected sqlite3_value] object may always be used where an
  5772. ** [unprotected sqlite3_value] object is required, so either
  5773. ** kind of [sqlite3_value] object can be used with this interface.
  5774. **
  5775. ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
  5776. ** SQL NULL value, just like [sqlite3_result_null(C)], except that it
  5777. ** also associates the host-language pointer P or type T with that
  5778. ** NULL value such that the pointer can be retrieved within an
  5779. ** [application-defined SQL function] using [sqlite3_value_pointer()].
  5780. ** ^If the D parameter is not NULL, then it is a pointer to a destructor
  5781. ** for the P parameter. ^SQLite invokes D with P as its only argument
  5782. ** when SQLite is finished with P. The T parameter should be a static
  5783. ** string and preferably a string literal. The sqlite3_result_pointer()
  5784. ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
  5785. **
  5786. ** If these routines are called from within the different thread
  5787. ** than the one containing the application-defined function that received
  5788. ** the [sqlite3_context] pointer, the results are undefined.
  5789. */
  5790. SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  5791. SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
  5792. sqlite3_uint64,void(*)(void*));
  5793. SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
  5794. SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
  5795. SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
  5796. SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
  5797. SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
  5798. SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
  5799. SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
  5800. SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
  5801. SQLITE_API void sqlite3_result_null(sqlite3_context*);
  5802. SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
  5803. SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
  5804. void(*)(void*), unsigned char encoding);
  5805. SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  5806. SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  5807. SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  5808. SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  5809. SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
  5810. SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
  5811. SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
  5812. /*
  5813. ** CAPI3REF: Setting The Subtype Of An SQL Function
  5814. ** METHOD: sqlite3_context
  5815. **
  5816. ** The sqlite3_result_subtype(C,T) function causes the subtype of
  5817. ** the result from the [application-defined SQL function] with
  5818. ** [sqlite3_context] C to be the value T. Only the lower 8 bits
  5819. ** of the subtype T are preserved in current versions of SQLite;
  5820. ** higher order bits are discarded.
  5821. ** The number of subtype bytes preserved by SQLite might increase
  5822. ** in future releases of SQLite.
  5823. */
  5824. SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
  5825. /*
  5826. ** CAPI3REF: Define New Collating Sequences
  5827. ** METHOD: sqlite3
  5828. **
  5829. ** ^These functions add, remove, or modify a [collation] associated
  5830. ** with the [database connection] specified as the first argument.
  5831. **
  5832. ** ^The name of the collation is a UTF-8 string
  5833. ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  5834. ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
  5835. ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
  5836. ** considered to be the same name.
  5837. **
  5838. ** ^(The third argument (eTextRep) must be one of the constants:
  5839. ** <ul>
  5840. ** <li> [SQLITE_UTF8],
  5841. ** <li> [SQLITE_UTF16LE],
  5842. ** <li> [SQLITE_UTF16BE],
  5843. ** <li> [SQLITE_UTF16], or
  5844. ** <li> [SQLITE_UTF16_ALIGNED].
  5845. ** </ul>)^
  5846. ** ^The eTextRep argument determines the encoding of strings passed
  5847. ** to the collating function callback, xCompare.
  5848. ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
  5849. ** force strings to be UTF16 with native byte order.
  5850. ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
  5851. ** on an even byte address.
  5852. **
  5853. ** ^The fourth argument, pArg, is an application data pointer that is passed
  5854. ** through as the first argument to the collating function callback.
  5855. **
  5856. ** ^The fifth argument, xCompare, is a pointer to the collating function.
  5857. ** ^Multiple collating functions can be registered using the same name but
  5858. ** with different eTextRep parameters and SQLite will use whichever
  5859. ** function requires the least amount of data transformation.
  5860. ** ^If the xCompare argument is NULL then the collating function is
  5861. ** deleted. ^When all collating functions having the same name are deleted,
  5862. ** that collation is no longer usable.
  5863. **
  5864. ** ^The collating function callback is invoked with a copy of the pArg
  5865. ** application data pointer and with two strings in the encoding specified
  5866. ** by the eTextRep argument. The two integer parameters to the collating
  5867. ** function callback are the length of the two strings, in bytes. The collating
  5868. ** function must return an integer that is negative, zero, or positive
  5869. ** if the first string is less than, equal to, or greater than the second,
  5870. ** respectively. A collating function must always return the same answer
  5871. ** given the same inputs. If two or more collating functions are registered
  5872. ** to the same collation name (using different eTextRep values) then all
  5873. ** must give an equivalent answer when invoked with equivalent strings.
  5874. ** The collating function must obey the following properties for all
  5875. ** strings A, B, and C:
  5876. **
  5877. ** <ol>
  5878. ** <li> If A==B then B==A.
  5879. ** <li> If A==B and B==C then A==C.
  5880. ** <li> If A&lt;B THEN B&gt;A.
  5881. ** <li> If A&lt;B and B&lt;C then A&lt;C.
  5882. ** </ol>
  5883. **
  5884. ** If a collating function fails any of the above constraints and that
  5885. ** collating function is registered and used, then the behavior of SQLite
  5886. ** is undefined.
  5887. **
  5888. ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  5889. ** with the addition that the xDestroy callback is invoked on pArg when
  5890. ** the collating function is deleted.
  5891. ** ^Collating functions are deleted when they are overridden by later
  5892. ** calls to the collation creation functions or when the
  5893. ** [database connection] is closed using [sqlite3_close()].
  5894. **
  5895. ** ^The xDestroy callback is <u>not</u> called if the
  5896. ** sqlite3_create_collation_v2() function fails. Applications that invoke
  5897. ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
  5898. ** check the return code and dispose of the application data pointer
  5899. ** themselves rather than expecting SQLite to deal with it for them.
  5900. ** This is different from every other SQLite interface. The inconsistency
  5901. ** is unfortunate but cannot be changed without breaking backwards
  5902. ** compatibility.
  5903. **
  5904. ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
  5905. */
  5906. SQLITE_API int sqlite3_create_collation(
  5907. sqlite3*,
  5908. const char *zName,
  5909. int eTextRep,
  5910. void *pArg,
  5911. int(*xCompare)(void*,int,const void*,int,const void*)
  5912. );
  5913. SQLITE_API int sqlite3_create_collation_v2(
  5914. sqlite3*,
  5915. const char *zName,
  5916. int eTextRep,
  5917. void *pArg,
  5918. int(*xCompare)(void*,int,const void*,int,const void*),
  5919. void(*xDestroy)(void*)
  5920. );
  5921. SQLITE_API int sqlite3_create_collation16(
  5922. sqlite3*,
  5923. const void *zName,
  5924. int eTextRep,
  5925. void *pArg,
  5926. int(*xCompare)(void*,int,const void*,int,const void*)
  5927. );
  5928. /*
  5929. ** CAPI3REF: Collation Needed Callbacks
  5930. ** METHOD: sqlite3
  5931. **
  5932. ** ^To avoid having to register all collation sequences before a database
  5933. ** can be used, a single callback function may be registered with the
  5934. ** [database connection] to be invoked whenever an undefined collation
  5935. ** sequence is required.
  5936. **
  5937. ** ^If the function is registered using the sqlite3_collation_needed() API,
  5938. ** then it is passed the names of undefined collation sequences as strings
  5939. ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
  5940. ** the names are passed as UTF-16 in machine native byte order.
  5941. ** ^A call to either function replaces the existing collation-needed callback.
  5942. **
  5943. ** ^(When the callback is invoked, the first argument passed is a copy
  5944. ** of the second argument to sqlite3_collation_needed() or
  5945. ** sqlite3_collation_needed16(). The second argument is the database
  5946. ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
  5947. ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
  5948. ** sequence function required. The fourth parameter is the name of the
  5949. ** required collation sequence.)^
  5950. **
  5951. ** The callback function should register the desired collation using
  5952. ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
  5953. ** [sqlite3_create_collation_v2()].
  5954. */
  5955. SQLITE_API int sqlite3_collation_needed(
  5956. sqlite3*,
  5957. void*,
  5958. void(*)(void*,sqlite3*,int eTextRep,const char*)
  5959. );
  5960. SQLITE_API int sqlite3_collation_needed16(
  5961. sqlite3*,
  5962. void*,
  5963. void(*)(void*,sqlite3*,int eTextRep,const void*)
  5964. );
  5965. #ifdef SQLITE_ENABLE_CEROD
  5966. /*
  5967. ** Specify the activation key for a CEROD database. Unless
  5968. ** activated, none of the CEROD routines will work.
  5969. */
  5970. SQLITE_API void sqlite3_activate_cerod(
  5971. const char *zPassPhrase /* Activation phrase */
  5972. );
  5973. #endif
  5974. /*
  5975. ** CAPI3REF: Suspend Execution For A Short Time
  5976. **
  5977. ** The sqlite3_sleep() function causes the current thread to suspend execution
  5978. ** for at least a number of milliseconds specified in its parameter.
  5979. **
  5980. ** If the operating system does not support sleep requests with
  5981. ** millisecond time resolution, then the time will be rounded up to
  5982. ** the nearest second. The number of milliseconds of sleep actually
  5983. ** requested from the operating system is returned.
  5984. **
  5985. ** ^SQLite implements this interface by calling the xSleep()
  5986. ** method of the default [sqlite3_vfs] object. If the xSleep() method
  5987. ** of the default VFS is not implemented correctly, or not implemented at
  5988. ** all, then the behavior of sqlite3_sleep() may deviate from the description
  5989. ** in the previous paragraphs.
  5990. */
  5991. SQLITE_API int sqlite3_sleep(int);
  5992. /*
  5993. ** CAPI3REF: Name Of The Folder Holding Temporary Files
  5994. **
  5995. ** ^(If this global variable is made to point to a string which is
  5996. ** the name of a folder (a.k.a. directory), then all temporary files
  5997. ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
  5998. ** will be placed in that directory.)^ ^If this variable
  5999. ** is a NULL pointer, then SQLite performs a search for an appropriate
  6000. ** temporary file directory.
  6001. **
  6002. ** Applications are strongly discouraged from using this global variable.
  6003. ** It is required to set a temporary folder on Windows Runtime (WinRT).
  6004. ** But for all other platforms, it is highly recommended that applications
  6005. ** neither read nor write this variable. This global variable is a relic
  6006. ** that exists for backwards compatibility of legacy applications and should
  6007. ** be avoided in new projects.
  6008. **
  6009. ** It is not safe to read or modify this variable in more than one
  6010. ** thread at a time. It is not safe to read or modify this variable
  6011. ** if a [database connection] is being used at the same time in a separate
  6012. ** thread.
  6013. ** It is intended that this variable be set once
  6014. ** as part of process initialization and before any SQLite interface
  6015. ** routines have been called and that this variable remain unchanged
  6016. ** thereafter.
  6017. **
  6018. ** ^The [temp_store_directory pragma] may modify this variable and cause
  6019. ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
  6020. ** the [temp_store_directory pragma] always assumes that any string
  6021. ** that this variable points to is held in memory obtained from
  6022. ** [sqlite3_malloc] and the pragma may attempt to free that memory
  6023. ** using [sqlite3_free].
  6024. ** Hence, if this variable is modified directly, either it should be
  6025. ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  6026. ** or else the use of the [temp_store_directory pragma] should be avoided.
  6027. ** Except when requested by the [temp_store_directory pragma], SQLite
  6028. ** does not free the memory that sqlite3_temp_directory points to. If
  6029. ** the application wants that memory to be freed, it must do
  6030. ** so itself, taking care to only do so after all [database connection]
  6031. ** objects have been destroyed.
  6032. **
  6033. ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
  6034. ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
  6035. ** features that require the use of temporary files may fail. Here is an
  6036. ** example of how to do this using C++ with the Windows Runtime:
  6037. **
  6038. ** <blockquote><pre>
  6039. ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
  6040. ** &nbsp; TemporaryFolder->Path->Data();
  6041. ** char zPathBuf&#91;MAX_PATH + 1&#93;;
  6042. ** memset(zPathBuf, 0, sizeof(zPathBuf));
  6043. ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
  6044. ** &nbsp; NULL, NULL);
  6045. ** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
  6046. ** </pre></blockquote>
  6047. */
  6048. SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
  6049. /*
  6050. ** CAPI3REF: Name Of The Folder Holding Database Files
  6051. **
  6052. ** ^(If this global variable is made to point to a string which is
  6053. ** the name of a folder (a.k.a. directory), then all database files
  6054. ** specified with a relative pathname and created or accessed by
  6055. ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
  6056. ** to be relative to that directory.)^ ^If this variable is a NULL
  6057. ** pointer, then SQLite assumes that all database files specified
  6058. ** with a relative pathname are relative to the current directory
  6059. ** for the process. Only the windows VFS makes use of this global
  6060. ** variable; it is ignored by the unix VFS.
  6061. **
  6062. ** Changing the value of this variable while a database connection is
  6063. ** open can result in a corrupt database.
  6064. **
  6065. ** It is not safe to read or modify this variable in more than one
  6066. ** thread at a time. It is not safe to read or modify this variable
  6067. ** if a [database connection] is being used at the same time in a separate
  6068. ** thread.
  6069. ** It is intended that this variable be set once
  6070. ** as part of process initialization and before any SQLite interface
  6071. ** routines have been called and that this variable remain unchanged
  6072. ** thereafter.
  6073. **
  6074. ** ^The [data_store_directory pragma] may modify this variable and cause
  6075. ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
  6076. ** the [data_store_directory pragma] always assumes that any string
  6077. ** that this variable points to is held in memory obtained from
  6078. ** [sqlite3_malloc] and the pragma may attempt to free that memory
  6079. ** using [sqlite3_free].
  6080. ** Hence, if this variable is modified directly, either it should be
  6081. ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  6082. ** or else the use of the [data_store_directory pragma] should be avoided.
  6083. */
  6084. SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
  6085. /*
  6086. ** CAPI3REF: Win32 Specific Interface
  6087. **
  6088. ** These interfaces are available only on Windows. The
  6089. ** [sqlite3_win32_set_directory] interface is used to set the value associated
  6090. ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
  6091. ** zValue, depending on the value of the type parameter. The zValue parameter
  6092. ** should be NULL to cause the previous value to be freed via [sqlite3_free];
  6093. ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
  6094. ** prior to being used. The [sqlite3_win32_set_directory] interface returns
  6095. ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
  6096. ** or [SQLITE_NOMEM] if memory could not be allocated. The value of the
  6097. ** [sqlite3_data_directory] variable is intended to act as a replacement for
  6098. ** the current directory on the sub-platforms of Win32 where that concept is
  6099. ** not present, e.g. WinRT and UWP. The [sqlite3_win32_set_directory8] and
  6100. ** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
  6101. ** sqlite3_win32_set_directory interface except the string parameter must be
  6102. ** UTF-8 or UTF-16, respectively.
  6103. */
  6104. SQLITE_API int sqlite3_win32_set_directory(
  6105. unsigned long type, /* Identifier for directory being set or reset */
  6106. void *zValue /* New value for directory being set or reset */
  6107. );
  6108. SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
  6109. SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
  6110. /*
  6111. ** CAPI3REF: Win32 Directory Types
  6112. **
  6113. ** These macros are only available on Windows. They define the allowed values
  6114. ** for the type argument to the [sqlite3_win32_set_directory] interface.
  6115. */
  6116. #define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1
  6117. #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2
  6118. /*
  6119. ** CAPI3REF: Test For Auto-Commit Mode
  6120. ** KEYWORDS: {autocommit mode}
  6121. ** METHOD: sqlite3
  6122. **
  6123. ** ^The sqlite3_get_autocommit() interface returns non-zero or
  6124. ** zero if the given database connection is or is not in autocommit mode,
  6125. ** respectively. ^Autocommit mode is on by default.
  6126. ** ^Autocommit mode is disabled by a [BEGIN] statement.
  6127. ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
  6128. **
  6129. ** If certain kinds of errors occur on a statement within a multi-statement
  6130. ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
  6131. ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  6132. ** transaction might be rolled back automatically. The only way to
  6133. ** find out whether SQLite automatically rolled back the transaction after
  6134. ** an error is to use this function.
  6135. **
  6136. ** If another thread changes the autocommit status of the database
  6137. ** connection while this routine is running, then the return value
  6138. ** is undefined.
  6139. */
  6140. SQLITE_API int sqlite3_get_autocommit(sqlite3*);
  6141. /*
  6142. ** CAPI3REF: Find The Database Handle Of A Prepared Statement
  6143. ** METHOD: sqlite3_stmt
  6144. **
  6145. ** ^The sqlite3_db_handle interface returns the [database connection] handle
  6146. ** to which a [prepared statement] belongs. ^The [database connection]
  6147. ** returned by sqlite3_db_handle is the same [database connection]
  6148. ** that was the first argument
  6149. ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
  6150. ** create the statement in the first place.
  6151. */
  6152. SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  6153. /*
  6154. ** CAPI3REF: Return The Filename For A Database Connection
  6155. ** METHOD: sqlite3
  6156. **
  6157. ** ^The sqlite3_db_filename(D,N) interface returns a pointer to the filename
  6158. ** associated with database N of connection D.
  6159. ** ^If there is no attached database N on the database
  6160. ** connection D, or if database N is a temporary or in-memory database, then
  6161. ** this function will return either a NULL pointer or an empty string.
  6162. **
  6163. ** ^The string value returned by this routine is owned and managed by
  6164. ** the database connection. ^The value will be valid until the database N
  6165. ** is [DETACH]-ed or until the database connection closes.
  6166. **
  6167. ** ^The filename returned by this function is the output of the
  6168. ** xFullPathname method of the [VFS]. ^In other words, the filename
  6169. ** will be an absolute pathname, even if the filename used
  6170. ** to open the database originally was a URI or relative pathname.
  6171. **
  6172. ** If the filename pointer returned by this routine is not NULL, then it
  6173. ** can be used as the filename input parameter to these routines:
  6174. ** <ul>
  6175. ** <li> [sqlite3_uri_parameter()]
  6176. ** <li> [sqlite3_uri_boolean()]
  6177. ** <li> [sqlite3_uri_int64()]
  6178. ** <li> [sqlite3_filename_database()]
  6179. ** <li> [sqlite3_filename_journal()]
  6180. ** <li> [sqlite3_filename_wal()]
  6181. ** </ul>
  6182. */
  6183. SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
  6184. /*
  6185. ** CAPI3REF: Determine if a database is read-only
  6186. ** METHOD: sqlite3
  6187. **
  6188. ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
  6189. ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
  6190. ** the name of a database on connection D.
  6191. */
  6192. SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
  6193. /*
  6194. ** CAPI3REF: Determine the transaction state of a database
  6195. ** METHOD: sqlite3
  6196. **
  6197. ** ^The sqlite3_txn_state(D,S) interface returns the current
  6198. ** [transaction state] of schema S in database connection D. ^If S is NULL,
  6199. ** then the highest transaction state of any schema on database connection D
  6200. ** is returned. Transaction states are (in order of lowest to highest):
  6201. ** <ol>
  6202. ** <li value="0"> SQLITE_TXN_NONE
  6203. ** <li value="1"> SQLITE_TXN_READ
  6204. ** <li value="2"> SQLITE_TXN_WRITE
  6205. ** </ol>
  6206. ** ^If the S argument to sqlite3_txn_state(D,S) is not the name of
  6207. ** a valid schema, then -1 is returned.
  6208. */
  6209. SQLITE_API int sqlite3_txn_state(sqlite3*,const char *zSchema);
  6210. /*
  6211. ** CAPI3REF: Allowed return values from [sqlite3_txn_state()]
  6212. ** KEYWORDS: {transaction state}
  6213. **
  6214. ** These constants define the current transaction state of a database file.
  6215. ** ^The [sqlite3_txn_state(D,S)] interface returns one of these
  6216. ** constants in order to describe the transaction state of schema S
  6217. ** in [database connection] D.
  6218. **
  6219. ** <dl>
  6220. ** [[SQLITE_TXN_NONE]] <dt>SQLITE_TXN_NONE</dt>
  6221. ** <dd>The SQLITE_TXN_NONE state means that no transaction is currently
  6222. ** pending.</dd>
  6223. **
  6224. ** [[SQLITE_TXN_READ]] <dt>SQLITE_TXN_READ</dt>
  6225. ** <dd>The SQLITE_TXN_READ state means that the database is currently
  6226. ** in a read transaction. Content has been read from the database file
  6227. ** but nothing in the database file has changed. The transaction state
  6228. ** will advanced to SQLITE_TXN_WRITE if any changes occur and there are
  6229. ** no other conflicting concurrent write transactions. The transaction
  6230. ** state will revert to SQLITE_TXN_NONE following a [ROLLBACK] or
  6231. ** [COMMIT].</dd>
  6232. **
  6233. ** [[SQLITE_TXN_WRITE]] <dt>SQLITE_TXN_WRITE</dt>
  6234. ** <dd>The SQLITE_TXN_WRITE state means that the database is currently
  6235. ** in a write transaction. Content has been written to the database file
  6236. ** but has not yet committed. The transaction state will change to
  6237. ** to SQLITE_TXN_NONE at the next [ROLLBACK] or [COMMIT].</dd>
  6238. */
  6239. #define SQLITE_TXN_NONE 0
  6240. #define SQLITE_TXN_READ 1
  6241. #define SQLITE_TXN_WRITE 2
  6242. /*
  6243. ** CAPI3REF: Find the next prepared statement
  6244. ** METHOD: sqlite3
  6245. **
  6246. ** ^This interface returns a pointer to the next [prepared statement] after
  6247. ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
  6248. ** then this interface returns a pointer to the first prepared statement
  6249. ** associated with the database connection pDb. ^If no prepared statement
  6250. ** satisfies the conditions of this routine, it returns NULL.
  6251. **
  6252. ** The [database connection] pointer D in a call to
  6253. ** [sqlite3_next_stmt(D,S)] must refer to an open database
  6254. ** connection and in particular must not be a NULL pointer.
  6255. */
  6256. SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
  6257. /*
  6258. ** CAPI3REF: Commit And Rollback Notification Callbacks
  6259. ** METHOD: sqlite3
  6260. **
  6261. ** ^The sqlite3_commit_hook() interface registers a callback
  6262. ** function to be invoked whenever a transaction is [COMMIT | committed].
  6263. ** ^Any callback set by a previous call to sqlite3_commit_hook()
  6264. ** for the same database connection is overridden.
  6265. ** ^The sqlite3_rollback_hook() interface registers a callback
  6266. ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
  6267. ** ^Any callback set by a previous call to sqlite3_rollback_hook()
  6268. ** for the same database connection is overridden.
  6269. ** ^The pArg argument is passed through to the callback.
  6270. ** ^If the callback on a commit hook function returns non-zero,
  6271. ** then the commit is converted into a rollback.
  6272. **
  6273. ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
  6274. ** return the P argument from the previous call of the same function
  6275. ** on the same [database connection] D, or NULL for
  6276. ** the first call for each function on D.
  6277. **
  6278. ** The commit and rollback hook callbacks are not reentrant.
  6279. ** The callback implementation must not do anything that will modify
  6280. ** the database connection that invoked the callback. Any actions
  6281. ** to modify the database connection must be deferred until after the
  6282. ** completion of the [sqlite3_step()] call that triggered the commit
  6283. ** or rollback hook in the first place.
  6284. ** Note that running any other SQL statements, including SELECT statements,
  6285. ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
  6286. ** the database connections for the meaning of "modify" in this paragraph.
  6287. **
  6288. ** ^Registering a NULL function disables the callback.
  6289. **
  6290. ** ^When the commit hook callback routine returns zero, the [COMMIT]
  6291. ** operation is allowed to continue normally. ^If the commit hook
  6292. ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
  6293. ** ^The rollback hook is invoked on a rollback that results from a commit
  6294. ** hook returning non-zero, just as it would be with any other rollback.
  6295. **
  6296. ** ^For the purposes of this API, a transaction is said to have been
  6297. ** rolled back if an explicit "ROLLBACK" statement is executed, or
  6298. ** an error or constraint causes an implicit rollback to occur.
  6299. ** ^The rollback callback is not invoked if a transaction is
  6300. ** automatically rolled back because the database connection is closed.
  6301. **
  6302. ** See also the [sqlite3_update_hook()] interface.
  6303. */
  6304. SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
  6305. SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
  6306. /*
  6307. ** CAPI3REF: Autovacuum Compaction Amount Callback
  6308. ** METHOD: sqlite3
  6309. **
  6310. ** ^The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback
  6311. ** function C that is invoked prior to each autovacuum of the database
  6312. ** file. ^The callback is passed a copy of the generic data pointer (P),
  6313. ** the schema-name of the attached database that is being autovacuumed,
  6314. ** the the size of the database file in pages, the number of free pages,
  6315. ** and the number of bytes per page, respectively. The callback should
  6316. ** return the number of free pages that should be removed by the
  6317. ** autovacuum. ^If the callback returns zero, then no autovacuum happens.
  6318. ** ^If the value returned is greater than or equal to the number of
  6319. ** free pages, then a complete autovacuum happens.
  6320. **
  6321. ** <p>^If there are multiple ATTACH-ed database files that are being
  6322. ** modified as part of a transaction commit, then the autovacuum pages
  6323. ** callback is invoked separately for each file.
  6324. **
  6325. ** <p><b>The callback is not reentrant.</b> The callback function should
  6326. ** not attempt to invoke any other SQLite interface. If it does, bad
  6327. ** things may happen, including segmentation faults and corrupt database
  6328. ** files. The callback function should be a simple function that
  6329. ** does some arithmetic on its input parameters and returns a result.
  6330. **
  6331. ** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
  6332. ** destructor for the P parameter. ^If X is not NULL, then X(P) is
  6333. ** invoked whenever the database connection closes or when the callback
  6334. ** is overwritten by another invocation of sqlite3_autovacuum_pages().
  6335. **
  6336. ** <p>^There is only one autovacuum pages callback per database connection.
  6337. ** ^Each call to the sqlite3_autovacuum_pages() interface overrides all
  6338. ** previous invocations for that database connection. ^If the callback
  6339. ** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
  6340. ** then the autovacuum steps callback is cancelled. The return value
  6341. ** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
  6342. ** be some other error code if something goes wrong. The current
  6343. ** implementation will only return SQLITE_OK or SQLITE_MISUSE, but other
  6344. ** return codes might be added in future releases.
  6345. **
  6346. ** <p>If no autovacuum pages callback is specified (the usual case) or
  6347. ** a NULL pointer is provided for the callback,
  6348. ** then the default behavior is to vacuum all free pages. So, in other
  6349. ** words, the default behavior is the same as if the callback function
  6350. ** were something like this:
  6351. **
  6352. ** <blockquote><pre>
  6353. ** &nbsp; unsigned int demonstration_autovac_pages_callback(
  6354. ** &nbsp; void *pClientData,
  6355. ** &nbsp; const char *zSchema,
  6356. ** &nbsp; unsigned int nDbPage,
  6357. ** &nbsp; unsigned int nFreePage,
  6358. ** &nbsp; unsigned int nBytePerPage
  6359. ** &nbsp; ){
  6360. ** &nbsp; return nFreePage;
  6361. ** &nbsp; }
  6362. ** </pre></blockquote>
  6363. */
  6364. SQLITE_API int sqlite3_autovacuum_pages(
  6365. sqlite3 *db,
  6366. unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
  6367. void*,
  6368. void(*)(void*)
  6369. );
  6370. /*
  6371. ** CAPI3REF: Data Change Notification Callbacks
  6372. ** METHOD: sqlite3
  6373. **
  6374. ** ^The sqlite3_update_hook() interface registers a callback function
  6375. ** with the [database connection] identified by the first argument
  6376. ** to be invoked whenever a row is updated, inserted or deleted in
  6377. ** a [rowid table].
  6378. ** ^Any callback set by a previous call to this function
  6379. ** for the same database connection is overridden.
  6380. **
  6381. ** ^The second argument is a pointer to the function to invoke when a
  6382. ** row is updated, inserted or deleted in a rowid table.
  6383. ** ^The first argument to the callback is a copy of the third argument
  6384. ** to sqlite3_update_hook().
  6385. ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
  6386. ** or [SQLITE_UPDATE], depending on the operation that caused the callback
  6387. ** to be invoked.
  6388. ** ^The third and fourth arguments to the callback contain pointers to the
  6389. ** database and table name containing the affected row.
  6390. ** ^The final callback parameter is the [rowid] of the row.
  6391. ** ^In the case of an update, this is the [rowid] after the update takes place.
  6392. **
  6393. ** ^(The update hook is not invoked when internal system tables are
  6394. ** modified (i.e. sqlite_sequence).)^
  6395. ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
  6396. **
  6397. ** ^In the current implementation, the update hook
  6398. ** is not invoked when conflicting rows are deleted because of an
  6399. ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
  6400. ** invoked when rows are deleted using the [truncate optimization].
  6401. ** The exceptions defined in this paragraph might change in a future
  6402. ** release of SQLite.
  6403. **
  6404. ** The update hook implementation must not do anything that will modify
  6405. ** the database connection that invoked the update hook. Any actions
  6406. ** to modify the database connection must be deferred until after the
  6407. ** completion of the [sqlite3_step()] call that triggered the update hook.
  6408. ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  6409. ** database connections for the meaning of "modify" in this paragraph.
  6410. **
  6411. ** ^The sqlite3_update_hook(D,C,P) function
  6412. ** returns the P argument from the previous call
  6413. ** on the same [database connection] D, or NULL for
  6414. ** the first call on D.
  6415. **
  6416. ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
  6417. ** and [sqlite3_preupdate_hook()] interfaces.
  6418. */
  6419. SQLITE_API void *sqlite3_update_hook(
  6420. sqlite3*,
  6421. void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  6422. void*
  6423. );
  6424. /*
  6425. ** CAPI3REF: Enable Or Disable Shared Pager Cache
  6426. **
  6427. ** ^(This routine enables or disables the sharing of the database cache
  6428. ** and schema data structures between [database connection | connections]
  6429. ** to the same database. Sharing is enabled if the argument is true
  6430. ** and disabled if the argument is false.)^
  6431. **
  6432. ** ^Cache sharing is enabled and disabled for an entire process.
  6433. ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
  6434. ** In prior versions of SQLite,
  6435. ** sharing was enabled or disabled for each thread separately.
  6436. **
  6437. ** ^(The cache sharing mode set by this interface effects all subsequent
  6438. ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
  6439. ** Existing database connections continue to use the sharing mode
  6440. ** that was in effect at the time they were opened.)^
  6441. **
  6442. ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
  6443. ** successfully. An [error code] is returned otherwise.)^
  6444. **
  6445. ** ^Shared cache is disabled by default. It is recommended that it stay
  6446. ** that way. In other words, do not use this routine. This interface
  6447. ** continues to be provided for historical compatibility, but its use is
  6448. ** discouraged. Any use of shared cache is discouraged. If shared cache
  6449. ** must be used, it is recommended that shared cache only be enabled for
  6450. ** individual database connections using the [sqlite3_open_v2()] interface
  6451. ** with the [SQLITE_OPEN_SHAREDCACHE] flag.
  6452. **
  6453. ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
  6454. ** and will always return SQLITE_MISUSE. On those systems,
  6455. ** shared cache mode should be enabled per-database connection via
  6456. ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
  6457. **
  6458. ** This interface is threadsafe on processors where writing a
  6459. ** 32-bit integer is atomic.
  6460. **
  6461. ** See Also: [SQLite Shared-Cache Mode]
  6462. */
  6463. SQLITE_API int sqlite3_enable_shared_cache(int);
  6464. /*
  6465. ** CAPI3REF: Attempt To Free Heap Memory
  6466. **
  6467. ** ^The sqlite3_release_memory() interface attempts to free N bytes
  6468. ** of heap memory by deallocating non-essential memory allocations
  6469. ** held by the database library. Memory used to cache database
  6470. ** pages to improve performance is an example of non-essential memory.
  6471. ** ^sqlite3_release_memory() returns the number of bytes actually freed,
  6472. ** which might be more or less than the amount requested.
  6473. ** ^The sqlite3_release_memory() routine is a no-op returning zero
  6474. ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
  6475. **
  6476. ** See also: [sqlite3_db_release_memory()]
  6477. */
  6478. SQLITE_API int sqlite3_release_memory(int);
  6479. /*
  6480. ** CAPI3REF: Free Memory Used By A Database Connection
  6481. ** METHOD: sqlite3
  6482. **
  6483. ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
  6484. ** memory as possible from database connection D. Unlike the
  6485. ** [sqlite3_release_memory()] interface, this interface is in effect even
  6486. ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
  6487. ** omitted.
  6488. **
  6489. ** See also: [sqlite3_release_memory()]
  6490. */
  6491. SQLITE_API int sqlite3_db_release_memory(sqlite3*);
  6492. /*
  6493. ** CAPI3REF: Impose A Limit On Heap Size
  6494. **
  6495. ** These interfaces impose limits on the amount of heap memory that will be
  6496. ** by all database connections within a single process.
  6497. **
  6498. ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
  6499. ** soft limit on the amount of heap memory that may be allocated by SQLite.
  6500. ** ^SQLite strives to keep heap memory utilization below the soft heap
  6501. ** limit by reducing the number of pages held in the page cache
  6502. ** as heap memory usages approaches the limit.
  6503. ** ^The soft heap limit is "soft" because even though SQLite strives to stay
  6504. ** below the limit, it will exceed the limit rather than generate
  6505. ** an [SQLITE_NOMEM] error. In other words, the soft heap limit
  6506. ** is advisory only.
  6507. **
  6508. ** ^The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of
  6509. ** N bytes on the amount of memory that will be allocated. ^The
  6510. ** sqlite3_hard_heap_limit64(N) interface is similar to
  6511. ** sqlite3_soft_heap_limit64(N) except that memory allocations will fail
  6512. ** when the hard heap limit is reached.
  6513. **
  6514. ** ^The return value from both sqlite3_soft_heap_limit64() and
  6515. ** sqlite3_hard_heap_limit64() is the size of
  6516. ** the heap limit prior to the call, or negative in the case of an
  6517. ** error. ^If the argument N is negative
  6518. ** then no change is made to the heap limit. Hence, the current
  6519. ** size of heap limits can be determined by invoking
  6520. ** sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).
  6521. **
  6522. ** ^Setting the heap limits to zero disables the heap limiter mechanism.
  6523. **
  6524. ** ^The soft heap limit may not be greater than the hard heap limit.
  6525. ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
  6526. ** is invoked with a value of N that is greater than the hard heap limit,
  6527. ** the the soft heap limit is set to the value of the hard heap limit.
  6528. ** ^The soft heap limit is automatically enabled whenever the hard heap
  6529. ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
  6530. ** the soft heap limit is outside the range of 1..N, then the soft heap
  6531. ** limit is set to N. ^Invoking sqlite3_soft_heap_limit64(0) when the
  6532. ** hard heap limit is enabled makes the soft heap limit equal to the
  6533. ** hard heap limit.
  6534. **
  6535. ** The memory allocation limits can also be adjusted using
  6536. ** [PRAGMA soft_heap_limit] and [PRAGMA hard_heap_limit].
  6537. **
  6538. ** ^(The heap limits are not enforced in the current implementation
  6539. ** if one or more of following conditions are true:
  6540. **
  6541. ** <ul>
  6542. ** <li> The limit value is set to zero.
  6543. ** <li> Memory accounting is disabled using a combination of the
  6544. ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
  6545. ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
  6546. ** <li> An alternative page cache implementation is specified using
  6547. ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
  6548. ** <li> The page cache allocates from its own memory pool supplied
  6549. ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
  6550. ** from the heap.
  6551. ** </ul>)^
  6552. **
  6553. ** The circumstances under which SQLite will enforce the heap limits may
  6554. ** changes in future releases of SQLite.
  6555. */
  6556. SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
  6557. SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);
  6558. /*
  6559. ** CAPI3REF: Deprecated Soft Heap Limit Interface
  6560. ** DEPRECATED
  6561. **
  6562. ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
  6563. ** interface. This routine is provided for historical compatibility
  6564. ** only. All new applications should use the
  6565. ** [sqlite3_soft_heap_limit64()] interface rather than this one.
  6566. */
  6567. SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
  6568. /*
  6569. ** CAPI3REF: Extract Metadata About A Column Of A Table
  6570. ** METHOD: sqlite3
  6571. **
  6572. ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
  6573. ** information about column C of table T in database D
  6574. ** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
  6575. ** interface returns SQLITE_OK and fills in the non-NULL pointers in
  6576. ** the final five arguments with appropriate values if the specified
  6577. ** column exists. ^The sqlite3_table_column_metadata() interface returns
  6578. ** SQLITE_ERROR if the specified column does not exist.
  6579. ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
  6580. ** NULL pointer, then this routine simply checks for the existence of the
  6581. ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
  6582. ** does not. If the table name parameter T in a call to
  6583. ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
  6584. ** undefined behavior.
  6585. **
  6586. ** ^The column is identified by the second, third and fourth parameters to
  6587. ** this function. ^(The second parameter is either the name of the database
  6588. ** (i.e. "main", "temp", or an attached database) containing the specified
  6589. ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
  6590. ** for the table using the same algorithm used by the database engine to
  6591. ** resolve unqualified table references.
  6592. **
  6593. ** ^The third and fourth parameters to this function are the table and column
  6594. ** name of the desired column, respectively.
  6595. **
  6596. ** ^Metadata is returned by writing to the memory locations passed as the 5th
  6597. ** and subsequent parameters to this function. ^Any of these arguments may be
  6598. ** NULL, in which case the corresponding element of metadata is omitted.
  6599. **
  6600. ** ^(<blockquote>
  6601. ** <table border="1">
  6602. ** <tr><th> Parameter <th> Output<br>Type <th> Description
  6603. **
  6604. ** <tr><td> 5th <td> const char* <td> Data type
  6605. ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
  6606. ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
  6607. ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
  6608. ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
  6609. ** </table>
  6610. ** </blockquote>)^
  6611. **
  6612. ** ^The memory pointed to by the character pointers returned for the
  6613. ** declaration type and collation sequence is valid until the next
  6614. ** call to any SQLite API function.
  6615. **
  6616. ** ^If the specified table is actually a view, an [error code] is returned.
  6617. **
  6618. ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
  6619. ** is not a [WITHOUT ROWID] table and an
  6620. ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
  6621. ** parameters are set for the explicitly declared column. ^(If there is no
  6622. ** [INTEGER PRIMARY KEY] column, then the outputs
  6623. ** for the [rowid] are set as follows:
  6624. **
  6625. ** <pre>
  6626. ** data type: "INTEGER"
  6627. ** collation sequence: "BINARY"
  6628. ** not null: 0
  6629. ** primary key: 1
  6630. ** auto increment: 0
  6631. ** </pre>)^
  6632. **
  6633. ** ^This function causes all database schemas to be read from disk and
  6634. ** parsed, if that has not already been done, and returns an error if
  6635. ** any errors are encountered while loading the schema.
  6636. */
  6637. SQLITE_API int sqlite3_table_column_metadata(
  6638. sqlite3 *db, /* Connection handle */
  6639. const char *zDbName, /* Database name or NULL */
  6640. const char *zTableName, /* Table name */
  6641. const char *zColumnName, /* Column name */
  6642. char const **pzDataType, /* OUTPUT: Declared data type */
  6643. char const **pzCollSeq, /* OUTPUT: Collation sequence name */
  6644. int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
  6645. int *pPrimaryKey, /* OUTPUT: True if column part of PK */
  6646. int *pAutoinc /* OUTPUT: True if column is auto-increment */
  6647. );
  6648. /*
  6649. ** CAPI3REF: Load An Extension
  6650. ** METHOD: sqlite3
  6651. **
  6652. ** ^This interface loads an SQLite extension library from the named file.
  6653. **
  6654. ** ^The sqlite3_load_extension() interface attempts to load an
  6655. ** [SQLite extension] library contained in the file zFile. If
  6656. ** the file cannot be loaded directly, attempts are made to load
  6657. ** with various operating-system specific extensions added.
  6658. ** So for example, if "samplelib" cannot be loaded, then names like
  6659. ** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
  6660. ** be tried also.
  6661. **
  6662. ** ^The entry point is zProc.
  6663. ** ^(zProc may be 0, in which case SQLite will try to come up with an
  6664. ** entry point name on its own. It first tries "sqlite3_extension_init".
  6665. ** If that does not work, it constructs a name "sqlite3_X_init" where the
  6666. ** X is consists of the lower-case equivalent of all ASCII alphabetic
  6667. ** characters in the filename from the last "/" to the first following
  6668. ** "." and omitting any initial "lib".)^
  6669. ** ^The sqlite3_load_extension() interface returns
  6670. ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
  6671. ** ^If an error occurs and pzErrMsg is not 0, then the
  6672. ** [sqlite3_load_extension()] interface shall attempt to
  6673. ** fill *pzErrMsg with error message text stored in memory
  6674. ** obtained from [sqlite3_malloc()]. The calling function
  6675. ** should free this memory by calling [sqlite3_free()].
  6676. **
  6677. ** ^Extension loading must be enabled using
  6678. ** [sqlite3_enable_load_extension()] or
  6679. ** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
  6680. ** prior to calling this API,
  6681. ** otherwise an error will be returned.
  6682. **
  6683. ** <b>Security warning:</b> It is recommended that the
  6684. ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
  6685. ** interface. The use of the [sqlite3_enable_load_extension()] interface
  6686. ** should be avoided. This will keep the SQL function [load_extension()]
  6687. ** disabled and prevent SQL injections from giving attackers
  6688. ** access to extension loading capabilities.
  6689. **
  6690. ** See also the [load_extension() SQL function].
  6691. */
  6692. SQLITE_API int sqlite3_load_extension(
  6693. sqlite3 *db, /* Load the extension into this database connection */
  6694. const char *zFile, /* Name of the shared library containing extension */
  6695. const char *zProc, /* Entry point. Derived from zFile if 0 */
  6696. char **pzErrMsg /* Put error message here if not 0 */
  6697. );
  6698. /*
  6699. ** CAPI3REF: Enable Or Disable Extension Loading
  6700. ** METHOD: sqlite3
  6701. **
  6702. ** ^So as not to open security holes in older applications that are
  6703. ** unprepared to deal with [extension loading], and as a means of disabling
  6704. ** [extension loading] while evaluating user-entered SQL, the following API
  6705. ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
  6706. **
  6707. ** ^Extension loading is off by default.
  6708. ** ^Call the sqlite3_enable_load_extension() routine with onoff==1
  6709. ** to turn extension loading on and call it with onoff==0 to turn
  6710. ** it back off again.
  6711. **
  6712. ** ^This interface enables or disables both the C-API
  6713. ** [sqlite3_load_extension()] and the SQL function [load_extension()].
  6714. ** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)
  6715. ** to enable or disable only the C-API.)^
  6716. **
  6717. ** <b>Security warning:</b> It is recommended that extension loading
  6718. ** be enabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method
  6719. ** rather than this interface, so the [load_extension()] SQL function
  6720. ** remains disabled. This will prevent SQL injections from giving attackers
  6721. ** access to extension loading capabilities.
  6722. */
  6723. SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
  6724. /*
  6725. ** CAPI3REF: Automatically Load Statically Linked Extensions
  6726. **
  6727. ** ^This interface causes the xEntryPoint() function to be invoked for
  6728. ** each new [database connection] that is created. The idea here is that
  6729. ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
  6730. ** that is to be automatically loaded into all new database connections.
  6731. **
  6732. ** ^(Even though the function prototype shows that xEntryPoint() takes
  6733. ** no arguments and returns void, SQLite invokes xEntryPoint() with three
  6734. ** arguments and expects an integer result as if the signature of the
  6735. ** entry point where as follows:
  6736. **
  6737. ** <blockquote><pre>
  6738. ** &nbsp; int xEntryPoint(
  6739. ** &nbsp; sqlite3 *db,
  6740. ** &nbsp; const char **pzErrMsg,
  6741. ** &nbsp; const struct sqlite3_api_routines *pThunk
  6742. ** &nbsp; );
  6743. ** </pre></blockquote>)^
  6744. **
  6745. ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
  6746. ** point to an appropriate error message (obtained from [sqlite3_mprintf()])
  6747. ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
  6748. ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
  6749. ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
  6750. ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
  6751. ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
  6752. **
  6753. ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
  6754. ** on the list of automatic extensions is a harmless no-op. ^No entry point
  6755. ** will be called more than once for each database connection that is opened.
  6756. **
  6757. ** See also: [sqlite3_reset_auto_extension()]
  6758. ** and [sqlite3_cancel_auto_extension()]
  6759. */
  6760. SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
  6761. /*
  6762. ** CAPI3REF: Cancel Automatic Extension Loading
  6763. **
  6764. ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
  6765. ** initialization routine X that was registered using a prior call to
  6766. ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)]
  6767. ** routine returns 1 if initialization routine X was successfully
  6768. ** unregistered and it returns 0 if X was not on the list of initialization
  6769. ** routines.
  6770. */
  6771. SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
  6772. /*
  6773. ** CAPI3REF: Reset Automatic Extension Loading
  6774. **
  6775. ** ^This interface disables all automatic extensions previously
  6776. ** registered using [sqlite3_auto_extension()].
  6777. */
  6778. SQLITE_API void sqlite3_reset_auto_extension(void);
  6779. /*
  6780. ** The interface to the virtual-table mechanism is currently considered
  6781. ** to be experimental. The interface might change in incompatible ways.
  6782. ** If this is a problem for you, do not use the interface at this time.
  6783. **
  6784. ** When the virtual-table mechanism stabilizes, we will declare the
  6785. ** interface fixed, support it indefinitely, and remove this comment.
  6786. */
  6787. /*
  6788. ** Structures used by the virtual table interface
  6789. */
  6790. typedef struct sqlite3_vtab sqlite3_vtab;
  6791. typedef struct sqlite3_index_info sqlite3_index_info;
  6792. typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
  6793. typedef struct sqlite3_module sqlite3_module;
  6794. /*
  6795. ** CAPI3REF: Virtual Table Object
  6796. ** KEYWORDS: sqlite3_module {virtual table module}
  6797. **
  6798. ** This structure, sometimes called a "virtual table module",
  6799. ** defines the implementation of a [virtual table].
  6800. ** This structure consists mostly of methods for the module.
  6801. **
  6802. ** ^A virtual table module is created by filling in a persistent
  6803. ** instance of this structure and passing a pointer to that instance
  6804. ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
  6805. ** ^The registration remains valid until it is replaced by a different
  6806. ** module or until the [database connection] closes. The content
  6807. ** of this structure must not change while it is registered with
  6808. ** any database connection.
  6809. */
  6810. struct sqlite3_module {
  6811. int iVersion;
  6812. int (*xCreate)(sqlite3*, void *pAux,
  6813. int argc, const char *const*argv,
  6814. sqlite3_vtab **ppVTab, char**);
  6815. int (*xConnect)(sqlite3*, void *pAux,
  6816. int argc, const char *const*argv,
  6817. sqlite3_vtab **ppVTab, char**);
  6818. int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  6819. int (*xDisconnect)(sqlite3_vtab *pVTab);
  6820. int (*xDestroy)(sqlite3_vtab *pVTab);
  6821. int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  6822. int (*xClose)(sqlite3_vtab_cursor*);
  6823. int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
  6824. int argc, sqlite3_value **argv);
  6825. int (*xNext)(sqlite3_vtab_cursor*);
  6826. int (*xEof)(sqlite3_vtab_cursor*);
  6827. int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  6828. int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  6829. int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  6830. int (*xBegin)(sqlite3_vtab *pVTab);
  6831. int (*xSync)(sqlite3_vtab *pVTab);
  6832. int (*xCommit)(sqlite3_vtab *pVTab);
  6833. int (*xRollback)(sqlite3_vtab *pVTab);
  6834. int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
  6835. void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
  6836. void **ppArg);
  6837. int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  6838. /* The methods above are in version 1 of the sqlite_module object. Those
  6839. ** below are for version 2 and greater. */
  6840. int (*xSavepoint)(sqlite3_vtab *pVTab, int);
  6841. int (*xRelease)(sqlite3_vtab *pVTab, int);
  6842. int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
  6843. /* The methods above are in versions 1 and 2 of the sqlite_module object.
  6844. ** Those below are for version 3 and greater. */
  6845. int (*xShadowName)(const char*);
  6846. };
  6847. /*
  6848. ** CAPI3REF: Virtual Table Indexing Information
  6849. ** KEYWORDS: sqlite3_index_info
  6850. **
  6851. ** The sqlite3_index_info structure and its substructures is used as part
  6852. ** of the [virtual table] interface to
  6853. ** pass information into and receive the reply from the [xBestIndex]
  6854. ** method of a [virtual table module]. The fields under **Inputs** are the
  6855. ** inputs to xBestIndex and are read-only. xBestIndex inserts its
  6856. ** results into the **Outputs** fields.
  6857. **
  6858. ** ^(The aConstraint[] array records WHERE clause constraints of the form:
  6859. **
  6860. ** <blockquote>column OP expr</blockquote>
  6861. **
  6862. ** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^ ^(The particular operator is
  6863. ** stored in aConstraint[].op using one of the
  6864. ** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
  6865. ** ^(The index of the column is stored in
  6866. ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
  6867. ** expr on the right-hand side can be evaluated (and thus the constraint
  6868. ** is usable) and false if it cannot.)^
  6869. **
  6870. ** ^The optimizer automatically inverts terms of the form "expr OP column"
  6871. ** and makes other simplifications to the WHERE clause in an attempt to
  6872. ** get as many WHERE clause terms into the form shown above as possible.
  6873. ** ^The aConstraint[] array only reports WHERE clause terms that are
  6874. ** relevant to the particular virtual table being queried.
  6875. **
  6876. ** ^Information about the ORDER BY clause is stored in aOrderBy[].
  6877. ** ^Each term of aOrderBy records a column of the ORDER BY clause.
  6878. **
  6879. ** The colUsed field indicates which columns of the virtual table may be
  6880. ** required by the current scan. Virtual table columns are numbered from
  6881. ** zero in the order in which they appear within the CREATE TABLE statement
  6882. ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
  6883. ** the corresponding bit is set within the colUsed mask if the column may be
  6884. ** required by SQLite. If the table has at least 64 columns and any column
  6885. ** to the right of the first 63 is required, then bit 63 of colUsed is also
  6886. ** set. In other words, column iCol may be required if the expression
  6887. ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
  6888. ** non-zero.
  6889. **
  6890. ** The [xBestIndex] method must fill aConstraintUsage[] with information
  6891. ** about what parameters to pass to xFilter. ^If argvIndex>0 then
  6892. ** the right-hand side of the corresponding aConstraint[] is evaluated
  6893. ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
  6894. ** is true, then the constraint is assumed to be fully handled by the
  6895. ** virtual table and might not be checked again by the byte code.)^ ^(The
  6896. ** aConstraintUsage[].omit flag is an optimization hint. When the omit flag
  6897. ** is left in its default setting of false, the constraint will always be
  6898. ** checked separately in byte code. If the omit flag is change to true, then
  6899. ** the constraint may or may not be checked in byte code. In other words,
  6900. ** when the omit flag is true there is no guarantee that the constraint will
  6901. ** not be checked again using byte code.)^
  6902. **
  6903. ** ^The idxNum and idxPtr values are recorded and passed into the
  6904. ** [xFilter] method.
  6905. ** ^[sqlite3_free()] is used to free idxPtr if and only if
  6906. ** needToFreeIdxPtr is true.
  6907. **
  6908. ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
  6909. ** the correct order to satisfy the ORDER BY clause so that no separate
  6910. ** sorting step is required.
  6911. **
  6912. ** ^The estimatedCost value is an estimate of the cost of a particular
  6913. ** strategy. A cost of N indicates that the cost of the strategy is similar
  6914. ** to a linear scan of an SQLite table with N rows. A cost of log(N)
  6915. ** indicates that the expense of the operation is similar to that of a
  6916. ** binary search on a unique indexed field of an SQLite table with N rows.
  6917. **
  6918. ** ^The estimatedRows value is an estimate of the number of rows that
  6919. ** will be returned by the strategy.
  6920. **
  6921. ** The xBestIndex method may optionally populate the idxFlags field with a
  6922. ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
  6923. ** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
  6924. ** assumes that the strategy may visit at most one row.
  6925. **
  6926. ** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
  6927. ** SQLite also assumes that if a call to the xUpdate() method is made as
  6928. ** part of the same statement to delete or update a virtual table row and the
  6929. ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
  6930. ** any database changes. In other words, if the xUpdate() returns
  6931. ** SQLITE_CONSTRAINT, the database contents must be exactly as they were
  6932. ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
  6933. ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
  6934. ** the xUpdate method are automatically rolled back by SQLite.
  6935. **
  6936. ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
  6937. ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
  6938. ** If a virtual table extension is
  6939. ** used with an SQLite version earlier than 3.8.2, the results of attempting
  6940. ** to read or write the estimatedRows field are undefined (but are likely
  6941. ** to include crashing the application). The estimatedRows field should
  6942. ** therefore only be used if [sqlite3_libversion_number()] returns a
  6943. ** value greater than or equal to 3008002. Similarly, the idxFlags field
  6944. ** was added for [version 3.9.0] ([dateof:3.9.0]).
  6945. ** It may therefore only be used if
  6946. ** sqlite3_libversion_number() returns a value greater than or equal to
  6947. ** 3009000.
  6948. */
  6949. struct sqlite3_index_info {
  6950. /* Inputs */
  6951. int nConstraint; /* Number of entries in aConstraint */
  6952. struct sqlite3_index_constraint {
  6953. int iColumn; /* Column constrained. -1 for ROWID */
  6954. unsigned char op; /* Constraint operator */
  6955. unsigned char usable; /* True if this constraint is usable */
  6956. int iTermOffset; /* Used internally - xBestIndex should ignore */
  6957. } *aConstraint; /* Table of WHERE clause constraints */
  6958. int nOrderBy; /* Number of terms in the ORDER BY clause */
  6959. struct sqlite3_index_orderby {
  6960. int iColumn; /* Column number */
  6961. unsigned char desc; /* True for DESC. False for ASC. */
  6962. } *aOrderBy; /* The ORDER BY clause */
  6963. /* Outputs */
  6964. struct sqlite3_index_constraint_usage {
  6965. int argvIndex; /* if >0, constraint is part of argv to xFilter */
  6966. unsigned char omit; /* Do not code a test for this constraint */
  6967. } *aConstraintUsage;
  6968. int idxNum; /* Number used to identify the index */
  6969. char *idxStr; /* String, possibly obtained from sqlite3_malloc */
  6970. int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
  6971. int orderByConsumed; /* True if output is already ordered */
  6972. double estimatedCost; /* Estimated cost of using this index */
  6973. /* Fields below are only available in SQLite 3.8.2 and later */
  6974. sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
  6975. /* Fields below are only available in SQLite 3.9.0 and later */
  6976. int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
  6977. /* Fields below are only available in SQLite 3.10.0 and later */
  6978. sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
  6979. };
  6980. /*
  6981. ** CAPI3REF: Virtual Table Scan Flags
  6982. **
  6983. ** Virtual table implementations are allowed to set the
  6984. ** [sqlite3_index_info].idxFlags field to some combination of
  6985. ** these bits.
  6986. */
  6987. #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
  6988. /*
  6989. ** CAPI3REF: Virtual Table Constraint Operator Codes
  6990. **
  6991. ** These macros define the allowed values for the
  6992. ** [sqlite3_index_info].aConstraint[].op field. Each value represents
  6993. ** an operator that is part of a constraint term in the WHERE clause of
  6994. ** a query that uses a [virtual table].
  6995. **
  6996. ** ^The left-hand operand of the operator is given by the corresponding
  6997. ** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand
  6998. ** operand is the rowid.
  6999. ** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
  7000. ** operators have no left-hand operand, and so for those operators the
  7001. ** corresponding aConstraint[].iColumn is meaningless and should not be
  7002. ** used.
  7003. **
  7004. ** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
  7005. ** value 255 are reserved to represent functions that are overloaded
  7006. ** by the [xFindFunction|xFindFunction method] of the virtual table
  7007. ** implementation.
  7008. **
  7009. ** The right-hand operands for each constraint might be accessible using
  7010. ** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand
  7011. ** operand is only available if it appears as a single constant literal
  7012. ** in the input SQL. If the right-hand operand is another column or an
  7013. ** expression (even a constant expression) or a parameter, then the
  7014. ** sqlite3_vtab_rhs_value() probably will not be able to extract it.
  7015. ** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and
  7016. ** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
  7017. ** and hence calls to sqlite3_vtab_rhs_value() for those operators will
  7018. ** always return SQLITE_NOTFOUND.
  7019. **
  7020. ** The collating sequence to be used for comparison can be found using
  7021. ** the [sqlite3_vtab_collation()] interface. For most real-world virtual
  7022. ** tables, the collating sequence of constraints does not matter (for example
  7023. ** because the constraints are numeric) and so the sqlite3_vtab_collation()
  7024. ** interface is no commonly needed.
  7025. */
  7026. #define SQLITE_INDEX_CONSTRAINT_EQ 2
  7027. #define SQLITE_INDEX_CONSTRAINT_GT 4
  7028. #define SQLITE_INDEX_CONSTRAINT_LE 8
  7029. #define SQLITE_INDEX_CONSTRAINT_LT 16
  7030. #define SQLITE_INDEX_CONSTRAINT_GE 32
  7031. #define SQLITE_INDEX_CONSTRAINT_MATCH 64
  7032. #define SQLITE_INDEX_CONSTRAINT_LIKE 65
  7033. #define SQLITE_INDEX_CONSTRAINT_GLOB 66
  7034. #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
  7035. #define SQLITE_INDEX_CONSTRAINT_NE 68
  7036. #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
  7037. #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
  7038. #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
  7039. #define SQLITE_INDEX_CONSTRAINT_IS 72
  7040. #define SQLITE_INDEX_CONSTRAINT_LIMIT 73
  7041. #define SQLITE_INDEX_CONSTRAINT_OFFSET 74
  7042. #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
  7043. /*
  7044. ** CAPI3REF: Register A Virtual Table Implementation
  7045. ** METHOD: sqlite3
  7046. **
  7047. ** ^These routines are used to register a new [virtual table module] name.
  7048. ** ^Module names must be registered before
  7049. ** creating a new [virtual table] using the module and before using a
  7050. ** preexisting [virtual table] for the module.
  7051. **
  7052. ** ^The module name is registered on the [database connection] specified
  7053. ** by the first parameter. ^The name of the module is given by the
  7054. ** second parameter. ^The third parameter is a pointer to
  7055. ** the implementation of the [virtual table module]. ^The fourth
  7056. ** parameter is an arbitrary client data pointer that is passed through
  7057. ** into the [xCreate] and [xConnect] methods of the virtual table module
  7058. ** when a new virtual table is be being created or reinitialized.
  7059. **
  7060. ** ^The sqlite3_create_module_v2() interface has a fifth parameter which
  7061. ** is a pointer to a destructor for the pClientData. ^SQLite will
  7062. ** invoke the destructor function (if it is not NULL) when SQLite
  7063. ** no longer needs the pClientData pointer. ^The destructor will also
  7064. ** be invoked if the call to sqlite3_create_module_v2() fails.
  7065. ** ^The sqlite3_create_module()
  7066. ** interface is equivalent to sqlite3_create_module_v2() with a NULL
  7067. ** destructor.
  7068. **
  7069. ** ^If the third parameter (the pointer to the sqlite3_module object) is
  7070. ** NULL then no new module is created and any existing modules with the
  7071. ** same name are dropped.
  7072. **
  7073. ** See also: [sqlite3_drop_modules()]
  7074. */
  7075. SQLITE_API int sqlite3_create_module(
  7076. sqlite3 *db, /* SQLite connection to register module with */
  7077. const char *zName, /* Name of the module */
  7078. const sqlite3_module *p, /* Methods for the module */
  7079. void *pClientData /* Client data for xCreate/xConnect */
  7080. );
  7081. SQLITE_API int sqlite3_create_module_v2(
  7082. sqlite3 *db, /* SQLite connection to register module with */
  7083. const char *zName, /* Name of the module */
  7084. const sqlite3_module *p, /* Methods for the module */
  7085. void *pClientData, /* Client data for xCreate/xConnect */
  7086. void(*xDestroy)(void*) /* Module destructor function */
  7087. );
  7088. /*
  7089. ** CAPI3REF: Remove Unnecessary Virtual Table Implementations
  7090. ** METHOD: sqlite3
  7091. **
  7092. ** ^The sqlite3_drop_modules(D,L) interface removes all virtual
  7093. ** table modules from database connection D except those named on list L.
  7094. ** The L parameter must be either NULL or a pointer to an array of pointers
  7095. ** to strings where the array is terminated by a single NULL pointer.
  7096. ** ^If the L parameter is NULL, then all virtual table modules are removed.
  7097. **
  7098. ** See also: [sqlite3_create_module()]
  7099. */
  7100. SQLITE_API int sqlite3_drop_modules(
  7101. sqlite3 *db, /* Remove modules from this connection */
  7102. const char **azKeep /* Except, do not remove the ones named here */
  7103. );
  7104. /*
  7105. ** CAPI3REF: Virtual Table Instance Object
  7106. ** KEYWORDS: sqlite3_vtab
  7107. **
  7108. ** Every [virtual table module] implementation uses a subclass
  7109. ** of this object to describe a particular instance
  7110. ** of the [virtual table]. Each subclass will
  7111. ** be tailored to the specific needs of the module implementation.
  7112. ** The purpose of this superclass is to define certain fields that are
  7113. ** common to all module implementations.
  7114. **
  7115. ** ^Virtual tables methods can set an error message by assigning a
  7116. ** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
  7117. ** take care that any prior string is freed by a call to [sqlite3_free()]
  7118. ** prior to assigning a new string to zErrMsg. ^After the error message
  7119. ** is delivered up to the client application, the string will be automatically
  7120. ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
  7121. */
  7122. struct sqlite3_vtab {
  7123. const sqlite3_module *pModule; /* The module for this virtual table */
  7124. int nRef; /* Number of open cursors */
  7125. char *zErrMsg; /* Error message from sqlite3_mprintf() */
  7126. /* Virtual table implementations will typically add additional fields */
  7127. };
  7128. /*
  7129. ** CAPI3REF: Virtual Table Cursor Object
  7130. ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
  7131. **
  7132. ** Every [virtual table module] implementation uses a subclass of the
  7133. ** following structure to describe cursors that point into the
  7134. ** [virtual table] and are used
  7135. ** to loop through the virtual table. Cursors are created using the
  7136. ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
  7137. ** by the [sqlite3_module.xClose | xClose] method. Cursors are used
  7138. ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
  7139. ** of the module. Each module implementation will define
  7140. ** the content of a cursor structure to suit its own needs.
  7141. **
  7142. ** This superclass exists in order to define fields of the cursor that
  7143. ** are common to all implementations.
  7144. */
  7145. struct sqlite3_vtab_cursor {
  7146. sqlite3_vtab *pVtab; /* Virtual table of this cursor */
  7147. /* Virtual table implementations will typically add additional fields */
  7148. };
  7149. /*
  7150. ** CAPI3REF: Declare The Schema Of A Virtual Table
  7151. **
  7152. ** ^The [xCreate] and [xConnect] methods of a
  7153. ** [virtual table module] call this interface
  7154. ** to declare the format (the names and datatypes of the columns) of
  7155. ** the virtual tables they implement.
  7156. */
  7157. SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
  7158. /*
  7159. ** CAPI3REF: Overload A Function For A Virtual Table
  7160. ** METHOD: sqlite3
  7161. **
  7162. ** ^(Virtual tables can provide alternative implementations of functions
  7163. ** using the [xFindFunction] method of the [virtual table module].
  7164. ** But global versions of those functions
  7165. ** must exist in order to be overloaded.)^
  7166. **
  7167. ** ^(This API makes sure a global version of a function with a particular
  7168. ** name and number of parameters exists. If no such function exists
  7169. ** before this API is called, a new function is created.)^ ^The implementation
  7170. ** of the new function always causes an exception to be thrown. So
  7171. ** the new function is not good for anything by itself. Its only
  7172. ** purpose is to be a placeholder function that can be overloaded
  7173. ** by a [virtual table].
  7174. */
  7175. SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
  7176. /*
  7177. ** The interface to the virtual-table mechanism defined above (back up
  7178. ** to a comment remarkably similar to this one) is currently considered
  7179. ** to be experimental. The interface might change in incompatible ways.
  7180. ** If this is a problem for you, do not use the interface at this time.
  7181. **
  7182. ** When the virtual-table mechanism stabilizes, we will declare the
  7183. ** interface fixed, support it indefinitely, and remove this comment.
  7184. */
  7185. /*
  7186. ** CAPI3REF: A Handle To An Open BLOB
  7187. ** KEYWORDS: {BLOB handle} {BLOB handles}
  7188. **
  7189. ** An instance of this object represents an open BLOB on which
  7190. ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
  7191. ** ^Objects of this type are created by [sqlite3_blob_open()]
  7192. ** and destroyed by [sqlite3_blob_close()].
  7193. ** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
  7194. ** can be used to read or write small subsections of the BLOB.
  7195. ** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
  7196. */
  7197. typedef struct sqlite3_blob sqlite3_blob;
  7198. /*
  7199. ** CAPI3REF: Open A BLOB For Incremental I/O
  7200. ** METHOD: sqlite3
  7201. ** CONSTRUCTOR: sqlite3_blob
  7202. **
  7203. ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
  7204. ** in row iRow, column zColumn, table zTable in database zDb;
  7205. ** in other words, the same BLOB that would be selected by:
  7206. **
  7207. ** <pre>
  7208. ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
  7209. ** </pre>)^
  7210. **
  7211. ** ^(Parameter zDb is not the filename that contains the database, but
  7212. ** rather the symbolic name of the database. For attached databases, this is
  7213. ** the name that appears after the AS keyword in the [ATTACH] statement.
  7214. ** For the main database file, the database name is "main". For TEMP
  7215. ** tables, the database name is "temp".)^
  7216. **
  7217. ** ^If the flags parameter is non-zero, then the BLOB is opened for read
  7218. ** and write access. ^If the flags parameter is zero, the BLOB is opened for
  7219. ** read-only access.
  7220. **
  7221. ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
  7222. ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
  7223. ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
  7224. ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
  7225. ** on *ppBlob after this function it returns.
  7226. **
  7227. ** This function fails with SQLITE_ERROR if any of the following are true:
  7228. ** <ul>
  7229. ** <li> ^(Database zDb does not exist)^,
  7230. ** <li> ^(Table zTable does not exist within database zDb)^,
  7231. ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
  7232. ** <li> ^(Column zColumn does not exist)^,
  7233. ** <li> ^(Row iRow is not present in the table)^,
  7234. ** <li> ^(The specified column of row iRow contains a value that is not
  7235. ** a TEXT or BLOB value)^,
  7236. ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
  7237. ** constraint and the blob is being opened for read/write access)^,
  7238. ** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
  7239. ** column zColumn is part of a [child key] definition and the blob is
  7240. ** being opened for read/write access)^.
  7241. ** </ul>
  7242. **
  7243. ** ^Unless it returns SQLITE_MISUSE, this function sets the
  7244. ** [database connection] error code and message accessible via
  7245. ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
  7246. **
  7247. ** A BLOB referenced by sqlite3_blob_open() may be read using the
  7248. ** [sqlite3_blob_read()] interface and modified by using
  7249. ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
  7250. ** different row of the same table using the [sqlite3_blob_reopen()]
  7251. ** interface. However, the column, table, or database of a [BLOB handle]
  7252. ** cannot be changed after the [BLOB handle] is opened.
  7253. **
  7254. ** ^(If the row that a BLOB handle points to is modified by an
  7255. ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
  7256. ** then the BLOB handle is marked as "expired".
  7257. ** This is true if any column of the row is changed, even a column
  7258. ** other than the one the BLOB handle is open on.)^
  7259. ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
  7260. ** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
  7261. ** ^(Changes written into a BLOB prior to the BLOB expiring are not
  7262. ** rolled back by the expiration of the BLOB. Such changes will eventually
  7263. ** commit if the transaction continues to completion.)^
  7264. **
  7265. ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
  7266. ** the opened blob. ^The size of a blob may not be changed by this
  7267. ** interface. Use the [UPDATE] SQL command to change the size of a
  7268. ** blob.
  7269. **
  7270. ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
  7271. ** and the built-in [zeroblob] SQL function may be used to create a
  7272. ** zero-filled blob to read or write using the incremental-blob interface.
  7273. **
  7274. ** To avoid a resource leak, every open [BLOB handle] should eventually
  7275. ** be released by a call to [sqlite3_blob_close()].
  7276. **
  7277. ** See also: [sqlite3_blob_close()],
  7278. ** [sqlite3_blob_reopen()], [sqlite3_blob_read()],
  7279. ** [sqlite3_blob_bytes()], [sqlite3_blob_write()].
  7280. */
  7281. SQLITE_API int sqlite3_blob_open(
  7282. sqlite3*,
  7283. const char *zDb,
  7284. const char *zTable,
  7285. const char *zColumn,
  7286. sqlite3_int64 iRow,
  7287. int flags,
  7288. sqlite3_blob **ppBlob
  7289. );
  7290. /*
  7291. ** CAPI3REF: Move a BLOB Handle to a New Row
  7292. ** METHOD: sqlite3_blob
  7293. **
  7294. ** ^This function is used to move an existing [BLOB handle] so that it points
  7295. ** to a different row of the same database table. ^The new row is identified
  7296. ** by the rowid value passed as the second argument. Only the row can be
  7297. ** changed. ^The database, table and column on which the blob handle is open
  7298. ** remain the same. Moving an existing [BLOB handle] to a new row is
  7299. ** faster than closing the existing handle and opening a new one.
  7300. **
  7301. ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
  7302. ** it must exist and there must be either a blob or text value stored in
  7303. ** the nominated column.)^ ^If the new row is not present in the table, or if
  7304. ** it does not contain a blob or text value, or if another error occurs, an
  7305. ** SQLite error code is returned and the blob handle is considered aborted.
  7306. ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
  7307. ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
  7308. ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
  7309. ** always returns zero.
  7310. **
  7311. ** ^This function sets the database handle error code and message.
  7312. */
  7313. SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
  7314. /*
  7315. ** CAPI3REF: Close A BLOB Handle
  7316. ** DESTRUCTOR: sqlite3_blob
  7317. **
  7318. ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
  7319. ** unconditionally. Even if this routine returns an error code, the
  7320. ** handle is still closed.)^
  7321. **
  7322. ** ^If the blob handle being closed was opened for read-write access, and if
  7323. ** the database is in auto-commit mode and there are no other open read-write
  7324. ** blob handles or active write statements, the current transaction is
  7325. ** committed. ^If an error occurs while committing the transaction, an error
  7326. ** code is returned and the transaction rolled back.
  7327. **
  7328. ** Calling this function with an argument that is not a NULL pointer or an
  7329. ** open blob handle results in undefined behaviour. ^Calling this routine
  7330. ** with a null pointer (such as would be returned by a failed call to
  7331. ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
  7332. ** is passed a valid open blob handle, the values returned by the
  7333. ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
  7334. */
  7335. SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
  7336. /*
  7337. ** CAPI3REF: Return The Size Of An Open BLOB
  7338. ** METHOD: sqlite3_blob
  7339. **
  7340. ** ^Returns the size in bytes of the BLOB accessible via the
  7341. ** successfully opened [BLOB handle] in its only argument. ^The
  7342. ** incremental blob I/O routines can only read or overwriting existing
  7343. ** blob content; they cannot change the size of a blob.
  7344. **
  7345. ** This routine only works on a [BLOB handle] which has been created
  7346. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  7347. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  7348. ** to this routine results in undefined and probably undesirable behavior.
  7349. */
  7350. SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
  7351. /*
  7352. ** CAPI3REF: Read Data From A BLOB Incrementally
  7353. ** METHOD: sqlite3_blob
  7354. **
  7355. ** ^(This function is used to read data from an open [BLOB handle] into a
  7356. ** caller-supplied buffer. N bytes of data are copied into buffer Z
  7357. ** from the open BLOB, starting at offset iOffset.)^
  7358. **
  7359. ** ^If offset iOffset is less than N bytes from the end of the BLOB,
  7360. ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
  7361. ** less than zero, [SQLITE_ERROR] is returned and no data is read.
  7362. ** ^The size of the blob (and hence the maximum value of N+iOffset)
  7363. ** can be determined using the [sqlite3_blob_bytes()] interface.
  7364. **
  7365. ** ^An attempt to read from an expired [BLOB handle] fails with an
  7366. ** error code of [SQLITE_ABORT].
  7367. **
  7368. ** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
  7369. ** Otherwise, an [error code] or an [extended error code] is returned.)^
  7370. **
  7371. ** This routine only works on a [BLOB handle] which has been created
  7372. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  7373. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  7374. ** to this routine results in undefined and probably undesirable behavior.
  7375. **
  7376. ** See also: [sqlite3_blob_write()].
  7377. */
  7378. SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
  7379. /*
  7380. ** CAPI3REF: Write Data Into A BLOB Incrementally
  7381. ** METHOD: sqlite3_blob
  7382. **
  7383. ** ^(This function is used to write data into an open [BLOB handle] from a
  7384. ** caller-supplied buffer. N bytes of data are copied from the buffer Z
  7385. ** into the open BLOB, starting at offset iOffset.)^
  7386. **
  7387. ** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
  7388. ** Otherwise, an [error code] or an [extended error code] is returned.)^
  7389. ** ^Unless SQLITE_MISUSE is returned, this function sets the
  7390. ** [database connection] error code and message accessible via
  7391. ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
  7392. **
  7393. ** ^If the [BLOB handle] passed as the first argument was not opened for
  7394. ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
  7395. ** this function returns [SQLITE_READONLY].
  7396. **
  7397. ** This function may only modify the contents of the BLOB; it is
  7398. ** not possible to increase the size of a BLOB using this API.
  7399. ** ^If offset iOffset is less than N bytes from the end of the BLOB,
  7400. ** [SQLITE_ERROR] is returned and no data is written. The size of the
  7401. ** BLOB (and hence the maximum value of N+iOffset) can be determined
  7402. ** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
  7403. ** than zero [SQLITE_ERROR] is returned and no data is written.
  7404. **
  7405. ** ^An attempt to write to an expired [BLOB handle] fails with an
  7406. ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
  7407. ** before the [BLOB handle] expired are not rolled back by the
  7408. ** expiration of the handle, though of course those changes might
  7409. ** have been overwritten by the statement that expired the BLOB handle
  7410. ** or by other independent statements.
  7411. **
  7412. ** This routine only works on a [BLOB handle] which has been created
  7413. ** by a prior successful call to [sqlite3_blob_open()] and which has not
  7414. ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
  7415. ** to this routine results in undefined and probably undesirable behavior.
  7416. **
  7417. ** See also: [sqlite3_blob_read()].
  7418. */
  7419. SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  7420. /*
  7421. ** CAPI3REF: Virtual File System Objects
  7422. **
  7423. ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
  7424. ** that SQLite uses to interact
  7425. ** with the underlying operating system. Most SQLite builds come with a
  7426. ** single default VFS that is appropriate for the host computer.
  7427. ** New VFSes can be registered and existing VFSes can be unregistered.
  7428. ** The following interfaces are provided.
  7429. **
  7430. ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
  7431. ** ^Names are case sensitive.
  7432. ** ^Names are zero-terminated UTF-8 strings.
  7433. ** ^If there is no match, a NULL pointer is returned.
  7434. ** ^If zVfsName is NULL then the default VFS is returned.
  7435. **
  7436. ** ^New VFSes are registered with sqlite3_vfs_register().
  7437. ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
  7438. ** ^The same VFS can be registered multiple times without injury.
  7439. ** ^To make an existing VFS into the default VFS, register it again
  7440. ** with the makeDflt flag set. If two different VFSes with the
  7441. ** same name are registered, the behavior is undefined. If a
  7442. ** VFS is registered with a name that is NULL or an empty string,
  7443. ** then the behavior is undefined.
  7444. **
  7445. ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
  7446. ** ^(If the default VFS is unregistered, another VFS is chosen as
  7447. ** the default. The choice for the new VFS is arbitrary.)^
  7448. */
  7449. SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
  7450. SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
  7451. SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
  7452. /*
  7453. ** CAPI3REF: Mutexes
  7454. **
  7455. ** The SQLite core uses these routines for thread
  7456. ** synchronization. Though they are intended for internal
  7457. ** use by SQLite, code that links against SQLite is
  7458. ** permitted to use any of these routines.
  7459. **
  7460. ** The SQLite source code contains multiple implementations
  7461. ** of these mutex routines. An appropriate implementation
  7462. ** is selected automatically at compile-time. The following
  7463. ** implementations are available in the SQLite core:
  7464. **
  7465. ** <ul>
  7466. ** <li> SQLITE_MUTEX_PTHREADS
  7467. ** <li> SQLITE_MUTEX_W32
  7468. ** <li> SQLITE_MUTEX_NOOP
  7469. ** </ul>
  7470. **
  7471. ** The SQLITE_MUTEX_NOOP implementation is a set of routines
  7472. ** that does no real locking and is appropriate for use in
  7473. ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
  7474. ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
  7475. ** and Windows.
  7476. **
  7477. ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
  7478. ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
  7479. ** implementation is included with the library. In this case the
  7480. ** application must supply a custom mutex implementation using the
  7481. ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
  7482. ** before calling sqlite3_initialize() or any other public sqlite3_
  7483. ** function that calls sqlite3_initialize().
  7484. **
  7485. ** ^The sqlite3_mutex_alloc() routine allocates a new
  7486. ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
  7487. ** routine returns NULL if it is unable to allocate the requested
  7488. ** mutex. The argument to sqlite3_mutex_alloc() must one of these
  7489. ** integer constants:
  7490. **
  7491. ** <ul>
  7492. ** <li> SQLITE_MUTEX_FAST
  7493. ** <li> SQLITE_MUTEX_RECURSIVE
  7494. ** <li> SQLITE_MUTEX_STATIC_MAIN
  7495. ** <li> SQLITE_MUTEX_STATIC_MEM
  7496. ** <li> SQLITE_MUTEX_STATIC_OPEN
  7497. ** <li> SQLITE_MUTEX_STATIC_PRNG
  7498. ** <li> SQLITE_MUTEX_STATIC_LRU
  7499. ** <li> SQLITE_MUTEX_STATIC_PMEM
  7500. ** <li> SQLITE_MUTEX_STATIC_APP1
  7501. ** <li> SQLITE_MUTEX_STATIC_APP2
  7502. ** <li> SQLITE_MUTEX_STATIC_APP3
  7503. ** <li> SQLITE_MUTEX_STATIC_VFS1
  7504. ** <li> SQLITE_MUTEX_STATIC_VFS2
  7505. ** <li> SQLITE_MUTEX_STATIC_VFS3
  7506. ** </ul>
  7507. **
  7508. ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
  7509. ** cause sqlite3_mutex_alloc() to create
  7510. ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
  7511. ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
  7512. ** The mutex implementation does not need to make a distinction
  7513. ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
  7514. ** not want to. SQLite will only request a recursive mutex in
  7515. ** cases where it really needs one. If a faster non-recursive mutex
  7516. ** implementation is available on the host platform, the mutex subsystem
  7517. ** might return such a mutex in response to SQLITE_MUTEX_FAST.
  7518. **
  7519. ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
  7520. ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
  7521. ** a pointer to a static preexisting mutex. ^Nine static mutexes are
  7522. ** used by the current version of SQLite. Future versions of SQLite
  7523. ** may add additional static mutexes. Static mutexes are for internal
  7524. ** use by SQLite only. Applications that use SQLite mutexes should
  7525. ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
  7526. ** SQLITE_MUTEX_RECURSIVE.
  7527. **
  7528. ** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
  7529. ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
  7530. ** returns a different mutex on every call. ^For the static
  7531. ** mutex types, the same mutex is returned on every call that has
  7532. ** the same type number.
  7533. **
  7534. ** ^The sqlite3_mutex_free() routine deallocates a previously
  7535. ** allocated dynamic mutex. Attempting to deallocate a static
  7536. ** mutex results in undefined behavior.
  7537. **
  7538. ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
  7539. ** to enter a mutex. ^If another thread is already within the mutex,
  7540. ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
  7541. ** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
  7542. ** upon successful entry. ^(Mutexes created using
  7543. ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
  7544. ** In such cases, the
  7545. ** mutex must be exited an equal number of times before another thread
  7546. ** can enter.)^ If the same thread tries to enter any mutex other
  7547. ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
  7548. **
  7549. ** ^(Some systems (for example, Windows 95) do not support the operation
  7550. ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
  7551. ** will always return SQLITE_BUSY. The SQLite core only ever uses
  7552. ** sqlite3_mutex_try() as an optimization so this is acceptable
  7553. ** behavior.)^
  7554. **
  7555. ** ^The sqlite3_mutex_leave() routine exits a mutex that was
  7556. ** previously entered by the same thread. The behavior
  7557. ** is undefined if the mutex is not currently entered by the
  7558. ** calling thread or is not currently allocated.
  7559. **
  7560. ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
  7561. ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
  7562. ** behave as no-ops.
  7563. **
  7564. ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
  7565. */
  7566. SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
  7567. SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
  7568. SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
  7569. SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
  7570. SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
  7571. /*
  7572. ** CAPI3REF: Mutex Methods Object
  7573. **
  7574. ** An instance of this structure defines the low-level routines
  7575. ** used to allocate and use mutexes.
  7576. **
  7577. ** Usually, the default mutex implementations provided by SQLite are
  7578. ** sufficient, however the application has the option of substituting a custom
  7579. ** implementation for specialized deployments or systems for which SQLite
  7580. ** does not provide a suitable implementation. In this case, the application
  7581. ** creates and populates an instance of this structure to pass
  7582. ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
  7583. ** Additionally, an instance of this structure can be used as an
  7584. ** output variable when querying the system for the current mutex
  7585. ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
  7586. **
  7587. ** ^The xMutexInit method defined by this structure is invoked as
  7588. ** part of system initialization by the sqlite3_initialize() function.
  7589. ** ^The xMutexInit routine is called by SQLite exactly once for each
  7590. ** effective call to [sqlite3_initialize()].
  7591. **
  7592. ** ^The xMutexEnd method defined by this structure is invoked as
  7593. ** part of system shutdown by the sqlite3_shutdown() function. The
  7594. ** implementation of this method is expected to release all outstanding
  7595. ** resources obtained by the mutex methods implementation, especially
  7596. ** those obtained by the xMutexInit method. ^The xMutexEnd()
  7597. ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
  7598. **
  7599. ** ^(The remaining seven methods defined by this structure (xMutexAlloc,
  7600. ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
  7601. ** xMutexNotheld) implement the following interfaces (respectively):
  7602. **
  7603. ** <ul>
  7604. ** <li> [sqlite3_mutex_alloc()] </li>
  7605. ** <li> [sqlite3_mutex_free()] </li>
  7606. ** <li> [sqlite3_mutex_enter()] </li>
  7607. ** <li> [sqlite3_mutex_try()] </li>
  7608. ** <li> [sqlite3_mutex_leave()] </li>
  7609. ** <li> [sqlite3_mutex_held()] </li>
  7610. ** <li> [sqlite3_mutex_notheld()] </li>
  7611. ** </ul>)^
  7612. **
  7613. ** The only difference is that the public sqlite3_XXX functions enumerated
  7614. ** above silently ignore any invocations that pass a NULL pointer instead
  7615. ** of a valid mutex handle. The implementations of the methods defined
  7616. ** by this structure are not required to handle this case. The results
  7617. ** of passing a NULL pointer instead of a valid mutex handle are undefined
  7618. ** (i.e. it is acceptable to provide an implementation that segfaults if
  7619. ** it is passed a NULL pointer).
  7620. **
  7621. ** The xMutexInit() method must be threadsafe. It must be harmless to
  7622. ** invoke xMutexInit() multiple times within the same process and without
  7623. ** intervening calls to xMutexEnd(). Second and subsequent calls to
  7624. ** xMutexInit() must be no-ops.
  7625. **
  7626. ** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
  7627. ** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
  7628. ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
  7629. ** memory allocation for a fast or recursive mutex.
  7630. **
  7631. ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
  7632. ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
  7633. ** If xMutexInit fails in any way, it is expected to clean up after itself
  7634. ** prior to returning.
  7635. */
  7636. typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
  7637. struct sqlite3_mutex_methods {
  7638. int (*xMutexInit)(void);
  7639. int (*xMutexEnd)(void);
  7640. sqlite3_mutex *(*xMutexAlloc)(int);
  7641. void (*xMutexFree)(sqlite3_mutex *);
  7642. void (*xMutexEnter)(sqlite3_mutex *);
  7643. int (*xMutexTry)(sqlite3_mutex *);
  7644. void (*xMutexLeave)(sqlite3_mutex *);
  7645. int (*xMutexHeld)(sqlite3_mutex *);
  7646. int (*xMutexNotheld)(sqlite3_mutex *);
  7647. };
  7648. /*
  7649. ** CAPI3REF: Mutex Verification Routines
  7650. **
  7651. ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
  7652. ** are intended for use inside assert() statements. The SQLite core
  7653. ** never uses these routines except inside an assert() and applications
  7654. ** are advised to follow the lead of the core. The SQLite core only
  7655. ** provides implementations for these routines when it is compiled
  7656. ** with the SQLITE_DEBUG flag. External mutex implementations
  7657. ** are only required to provide these routines if SQLITE_DEBUG is
  7658. ** defined and if NDEBUG is not defined.
  7659. **
  7660. ** These routines should return true if the mutex in their argument
  7661. ** is held or not held, respectively, by the calling thread.
  7662. **
  7663. ** The implementation is not required to provide versions of these
  7664. ** routines that actually work. If the implementation does not provide working
  7665. ** versions of these routines, it should at least provide stubs that always
  7666. ** return true so that one does not get spurious assertion failures.
  7667. **
  7668. ** If the argument to sqlite3_mutex_held() is a NULL pointer then
  7669. ** the routine should return 1. This seems counter-intuitive since
  7670. ** clearly the mutex cannot be held if it does not exist. But
  7671. ** the reason the mutex does not exist is because the build is not
  7672. ** using mutexes. And we do not want the assert() containing the
  7673. ** call to sqlite3_mutex_held() to fail, so a non-zero return is
  7674. ** the appropriate thing to do. The sqlite3_mutex_notheld()
  7675. ** interface should also return 1 when given a NULL pointer.
  7676. */
  7677. #ifndef NDEBUG
  7678. SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
  7679. SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
  7680. #endif
  7681. /*
  7682. ** CAPI3REF: Mutex Types
  7683. **
  7684. ** The [sqlite3_mutex_alloc()] interface takes a single argument
  7685. ** which is one of these integer constants.
  7686. **
  7687. ** The set of static mutexes may change from one SQLite release to the
  7688. ** next. Applications that override the built-in mutex logic must be
  7689. ** prepared to accommodate additional static mutexes.
  7690. */
  7691. #define SQLITE_MUTEX_FAST 0
  7692. #define SQLITE_MUTEX_RECURSIVE 1
  7693. #define SQLITE_MUTEX_STATIC_MAIN 2
  7694. #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
  7695. #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
  7696. #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
  7697. #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
  7698. #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
  7699. #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
  7700. #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
  7701. #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
  7702. #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
  7703. #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
  7704. #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
  7705. #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
  7706. #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
  7707. /* Legacy compatibility: */
  7708. #define SQLITE_MUTEX_STATIC_MASTER 2
  7709. /*
  7710. ** CAPI3REF: Retrieve the mutex for a database connection
  7711. ** METHOD: sqlite3
  7712. **
  7713. ** ^This interface returns a pointer the [sqlite3_mutex] object that
  7714. ** serializes access to the [database connection] given in the argument
  7715. ** when the [threading mode] is Serialized.
  7716. ** ^If the [threading mode] is Single-thread or Multi-thread then this
  7717. ** routine returns a NULL pointer.
  7718. */
  7719. SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
  7720. /*
  7721. ** CAPI3REF: Low-Level Control Of Database Files
  7722. ** METHOD: sqlite3
  7723. ** KEYWORDS: {file control}
  7724. **
  7725. ** ^The [sqlite3_file_control()] interface makes a direct call to the
  7726. ** xFileControl method for the [sqlite3_io_methods] object associated
  7727. ** with a particular database identified by the second argument. ^The
  7728. ** name of the database is "main" for the main database or "temp" for the
  7729. ** TEMP database, or the name that appears after the AS keyword for
  7730. ** databases that are added using the [ATTACH] SQL command.
  7731. ** ^A NULL pointer can be used in place of "main" to refer to the
  7732. ** main database file.
  7733. ** ^The third and fourth parameters to this routine
  7734. ** are passed directly through to the second and third parameters of
  7735. ** the xFileControl method. ^The return value of the xFileControl
  7736. ** method becomes the return value of this routine.
  7737. **
  7738. ** A few opcodes for [sqlite3_file_control()] are handled directly
  7739. ** by the SQLite core and never invoke the
  7740. ** sqlite3_io_methods.xFileControl method.
  7741. ** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes
  7742. ** a pointer to the underlying [sqlite3_file] object to be written into
  7743. ** the space pointed to by the 4th parameter. The
  7744. ** [SQLITE_FCNTL_JOURNAL_POINTER] works similarly except that it returns
  7745. ** the [sqlite3_file] object associated with the journal file instead of
  7746. ** the main database. The [SQLITE_FCNTL_VFS_POINTER] opcode returns
  7747. ** a pointer to the underlying [sqlite3_vfs] object for the file.
  7748. ** The [SQLITE_FCNTL_DATA_VERSION] returns the data version counter
  7749. ** from the pager.
  7750. **
  7751. ** ^If the second parameter (zDbName) does not match the name of any
  7752. ** open database file, then SQLITE_ERROR is returned. ^This error
  7753. ** code is not remembered and will not be recalled by [sqlite3_errcode()]
  7754. ** or [sqlite3_errmsg()]. The underlying xFileControl method might
  7755. ** also return SQLITE_ERROR. There is no way to distinguish between
  7756. ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
  7757. ** xFileControl method.
  7758. **
  7759. ** See also: [file control opcodes]
  7760. */
  7761. SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
  7762. /*
  7763. ** CAPI3REF: Testing Interface
  7764. **
  7765. ** ^The sqlite3_test_control() interface is used to read out internal
  7766. ** state of SQLite and to inject faults into SQLite for testing
  7767. ** purposes. ^The first parameter is an operation code that determines
  7768. ** the number, meaning, and operation of all subsequent parameters.
  7769. **
  7770. ** This interface is not for use by applications. It exists solely
  7771. ** for verifying the correct operation of the SQLite library. Depending
  7772. ** on how the SQLite library is compiled, this interface might not exist.
  7773. **
  7774. ** The details of the operation codes, their meanings, the parameters
  7775. ** they take, and what they do are all subject to change without notice.
  7776. ** Unlike most of the SQLite API, this function is not guaranteed to
  7777. ** operate consistently from one release to the next.
  7778. */
  7779. SQLITE_API int sqlite3_test_control(int op, ...);
  7780. /*
  7781. ** CAPI3REF: Testing Interface Operation Codes
  7782. **
  7783. ** These constants are the valid operation code parameters used
  7784. ** as the first argument to [sqlite3_test_control()].
  7785. **
  7786. ** These parameters and their meanings are subject to change
  7787. ** without notice. These values are for testing purposes only.
  7788. ** Applications should not use any of these parameters or the
  7789. ** [sqlite3_test_control()] interface.
  7790. */
  7791. #define SQLITE_TESTCTRL_FIRST 5
  7792. #define SQLITE_TESTCTRL_PRNG_SAVE 5
  7793. #define SQLITE_TESTCTRL_PRNG_RESTORE 6
  7794. #define SQLITE_TESTCTRL_PRNG_RESET 7 /* NOT USED */
  7795. #define SQLITE_TESTCTRL_BITVEC_TEST 8
  7796. #define SQLITE_TESTCTRL_FAULT_INSTALL 9
  7797. #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
  7798. #define SQLITE_TESTCTRL_PENDING_BYTE 11
  7799. #define SQLITE_TESTCTRL_ASSERT 12
  7800. #define SQLITE_TESTCTRL_ALWAYS 13
  7801. #define SQLITE_TESTCTRL_RESERVE 14 /* NOT USED */
  7802. #define SQLITE_TESTCTRL_OPTIMIZATIONS 15
  7803. #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */
  7804. #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
  7805. #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17
  7806. #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
  7807. #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
  7808. #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
  7809. #define SQLITE_TESTCTRL_NEVER_CORRUPT 20
  7810. #define SQLITE_TESTCTRL_VDBE_COVERAGE 21
  7811. #define SQLITE_TESTCTRL_BYTEORDER 22
  7812. #define SQLITE_TESTCTRL_ISINIT 23
  7813. #define SQLITE_TESTCTRL_SORTER_MMAP 24
  7814. #define SQLITE_TESTCTRL_IMPOSTER 25
  7815. #define SQLITE_TESTCTRL_PARSER_COVERAGE 26
  7816. #define SQLITE_TESTCTRL_RESULT_INTREAL 27
  7817. #define SQLITE_TESTCTRL_PRNG_SEED 28
  7818. #define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29
  7819. #define SQLITE_TESTCTRL_SEEK_COUNT 30
  7820. #define SQLITE_TESTCTRL_TRACEFLAGS 31
  7821. #define SQLITE_TESTCTRL_TUNE 32
  7822. #define SQLITE_TESTCTRL_LOGEST 33
  7823. #define SQLITE_TESTCTRL_LAST 33 /* Largest TESTCTRL */
  7824. /*
  7825. ** CAPI3REF: SQL Keyword Checking
  7826. **
  7827. ** These routines provide access to the set of SQL language keywords
  7828. ** recognized by SQLite. Applications can uses these routines to determine
  7829. ** whether or not a specific identifier needs to be escaped (for example,
  7830. ** by enclosing in double-quotes) so as not to confuse the parser.
  7831. **
  7832. ** The sqlite3_keyword_count() interface returns the number of distinct
  7833. ** keywords understood by SQLite.
  7834. **
  7835. ** The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and
  7836. ** makes *Z point to that keyword expressed as UTF8 and writes the number
  7837. ** of bytes in the keyword into *L. The string that *Z points to is not
  7838. ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
  7839. ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
  7840. ** or L are NULL or invalid pointers then calls to
  7841. ** sqlite3_keyword_name(N,Z,L) result in undefined behavior.
  7842. **
  7843. ** The sqlite3_keyword_check(Z,L) interface checks to see whether or not
  7844. ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
  7845. ** if it is and zero if not.
  7846. **
  7847. ** The parser used by SQLite is forgiving. It is often possible to use
  7848. ** a keyword as an identifier as long as such use does not result in a
  7849. ** parsing ambiguity. For example, the statement
  7850. ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
  7851. ** creates a new table named "BEGIN" with three columns named
  7852. ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
  7853. ** using keywords as identifiers. Common techniques used to avoid keyword
  7854. ** name collisions include:
  7855. ** <ul>
  7856. ** <li> Put all identifier names inside double-quotes. This is the official
  7857. ** SQL way to escape identifier names.
  7858. ** <li> Put identifier names inside &#91;...&#93;. This is not standard SQL,
  7859. ** but it is what SQL Server does and so lots of programmers use this
  7860. ** technique.
  7861. ** <li> Begin every identifier with the letter "Z" as no SQL keywords start
  7862. ** with "Z".
  7863. ** <li> Include a digit somewhere in every identifier name.
  7864. ** </ul>
  7865. **
  7866. ** Note that the number of keywords understood by SQLite can depend on
  7867. ** compile-time options. For example, "VACUUM" is not a keyword if
  7868. ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
  7869. ** new keywords may be added to future releases of SQLite.
  7870. */
  7871. SQLITE_API int sqlite3_keyword_count(void);
  7872. SQLITE_API int sqlite3_keyword_name(int,const char**,int*);
  7873. SQLITE_API int sqlite3_keyword_check(const char*,int);
  7874. /*
  7875. ** CAPI3REF: Dynamic String Object
  7876. ** KEYWORDS: {dynamic string}
  7877. **
  7878. ** An instance of the sqlite3_str object contains a dynamically-sized
  7879. ** string under construction.
  7880. **
  7881. ** The lifecycle of an sqlite3_str object is as follows:
  7882. ** <ol>
  7883. ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
  7884. ** <li> ^Text is appended to the sqlite3_str object using various
  7885. ** methods, such as [sqlite3_str_appendf()].
  7886. ** <li> ^The sqlite3_str object is destroyed and the string it created
  7887. ** is returned using the [sqlite3_str_finish()] interface.
  7888. ** </ol>
  7889. */
  7890. typedef struct sqlite3_str sqlite3_str;
  7891. /*
  7892. ** CAPI3REF: Create A New Dynamic String Object
  7893. ** CONSTRUCTOR: sqlite3_str
  7894. **
  7895. ** ^The [sqlite3_str_new(D)] interface allocates and initializes
  7896. ** a new [sqlite3_str] object. To avoid memory leaks, the object returned by
  7897. ** [sqlite3_str_new()] must be freed by a subsequent call to
  7898. ** [sqlite3_str_finish(X)].
  7899. **
  7900. ** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
  7901. ** valid [sqlite3_str] object, though in the event of an out-of-memory
  7902. ** error the returned object might be a special singleton that will
  7903. ** silently reject new text, always return SQLITE_NOMEM from
  7904. ** [sqlite3_str_errcode()], always return 0 for
  7905. ** [sqlite3_str_length()], and always return NULL from
  7906. ** [sqlite3_str_finish(X)]. It is always safe to use the value
  7907. ** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter
  7908. ** to any of the other [sqlite3_str] methods.
  7909. **
  7910. ** The D parameter to [sqlite3_str_new(D)] may be NULL. If the
  7911. ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
  7912. ** length of the string contained in the [sqlite3_str] object will be
  7913. ** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead
  7914. ** of [SQLITE_MAX_LENGTH].
  7915. */
  7916. SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);
  7917. /*
  7918. ** CAPI3REF: Finalize A Dynamic String
  7919. ** DESTRUCTOR: sqlite3_str
  7920. **
  7921. ** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X
  7922. ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
  7923. ** that contains the constructed string. The calling application should
  7924. ** pass the returned value to [sqlite3_free()] to avoid a memory leak.
  7925. ** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any
  7926. ** errors were encountered during construction of the string. ^The
  7927. ** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the
  7928. ** string in [sqlite3_str] object X is zero bytes long.
  7929. */
  7930. SQLITE_API char *sqlite3_str_finish(sqlite3_str*);
  7931. /*
  7932. ** CAPI3REF: Add Content To A Dynamic String
  7933. ** METHOD: sqlite3_str
  7934. **
  7935. ** These interfaces add content to an sqlite3_str object previously obtained
  7936. ** from [sqlite3_str_new()].
  7937. **
  7938. ** ^The [sqlite3_str_appendf(X,F,...)] and
  7939. ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
  7940. ** functionality of SQLite to append formatted text onto the end of
  7941. ** [sqlite3_str] object X.
  7942. **
  7943. ** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S
  7944. ** onto the end of the [sqlite3_str] object X. N must be non-negative.
  7945. ** S must contain at least N non-zero bytes of content. To append a
  7946. ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
  7947. ** method instead.
  7948. **
  7949. ** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of
  7950. ** zero-terminated string S onto the end of [sqlite3_str] object X.
  7951. **
  7952. ** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the
  7953. ** single-byte character C onto the end of [sqlite3_str] object X.
  7954. ** ^This method can be used, for example, to add whitespace indentation.
  7955. **
  7956. ** ^The [sqlite3_str_reset(X)] method resets the string under construction
  7957. ** inside [sqlite3_str] object X back to zero bytes in length.
  7958. **
  7959. ** These methods do not return a result code. ^If an error occurs, that fact
  7960. ** is recorded in the [sqlite3_str] object and can be recovered by a
  7961. ** subsequent call to [sqlite3_str_errcode(X)].
  7962. */
  7963. SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
  7964. SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
  7965. SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
  7966. SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
  7967. SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
  7968. SQLITE_API void sqlite3_str_reset(sqlite3_str*);
  7969. /*
  7970. ** CAPI3REF: Status Of A Dynamic String
  7971. ** METHOD: sqlite3_str
  7972. **
  7973. ** These interfaces return the current status of an [sqlite3_str] object.
  7974. **
  7975. ** ^If any prior errors have occurred while constructing the dynamic string
  7976. ** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return
  7977. ** an appropriate error code. ^The [sqlite3_str_errcode(X)] method returns
  7978. ** [SQLITE_NOMEM] following any out-of-memory error, or
  7979. ** [SQLITE_TOOBIG] if the size of the dynamic string exceeds
  7980. ** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors.
  7981. **
  7982. ** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,
  7983. ** of the dynamic string under construction in [sqlite3_str] object X.
  7984. ** ^The length returned by [sqlite3_str_length(X)] does not include the
  7985. ** zero-termination byte.
  7986. **
  7987. ** ^The [sqlite3_str_value(X)] method returns a pointer to the current
  7988. ** content of the dynamic string under construction in X. The value
  7989. ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
  7990. ** and might be freed or altered by any subsequent method on the same
  7991. ** [sqlite3_str] object. Applications must not used the pointer returned
  7992. ** [sqlite3_str_value(X)] after any subsequent method call on the same
  7993. ** object. ^Applications may change the content of the string returned
  7994. ** by [sqlite3_str_value(X)] as long as they do not write into any bytes
  7995. ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
  7996. ** write any byte after any subsequent sqlite3_str method call.
  7997. */
  7998. SQLITE_API int sqlite3_str_errcode(sqlite3_str*);
  7999. SQLITE_API int sqlite3_str_length(sqlite3_str*);
  8000. SQLITE_API char *sqlite3_str_value(sqlite3_str*);
  8001. /*
  8002. ** CAPI3REF: SQLite Runtime Status
  8003. **
  8004. ** ^These interfaces are used to retrieve runtime status information
  8005. ** about the performance of SQLite, and optionally to reset various
  8006. ** highwater marks. ^The first argument is an integer code for
  8007. ** the specific parameter to measure. ^(Recognized integer codes
  8008. ** are of the form [status parameters | SQLITE_STATUS_...].)^
  8009. ** ^The current value of the parameter is returned into *pCurrent.
  8010. ** ^The highest recorded value is returned in *pHighwater. ^If the
  8011. ** resetFlag is true, then the highest record value is reset after
  8012. ** *pHighwater is written. ^(Some parameters do not record the highest
  8013. ** value. For those parameters
  8014. ** nothing is written into *pHighwater and the resetFlag is ignored.)^
  8015. ** ^(Other parameters record only the highwater mark and not the current
  8016. ** value. For these latter parameters nothing is written into *pCurrent.)^
  8017. **
  8018. ** ^The sqlite3_status() and sqlite3_status64() routines return
  8019. ** SQLITE_OK on success and a non-zero [error code] on failure.
  8020. **
  8021. ** If either the current value or the highwater mark is too large to
  8022. ** be represented by a 32-bit integer, then the values returned by
  8023. ** sqlite3_status() are undefined.
  8024. **
  8025. ** See also: [sqlite3_db_status()]
  8026. */
  8027. SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
  8028. SQLITE_API int sqlite3_status64(
  8029. int op,
  8030. sqlite3_int64 *pCurrent,
  8031. sqlite3_int64 *pHighwater,
  8032. int resetFlag
  8033. );
  8034. /*
  8035. ** CAPI3REF: Status Parameters
  8036. ** KEYWORDS: {status parameters}
  8037. **
  8038. ** These integer constants designate various run-time status parameters
  8039. ** that can be returned by [sqlite3_status()].
  8040. **
  8041. ** <dl>
  8042. ** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
  8043. ** <dd>This parameter is the current amount of memory checked out
  8044. ** using [sqlite3_malloc()], either directly or indirectly. The
  8045. ** figure includes calls made to [sqlite3_malloc()] by the application
  8046. ** and internal memory usage by the SQLite library. Auxiliary page-cache
  8047. ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
  8048. ** this parameter. The amount returned is the sum of the allocation
  8049. ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
  8050. **
  8051. ** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
  8052. ** <dd>This parameter records the largest memory allocation request
  8053. ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
  8054. ** internal equivalents). Only the value returned in the
  8055. ** *pHighwater parameter to [sqlite3_status()] is of interest.
  8056. ** The value written into the *pCurrent parameter is undefined.</dd>)^
  8057. **
  8058. ** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
  8059. ** <dd>This parameter records the number of separate memory allocations
  8060. ** currently checked out.</dd>)^
  8061. **
  8062. ** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
  8063. ** <dd>This parameter returns the number of pages used out of the
  8064. ** [pagecache memory allocator] that was configured using
  8065. ** [SQLITE_CONFIG_PAGECACHE]. The
  8066. ** value returned is in pages, not in bytes.</dd>)^
  8067. **
  8068. ** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]
  8069. ** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
  8070. ** <dd>This parameter returns the number of bytes of page cache
  8071. ** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
  8072. ** buffer and where forced to overflow to [sqlite3_malloc()]. The
  8073. ** returned value includes allocations that overflowed because they
  8074. ** where too large (they were larger than the "sz" parameter to
  8075. ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
  8076. ** no space was left in the page cache.</dd>)^
  8077. **
  8078. ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
  8079. ** <dd>This parameter records the largest memory allocation request
  8080. ** handed to the [pagecache memory allocator]. Only the value returned in the
  8081. ** *pHighwater parameter to [sqlite3_status()] is of interest.
  8082. ** The value written into the *pCurrent parameter is undefined.</dd>)^
  8083. **
  8084. ** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
  8085. ** <dd>No longer used.</dd>
  8086. **
  8087. ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
  8088. ** <dd>No longer used.</dd>
  8089. **
  8090. ** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
  8091. ** <dd>No longer used.</dd>
  8092. **
  8093. ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
  8094. ** <dd>The *pHighwater parameter records the deepest parser stack.
  8095. ** The *pCurrent value is undefined. The *pHighwater value is only
  8096. ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
  8097. ** </dl>
  8098. **
  8099. ** New status parameters may be added from time to time.
  8100. */
  8101. #define SQLITE_STATUS_MEMORY_USED 0
  8102. #define SQLITE_STATUS_PAGECACHE_USED 1
  8103. #define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
  8104. #define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */
  8105. #define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */
  8106. #define SQLITE_STATUS_MALLOC_SIZE 5
  8107. #define SQLITE_STATUS_PARSER_STACK 6
  8108. #define SQLITE_STATUS_PAGECACHE_SIZE 7
  8109. #define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */
  8110. #define SQLITE_STATUS_MALLOC_COUNT 9
  8111. /*
  8112. ** CAPI3REF: Database Connection Status
  8113. ** METHOD: sqlite3
  8114. **
  8115. ** ^This interface is used to retrieve runtime status information
  8116. ** about a single [database connection]. ^The first argument is the
  8117. ** database connection object to be interrogated. ^The second argument
  8118. ** is an integer constant, taken from the set of
  8119. ** [SQLITE_DBSTATUS options], that
  8120. ** determines the parameter to interrogate. The set of
  8121. ** [SQLITE_DBSTATUS options] is likely
  8122. ** to grow in future releases of SQLite.
  8123. **
  8124. ** ^The current value of the requested parameter is written into *pCur
  8125. ** and the highest instantaneous value is written into *pHiwtr. ^If
  8126. ** the resetFlg is true, then the highest instantaneous value is
  8127. ** reset back down to the current value.
  8128. **
  8129. ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
  8130. ** non-zero [error code] on failure.
  8131. **
  8132. ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
  8133. */
  8134. SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
  8135. /*
  8136. ** CAPI3REF: Status Parameters for database connections
  8137. ** KEYWORDS: {SQLITE_DBSTATUS options}
  8138. **
  8139. ** These constants are the available integer "verbs" that can be passed as
  8140. ** the second argument to the [sqlite3_db_status()] interface.
  8141. **
  8142. ** New verbs may be added in future releases of SQLite. Existing verbs
  8143. ** might be discontinued. Applications should check the return code from
  8144. ** [sqlite3_db_status()] to make sure that the call worked.
  8145. ** The [sqlite3_db_status()] interface will return a non-zero error code
  8146. ** if a discontinued or unsupported verb is invoked.
  8147. **
  8148. ** <dl>
  8149. ** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
  8150. ** <dd>This parameter returns the number of lookaside memory slots currently
  8151. ** checked out.</dd>)^
  8152. **
  8153. ** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
  8154. ** <dd>This parameter returns the number of malloc attempts that were
  8155. ** satisfied using lookaside memory. Only the high-water value is meaningful;
  8156. ** the current value is always zero.)^
  8157. **
  8158. ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
  8159. ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
  8160. ** <dd>This parameter returns the number malloc attempts that might have
  8161. ** been satisfied using lookaside memory but failed due to the amount of
  8162. ** memory requested being larger than the lookaside slot size.
  8163. ** Only the high-water value is meaningful;
  8164. ** the current value is always zero.)^
  8165. **
  8166. ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
  8167. ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
  8168. ** <dd>This parameter returns the number malloc attempts that might have
  8169. ** been satisfied using lookaside memory but failed due to all lookaside
  8170. ** memory already being in use.
  8171. ** Only the high-water value is meaningful;
  8172. ** the current value is always zero.)^
  8173. **
  8174. ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
  8175. ** <dd>This parameter returns the approximate number of bytes of heap
  8176. ** memory used by all pager caches associated with the database connection.)^
  8177. ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
  8178. **
  8179. ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
  8180. ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
  8181. ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
  8182. ** pager cache is shared between two or more connections the bytes of heap
  8183. ** memory used by that pager cache is divided evenly between the attached
  8184. ** connections.)^ In other words, if none of the pager caches associated
  8185. ** with the database connection are shared, this request returns the same
  8186. ** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
  8187. ** shared, the value returned by this call will be smaller than that returned
  8188. ** by DBSTATUS_CACHE_USED. ^The highwater mark associated with
  8189. ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
  8190. **
  8191. ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
  8192. ** <dd>This parameter returns the approximate number of bytes of heap
  8193. ** memory used to store the schema for all databases associated
  8194. ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
  8195. ** ^The full amount of memory used by the schemas is reported, even if the
  8196. ** schema memory is shared with other database connections due to
  8197. ** [shared cache mode] being enabled.
  8198. ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
  8199. **
  8200. ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
  8201. ** <dd>This parameter returns the approximate number of bytes of heap
  8202. ** and lookaside memory used by all prepared statements associated with
  8203. ** the database connection.)^
  8204. ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
  8205. ** </dd>
  8206. **
  8207. ** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
  8208. ** <dd>This parameter returns the number of pager cache hits that have
  8209. ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
  8210. ** is always 0.
  8211. ** </dd>
  8212. **
  8213. ** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
  8214. ** <dd>This parameter returns the number of pager cache misses that have
  8215. ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
  8216. ** is always 0.
  8217. ** </dd>
  8218. **
  8219. ** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
  8220. ** <dd>This parameter returns the number of dirty cache entries that have
  8221. ** been written to disk. Specifically, the number of pages written to the
  8222. ** wal file in wal mode databases, or the number of pages written to the
  8223. ** database file in rollback mode databases. Any pages written as part of
  8224. ** transaction rollback or database recovery operations are not included.
  8225. ** If an IO or other error occurs while writing a page to disk, the effect
  8226. ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
  8227. ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
  8228. ** </dd>
  8229. **
  8230. ** [[SQLITE_DBSTATUS_CACHE_SPILL]] ^(<dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>
  8231. ** <dd>This parameter returns the number of dirty cache entries that have
  8232. ** been written to disk in the middle of a transaction due to the page
  8233. ** cache overflowing. Transactions are more efficient if they are written
  8234. ** to disk all at once. When pages spill mid-transaction, that introduces
  8235. ** additional overhead. This parameter can be used help identify
  8236. ** inefficiencies that can be resolved by increasing the cache size.
  8237. ** </dd>
  8238. **
  8239. ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
  8240. ** <dd>This parameter returns zero for the current value if and only if
  8241. ** all foreign key constraints (deferred or immediate) have been
  8242. ** resolved.)^ ^The highwater mark is always 0.
  8243. ** </dd>
  8244. ** </dl>
  8245. */
  8246. #define SQLITE_DBSTATUS_LOOKASIDE_USED 0
  8247. #define SQLITE_DBSTATUS_CACHE_USED 1
  8248. #define SQLITE_DBSTATUS_SCHEMA_USED 2
  8249. #define SQLITE_DBSTATUS_STMT_USED 3
  8250. #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
  8251. #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
  8252. #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
  8253. #define SQLITE_DBSTATUS_CACHE_HIT 7
  8254. #define SQLITE_DBSTATUS_CACHE_MISS 8
  8255. #define SQLITE_DBSTATUS_CACHE_WRITE 9
  8256. #define SQLITE_DBSTATUS_DEFERRED_FKS 10
  8257. #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
  8258. #define SQLITE_DBSTATUS_CACHE_SPILL 12
  8259. #define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */
  8260. /*
  8261. ** CAPI3REF: Prepared Statement Status
  8262. ** METHOD: sqlite3_stmt
  8263. **
  8264. ** ^(Each prepared statement maintains various
  8265. ** [SQLITE_STMTSTATUS counters] that measure the number
  8266. ** of times it has performed specific operations.)^ These counters can
  8267. ** be used to monitor the performance characteristics of the prepared
  8268. ** statements. For example, if the number of table steps greatly exceeds
  8269. ** the number of table searches or result rows, that would tend to indicate
  8270. ** that the prepared statement is using a full table scan rather than
  8271. ** an index.
  8272. **
  8273. ** ^(This interface is used to retrieve and reset counter values from
  8274. ** a [prepared statement]. The first argument is the prepared statement
  8275. ** object to be interrogated. The second argument
  8276. ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
  8277. ** to be interrogated.)^
  8278. ** ^The current value of the requested counter is returned.
  8279. ** ^If the resetFlg is true, then the counter is reset to zero after this
  8280. ** interface call returns.
  8281. **
  8282. ** See also: [sqlite3_status()] and [sqlite3_db_status()].
  8283. */
  8284. SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
  8285. /*
  8286. ** CAPI3REF: Status Parameters for prepared statements
  8287. ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
  8288. **
  8289. ** These preprocessor macros define integer codes that name counter
  8290. ** values associated with the [sqlite3_stmt_status()] interface.
  8291. ** The meanings of the various counters are as follows:
  8292. **
  8293. ** <dl>
  8294. ** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
  8295. ** <dd>^This is the number of times that SQLite has stepped forward in
  8296. ** a table as part of a full table scan. Large numbers for this counter
  8297. ** may indicate opportunities for performance improvement through
  8298. ** careful use of indices.</dd>
  8299. **
  8300. ** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
  8301. ** <dd>^This is the number of sort operations that have occurred.
  8302. ** A non-zero value in this counter may indicate an opportunity to
  8303. ** improvement performance through careful use of indices.</dd>
  8304. **
  8305. ** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
  8306. ** <dd>^This is the number of rows inserted into transient indices that
  8307. ** were created automatically in order to help joins run faster.
  8308. ** A non-zero value in this counter may indicate an opportunity to
  8309. ** improvement performance by adding permanent indices that do not
  8310. ** need to be reinitialized each time the statement is run.</dd>
  8311. **
  8312. ** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
  8313. ** <dd>^This is the number of virtual machine operations executed
  8314. ** by the prepared statement if that number is less than or equal
  8315. ** to 2147483647. The number of virtual machine operations can be
  8316. ** used as a proxy for the total work done by the prepared statement.
  8317. ** If the number of virtual machine operations exceeds 2147483647
  8318. ** then the value returned by this statement status code is undefined.
  8319. **
  8320. ** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
  8321. ** <dd>^This is the number of times that the prepare statement has been
  8322. ** automatically regenerated due to schema changes or changes to
  8323. ** [bound parameters] that might affect the query plan.
  8324. **
  8325. ** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
  8326. ** <dd>^This is the number of times that the prepared statement has
  8327. ** been run. A single "run" for the purposes of this counter is one
  8328. ** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
  8329. ** The counter is incremented on the first [sqlite3_step()] call of each
  8330. ** cycle.
  8331. **
  8332. ** [[SQLITE_STMTSTATUS_FILTER_MISS]]
  8333. ** [[SQLITE_STMTSTATUS_FILTER HIT]]
  8334. ** <dt>SQLITE_STMTSTATUS_FILTER_HIT<br>
  8335. ** SQLITE_STMTSTATUS_FILTER_MISS</dt>
  8336. ** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
  8337. ** step was bypassed because a Bloom filter returned not-found. The
  8338. ** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
  8339. ** times that the Bloom filter returned a find, and thus the join step
  8340. ** had to be processed as normal.
  8341. **
  8342. ** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
  8343. ** <dd>^This is the approximate number of bytes of heap memory
  8344. ** used to store the prepared statement. ^This value is not actually
  8345. ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
  8346. ** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
  8347. ** </dd>
  8348. ** </dl>
  8349. */
  8350. #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
  8351. #define SQLITE_STMTSTATUS_SORT 2
  8352. #define SQLITE_STMTSTATUS_AUTOINDEX 3
  8353. #define SQLITE_STMTSTATUS_VM_STEP 4
  8354. #define SQLITE_STMTSTATUS_REPREPARE 5
  8355. #define SQLITE_STMTSTATUS_RUN 6
  8356. #define SQLITE_STMTSTATUS_FILTER_MISS 7
  8357. #define SQLITE_STMTSTATUS_FILTER_HIT 8
  8358. #define SQLITE_STMTSTATUS_MEMUSED 99
  8359. /*
  8360. ** CAPI3REF: Custom Page Cache Object
  8361. **
  8362. ** The sqlite3_pcache type is opaque. It is implemented by
  8363. ** the pluggable module. The SQLite core has no knowledge of
  8364. ** its size or internal structure and never deals with the
  8365. ** sqlite3_pcache object except by holding and passing pointers
  8366. ** to the object.
  8367. **
  8368. ** See [sqlite3_pcache_methods2] for additional information.
  8369. */
  8370. typedef struct sqlite3_pcache sqlite3_pcache;
  8371. /*
  8372. ** CAPI3REF: Custom Page Cache Object
  8373. **
  8374. ** The sqlite3_pcache_page object represents a single page in the
  8375. ** page cache. The page cache will allocate instances of this
  8376. ** object. Various methods of the page cache use pointers to instances
  8377. ** of this object as parameters or as their return value.
  8378. **
  8379. ** See [sqlite3_pcache_methods2] for additional information.
  8380. */
  8381. typedef struct sqlite3_pcache_page sqlite3_pcache_page;
  8382. struct sqlite3_pcache_page {
  8383. void *pBuf; /* The content of the page */
  8384. void *pExtra; /* Extra information associated with the page */
  8385. };
  8386. /*
  8387. ** CAPI3REF: Application Defined Page Cache.
  8388. ** KEYWORDS: {page cache}
  8389. **
  8390. ** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
  8391. ** register an alternative page cache implementation by passing in an
  8392. ** instance of the sqlite3_pcache_methods2 structure.)^
  8393. ** In many applications, most of the heap memory allocated by
  8394. ** SQLite is used for the page cache.
  8395. ** By implementing a
  8396. ** custom page cache using this API, an application can better control
  8397. ** the amount of memory consumed by SQLite, the way in which
  8398. ** that memory is allocated and released, and the policies used to
  8399. ** determine exactly which parts of a database file are cached and for
  8400. ** how long.
  8401. **
  8402. ** The alternative page cache mechanism is an
  8403. ** extreme measure that is only needed by the most demanding applications.
  8404. ** The built-in page cache is recommended for most uses.
  8405. **
  8406. ** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
  8407. ** internal buffer by SQLite within the call to [sqlite3_config]. Hence
  8408. ** the application may discard the parameter after the call to
  8409. ** [sqlite3_config()] returns.)^
  8410. **
  8411. ** [[the xInit() page cache method]]
  8412. ** ^(The xInit() method is called once for each effective
  8413. ** call to [sqlite3_initialize()])^
  8414. ** (usually only once during the lifetime of the process). ^(The xInit()
  8415. ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
  8416. ** The intent of the xInit() method is to set up global data structures
  8417. ** required by the custom page cache implementation.
  8418. ** ^(If the xInit() method is NULL, then the
  8419. ** built-in default page cache is used instead of the application defined
  8420. ** page cache.)^
  8421. **
  8422. ** [[the xShutdown() page cache method]]
  8423. ** ^The xShutdown() method is called by [sqlite3_shutdown()].
  8424. ** It can be used to clean up
  8425. ** any outstanding resources before process shutdown, if required.
  8426. ** ^The xShutdown() method may be NULL.
  8427. **
  8428. ** ^SQLite automatically serializes calls to the xInit method,
  8429. ** so the xInit method need not be threadsafe. ^The
  8430. ** xShutdown method is only called from [sqlite3_shutdown()] so it does
  8431. ** not need to be threadsafe either. All other methods must be threadsafe
  8432. ** in multithreaded applications.
  8433. **
  8434. ** ^SQLite will never invoke xInit() more than once without an intervening
  8435. ** call to xShutdown().
  8436. **
  8437. ** [[the xCreate() page cache methods]]
  8438. ** ^SQLite invokes the xCreate() method to construct a new cache instance.
  8439. ** SQLite will typically create one cache instance for each open database file,
  8440. ** though this is not guaranteed. ^The
  8441. ** first parameter, szPage, is the size in bytes of the pages that must
  8442. ** be allocated by the cache. ^szPage will always a power of two. ^The
  8443. ** second parameter szExtra is a number of bytes of extra storage
  8444. ** associated with each page cache entry. ^The szExtra parameter will
  8445. ** a number less than 250. SQLite will use the
  8446. ** extra szExtra bytes on each page to store metadata about the underlying
  8447. ** database page on disk. The value passed into szExtra depends
  8448. ** on the SQLite version, the target platform, and how SQLite was compiled.
  8449. ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
  8450. ** created will be used to cache database pages of a file stored on disk, or
  8451. ** false if it is used for an in-memory database. The cache implementation
  8452. ** does not have to do anything special based with the value of bPurgeable;
  8453. ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
  8454. ** never invoke xUnpin() except to deliberately delete a page.
  8455. ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
  8456. ** false will always have the "discard" flag set to true.
  8457. ** ^Hence, a cache created with bPurgeable false will
  8458. ** never contain any unpinned pages.
  8459. **
  8460. ** [[the xCachesize() page cache method]]
  8461. ** ^(The xCachesize() method may be called at any time by SQLite to set the
  8462. ** suggested maximum cache-size (number of pages stored by) the cache
  8463. ** instance passed as the first argument. This is the value configured using
  8464. ** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
  8465. ** parameter, the implementation is not required to do anything with this
  8466. ** value; it is advisory only.
  8467. **
  8468. ** [[the xPagecount() page cache methods]]
  8469. ** The xPagecount() method must return the number of pages currently
  8470. ** stored in the cache, both pinned and unpinned.
  8471. **
  8472. ** [[the xFetch() page cache methods]]
  8473. ** The xFetch() method locates a page in the cache and returns a pointer to
  8474. ** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
  8475. ** The pBuf element of the returned sqlite3_pcache_page object will be a
  8476. ** pointer to a buffer of szPage bytes used to store the content of a
  8477. ** single database page. The pExtra element of sqlite3_pcache_page will be
  8478. ** a pointer to the szExtra bytes of extra storage that SQLite has requested
  8479. ** for each entry in the page cache.
  8480. **
  8481. ** The page to be fetched is determined by the key. ^The minimum key value
  8482. ** is 1. After it has been retrieved using xFetch, the page is considered
  8483. ** to be "pinned".
  8484. **
  8485. ** If the requested page is already in the page cache, then the page cache
  8486. ** implementation must return a pointer to the page buffer with its content
  8487. ** intact. If the requested page is not already in the cache, then the
  8488. ** cache implementation should use the value of the createFlag
  8489. ** parameter to help it determined what action to take:
  8490. **
  8491. ** <table border=1 width=85% align=center>
  8492. ** <tr><th> createFlag <th> Behavior when page is not already in cache
  8493. ** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
  8494. ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
  8495. ** Otherwise return NULL.
  8496. ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
  8497. ** NULL if allocating a new page is effectively impossible.
  8498. ** </table>
  8499. **
  8500. ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
  8501. ** will only use a createFlag of 2 after a prior call with a createFlag of 1
  8502. ** failed.)^ In between the xFetch() calls, SQLite may
  8503. ** attempt to unpin one or more cache pages by spilling the content of
  8504. ** pinned pages to disk and synching the operating system disk cache.
  8505. **
  8506. ** [[the xUnpin() page cache method]]
  8507. ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
  8508. ** as its second argument. If the third parameter, discard, is non-zero,
  8509. ** then the page must be evicted from the cache.
  8510. ** ^If the discard parameter is
  8511. ** zero, then the page may be discarded or retained at the discretion of
  8512. ** page cache implementation. ^The page cache implementation
  8513. ** may choose to evict unpinned pages at any time.
  8514. **
  8515. ** The cache must not perform any reference counting. A single
  8516. ** call to xUnpin() unpins the page regardless of the number of prior calls
  8517. ** to xFetch().
  8518. **
  8519. ** [[the xRekey() page cache methods]]
  8520. ** The xRekey() method is used to change the key value associated with the
  8521. ** page passed as the second argument. If the cache
  8522. ** previously contains an entry associated with newKey, it must be
  8523. ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
  8524. ** to be pinned.
  8525. **
  8526. ** When SQLite calls the xTruncate() method, the cache must discard all
  8527. ** existing cache entries with page numbers (keys) greater than or equal
  8528. ** to the value of the iLimit parameter passed to xTruncate(). If any
  8529. ** of these pages are pinned, they are implicitly unpinned, meaning that
  8530. ** they can be safely discarded.
  8531. **
  8532. ** [[the xDestroy() page cache method]]
  8533. ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
  8534. ** All resources associated with the specified cache should be freed. ^After
  8535. ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
  8536. ** handle invalid, and will not use it with any other sqlite3_pcache_methods2
  8537. ** functions.
  8538. **
  8539. ** [[the xShrink() page cache method]]
  8540. ** ^SQLite invokes the xShrink() method when it wants the page cache to
  8541. ** free up as much of heap memory as possible. The page cache implementation
  8542. ** is not obligated to free any memory, but well-behaved implementations should
  8543. ** do their best.
  8544. */
  8545. typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
  8546. struct sqlite3_pcache_methods2 {
  8547. int iVersion;
  8548. void *pArg;
  8549. int (*xInit)(void*);
  8550. void (*xShutdown)(void*);
  8551. sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
  8552. void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  8553. int (*xPagecount)(sqlite3_pcache*);
  8554. sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  8555. void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  8556. void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
  8557. unsigned oldKey, unsigned newKey);
  8558. void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  8559. void (*xDestroy)(sqlite3_pcache*);
  8560. void (*xShrink)(sqlite3_pcache*);
  8561. };
  8562. /*
  8563. ** This is the obsolete pcache_methods object that has now been replaced
  8564. ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
  8565. ** retained in the header file for backwards compatibility only.
  8566. */
  8567. typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
  8568. struct sqlite3_pcache_methods {
  8569. void *pArg;
  8570. int (*xInit)(void*);
  8571. void (*xShutdown)(void*);
  8572. sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
  8573. void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  8574. int (*xPagecount)(sqlite3_pcache*);
  8575. void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  8576. void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  8577. void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  8578. void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  8579. void (*xDestroy)(sqlite3_pcache*);
  8580. };
  8581. /*
  8582. ** CAPI3REF: Online Backup Object
  8583. **
  8584. ** The sqlite3_backup object records state information about an ongoing
  8585. ** online backup operation. ^The sqlite3_backup object is created by
  8586. ** a call to [sqlite3_backup_init()] and is destroyed by a call to
  8587. ** [sqlite3_backup_finish()].
  8588. **
  8589. ** See Also: [Using the SQLite Online Backup API]
  8590. */
  8591. typedef struct sqlite3_backup sqlite3_backup;
  8592. /*
  8593. ** CAPI3REF: Online Backup API.
  8594. **
  8595. ** The backup API copies the content of one database into another.
  8596. ** It is useful either for creating backups of databases or
  8597. ** for copying in-memory databases to or from persistent files.
  8598. **
  8599. ** See Also: [Using the SQLite Online Backup API]
  8600. **
  8601. ** ^SQLite holds a write transaction open on the destination database file
  8602. ** for the duration of the backup operation.
  8603. ** ^The source database is read-locked only while it is being read;
  8604. ** it is not locked continuously for the entire backup operation.
  8605. ** ^Thus, the backup may be performed on a live source database without
  8606. ** preventing other database connections from
  8607. ** reading or writing to the source database while the backup is underway.
  8608. **
  8609. ** ^(To perform a backup operation:
  8610. ** <ol>
  8611. ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
  8612. ** backup,
  8613. ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
  8614. ** the data between the two databases, and finally
  8615. ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
  8616. ** associated with the backup operation.
  8617. ** </ol>)^
  8618. ** There should be exactly one call to sqlite3_backup_finish() for each
  8619. ** successful call to sqlite3_backup_init().
  8620. **
  8621. ** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
  8622. **
  8623. ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
  8624. ** [database connection] associated with the destination database
  8625. ** and the database name, respectively.
  8626. ** ^The database name is "main" for the main database, "temp" for the
  8627. ** temporary database, or the name specified after the AS keyword in
  8628. ** an [ATTACH] statement for an attached database.
  8629. ** ^The S and M arguments passed to
  8630. ** sqlite3_backup_init(D,N,S,M) identify the [database connection]
  8631. ** and database name of the source database, respectively.
  8632. ** ^The source and destination [database connections] (parameters S and D)
  8633. ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
  8634. ** an error.
  8635. **
  8636. ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
  8637. ** there is already a read or read-write transaction open on the
  8638. ** destination database.
  8639. **
  8640. ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
  8641. ** returned and an error code and error message are stored in the
  8642. ** destination [database connection] D.
  8643. ** ^The error code and message for the failed call to sqlite3_backup_init()
  8644. ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
  8645. ** [sqlite3_errmsg16()] functions.
  8646. ** ^A successful call to sqlite3_backup_init() returns a pointer to an
  8647. ** [sqlite3_backup] object.
  8648. ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
  8649. ** sqlite3_backup_finish() functions to perform the specified backup
  8650. ** operation.
  8651. **
  8652. ** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
  8653. **
  8654. ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
  8655. ** the source and destination databases specified by [sqlite3_backup] object B.
  8656. ** ^If N is negative, all remaining source pages are copied.
  8657. ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
  8658. ** are still more pages to be copied, then the function returns [SQLITE_OK].
  8659. ** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
  8660. ** from source to destination, then it returns [SQLITE_DONE].
  8661. ** ^If an error occurs while running sqlite3_backup_step(B,N),
  8662. ** then an [error code] is returned. ^As well as [SQLITE_OK] and
  8663. ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
  8664. ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
  8665. ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
  8666. **
  8667. ** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
  8668. ** <ol>
  8669. ** <li> the destination database was opened read-only, or
  8670. ** <li> the destination database is using write-ahead-log journaling
  8671. ** and the destination and source page sizes differ, or
  8672. ** <li> the destination database is an in-memory database and the
  8673. ** destination and source page sizes differ.
  8674. ** </ol>)^
  8675. **
  8676. ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
  8677. ** the [sqlite3_busy_handler | busy-handler function]
  8678. ** is invoked (if one is specified). ^If the
  8679. ** busy-handler returns non-zero before the lock is available, then
  8680. ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
  8681. ** sqlite3_backup_step() can be retried later. ^If the source
  8682. ** [database connection]
  8683. ** is being used to write to the source database when sqlite3_backup_step()
  8684. ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
  8685. ** case the call to sqlite3_backup_step() can be retried later on. ^(If
  8686. ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
  8687. ** [SQLITE_READONLY] is returned, then
  8688. ** there is no point in retrying the call to sqlite3_backup_step(). These
  8689. ** errors are considered fatal.)^ The application must accept
  8690. ** that the backup operation has failed and pass the backup operation handle
  8691. ** to the sqlite3_backup_finish() to release associated resources.
  8692. **
  8693. ** ^The first call to sqlite3_backup_step() obtains an exclusive lock
  8694. ** on the destination file. ^The exclusive lock is not released until either
  8695. ** sqlite3_backup_finish() is called or the backup operation is complete
  8696. ** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
  8697. ** sqlite3_backup_step() obtains a [shared lock] on the source database that
  8698. ** lasts for the duration of the sqlite3_backup_step() call.
  8699. ** ^Because the source database is not locked between calls to
  8700. ** sqlite3_backup_step(), the source database may be modified mid-way
  8701. ** through the backup process. ^If the source database is modified by an
  8702. ** external process or via a database connection other than the one being
  8703. ** used by the backup operation, then the backup will be automatically
  8704. ** restarted by the next call to sqlite3_backup_step(). ^If the source
  8705. ** database is modified by the using the same database connection as is used
  8706. ** by the backup operation, then the backup database is automatically
  8707. ** updated at the same time.
  8708. **
  8709. ** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
  8710. **
  8711. ** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
  8712. ** application wishes to abandon the backup operation, the application
  8713. ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
  8714. ** ^The sqlite3_backup_finish() interfaces releases all
  8715. ** resources associated with the [sqlite3_backup] object.
  8716. ** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
  8717. ** active write-transaction on the destination database is rolled back.
  8718. ** The [sqlite3_backup] object is invalid
  8719. ** and may not be used following a call to sqlite3_backup_finish().
  8720. **
  8721. ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
  8722. ** sqlite3_backup_step() errors occurred, regardless or whether or not
  8723. ** sqlite3_backup_step() completed.
  8724. ** ^If an out-of-memory condition or IO error occurred during any prior
  8725. ** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
  8726. ** sqlite3_backup_finish() returns the corresponding [error code].
  8727. **
  8728. ** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
  8729. ** is not a permanent error and does not affect the return value of
  8730. ** sqlite3_backup_finish().
  8731. **
  8732. ** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
  8733. ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
  8734. **
  8735. ** ^The sqlite3_backup_remaining() routine returns the number of pages still
  8736. ** to be backed up at the conclusion of the most recent sqlite3_backup_step().
  8737. ** ^The sqlite3_backup_pagecount() routine returns the total number of pages
  8738. ** in the source database at the conclusion of the most recent
  8739. ** sqlite3_backup_step().
  8740. ** ^(The values returned by these functions are only updated by
  8741. ** sqlite3_backup_step(). If the source database is modified in a way that
  8742. ** changes the size of the source database or the number of pages remaining,
  8743. ** those changes are not reflected in the output of sqlite3_backup_pagecount()
  8744. ** and sqlite3_backup_remaining() until after the next
  8745. ** sqlite3_backup_step().)^
  8746. **
  8747. ** <b>Concurrent Usage of Database Handles</b>
  8748. **
  8749. ** ^The source [database connection] may be used by the application for other
  8750. ** purposes while a backup operation is underway or being initialized.
  8751. ** ^If SQLite is compiled and configured to support threadsafe database
  8752. ** connections, then the source database connection may be used concurrently
  8753. ** from within other threads.
  8754. **
  8755. ** However, the application must guarantee that the destination
  8756. ** [database connection] is not passed to any other API (by any thread) after
  8757. ** sqlite3_backup_init() is called and before the corresponding call to
  8758. ** sqlite3_backup_finish(). SQLite does not currently check to see
  8759. ** if the application incorrectly accesses the destination [database connection]
  8760. ** and so no error code is reported, but the operations may malfunction
  8761. ** nevertheless. Use of the destination database connection while a
  8762. ** backup is in progress might also also cause a mutex deadlock.
  8763. **
  8764. ** If running in [shared cache mode], the application must
  8765. ** guarantee that the shared cache used by the destination database
  8766. ** is not accessed while the backup is running. In practice this means
  8767. ** that the application must guarantee that the disk file being
  8768. ** backed up to is not accessed by any connection within the process,
  8769. ** not just the specific connection that was passed to sqlite3_backup_init().
  8770. **
  8771. ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
  8772. ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
  8773. ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
  8774. ** APIs are not strictly speaking threadsafe. If they are invoked at the
  8775. ** same time as another thread is invoking sqlite3_backup_step() it is
  8776. ** possible that they return invalid values.
  8777. */
  8778. SQLITE_API sqlite3_backup *sqlite3_backup_init(
  8779. sqlite3 *pDest, /* Destination database handle */
  8780. const char *zDestName, /* Destination database name */
  8781. sqlite3 *pSource, /* Source database handle */
  8782. const char *zSourceName /* Source database name */
  8783. );
  8784. SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
  8785. SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
  8786. SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
  8787. SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
  8788. /*
  8789. ** CAPI3REF: Unlock Notification
  8790. ** METHOD: sqlite3
  8791. **
  8792. ** ^When running in shared-cache mode, a database operation may fail with
  8793. ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
  8794. ** individual tables within the shared-cache cannot be obtained. See
  8795. ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
  8796. ** ^This API may be used to register a callback that SQLite will invoke
  8797. ** when the connection currently holding the required lock relinquishes it.
  8798. ** ^This API is only available if the library was compiled with the
  8799. ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
  8800. **
  8801. ** See Also: [Using the SQLite Unlock Notification Feature].
  8802. **
  8803. ** ^Shared-cache locks are released when a database connection concludes
  8804. ** its current transaction, either by committing it or rolling it back.
  8805. **
  8806. ** ^When a connection (known as the blocked connection) fails to obtain a
  8807. ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
  8808. ** identity of the database connection (the blocking connection) that
  8809. ** has locked the required resource is stored internally. ^After an
  8810. ** application receives an SQLITE_LOCKED error, it may call the
  8811. ** sqlite3_unlock_notify() method with the blocked connection handle as
  8812. ** the first argument to register for a callback that will be invoked
  8813. ** when the blocking connections current transaction is concluded. ^The
  8814. ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
  8815. ** call that concludes the blocking connection's transaction.
  8816. **
  8817. ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
  8818. ** there is a chance that the blocking connection will have already
  8819. ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
  8820. ** If this happens, then the specified callback is invoked immediately,
  8821. ** from within the call to sqlite3_unlock_notify().)^
  8822. **
  8823. ** ^If the blocked connection is attempting to obtain a write-lock on a
  8824. ** shared-cache table, and more than one other connection currently holds
  8825. ** a read-lock on the same table, then SQLite arbitrarily selects one of
  8826. ** the other connections to use as the blocking connection.
  8827. **
  8828. ** ^(There may be at most one unlock-notify callback registered by a
  8829. ** blocked connection. If sqlite3_unlock_notify() is called when the
  8830. ** blocked connection already has a registered unlock-notify callback,
  8831. ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
  8832. ** called with a NULL pointer as its second argument, then any existing
  8833. ** unlock-notify callback is canceled. ^The blocked connections
  8834. ** unlock-notify callback may also be canceled by closing the blocked
  8835. ** connection using [sqlite3_close()].
  8836. **
  8837. ** The unlock-notify callback is not reentrant. If an application invokes
  8838. ** any sqlite3_xxx API functions from within an unlock-notify callback, a
  8839. ** crash or deadlock may be the result.
  8840. **
  8841. ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
  8842. ** returns SQLITE_OK.
  8843. **
  8844. ** <b>Callback Invocation Details</b>
  8845. **
  8846. ** When an unlock-notify callback is registered, the application provides a
  8847. ** single void* pointer that is passed to the callback when it is invoked.
  8848. ** However, the signature of the callback function allows SQLite to pass
  8849. ** it an array of void* context pointers. The first argument passed to
  8850. ** an unlock-notify callback is a pointer to an array of void* pointers,
  8851. ** and the second is the number of entries in the array.
  8852. **
  8853. ** When a blocking connection's transaction is concluded, there may be
  8854. ** more than one blocked connection that has registered for an unlock-notify
  8855. ** callback. ^If two or more such blocked connections have specified the
  8856. ** same callback function, then instead of invoking the callback function
  8857. ** multiple times, it is invoked once with the set of void* context pointers
  8858. ** specified by the blocked connections bundled together into an array.
  8859. ** This gives the application an opportunity to prioritize any actions
  8860. ** related to the set of unblocked database connections.
  8861. **
  8862. ** <b>Deadlock Detection</b>
  8863. **
  8864. ** Assuming that after registering for an unlock-notify callback a
  8865. ** database waits for the callback to be issued before taking any further
  8866. ** action (a reasonable assumption), then using this API may cause the
  8867. ** application to deadlock. For example, if connection X is waiting for
  8868. ** connection Y's transaction to be concluded, and similarly connection
  8869. ** Y is waiting on connection X's transaction, then neither connection
  8870. ** will proceed and the system may remain deadlocked indefinitely.
  8871. **
  8872. ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
  8873. ** detection. ^If a given call to sqlite3_unlock_notify() would put the
  8874. ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
  8875. ** unlock-notify callback is registered. The system is said to be in
  8876. ** a deadlocked state if connection A has registered for an unlock-notify
  8877. ** callback on the conclusion of connection B's transaction, and connection
  8878. ** B has itself registered for an unlock-notify callback when connection
  8879. ** A's transaction is concluded. ^Indirect deadlock is also detected, so
  8880. ** the system is also considered to be deadlocked if connection B has
  8881. ** registered for an unlock-notify callback on the conclusion of connection
  8882. ** C's transaction, where connection C is waiting on connection A. ^Any
  8883. ** number of levels of indirection are allowed.
  8884. **
  8885. ** <b>The "DROP TABLE" Exception</b>
  8886. **
  8887. ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
  8888. ** always appropriate to call sqlite3_unlock_notify(). There is however,
  8889. ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
  8890. ** SQLite checks if there are any currently executing SELECT statements
  8891. ** that belong to the same connection. If there are, SQLITE_LOCKED is
  8892. ** returned. In this case there is no "blocking connection", so invoking
  8893. ** sqlite3_unlock_notify() results in the unlock-notify callback being
  8894. ** invoked immediately. If the application then re-attempts the "DROP TABLE"
  8895. ** or "DROP INDEX" query, an infinite loop might be the result.
  8896. **
  8897. ** One way around this problem is to check the extended error code returned
  8898. ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
  8899. ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
  8900. ** the special "DROP TABLE/INDEX" case, the extended error code is just
  8901. ** SQLITE_LOCKED.)^
  8902. */
  8903. SQLITE_API int sqlite3_unlock_notify(
  8904. sqlite3 *pBlocked, /* Waiting connection */
  8905. void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
  8906. void *pNotifyArg /* Argument to pass to xNotify */
  8907. );
  8908. /*
  8909. ** CAPI3REF: String Comparison
  8910. **
  8911. ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
  8912. ** and extensions to compare the contents of two buffers containing UTF-8
  8913. ** strings in a case-independent fashion, using the same definition of "case
  8914. ** independence" that SQLite uses internally when comparing identifiers.
  8915. */
  8916. SQLITE_API int sqlite3_stricmp(const char *, const char *);
  8917. SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
  8918. /*
  8919. ** CAPI3REF: String Globbing
  8920. *
  8921. ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
  8922. ** string X matches the [GLOB] pattern P.
  8923. ** ^The definition of [GLOB] pattern matching used in
  8924. ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
  8925. ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
  8926. ** is case sensitive.
  8927. **
  8928. ** Note that this routine returns zero on a match and non-zero if the strings
  8929. ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
  8930. **
  8931. ** See also: [sqlite3_strlike()].
  8932. */
  8933. SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
  8934. /*
  8935. ** CAPI3REF: String LIKE Matching
  8936. *
  8937. ** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
  8938. ** string X matches the [LIKE] pattern P with escape character E.
  8939. ** ^The definition of [LIKE] pattern matching used in
  8940. ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
  8941. ** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
  8942. ** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
  8943. ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
  8944. ** insensitive - equivalent upper and lower case ASCII characters match
  8945. ** one another.
  8946. **
  8947. ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
  8948. ** only ASCII characters are case folded.
  8949. **
  8950. ** Note that this routine returns zero on a match and non-zero if the strings
  8951. ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
  8952. **
  8953. ** See also: [sqlite3_strglob()].
  8954. */
  8955. SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
  8956. /*
  8957. ** CAPI3REF: Error Logging Interface
  8958. **
  8959. ** ^The [sqlite3_log()] interface writes a message into the [error log]
  8960. ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
  8961. ** ^If logging is enabled, the zFormat string and subsequent arguments are
  8962. ** used with [sqlite3_snprintf()] to generate the final output string.
  8963. **
  8964. ** The sqlite3_log() interface is intended for use by extensions such as
  8965. ** virtual tables, collating functions, and SQL functions. While there is
  8966. ** nothing to prevent an application from calling sqlite3_log(), doing so
  8967. ** is considered bad form.
  8968. **
  8969. ** The zFormat string must not be NULL.
  8970. **
  8971. ** To avoid deadlocks and other threading problems, the sqlite3_log() routine
  8972. ** will not use dynamically allocated memory. The log message is stored in
  8973. ** a fixed-length buffer on the stack. If the log message is longer than
  8974. ** a few hundred characters, it will be truncated to the length of the
  8975. ** buffer.
  8976. */
  8977. SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
  8978. /*
  8979. ** CAPI3REF: Write-Ahead Log Commit Hook
  8980. ** METHOD: sqlite3
  8981. **
  8982. ** ^The [sqlite3_wal_hook()] function is used to register a callback that
  8983. ** is invoked each time data is committed to a database in wal mode.
  8984. **
  8985. ** ^(The callback is invoked by SQLite after the commit has taken place and
  8986. ** the associated write-lock on the database released)^, so the implementation
  8987. ** may read, write or [checkpoint] the database as required.
  8988. **
  8989. ** ^The first parameter passed to the callback function when it is invoked
  8990. ** is a copy of the third parameter passed to sqlite3_wal_hook() when
  8991. ** registering the callback. ^The second is a copy of the database handle.
  8992. ** ^The third parameter is the name of the database that was written to -
  8993. ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
  8994. ** is the number of pages currently in the write-ahead log file,
  8995. ** including those that were just committed.
  8996. **
  8997. ** The callback function should normally return [SQLITE_OK]. ^If an error
  8998. ** code is returned, that error will propagate back up through the
  8999. ** SQLite code base to cause the statement that provoked the callback
  9000. ** to report an error, though the commit will have still occurred. If the
  9001. ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
  9002. ** that does not correspond to any valid SQLite error code, the results
  9003. ** are undefined.
  9004. **
  9005. ** A single database handle may have at most a single write-ahead log callback
  9006. ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
  9007. ** previously registered write-ahead log callback. ^The return value is
  9008. ** a copy of the third parameter from the previous call, if any, or 0.
  9009. ** ^Note that the [sqlite3_wal_autocheckpoint()] interface and the
  9010. ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
  9011. ** overwrite any prior [sqlite3_wal_hook()] settings.
  9012. */
  9013. SQLITE_API void *sqlite3_wal_hook(
  9014. sqlite3*,
  9015. int(*)(void *,sqlite3*,const char*,int),
  9016. void*
  9017. );
  9018. /*
  9019. ** CAPI3REF: Configure an auto-checkpoint
  9020. ** METHOD: sqlite3
  9021. **
  9022. ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
  9023. ** [sqlite3_wal_hook()] that causes any database on [database connection] D
  9024. ** to automatically [checkpoint]
  9025. ** after committing a transaction if there are N or
  9026. ** more frames in the [write-ahead log] file. ^Passing zero or
  9027. ** a negative value as the nFrame parameter disables automatic
  9028. ** checkpoints entirely.
  9029. **
  9030. ** ^The callback registered by this function replaces any existing callback
  9031. ** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
  9032. ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
  9033. ** configured by this function.
  9034. **
  9035. ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
  9036. ** from SQL.
  9037. **
  9038. ** ^Checkpoints initiated by this mechanism are
  9039. ** [sqlite3_wal_checkpoint_v2|PASSIVE].
  9040. **
  9041. ** ^Every new [database connection] defaults to having the auto-checkpoint
  9042. ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
  9043. ** pages. The use of this interface
  9044. ** is only necessary if the default setting is found to be suboptimal
  9045. ** for a particular application.
  9046. */
  9047. SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
  9048. /*
  9049. ** CAPI3REF: Checkpoint a database
  9050. ** METHOD: sqlite3
  9051. **
  9052. ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
  9053. ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
  9054. **
  9055. ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
  9056. ** [write-ahead log] for database X on [database connection] D to be
  9057. ** transferred into the database file and for the write-ahead log to
  9058. ** be reset. See the [checkpointing] documentation for addition
  9059. ** information.
  9060. **
  9061. ** This interface used to be the only way to cause a checkpoint to
  9062. ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
  9063. ** interface was added. This interface is retained for backwards
  9064. ** compatibility and as a convenience for applications that need to manually
  9065. ** start a callback but which do not need the full power (and corresponding
  9066. ** complication) of [sqlite3_wal_checkpoint_v2()].
  9067. */
  9068. SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
  9069. /*
  9070. ** CAPI3REF: Checkpoint a database
  9071. ** METHOD: sqlite3
  9072. **
  9073. ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
  9074. ** operation on database X of [database connection] D in mode M. Status
  9075. ** information is written back into integers pointed to by L and C.)^
  9076. ** ^(The M parameter must be a valid [checkpoint mode]:)^
  9077. **
  9078. ** <dl>
  9079. ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
  9080. ** ^Checkpoint as many frames as possible without waiting for any database
  9081. ** readers or writers to finish, then sync the database file if all frames
  9082. ** in the log were checkpointed. ^The [busy-handler callback]
  9083. ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
  9084. ** ^On the other hand, passive mode might leave the checkpoint unfinished
  9085. ** if there are concurrent readers or writers.
  9086. **
  9087. ** <dt>SQLITE_CHECKPOINT_FULL<dd>
  9088. ** ^This mode blocks (it invokes the
  9089. ** [sqlite3_busy_handler|busy-handler callback]) until there is no
  9090. ** database writer and all readers are reading from the most recent database
  9091. ** snapshot. ^It then checkpoints all frames in the log file and syncs the
  9092. ** database file. ^This mode blocks new database writers while it is pending,
  9093. ** but new database readers are allowed to continue unimpeded.
  9094. **
  9095. ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
  9096. ** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
  9097. ** that after checkpointing the log file it blocks (calls the
  9098. ** [busy-handler callback])
  9099. ** until all readers are reading from the database file only. ^This ensures
  9100. ** that the next writer will restart the log file from the beginning.
  9101. ** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
  9102. ** database writer attempts while it is pending, but does not impede readers.
  9103. **
  9104. ** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
  9105. ** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
  9106. ** addition that it also truncates the log file to zero bytes just prior
  9107. ** to a successful return.
  9108. ** </dl>
  9109. **
  9110. ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
  9111. ** the log file or to -1 if the checkpoint could not run because
  9112. ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
  9113. ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
  9114. ** log file (including any that were already checkpointed before the function
  9115. ** was called) or to -1 if the checkpoint could not run due to an error or
  9116. ** because the database is not in WAL mode. ^Note that upon successful
  9117. ** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
  9118. ** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
  9119. **
  9120. ** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
  9121. ** any other process is running a checkpoint operation at the same time, the
  9122. ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
  9123. ** busy-handler configured, it will not be invoked in this case.
  9124. **
  9125. ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
  9126. ** exclusive "writer" lock on the database file. ^If the writer lock cannot be
  9127. ** obtained immediately, and a busy-handler is configured, it is invoked and
  9128. ** the writer lock retried until either the busy-handler returns 0 or the lock
  9129. ** is successfully obtained. ^The busy-handler is also invoked while waiting for
  9130. ** database readers as described above. ^If the busy-handler returns 0 before
  9131. ** the writer lock is obtained or while waiting for database readers, the
  9132. ** checkpoint operation proceeds from that point in the same way as
  9133. ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
  9134. ** without blocking any further. ^SQLITE_BUSY is returned in this case.
  9135. **
  9136. ** ^If parameter zDb is NULL or points to a zero length string, then the
  9137. ** specified operation is attempted on all WAL databases [attached] to
  9138. ** [database connection] db. In this case the
  9139. ** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
  9140. ** an SQLITE_BUSY error is encountered when processing one or more of the
  9141. ** attached WAL databases, the operation is still attempted on any remaining
  9142. ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
  9143. ** error occurs while processing an attached database, processing is abandoned
  9144. ** and the error code is returned to the caller immediately. ^If no error
  9145. ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
  9146. ** databases, SQLITE_OK is returned.
  9147. **
  9148. ** ^If database zDb is the name of an attached database that is not in WAL
  9149. ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
  9150. ** zDb is not NULL (or a zero length string) and is not the name of any
  9151. ** attached database, SQLITE_ERROR is returned to the caller.
  9152. **
  9153. ** ^Unless it returns SQLITE_MISUSE,
  9154. ** the sqlite3_wal_checkpoint_v2() interface
  9155. ** sets the error information that is queried by
  9156. ** [sqlite3_errcode()] and [sqlite3_errmsg()].
  9157. **
  9158. ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
  9159. ** from SQL.
  9160. */
  9161. SQLITE_API int sqlite3_wal_checkpoint_v2(
  9162. sqlite3 *db, /* Database handle */
  9163. const char *zDb, /* Name of attached database (or NULL) */
  9164. int eMode, /* SQLITE_CHECKPOINT_* value */
  9165. int *pnLog, /* OUT: Size of WAL log in frames */
  9166. int *pnCkpt /* OUT: Total number of frames checkpointed */
  9167. );
  9168. /*
  9169. ** CAPI3REF: Checkpoint Mode Values
  9170. ** KEYWORDS: {checkpoint mode}
  9171. **
  9172. ** These constants define all valid values for the "checkpoint mode" passed
  9173. ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
  9174. ** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
  9175. ** meaning of each of these checkpoint modes.
  9176. */
  9177. #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
  9178. #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
  9179. #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
  9180. #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
  9181. /*
  9182. ** CAPI3REF: Virtual Table Interface Configuration
  9183. **
  9184. ** This function may be called by either the [xConnect] or [xCreate] method
  9185. ** of a [virtual table] implementation to configure
  9186. ** various facets of the virtual table interface.
  9187. **
  9188. ** If this interface is invoked outside the context of an xConnect or
  9189. ** xCreate virtual table method then the behavior is undefined.
  9190. **
  9191. ** In the call sqlite3_vtab_config(D,C,...) the D parameter is the
  9192. ** [database connection] in which the virtual table is being created and
  9193. ** which is passed in as the first argument to the [xConnect] or [xCreate]
  9194. ** method that is invoking sqlite3_vtab_config(). The C parameter is one
  9195. ** of the [virtual table configuration options]. The presence and meaning
  9196. ** of parameters after C depend on which [virtual table configuration option]
  9197. ** is used.
  9198. */
  9199. SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
  9200. /*
  9201. ** CAPI3REF: Virtual Table Configuration Options
  9202. ** KEYWORDS: {virtual table configuration options}
  9203. ** KEYWORDS: {virtual table configuration option}
  9204. **
  9205. ** These macros define the various options to the
  9206. ** [sqlite3_vtab_config()] interface that [virtual table] implementations
  9207. ** can use to customize and optimize their behavior.
  9208. **
  9209. ** <dl>
  9210. ** [[SQLITE_VTAB_CONSTRAINT_SUPPORT]]
  9211. ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT</dt>
  9212. ** <dd>Calls of the form
  9213. ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
  9214. ** where X is an integer. If X is zero, then the [virtual table] whose
  9215. ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
  9216. ** support constraints. In this configuration (which is the default) if
  9217. ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
  9218. ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
  9219. ** specified as part of the users SQL statement, regardless of the actual
  9220. ** ON CONFLICT mode specified.
  9221. **
  9222. ** If X is non-zero, then the virtual table implementation guarantees
  9223. ** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
  9224. ** any modifications to internal or persistent data structures have been made.
  9225. ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
  9226. ** is able to roll back a statement or database transaction, and abandon
  9227. ** or continue processing the current SQL statement as appropriate.
  9228. ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
  9229. ** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
  9230. ** had been ABORT.
  9231. **
  9232. ** Virtual table implementations that are required to handle OR REPLACE
  9233. ** must do so within the [xUpdate] method. If a call to the
  9234. ** [sqlite3_vtab_on_conflict()] function indicates that the current ON
  9235. ** CONFLICT policy is REPLACE, the virtual table implementation should
  9236. ** silently replace the appropriate rows within the xUpdate callback and
  9237. ** return SQLITE_OK. Or, if this is not possible, it may return
  9238. ** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
  9239. ** constraint handling.
  9240. ** </dd>
  9241. **
  9242. ** [[SQLITE_VTAB_DIRECTONLY]]<dt>SQLITE_VTAB_DIRECTONLY</dt>
  9243. ** <dd>Calls of the form
  9244. ** [sqlite3_vtab_config](db,SQLITE_VTAB_DIRECTONLY) from within the
  9245. ** the [xConnect] or [xCreate] methods of a [virtual table] implmentation
  9246. ** prohibits that virtual table from being used from within triggers and
  9247. ** views.
  9248. ** </dd>
  9249. **
  9250. ** [[SQLITE_VTAB_INNOCUOUS]]<dt>SQLITE_VTAB_INNOCUOUS</dt>
  9251. ** <dd>Calls of the form
  9252. ** [sqlite3_vtab_config](db,SQLITE_VTAB_INNOCUOUS) from within the
  9253. ** the [xConnect] or [xCreate] methods of a [virtual table] implmentation
  9254. ** identify that virtual table as being safe to use from within triggers
  9255. ** and views. Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the
  9256. ** virtual table can do no serious harm even if it is controlled by a
  9257. ** malicious hacker. Developers should avoid setting the SQLITE_VTAB_INNOCUOUS
  9258. ** flag unless absolutely necessary.
  9259. ** </dd>
  9260. ** </dl>
  9261. */
  9262. #define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
  9263. #define SQLITE_VTAB_INNOCUOUS 2
  9264. #define SQLITE_VTAB_DIRECTONLY 3
  9265. /*
  9266. ** CAPI3REF: Determine The Virtual Table Conflict Policy
  9267. **
  9268. ** This function may only be called from within a call to the [xUpdate] method
  9269. ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
  9270. ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
  9271. ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
  9272. ** of the SQL statement that triggered the call to the [xUpdate] method of the
  9273. ** [virtual table].
  9274. */
  9275. SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
  9276. /*
  9277. ** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE
  9278. **
  9279. ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
  9280. ** method of a [virtual table], then it might return true if the
  9281. ** column is being fetched as part of an UPDATE operation during which the
  9282. ** column value will not change. The virtual table implementation can use
  9283. ** this hint as permission to substitute a return value that is less
  9284. ** expensive to compute and that the corresponding
  9285. ** [xUpdate] method understands as a "no-change" value.
  9286. **
  9287. ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that
  9288. ** the column is not changed by the UPDATE statement, then the xColumn
  9289. ** method can optionally return without setting a result, without calling
  9290. ** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].
  9291. ** In that case, [sqlite3_value_nochange(X)] will return true for the
  9292. ** same column in the [xUpdate] method.
  9293. **
  9294. ** The sqlite3_vtab_nochange() routine is an optimization. Virtual table
  9295. ** implementations should continue to give a correct answer even if the
  9296. ** sqlite3_vtab_nochange() interface were to always return false. In the
  9297. ** current implementation, the sqlite3_vtab_nochange() interface does always
  9298. ** returns false for the enhanced [UPDATE FROM] statement.
  9299. */
  9300. SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
  9301. /*
  9302. ** CAPI3REF: Determine The Collation For a Virtual Table Constraint
  9303. ** METHOD: sqlite3_index_info
  9304. **
  9305. ** This function may only be called from within a call to the [xBestIndex]
  9306. ** method of a [virtual table]. This function returns a pointer to a string
  9307. ** that is the name of the appropriate collation sequence to use for text
  9308. ** comparisons on the constraint identified by its arguments.
  9309. **
  9310. ** The first argument must be the pointer to the [sqlite3_index_info] object
  9311. ** that is the first parameter to the xBestIndex() method. The second argument
  9312. ** must be an index into the aConstraint[] array belonging to the
  9313. ** sqlite3_index_info structure passed to xBestIndex.
  9314. **
  9315. ** Important:
  9316. ** The first parameter must be the same pointer that is passed into the
  9317. ** xBestMethod() method. The first parameter may not be a pointer to a
  9318. ** different [sqlite3_index_info] object, even an exact copy.
  9319. **
  9320. ** The return value is computed as follows:
  9321. **
  9322. ** <ol>
  9323. ** <li><p> If the constraint comes from a WHERE clause expression that contains
  9324. ** a [COLLATE operator], then the name of the collation specified by
  9325. ** that COLLATE operator is returned.
  9326. ** <li><p> If there is no COLLATE operator, but the column that is the subject
  9327. ** of the constraint specifies an alternative collating sequence via
  9328. ** a [COLLATE clause] on the column definition within the CREATE TABLE
  9329. ** statement that was passed into [sqlite3_declare_vtab()], then the
  9330. ** name of that alternative collating sequence is returned.
  9331. ** <li><p> Otherwise, "BINARY" is returned.
  9332. ** </ol>
  9333. */
  9334. SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
  9335. /*
  9336. ** CAPI3REF: Determine if a virtual table query is DISTINCT
  9337. ** METHOD: sqlite3_index_info
  9338. **
  9339. ** This API may only be used from within an [xBestIndex|xBestIndex method]
  9340. ** of a [virtual table] implementation. The result of calling this
  9341. ** interface from outside of xBestIndex() is undefined and probably harmful.
  9342. **
  9343. ** ^The sqlite3_vtab_distinct() interface returns an integer that is
  9344. ** either 0, 1, or 2. The integer returned by sqlite3_vtab_distinct()
  9345. ** gives the virtual table additional information about how the query
  9346. ** planner wants the output to be ordered. As long as the virtual table
  9347. ** can meet the ordering requirements of the query planner, it may set
  9348. ** the "orderByConsumed" flag.
  9349. **
  9350. ** <ol><li value="0"><p>
  9351. ** ^If the sqlite3_vtab_distinct() interface returns 0, that means
  9352. ** that the query planner needs the virtual table to return all rows in the
  9353. ** sort order defined by the "nOrderBy" and "aOrderBy" fields of the
  9354. ** [sqlite3_index_info] object. This is the default expectation. If the
  9355. ** virtual table outputs all rows in sorted order, then it is always safe for
  9356. ** the xBestIndex method to set the "orderByConsumed" flag, regardless of
  9357. ** the return value from sqlite3_vtab_distinct().
  9358. ** <li value="1"><p>
  9359. ** ^(If the sqlite3_vtab_distinct() interface returns 1, that means
  9360. ** that the query planner does not need the rows to be returned in sorted order
  9361. ** as long as all rows with the same values in all columns identified by the
  9362. ** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
  9363. ** is doing a GROUP BY.
  9364. ** <li value="2"><p>
  9365. ** ^(If the sqlite3_vtab_distinct() interface returns 2, that means
  9366. ** that the query planner does not need the rows returned in any particular
  9367. ** order, as long as rows with the same values in all "aOrderBy" columns
  9368. ** are adjacent.)^ ^(Furthermore, only a single row for each particular
  9369. ** combination of values in the columns identified by the "aOrderBy" field
  9370. ** needs to be returned.)^ ^It is always ok for two or more rows with the same
  9371. ** values in all "aOrderBy" columns to be returned, as long as all such rows
  9372. ** are adjacent. ^The virtual table may, if it chooses, omit extra rows
  9373. ** that have the same value for all columns identified by "aOrderBy".
  9374. ** ^However omitting the extra rows is optional.
  9375. ** This mode is used for a DISTINCT query.
  9376. ** </ol>
  9377. **
  9378. ** ^For the purposes of comparing virtual table output values to see if the
  9379. ** values are same value for sorting purposes, two NULL values are considered
  9380. ** to be the same. In other words, the comparison operator is "IS"
  9381. ** (or "IS NOT DISTINCT FROM") and not "==".
  9382. **
  9383. ** If a virtual table implementation is unable to meet the requirements
  9384. ** specified above, then it must not set the "orderByConsumed" flag in the
  9385. ** [sqlite3_index_info] object or an incorrect answer may result.
  9386. **
  9387. ** ^A virtual table implementation is always free to return rows in any order
  9388. ** it wants, as long as the "orderByConsumed" flag is not set. ^When the
  9389. ** the "orderByConsumed" flag is unset, the query planner will add extra
  9390. ** [bytecode] to ensure that the final results returned by the SQL query are
  9391. ** ordered correctly. The use of the "orderByConsumed" flag and the
  9392. ** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
  9393. ** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
  9394. ** flag might help queries against a virtual table to run faster. Being
  9395. ** overly aggressive and setting the "orderByConsumed" flag when it is not
  9396. ** valid to do so, on the other hand, might cause SQLite to return incorrect
  9397. ** results.
  9398. */
  9399. SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*);
  9400. /*
  9401. ** CAPI3REF: Identify and handle IN constraints in xBestIndex
  9402. **
  9403. ** This interface may only be used from within an
  9404. ** [xBestIndex|xBestIndex() method] of a [virtual table] implementation.
  9405. ** The result of invoking this interface from any other context is
  9406. ** undefined and probably harmful.
  9407. **
  9408. ** ^(A constraint on a virtual table of the form
  9409. ** "[IN operator|column IN (...)]" is
  9410. ** communicated to the xBestIndex method as a
  9411. ** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use
  9412. ** this constraint, it must set the corresponding
  9413. ** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under
  9414. ** the usual mode of handling IN operators, SQLite generates [bytecode]
  9415. ** that invokes the [xFilter|xFilter() method] once for each value
  9416. ** on the right-hand side of the IN operator.)^ Thus the virtual table
  9417. ** only sees a single value from the right-hand side of the IN operator
  9418. ** at a time.
  9419. **
  9420. ** In some cases, however, it would be advantageous for the virtual
  9421. ** table to see all values on the right-hand of the IN operator all at
  9422. ** once. The sqlite3_vtab_in() interfaces facilitates this in two ways:
  9423. **
  9424. ** <ol>
  9425. ** <li><p>
  9426. ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
  9427. ** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
  9428. ** is an [IN operator] that can be processed all at once. ^In other words,
  9429. ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
  9430. ** by which the virtual table can ask SQLite if all-at-once processing
  9431. ** of the IN operator is even possible.
  9432. **
  9433. ** <li><p>
  9434. ** ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
  9435. ** to SQLite that the virtual table does or does not want to process
  9436. ** the IN operator all-at-once, respectively. ^Thus when the third
  9437. ** parameter (F) is non-negative, this interface is the mechanism by
  9438. ** which the virtual table tells SQLite how it wants to process the
  9439. ** IN operator.
  9440. ** </ol>
  9441. **
  9442. ** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
  9443. ** within the same xBestIndex method call. ^For any given P,N pair,
  9444. ** the return value from sqlite3_vtab_in(P,N,F) will always be the same
  9445. ** within the same xBestIndex call. ^If the interface returns true
  9446. ** (non-zero), that means that the constraint is an IN operator
  9447. ** that can be processed all-at-once. ^If the constraint is not an IN
  9448. ** operator or cannot be processed all-at-once, then the interface returns
  9449. ** false.
  9450. **
  9451. ** ^(All-at-once processing of the IN operator is selected if both of the
  9452. ** following conditions are met:
  9453. **
  9454. ** <ol>
  9455. ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
  9456. ** integer. This is how the virtual table tells SQLite that it wants to
  9457. ** use the N-th constraint.
  9458. **
  9459. ** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was
  9460. ** non-negative had F>=1.
  9461. ** </ol>)^
  9462. **
  9463. ** ^If either or both of the conditions above are false, then SQLite uses
  9464. ** the traditional one-at-a-time processing strategy for the IN constraint.
  9465. ** ^If both conditions are true, then the argvIndex-th parameter to the
  9466. ** xFilter method will be an [sqlite3_value] that appears to be NULL,
  9467. ** but which can be passed to [sqlite3_vtab_in_first()] and
  9468. ** [sqlite3_vtab_in_next()] to find all values on the right-hand side
  9469. ** of the IN constraint.
  9470. */
  9471. SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
  9472. /*
  9473. ** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
  9474. **
  9475. ** These interfaces are only useful from within the
  9476. ** [xFilter|xFilter() method] of a [virtual table] implementation.
  9477. ** The result of invoking these interfaces from any other context
  9478. ** is undefined and probably harmful.
  9479. **
  9480. ** The X parameter in a call to sqlite3_vtab_in_first(X,P) or
  9481. ** sqlite3_vtab_in_next(X,P) must be one of the parameters to the
  9482. ** xFilter method which invokes these routines, and specifically
  9483. ** a parameter that was previously selected for all-at-once IN constraint
  9484. ** processing use the [sqlite3_vtab_in()] interface in the
  9485. ** [xBestIndex|xBestIndex method]. ^(If the X parameter is not
  9486. ** an xFilter argument that was selected for all-at-once IN constraint
  9487. ** processing, then these routines return [SQLITE_MISUSE])^ or perhaps
  9488. ** exhibit some other undefined or harmful behavior.
  9489. **
  9490. ** ^(Use these routines to access all values on the right-hand side
  9491. ** of the IN constraint using code like the following:
  9492. **
  9493. ** <blockquote><pre>
  9494. ** &nbsp; for(rc=sqlite3_vtab_in_first(pList, &pVal);
  9495. ** &nbsp; rc==SQLITE_OK && pVal
  9496. ** &nbsp; rc=sqlite3_vtab_in_next(pList, &pVal)
  9497. ** &nbsp; ){
  9498. ** &nbsp; // do something with pVal
  9499. ** &nbsp; }
  9500. ** &nbsp; if( rc!=SQLITE_OK ){
  9501. ** &nbsp; // an error has occurred
  9502. ** &nbsp; }
  9503. ** </pre></blockquote>)^
  9504. **
  9505. ** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
  9506. ** routines return SQLITE_OK and set *P to point to the first or next value
  9507. ** on the RHS of the IN constraint. ^If there are no more values on the
  9508. ** right hand side of the IN constraint, then *P is set to NULL and these
  9509. ** routines return [SQLITE_DONE]. ^The return value might be
  9510. ** some other value, such as SQLITE_NOMEM, in the event of a malfunction.
  9511. **
  9512. ** The *ppOut values returned by these routines are only valid until the
  9513. ** next call to either of these routines or until the end of the xFilter
  9514. ** method from which these routines were called. If the virtual table
  9515. ** implementation needs to retain the *ppOut values for longer, it must make
  9516. ** copies. The *ppOut values are [protected sqlite3_value|protected].
  9517. */
  9518. SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
  9519. SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);
  9520. /*
  9521. ** CAPI3REF: Constraint values in xBestIndex()
  9522. ** METHOD: sqlite3_index_info
  9523. **
  9524. ** This API may only be used from within the [xBestIndex|xBestIndex method]
  9525. ** of a [virtual table] implementation. The result of calling this interface
  9526. ** from outside of an xBestIndex method are undefined and probably harmful.
  9527. **
  9528. ** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
  9529. ** the [xBestIndex] method of a [virtual table] implementation, with P being
  9530. ** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and
  9531. ** J being a 0-based index into P->aConstraint[], then this routine
  9532. ** attempts to set *V to the value of the right-hand operand of
  9533. ** that constraint if the right-hand operand is known. ^If the
  9534. ** right-hand operand is not known, then *V is set to a NULL pointer.
  9535. ** ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if
  9536. ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
  9537. ** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
  9538. ** constraint is not available. ^The sqlite3_vtab_rhs_value() interface
  9539. ** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if
  9540. ** something goes wrong.
  9541. **
  9542. ** The sqlite3_vtab_rhs_value() interface is usually only successful if
  9543. ** the right-hand operand of a constraint is a literal value in the original
  9544. ** SQL statement. If the right-hand operand is an expression or a reference
  9545. ** to some other column or a [host parameter], then sqlite3_vtab_rhs_value()
  9546. ** will probably return [SQLITE_NOTFOUND].
  9547. **
  9548. ** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and
  9549. ** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such
  9550. ** constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^
  9551. **
  9552. ** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value
  9553. ** and remains valid for the duration of the xBestIndex method call.
  9554. ** ^When xBestIndex returns, the sqlite3_value object returned by
  9555. ** sqlite3_vtab_rhs_value() is automatically deallocated.
  9556. **
  9557. ** The "_rhs_" in the name of this routine is an appreviation for
  9558. ** "Right-Hand Side".
  9559. */
  9560. SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
  9561. /*
  9562. ** CAPI3REF: Conflict resolution modes
  9563. ** KEYWORDS: {conflict resolution mode}
  9564. **
  9565. ** These constants are returned by [sqlite3_vtab_on_conflict()] to
  9566. ** inform a [virtual table] implementation what the [ON CONFLICT] mode
  9567. ** is for the SQL statement being evaluated.
  9568. **
  9569. ** Note that the [SQLITE_IGNORE] constant is also used as a potential
  9570. ** return value from the [sqlite3_set_authorizer()] callback and that
  9571. ** [SQLITE_ABORT] is also a [result code].
  9572. */
  9573. #define SQLITE_ROLLBACK 1
  9574. /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
  9575. #define SQLITE_FAIL 3
  9576. /* #define SQLITE_ABORT 4 // Also an error code */
  9577. #define SQLITE_REPLACE 5
  9578. /*
  9579. ** CAPI3REF: Prepared Statement Scan Status Opcodes
  9580. ** KEYWORDS: {scanstatus options}
  9581. **
  9582. ** The following constants can be used for the T parameter to the
  9583. ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
  9584. ** different metric for sqlite3_stmt_scanstatus() to return.
  9585. **
  9586. ** When the value returned to V is a string, space to hold that string is
  9587. ** managed by the prepared statement S and will be automatically freed when
  9588. ** S is finalized.
  9589. **
  9590. ** <dl>
  9591. ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
  9592. ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be
  9593. ** set to the total number of times that the X-th loop has run.</dd>
  9594. **
  9595. ** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
  9596. ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be set
  9597. ** to the total number of rows examined by all iterations of the X-th loop.</dd>
  9598. **
  9599. ** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
  9600. ** <dd>^The "double" variable pointed to by the V parameter will be set to the
  9601. ** query planner's estimate for the average number of rows output from each
  9602. ** iteration of the X-th loop. If the query planner's estimates was accurate,
  9603. ** then this value will approximate the quotient NVISIT/NLOOP and the
  9604. ** product of this value for all prior loops with the same SELECTID will
  9605. ** be the NLOOP value for the current loop.
  9606. **
  9607. ** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
  9608. ** <dd>^The "const char *" variable pointed to by the V parameter will be set
  9609. ** to a zero-terminated UTF-8 string containing the name of the index or table
  9610. ** used for the X-th loop.
  9611. **
  9612. ** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
  9613. ** <dd>^The "const char *" variable pointed to by the V parameter will be set
  9614. ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
  9615. ** description for the X-th loop.
  9616. **
  9617. ** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
  9618. ** <dd>^The "int" variable pointed to by the V parameter will be set to the
  9619. ** "select-id" for the X-th loop. The select-id identifies which query or
  9620. ** subquery the loop is part of. The main query has a select-id of zero.
  9621. ** The select-id is the same value as is output in the first column
  9622. ** of an [EXPLAIN QUERY PLAN] query.
  9623. ** </dl>
  9624. */
  9625. #define SQLITE_SCANSTAT_NLOOP 0
  9626. #define SQLITE_SCANSTAT_NVISIT 1
  9627. #define SQLITE_SCANSTAT_EST 2
  9628. #define SQLITE_SCANSTAT_NAME 3
  9629. #define SQLITE_SCANSTAT_EXPLAIN 4
  9630. #define SQLITE_SCANSTAT_SELECTID 5
  9631. /*
  9632. ** CAPI3REF: Prepared Statement Scan Status
  9633. ** METHOD: sqlite3_stmt
  9634. **
  9635. ** This interface returns information about the predicted and measured
  9636. ** performance for pStmt. Advanced applications can use this
  9637. ** interface to compare the predicted and the measured performance and
  9638. ** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
  9639. **
  9640. ** Since this interface is expected to be rarely used, it is only
  9641. ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
  9642. ** compile-time option.
  9643. **
  9644. ** The "iScanStatusOp" parameter determines which status information to return.
  9645. ** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
  9646. ** of this interface is undefined.
  9647. ** ^The requested measurement is written into a variable pointed to by
  9648. ** the "pOut" parameter.
  9649. ** Parameter "idx" identifies the specific loop to retrieve statistics for.
  9650. ** Loops are numbered starting from zero. ^If idx is out of range - less than
  9651. ** zero or greater than or equal to the total number of loops used to implement
  9652. ** the statement - a non-zero value is returned and the variable that pOut
  9653. ** points to is unchanged.
  9654. **
  9655. ** ^Statistics might not be available for all loops in all statements. ^In cases
  9656. ** where there exist loops with no available statistics, this function behaves
  9657. ** as if the loop did not exist - it returns non-zero and leave the variable
  9658. ** that pOut points to unchanged.
  9659. **
  9660. ** See also: [sqlite3_stmt_scanstatus_reset()]
  9661. */
  9662. SQLITE_API int sqlite3_stmt_scanstatus(
  9663. sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
  9664. int idx, /* Index of loop to report on */
  9665. int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
  9666. void *pOut /* Result written here */
  9667. );
  9668. /*
  9669. ** CAPI3REF: Zero Scan-Status Counters
  9670. ** METHOD: sqlite3_stmt
  9671. **
  9672. ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
  9673. **
  9674. ** This API is only available if the library is built with pre-processor
  9675. ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
  9676. */
  9677. SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
  9678. /*
  9679. ** CAPI3REF: Flush caches to disk mid-transaction
  9680. ** METHOD: sqlite3
  9681. **
  9682. ** ^If a write-transaction is open on [database connection] D when the
  9683. ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
  9684. ** pages in the pager-cache that are not currently in use are written out
  9685. ** to disk. A dirty page may be in use if a database cursor created by an
  9686. ** active SQL statement is reading from it, or if it is page 1 of a database
  9687. ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
  9688. ** interface flushes caches for all schemas - "main", "temp", and
  9689. ** any [attached] databases.
  9690. **
  9691. ** ^If this function needs to obtain extra database locks before dirty pages
  9692. ** can be flushed to disk, it does so. ^If those locks cannot be obtained
  9693. ** immediately and there is a busy-handler callback configured, it is invoked
  9694. ** in the usual manner. ^If the required lock still cannot be obtained, then
  9695. ** the database is skipped and an attempt made to flush any dirty pages
  9696. ** belonging to the next (if any) database. ^If any databases are skipped
  9697. ** because locks cannot be obtained, but no other error occurs, this
  9698. ** function returns SQLITE_BUSY.
  9699. **
  9700. ** ^If any other error occurs while flushing dirty pages to disk (for
  9701. ** example an IO error or out-of-memory condition), then processing is
  9702. ** abandoned and an SQLite [error code] is returned to the caller immediately.
  9703. **
  9704. ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
  9705. **
  9706. ** ^This function does not set the database handle error code or message
  9707. ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
  9708. */
  9709. SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
  9710. /*
  9711. ** CAPI3REF: The pre-update hook.
  9712. ** METHOD: sqlite3
  9713. **
  9714. ** ^These interfaces are only available if SQLite is compiled using the
  9715. ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
  9716. **
  9717. ** ^The [sqlite3_preupdate_hook()] interface registers a callback function
  9718. ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
  9719. ** on a database table.
  9720. ** ^At most one preupdate hook may be registered at a time on a single
  9721. ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
  9722. ** the previous setting.
  9723. ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
  9724. ** with a NULL pointer as the second parameter.
  9725. ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
  9726. ** the first parameter to callbacks.
  9727. **
  9728. ** ^The preupdate hook only fires for changes to real database tables; the
  9729. ** preupdate hook is not invoked for changes to [virtual tables] or to
  9730. ** system tables like sqlite_sequence or sqlite_stat1.
  9731. **
  9732. ** ^The second parameter to the preupdate callback is a pointer to
  9733. ** the [database connection] that registered the preupdate hook.
  9734. ** ^The third parameter to the preupdate callback is one of the constants
  9735. ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
  9736. ** kind of update operation that is about to occur.
  9737. ** ^(The fourth parameter to the preupdate callback is the name of the
  9738. ** database within the database connection that is being modified. This
  9739. ** will be "main" for the main database or "temp" for TEMP tables or
  9740. ** the name given after the AS keyword in the [ATTACH] statement for attached
  9741. ** databases.)^
  9742. ** ^The fifth parameter to the preupdate callback is the name of the
  9743. ** table that is being modified.
  9744. **
  9745. ** For an UPDATE or DELETE operation on a [rowid table], the sixth
  9746. ** parameter passed to the preupdate callback is the initial [rowid] of the
  9747. ** row being modified or deleted. For an INSERT operation on a rowid table,
  9748. ** or any operation on a WITHOUT ROWID table, the value of the sixth
  9749. ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
  9750. ** seventh parameter is the final rowid value of the row being inserted
  9751. ** or updated. The value of the seventh parameter passed to the callback
  9752. ** function is not defined for operations on WITHOUT ROWID tables, or for
  9753. ** DELETE operations on rowid tables.
  9754. **
  9755. ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
  9756. ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
  9757. ** provide additional information about a preupdate event. These routines
  9758. ** may only be called from within a preupdate callback. Invoking any of
  9759. ** these routines from outside of a preupdate callback or with a
  9760. ** [database connection] pointer that is different from the one supplied
  9761. ** to the preupdate callback results in undefined and probably undesirable
  9762. ** behavior.
  9763. **
  9764. ** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
  9765. ** in the row that is being inserted, updated, or deleted.
  9766. **
  9767. ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
  9768. ** a [protected sqlite3_value] that contains the value of the Nth column of
  9769. ** the table row before it is updated. The N parameter must be between 0
  9770. ** and one less than the number of columns or the behavior will be
  9771. ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
  9772. ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
  9773. ** behavior is undefined. The [sqlite3_value] that P points to
  9774. ** will be destroyed when the preupdate callback returns.
  9775. **
  9776. ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
  9777. ** a [protected sqlite3_value] that contains the value of the Nth column of
  9778. ** the table row after it is updated. The N parameter must be between 0
  9779. ** and one less than the number of columns or the behavior will be
  9780. ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
  9781. ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
  9782. ** behavior is undefined. The [sqlite3_value] that P points to
  9783. ** will be destroyed when the preupdate callback returns.
  9784. **
  9785. ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
  9786. ** callback was invoked as a result of a direct insert, update, or delete
  9787. ** operation; or 1 for inserts, updates, or deletes invoked by top-level
  9788. ** triggers; or 2 for changes resulting from triggers called by top-level
  9789. ** triggers; and so forth.
  9790. **
  9791. ** When the [sqlite3_blob_write()] API is used to update a blob column,
  9792. ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
  9793. ** in this case the new values are not available. In this case, when a
  9794. ** callback made with op==SQLITE_DELETE is actuall a write using the
  9795. ** sqlite3_blob_write() API, the [sqlite3_preupdate_blobwrite()] returns
  9796. ** the index of the column being written. In other cases, where the
  9797. ** pre-update hook is being invoked for some other reason, including a
  9798. ** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.
  9799. **
  9800. ** See also: [sqlite3_update_hook()]
  9801. */
  9802. #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
  9803. SQLITE_API void *sqlite3_preupdate_hook(
  9804. sqlite3 *db,
  9805. void(*xPreUpdate)(
  9806. void *pCtx, /* Copy of third arg to preupdate_hook() */
  9807. sqlite3 *db, /* Database handle */
  9808. int op, /* SQLITE_UPDATE, DELETE or INSERT */
  9809. char const *zDb, /* Database name */
  9810. char const *zName, /* Table name */
  9811. sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
  9812. sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
  9813. ),
  9814. void*
  9815. );
  9816. SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
  9817. SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
  9818. SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
  9819. SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
  9820. SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *);
  9821. #endif
  9822. /*
  9823. ** CAPI3REF: Low-level system error code
  9824. ** METHOD: sqlite3
  9825. **
  9826. ** ^Attempt to return the underlying operating system error code or error
  9827. ** number that caused the most recent I/O error or failure to open a file.
  9828. ** The return value is OS-dependent. For example, on unix systems, after
  9829. ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
  9830. ** called to get back the underlying "errno" that caused the problem, such
  9831. ** as ENOSPC, EAUTH, EISDIR, and so forth.
  9832. */
  9833. SQLITE_API int sqlite3_system_errno(sqlite3*);
  9834. /*
  9835. ** CAPI3REF: Database Snapshot
  9836. ** KEYWORDS: {snapshot} {sqlite3_snapshot}
  9837. **
  9838. ** An instance of the snapshot object records the state of a [WAL mode]
  9839. ** database for some specific point in history.
  9840. **
  9841. ** In [WAL mode], multiple [database connections] that are open on the
  9842. ** same database file can each be reading a different historical version
  9843. ** of the database file. When a [database connection] begins a read
  9844. ** transaction, that connection sees an unchanging copy of the database
  9845. ** as it existed for the point in time when the transaction first started.
  9846. ** Subsequent changes to the database from other connections are not seen
  9847. ** by the reader until a new read transaction is started.
  9848. **
  9849. ** The sqlite3_snapshot object records state information about an historical
  9850. ** version of the database file so that it is possible to later open a new read
  9851. ** transaction that sees that historical version of the database rather than
  9852. ** the most recent version.
  9853. */
  9854. typedef struct sqlite3_snapshot {
  9855. unsigned char hidden[48];
  9856. } sqlite3_snapshot;
  9857. /*
  9858. ** CAPI3REF: Record A Database Snapshot
  9859. ** CONSTRUCTOR: sqlite3_snapshot
  9860. **
  9861. ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
  9862. ** new [sqlite3_snapshot] object that records the current state of
  9863. ** schema S in database connection D. ^On success, the
  9864. ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
  9865. ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
  9866. ** If there is not already a read-transaction open on schema S when
  9867. ** this function is called, one is opened automatically.
  9868. **
  9869. ** The following must be true for this function to succeed. If any of
  9870. ** the following statements are false when sqlite3_snapshot_get() is
  9871. ** called, SQLITE_ERROR is returned. The final value of *P is undefined
  9872. ** in this case.
  9873. **
  9874. ** <ul>
  9875. ** <li> The database handle must not be in [autocommit mode].
  9876. **
  9877. ** <li> Schema S of [database connection] D must be a [WAL mode] database.
  9878. **
  9879. ** <li> There must not be a write transaction open on schema S of database
  9880. ** connection D.
  9881. **
  9882. ** <li> One or more transactions must have been written to the current wal
  9883. ** file since it was created on disk (by any connection). This means
  9884. ** that a snapshot cannot be taken on a wal mode database with no wal
  9885. ** file immediately after it is first opened. At least one transaction
  9886. ** must be written to it first.
  9887. ** </ul>
  9888. **
  9889. ** This function may also return SQLITE_NOMEM. If it is called with the
  9890. ** database handle in autocommit mode but fails for some other reason,
  9891. ** whether or not a read transaction is opened on schema S is undefined.
  9892. **
  9893. ** The [sqlite3_snapshot] object returned from a successful call to
  9894. ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
  9895. ** to avoid a memory leak.
  9896. **
  9897. ** The [sqlite3_snapshot_get()] interface is only available when the
  9898. ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9899. */
  9900. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
  9901. sqlite3 *db,
  9902. const char *zSchema,
  9903. sqlite3_snapshot **ppSnapshot
  9904. );
  9905. /*
  9906. ** CAPI3REF: Start a read transaction on an historical snapshot
  9907. ** METHOD: sqlite3_snapshot
  9908. **
  9909. ** ^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read
  9910. ** transaction or upgrades an existing one for schema S of
  9911. ** [database connection] D such that the read transaction refers to
  9912. ** historical [snapshot] P, rather than the most recent change to the
  9913. ** database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK
  9914. ** on success or an appropriate [error code] if it fails.
  9915. **
  9916. ** ^In order to succeed, the database connection must not be in
  9917. ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there
  9918. ** is already a read transaction open on schema S, then the database handle
  9919. ** must have no active statements (SELECT statements that have been passed
  9920. ** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
  9921. ** SQLITE_ERROR is returned if either of these conditions is violated, or
  9922. ** if schema S does not exist, or if the snapshot object is invalid.
  9923. **
  9924. ** ^A call to sqlite3_snapshot_open() will fail to open if the specified
  9925. ** snapshot has been overwritten by a [checkpoint]. In this case
  9926. ** SQLITE_ERROR_SNAPSHOT is returned.
  9927. **
  9928. ** If there is already a read transaction open when this function is
  9929. ** invoked, then the same read transaction remains open (on the same
  9930. ** database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT
  9931. ** is returned. If another error code - for example SQLITE_PROTOCOL or an
  9932. ** SQLITE_IOERR error code - is returned, then the final state of the
  9933. ** read transaction is undefined. If SQLITE_OK is returned, then the
  9934. ** read transaction is now open on database snapshot P.
  9935. **
  9936. ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
  9937. ** database connection D does not know that the database file for
  9938. ** schema S is in [WAL mode]. A database connection might not know
  9939. ** that the database file is in [WAL mode] if there has been no prior
  9940. ** I/O on that database connection, or if the database entered [WAL mode]
  9941. ** after the most recent I/O on the database connection.)^
  9942. ** (Hint: Run "[PRAGMA application_id]" against a newly opened
  9943. ** database connection in order to make it ready to use snapshots.)
  9944. **
  9945. ** The [sqlite3_snapshot_open()] interface is only available when the
  9946. ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9947. */
  9948. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
  9949. sqlite3 *db,
  9950. const char *zSchema,
  9951. sqlite3_snapshot *pSnapshot
  9952. );
  9953. /*
  9954. ** CAPI3REF: Destroy a snapshot
  9955. ** DESTRUCTOR: sqlite3_snapshot
  9956. **
  9957. ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
  9958. ** The application must eventually free every [sqlite3_snapshot] object
  9959. ** using this routine to avoid a memory leak.
  9960. **
  9961. ** The [sqlite3_snapshot_free()] interface is only available when the
  9962. ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9963. */
  9964. SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
  9965. /*
  9966. ** CAPI3REF: Compare the ages of two snapshot handles.
  9967. ** METHOD: sqlite3_snapshot
  9968. **
  9969. ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
  9970. ** of two valid snapshot handles.
  9971. **
  9972. ** If the two snapshot handles are not associated with the same database
  9973. ** file, the result of the comparison is undefined.
  9974. **
  9975. ** Additionally, the result of the comparison is only valid if both of the
  9976. ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
  9977. ** last time the wal file was deleted. The wal file is deleted when the
  9978. ** database is changed back to rollback mode or when the number of database
  9979. ** clients drops to zero. If either snapshot handle was obtained before the
  9980. ** wal file was last deleted, the value returned by this function
  9981. ** is undefined.
  9982. **
  9983. ** Otherwise, this API returns a negative value if P1 refers to an older
  9984. ** snapshot than P2, zero if the two handles refer to the same database
  9985. ** snapshot, and a positive value if P1 is a newer snapshot than P2.
  9986. **
  9987. ** This interface is only available if SQLite is compiled with the
  9988. ** [SQLITE_ENABLE_SNAPSHOT] option.
  9989. */
  9990. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
  9991. sqlite3_snapshot *p1,
  9992. sqlite3_snapshot *p2
  9993. );
  9994. /*
  9995. ** CAPI3REF: Recover snapshots from a wal file
  9996. ** METHOD: sqlite3_snapshot
  9997. **
  9998. ** If a [WAL file] remains on disk after all database connections close
  9999. ** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control]
  10000. ** or because the last process to have the database opened exited without
  10001. ** calling [sqlite3_close()]) and a new connection is subsequently opened
  10002. ** on that database and [WAL file], the [sqlite3_snapshot_open()] interface
  10003. ** will only be able to open the last transaction added to the WAL file
  10004. ** even though the WAL file contains other valid transactions.
  10005. **
  10006. ** This function attempts to scan the WAL file associated with database zDb
  10007. ** of database handle db and make all valid snapshots available to
  10008. ** sqlite3_snapshot_open(). It is an error if there is already a read
  10009. ** transaction open on the database, or if the database is not a WAL mode
  10010. ** database.
  10011. **
  10012. ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
  10013. **
  10014. ** This interface is only available if SQLite is compiled with the
  10015. ** [SQLITE_ENABLE_SNAPSHOT] option.
  10016. */
  10017. SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
  10018. /*
  10019. ** CAPI3REF: Serialize a database
  10020. **
  10021. ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
  10022. ** that is a serialization of the S database on [database connection] D.
  10023. ** If P is not a NULL pointer, then the size of the database in bytes
  10024. ** is written into *P.
  10025. **
  10026. ** For an ordinary on-disk database file, the serialization is just a
  10027. ** copy of the disk file. For an in-memory database or a "TEMP" database,
  10028. ** the serialization is the same sequence of bytes which would be written
  10029. ** to disk if that database where backed up to disk.
  10030. **
  10031. ** The usual case is that sqlite3_serialize() copies the serialization of
  10032. ** the database into memory obtained from [sqlite3_malloc64()] and returns
  10033. ** a pointer to that memory. The caller is responsible for freeing the
  10034. ** returned value to avoid a memory leak. However, if the F argument
  10035. ** contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
  10036. ** are made, and the sqlite3_serialize() function will return a pointer
  10037. ** to the contiguous memory representation of the database that SQLite
  10038. ** is currently using for that database, or NULL if the no such contiguous
  10039. ** memory representation of the database exists. A contiguous memory
  10040. ** representation of the database will usually only exist if there has
  10041. ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same
  10042. ** values of D and S.
  10043. ** The size of the database is written into *P even if the
  10044. ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
  10045. ** of the database exists.
  10046. **
  10047. ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
  10048. ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
  10049. ** allocation error occurs.
  10050. **
  10051. ** This interface is omitted if SQLite is compiled with the
  10052. ** [SQLITE_OMIT_DESERIALIZE] option.
  10053. */
  10054. SQLITE_API unsigned char *sqlite3_serialize(
  10055. sqlite3 *db, /* The database connection */
  10056. const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */
  10057. sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
  10058. unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */
  10059. );
  10060. /*
  10061. ** CAPI3REF: Flags for sqlite3_serialize
  10062. **
  10063. ** Zero or more of the following constants can be OR-ed together for
  10064. ** the F argument to [sqlite3_serialize(D,S,P,F)].
  10065. **
  10066. ** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return
  10067. ** a pointer to contiguous in-memory database that it is currently using,
  10068. ** without making a copy of the database. If SQLite is not currently using
  10069. ** a contiguous in-memory database, then this option causes
  10070. ** [sqlite3_serialize()] to return a NULL pointer. SQLite will only be
  10071. ** using a contiguous in-memory database if it has been initialized by a
  10072. ** prior call to [sqlite3_deserialize()].
  10073. */
  10074. #define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */
  10075. /*
  10076. ** CAPI3REF: Deserialize a database
  10077. **
  10078. ** The sqlite3_deserialize(D,S,P,N,M,F) interface causes the
  10079. ** [database connection] D to disconnect from database S and then
  10080. ** reopen S as an in-memory database based on the serialization contained
  10081. ** in P. The serialized database P is N bytes in size. M is the size of
  10082. ** the buffer P, which might be larger than N. If M is larger than N, and
  10083. ** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
  10084. ** permitted to add content to the in-memory database as long as the total
  10085. ** size does not exceed M bytes.
  10086. **
  10087. ** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
  10088. ** invoke sqlite3_free() on the serialization buffer when the database
  10089. ** connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
  10090. ** SQLite will try to increase the buffer size using sqlite3_realloc64()
  10091. ** if writes on the database cause it to grow larger than M bytes.
  10092. **
  10093. ** The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
  10094. ** database is currently in a read transaction or is involved in a backup
  10095. ** operation.
  10096. **
  10097. ** It is not possible to deserialized into the TEMP database. If the
  10098. ** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
  10099. ** function returns SQLITE_ERROR.
  10100. **
  10101. ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
  10102. ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
  10103. ** [sqlite3_free()] is invoked on argument P prior to returning.
  10104. **
  10105. ** This interface is omitted if SQLite is compiled with the
  10106. ** [SQLITE_OMIT_DESERIALIZE] option.
  10107. */
  10108. SQLITE_API int sqlite3_deserialize(
  10109. sqlite3 *db, /* The database connection */
  10110. const char *zSchema, /* Which DB to reopen with the deserialization */
  10111. unsigned char *pData, /* The serialized database content */
  10112. sqlite3_int64 szDb, /* Number bytes in the deserialization */
  10113. sqlite3_int64 szBuf, /* Total size of buffer pData[] */
  10114. unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */
  10115. );
  10116. /*
  10117. ** CAPI3REF: Flags for sqlite3_deserialize()
  10118. **
  10119. ** The following are allowed values for 6th argument (the F argument) to
  10120. ** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.
  10121. **
  10122. ** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
  10123. ** in the P argument is held in memory obtained from [sqlite3_malloc64()]
  10124. ** and that SQLite should take ownership of this memory and automatically
  10125. ** free it when it has finished using it. Without this flag, the caller
  10126. ** is responsible for freeing any dynamically allocated memory.
  10127. **
  10128. ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
  10129. ** grow the size of the database using calls to [sqlite3_realloc64()]. This
  10130. ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
  10131. ** Without this flag, the deserialized database cannot increase in size beyond
  10132. ** the number of bytes specified by the M parameter.
  10133. **
  10134. ** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
  10135. ** should be treated as read-only.
  10136. */
  10137. #define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
  10138. #define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */
  10139. #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
  10140. /*
  10141. ** Undo the hack that converts floating point types to integer for
  10142. ** builds on processors without floating point support.
  10143. */
  10144. #ifdef SQLITE_OMIT_FLOATING_POINT
  10145. # undef double
  10146. #endif
  10147. #ifdef __cplusplus
  10148. } /* End of the 'extern "C"' block */
  10149. #endif
  10150. #endif /* SQLITE3_H */
  10151. /******** Begin file sqlite3rtree.h *********/
  10152. /*
  10153. ** 2010 August 30
  10154. **
  10155. ** The author disclaims copyright to this source code. In place of
  10156. ** a legal notice, here is a blessing:
  10157. **
  10158. ** May you do good and not evil.
  10159. ** May you find forgiveness for yourself and forgive others.
  10160. ** May you share freely, never taking more than you give.
  10161. **
  10162. *************************************************************************
  10163. */
  10164. #ifndef _SQLITE3RTREE_H_
  10165. #define _SQLITE3RTREE_H_
  10166. #ifdef __cplusplus
  10167. extern "C" {
  10168. #endif
  10169. typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
  10170. typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
  10171. /* The double-precision datatype used by RTree depends on the
  10172. ** SQLITE_RTREE_INT_ONLY compile-time option.
  10173. */
  10174. #ifdef SQLITE_RTREE_INT_ONLY
  10175. typedef sqlite3_int64 sqlite3_rtree_dbl;
  10176. #else
  10177. typedef double sqlite3_rtree_dbl;
  10178. #endif
  10179. /*
  10180. ** Register a geometry callback named zGeom that can be used as part of an
  10181. ** R-Tree geometry query as follows:
  10182. **
  10183. ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
  10184. */
  10185. SQLITE_API int sqlite3_rtree_geometry_callback(
  10186. sqlite3 *db,
  10187. const char *zGeom,
  10188. int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
  10189. void *pContext
  10190. );
  10191. /*
  10192. ** A pointer to a structure of the following type is passed as the first
  10193. ** argument to callbacks registered using rtree_geometry_callback().
  10194. */
  10195. struct sqlite3_rtree_geometry {
  10196. void *pContext; /* Copy of pContext passed to s_r_g_c() */
  10197. int nParam; /* Size of array aParam[] */
  10198. sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
  10199. void *pUser; /* Callback implementation user data */
  10200. void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
  10201. };
  10202. /*
  10203. ** Register a 2nd-generation geometry callback named zScore that can be
  10204. ** used as part of an R-Tree geometry query as follows:
  10205. **
  10206. ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
  10207. */
  10208. SQLITE_API int sqlite3_rtree_query_callback(
  10209. sqlite3 *db,
  10210. const char *zQueryFunc,
  10211. int (*xQueryFunc)(sqlite3_rtree_query_info*),
  10212. void *pContext,
  10213. void (*xDestructor)(void*)
  10214. );
  10215. /*
  10216. ** A pointer to a structure of the following type is passed as the
  10217. ** argument to scored geometry callback registered using
  10218. ** sqlite3_rtree_query_callback().
  10219. **
  10220. ** Note that the first 5 fields of this structure are identical to
  10221. ** sqlite3_rtree_geometry. This structure is a subclass of
  10222. ** sqlite3_rtree_geometry.
  10223. */
  10224. struct sqlite3_rtree_query_info {
  10225. void *pContext; /* pContext from when function registered */
  10226. int nParam; /* Number of function parameters */
  10227. sqlite3_rtree_dbl *aParam; /* value of function parameters */
  10228. void *pUser; /* callback can use this, if desired */
  10229. void (*xDelUser)(void*); /* function to free pUser */
  10230. sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
  10231. unsigned int *anQueue; /* Number of pending entries in the queue */
  10232. int nCoord; /* Number of coordinates */
  10233. int iLevel; /* Level of current node or entry */
  10234. int mxLevel; /* The largest iLevel value in the tree */
  10235. sqlite3_int64 iRowid; /* Rowid for current entry */
  10236. sqlite3_rtree_dbl rParentScore; /* Score of parent node */
  10237. int eParentWithin; /* Visibility of parent node */
  10238. int eWithin; /* OUT: Visibility */
  10239. sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
  10240. /* The following fields are only available in 3.8.11 and later */
  10241. sqlite3_value **apSqlParam; /* Original SQL values of parameters */
  10242. };
  10243. /*
  10244. ** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
  10245. */
  10246. #define NOT_WITHIN 0 /* Object completely outside of query region */
  10247. #define PARTLY_WITHIN 1 /* Object partially overlaps query region */
  10248. #define FULLY_WITHIN 2 /* Object fully contained within query region */
  10249. #ifdef __cplusplus
  10250. } /* end of the 'extern "C"' block */
  10251. #endif
  10252. #endif /* ifndef _SQLITE3RTREE_H_ */
  10253. /******** End of sqlite3rtree.h *********/
  10254. /******** Begin file sqlite3session.h *********/
  10255. #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
  10256. #define __SQLITESESSION_H_ 1
  10257. /*
  10258. ** Make sure we can call this stuff from C++.
  10259. */
  10260. #ifdef __cplusplus
  10261. extern "C" {
  10262. #endif
  10263. /*
  10264. ** CAPI3REF: Session Object Handle
  10265. **
  10266. ** An instance of this object is a [session] that can be used to
  10267. ** record changes to a database.
  10268. */
  10269. typedef struct sqlite3_session sqlite3_session;
  10270. /*
  10271. ** CAPI3REF: Changeset Iterator Handle
  10272. **
  10273. ** An instance of this object acts as a cursor for iterating
  10274. ** over the elements of a [changeset] or [patchset].
  10275. */
  10276. typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
  10277. /*
  10278. ** CAPI3REF: Create A New Session Object
  10279. ** CONSTRUCTOR: sqlite3_session
  10280. **
  10281. ** Create a new session object attached to database handle db. If successful,
  10282. ** a pointer to the new object is written to *ppSession and SQLITE_OK is
  10283. ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
  10284. ** error code (e.g. SQLITE_NOMEM) is returned.
  10285. **
  10286. ** It is possible to create multiple session objects attached to a single
  10287. ** database handle.
  10288. **
  10289. ** Session objects created using this function should be deleted using the
  10290. ** [sqlite3session_delete()] function before the database handle that they
  10291. ** are attached to is itself closed. If the database handle is closed before
  10292. ** the session object is deleted, then the results of calling any session
  10293. ** module function, including [sqlite3session_delete()] on the session object
  10294. ** are undefined.
  10295. **
  10296. ** Because the session module uses the [sqlite3_preupdate_hook()] API, it
  10297. ** is not possible for an application to register a pre-update hook on a
  10298. ** database handle that has one or more session objects attached. Nor is
  10299. ** it possible to create a session object attached to a database handle for
  10300. ** which a pre-update hook is already defined. The results of attempting
  10301. ** either of these things are undefined.
  10302. **
  10303. ** The session object will be used to create changesets for tables in
  10304. ** database zDb, where zDb is either "main", or "temp", or the name of an
  10305. ** attached database. It is not an error if database zDb is not attached
  10306. ** to the database when the session object is created.
  10307. */
  10308. SQLITE_API int sqlite3session_create(
  10309. sqlite3 *db, /* Database handle */
  10310. const char *zDb, /* Name of db (e.g. "main") */
  10311. sqlite3_session **ppSession /* OUT: New session object */
  10312. );
  10313. /*
  10314. ** CAPI3REF: Delete A Session Object
  10315. ** DESTRUCTOR: sqlite3_session
  10316. **
  10317. ** Delete a session object previously allocated using
  10318. ** [sqlite3session_create()]. Once a session object has been deleted, the
  10319. ** results of attempting to use pSession with any other session module
  10320. ** function are undefined.
  10321. **
  10322. ** Session objects must be deleted before the database handle to which they
  10323. ** are attached is closed. Refer to the documentation for
  10324. ** [sqlite3session_create()] for details.
  10325. */
  10326. SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
  10327. /*
  10328. ** CAPIREF: Conigure a Session Object
  10329. ** METHOD: sqlite3_session
  10330. **
  10331. ** This method is used to configure a session object after it has been
  10332. ** created. At present the only valid value for the second parameter is
  10333. ** [SQLITE_SESSION_OBJCONFIG_SIZE].
  10334. **
  10335. ** Arguments for sqlite3session_object_config()
  10336. **
  10337. ** The following values may passed as the the 4th parameter to
  10338. ** sqlite3session_object_config().
  10339. **
  10340. ** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>
  10341. ** This option is used to set, clear or query the flag that enables
  10342. ** the [sqlite3session_changeset_size()] API. Because it imposes some
  10343. ** computational overhead, this API is disabled by default. Argument
  10344. ** pArg must point to a value of type (int). If the value is initially
  10345. ** 0, then the sqlite3session_changeset_size() API is disabled. If it
  10346. ** is greater than 0, then the same API is enabled. Or, if the initial
  10347. ** value is less than zero, no change is made. In all cases the (int)
  10348. ** variable is set to 1 if the sqlite3session_changeset_size() API is
  10349. ** enabled following the current call, or 0 otherwise.
  10350. **
  10351. ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
  10352. ** the first table has been attached to the session object.
  10353. */
  10354. SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
  10355. /*
  10356. */
  10357. #define SQLITE_SESSION_OBJCONFIG_SIZE 1
  10358. /*
  10359. ** CAPI3REF: Enable Or Disable A Session Object
  10360. ** METHOD: sqlite3_session
  10361. **
  10362. ** Enable or disable the recording of changes by a session object. When
  10363. ** enabled, a session object records changes made to the database. When
  10364. ** disabled - it does not. A newly created session object is enabled.
  10365. ** Refer to the documentation for [sqlite3session_changeset()] for further
  10366. ** details regarding how enabling and disabling a session object affects
  10367. ** the eventual changesets.
  10368. **
  10369. ** Passing zero to this function disables the session. Passing a value
  10370. ** greater than zero enables it. Passing a value less than zero is a
  10371. ** no-op, and may be used to query the current state of the session.
  10372. **
  10373. ** The return value indicates the final state of the session object: 0 if
  10374. ** the session is disabled, or 1 if it is enabled.
  10375. */
  10376. SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
  10377. /*
  10378. ** CAPI3REF: Set Or Clear the Indirect Change Flag
  10379. ** METHOD: sqlite3_session
  10380. **
  10381. ** Each change recorded by a session object is marked as either direct or
  10382. ** indirect. A change is marked as indirect if either:
  10383. **
  10384. ** <ul>
  10385. ** <li> The session object "indirect" flag is set when the change is
  10386. ** made, or
  10387. ** <li> The change is made by an SQL trigger or foreign key action
  10388. ** instead of directly as a result of a users SQL statement.
  10389. ** </ul>
  10390. **
  10391. ** If a single row is affected by more than one operation within a session,
  10392. ** then the change is considered indirect if all operations meet the criteria
  10393. ** for an indirect change above, or direct otherwise.
  10394. **
  10395. ** This function is used to set, clear or query the session object indirect
  10396. ** flag. If the second argument passed to this function is zero, then the
  10397. ** indirect flag is cleared. If it is greater than zero, the indirect flag
  10398. ** is set. Passing a value less than zero does not modify the current value
  10399. ** of the indirect flag, and may be used to query the current state of the
  10400. ** indirect flag for the specified session object.
  10401. **
  10402. ** The return value indicates the final state of the indirect flag: 0 if
  10403. ** it is clear, or 1 if it is set.
  10404. */
  10405. SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
  10406. /*
  10407. ** CAPI3REF: Attach A Table To A Session Object
  10408. ** METHOD: sqlite3_session
  10409. **
  10410. ** If argument zTab is not NULL, then it is the name of a table to attach
  10411. ** to the session object passed as the first argument. All subsequent changes
  10412. ** made to the table while the session object is enabled will be recorded. See
  10413. ** documentation for [sqlite3session_changeset()] for further details.
  10414. **
  10415. ** Or, if argument zTab is NULL, then changes are recorded for all tables
  10416. ** in the database. If additional tables are added to the database (by
  10417. ** executing "CREATE TABLE" statements) after this call is made, changes for
  10418. ** the new tables are also recorded.
  10419. **
  10420. ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
  10421. ** defined as part of their CREATE TABLE statement. It does not matter if the
  10422. ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
  10423. ** KEY may consist of a single column, or may be a composite key.
  10424. **
  10425. ** It is not an error if the named table does not exist in the database. Nor
  10426. ** is it an error if the named table does not have a PRIMARY KEY. However,
  10427. ** no changes will be recorded in either of these scenarios.
  10428. **
  10429. ** Changes are not recorded for individual rows that have NULL values stored
  10430. ** in one or more of their PRIMARY KEY columns.
  10431. **
  10432. ** SQLITE_OK is returned if the call completes without error. Or, if an error
  10433. ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
  10434. **
  10435. ** <h3>Special sqlite_stat1 Handling</h3>
  10436. **
  10437. ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
  10438. ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
  10439. ** <pre>
  10440. ** &nbsp; CREATE TABLE sqlite_stat1(tbl,idx,stat)
  10441. ** </pre>
  10442. **
  10443. ** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
  10444. ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
  10445. ** are recorded for rows for which (idx IS NULL) is true. However, for such
  10446. ** rows a zero-length blob (SQL value X'') is stored in the changeset or
  10447. ** patchset instead of a NULL value. This allows such changesets to be
  10448. ** manipulated by legacy implementations of sqlite3changeset_invert(),
  10449. ** concat() and similar.
  10450. **
  10451. ** The sqlite3changeset_apply() function automatically converts the
  10452. ** zero-length blob back to a NULL value when updating the sqlite_stat1
  10453. ** table. However, if the application calls sqlite3changeset_new(),
  10454. ** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
  10455. ** iterator directly (including on a changeset iterator passed to a
  10456. ** conflict-handler callback) then the X'' value is returned. The application
  10457. ** must translate X'' to NULL itself if required.
  10458. **
  10459. ** Legacy (older than 3.22.0) versions of the sessions module cannot capture
  10460. ** changes made to the sqlite_stat1 table. Legacy versions of the
  10461. ** sqlite3changeset_apply() function silently ignore any modifications to the
  10462. ** sqlite_stat1 table that are part of a changeset or patchset.
  10463. */
  10464. SQLITE_API int sqlite3session_attach(
  10465. sqlite3_session *pSession, /* Session object */
  10466. const char *zTab /* Table name */
  10467. );
  10468. /*
  10469. ** CAPI3REF: Set a table filter on a Session Object.
  10470. ** METHOD: sqlite3_session
  10471. **
  10472. ** The second argument (xFilter) is the "filter callback". For changes to rows
  10473. ** in tables that are not attached to the Session object, the filter is called
  10474. ** to determine whether changes to the table's rows should be tracked or not.
  10475. ** If xFilter returns 0, changes are not tracked. Note that once a table is
  10476. ** attached, xFilter will not be called again.
  10477. */
  10478. SQLITE_API void sqlite3session_table_filter(
  10479. sqlite3_session *pSession, /* Session object */
  10480. int(*xFilter)(
  10481. void *pCtx, /* Copy of third arg to _filter_table() */
  10482. const char *zTab /* Table name */
  10483. ),
  10484. void *pCtx /* First argument passed to xFilter */
  10485. );
  10486. /*
  10487. ** CAPI3REF: Generate A Changeset From A Session Object
  10488. ** METHOD: sqlite3_session
  10489. **
  10490. ** Obtain a changeset containing changes to the tables attached to the
  10491. ** session object passed as the first argument. If successful,
  10492. ** set *ppChangeset to point to a buffer containing the changeset
  10493. ** and *pnChangeset to the size of the changeset in bytes before returning
  10494. ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
  10495. ** zero and return an SQLite error code.
  10496. **
  10497. ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
  10498. ** each representing a change to a single row of an attached table. An INSERT
  10499. ** change contains the values of each field of a new database row. A DELETE
  10500. ** contains the original values of each field of a deleted database row. An
  10501. ** UPDATE change contains the original values of each field of an updated
  10502. ** database row along with the updated values for each updated non-primary-key
  10503. ** column. It is not possible for an UPDATE change to represent a change that
  10504. ** modifies the values of primary key columns. If such a change is made, it
  10505. ** is represented in a changeset as a DELETE followed by an INSERT.
  10506. **
  10507. ** Changes are not recorded for rows that have NULL values stored in one or
  10508. ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
  10509. ** no corresponding change is present in the changesets returned by this
  10510. ** function. If an existing row with one or more NULL values stored in
  10511. ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
  10512. ** only an INSERT is appears in the changeset. Similarly, if an existing row
  10513. ** with non-NULL PRIMARY KEY values is updated so that one or more of its
  10514. ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
  10515. ** DELETE change only.
  10516. **
  10517. ** The contents of a changeset may be traversed using an iterator created
  10518. ** using the [sqlite3changeset_start()] API. A changeset may be applied to
  10519. ** a database with a compatible schema using the [sqlite3changeset_apply()]
  10520. ** API.
  10521. **
  10522. ** Within a changeset generated by this function, all changes related to a
  10523. ** single table are grouped together. In other words, when iterating through
  10524. ** a changeset or when applying a changeset to a database, all changes related
  10525. ** to a single table are processed before moving on to the next table. Tables
  10526. ** are sorted in the same order in which they were attached (or auto-attached)
  10527. ** to the sqlite3_session object. The order in which the changes related to
  10528. ** a single table are stored is undefined.
  10529. **
  10530. ** Following a successful call to this function, it is the responsibility of
  10531. ** the caller to eventually free the buffer that *ppChangeset points to using
  10532. ** [sqlite3_free()].
  10533. **
  10534. ** <h3>Changeset Generation</h3>
  10535. **
  10536. ** Once a table has been attached to a session object, the session object
  10537. ** records the primary key values of all new rows inserted into the table.
  10538. ** It also records the original primary key and other column values of any
  10539. ** deleted or updated rows. For each unique primary key value, data is only
  10540. ** recorded once - the first time a row with said primary key is inserted,
  10541. ** updated or deleted in the lifetime of the session.
  10542. **
  10543. ** There is one exception to the previous paragraph: when a row is inserted,
  10544. ** updated or deleted, if one or more of its primary key columns contain a
  10545. ** NULL value, no record of the change is made.
  10546. **
  10547. ** The session object therefore accumulates two types of records - those
  10548. ** that consist of primary key values only (created when the user inserts
  10549. ** a new record) and those that consist of the primary key values and the
  10550. ** original values of other table columns (created when the users deletes
  10551. ** or updates a record).
  10552. **
  10553. ** When this function is called, the requested changeset is created using
  10554. ** both the accumulated records and the current contents of the database
  10555. ** file. Specifically:
  10556. **
  10557. ** <ul>
  10558. ** <li> For each record generated by an insert, the database is queried
  10559. ** for a row with a matching primary key. If one is found, an INSERT
  10560. ** change is added to the changeset. If no such row is found, no change
  10561. ** is added to the changeset.
  10562. **
  10563. ** <li> For each record generated by an update or delete, the database is
  10564. ** queried for a row with a matching primary key. If such a row is
  10565. ** found and one or more of the non-primary key fields have been
  10566. ** modified from their original values, an UPDATE change is added to
  10567. ** the changeset. Or, if no such row is found in the table, a DELETE
  10568. ** change is added to the changeset. If there is a row with a matching
  10569. ** primary key in the database, but all fields contain their original
  10570. ** values, no change is added to the changeset.
  10571. ** </ul>
  10572. **
  10573. ** This means, amongst other things, that if a row is inserted and then later
  10574. ** deleted while a session object is active, neither the insert nor the delete
  10575. ** will be present in the changeset. Or if a row is deleted and then later a
  10576. ** row with the same primary key values inserted while a session object is
  10577. ** active, the resulting changeset will contain an UPDATE change instead of
  10578. ** a DELETE and an INSERT.
  10579. **
  10580. ** When a session object is disabled (see the [sqlite3session_enable()] API),
  10581. ** it does not accumulate records when rows are inserted, updated or deleted.
  10582. ** This may appear to have some counter-intuitive effects if a single row
  10583. ** is written to more than once during a session. For example, if a row
  10584. ** is inserted while a session object is enabled, then later deleted while
  10585. ** the same session object is disabled, no INSERT record will appear in the
  10586. ** changeset, even though the delete took place while the session was disabled.
  10587. ** Or, if one field of a row is updated while a session is disabled, and
  10588. ** another field of the same row is updated while the session is enabled, the
  10589. ** resulting changeset will contain an UPDATE change that updates both fields.
  10590. */
  10591. SQLITE_API int sqlite3session_changeset(
  10592. sqlite3_session *pSession, /* Session object */
  10593. int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
  10594. void **ppChangeset /* OUT: Buffer containing changeset */
  10595. );
  10596. /*
  10597. ** CAPI3REF: Return An Upper-limit For The Size Of The Changeset
  10598. ** METHOD: sqlite3_session
  10599. **
  10600. ** By default, this function always returns 0. For it to return
  10601. ** a useful result, the sqlite3_session object must have been configured
  10602. ** to enable this API using sqlite3session_object_config() with the
  10603. ** SQLITE_SESSION_OBJCONFIG_SIZE verb.
  10604. **
  10605. ** When enabled, this function returns an upper limit, in bytes, for the size
  10606. ** of the changeset that might be produced if sqlite3session_changeset() were
  10607. ** called. The final changeset size might be equal to or smaller than the
  10608. ** size in bytes returned by this function.
  10609. */
  10610. SQLITE_API sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);
  10611. /*
  10612. ** CAPI3REF: Load The Difference Between Tables Into A Session
  10613. ** METHOD: sqlite3_session
  10614. **
  10615. ** If it is not already attached to the session object passed as the first
  10616. ** argument, this function attaches table zTbl in the same manner as the
  10617. ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
  10618. ** does not have a primary key, this function is a no-op (but does not return
  10619. ** an error).
  10620. **
  10621. ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
  10622. ** attached to the same database handle as the session object that contains
  10623. ** a table compatible with the table attached to the session by this function.
  10624. ** A table is considered compatible if it:
  10625. **
  10626. ** <ul>
  10627. ** <li> Has the same name,
  10628. ** <li> Has the same set of columns declared in the same order, and
  10629. ** <li> Has the same PRIMARY KEY definition.
  10630. ** </ul>
  10631. **
  10632. ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
  10633. ** are compatible but do not have any PRIMARY KEY columns, it is not an error
  10634. ** but no changes are added to the session object. As with other session
  10635. ** APIs, tables without PRIMARY KEYs are simply ignored.
  10636. **
  10637. ** This function adds a set of changes to the session object that could be
  10638. ** used to update the table in database zFrom (call this the "from-table")
  10639. ** so that its content is the same as the table attached to the session
  10640. ** object (call this the "to-table"). Specifically:
  10641. **
  10642. ** <ul>
  10643. ** <li> For each row (primary key) that exists in the to-table but not in
  10644. ** the from-table, an INSERT record is added to the session object.
  10645. **
  10646. ** <li> For each row (primary key) that exists in the to-table but not in
  10647. ** the from-table, a DELETE record is added to the session object.
  10648. **
  10649. ** <li> For each row (primary key) that exists in both tables, but features
  10650. ** different non-PK values in each, an UPDATE record is added to the
  10651. ** session.
  10652. ** </ul>
  10653. **
  10654. ** To clarify, if this function is called and then a changeset constructed
  10655. ** using [sqlite3session_changeset()], then after applying that changeset to
  10656. ** database zFrom the contents of the two compatible tables would be
  10657. ** identical.
  10658. **
  10659. ** It an error if database zFrom does not exist or does not contain the
  10660. ** required compatible table.
  10661. **
  10662. ** If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite
  10663. ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
  10664. ** may be set to point to a buffer containing an English language error
  10665. ** message. It is the responsibility of the caller to free this buffer using
  10666. ** sqlite3_free().
  10667. */
  10668. SQLITE_API int sqlite3session_diff(
  10669. sqlite3_session *pSession,
  10670. const char *zFromDb,
  10671. const char *zTbl,
  10672. char **pzErrMsg
  10673. );
  10674. /*
  10675. ** CAPI3REF: Generate A Patchset From A Session Object
  10676. ** METHOD: sqlite3_session
  10677. **
  10678. ** The differences between a patchset and a changeset are that:
  10679. **
  10680. ** <ul>
  10681. ** <li> DELETE records consist of the primary key fields only. The
  10682. ** original values of other fields are omitted.
  10683. ** <li> The original values of any modified fields are omitted from
  10684. ** UPDATE records.
  10685. ** </ul>
  10686. **
  10687. ** A patchset blob may be used with up to date versions of all
  10688. ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
  10689. ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
  10690. ** attempting to use a patchset blob with old versions of the
  10691. ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
  10692. **
  10693. ** Because the non-primary key "old.*" fields are omitted, no
  10694. ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
  10695. ** is passed to the sqlite3changeset_apply() API. Other conflict types work
  10696. ** in the same way as for changesets.
  10697. **
  10698. ** Changes within a patchset are ordered in the same way as for changesets
  10699. ** generated by the sqlite3session_changeset() function (i.e. all changes for
  10700. ** a single table are grouped together, tables appear in the order in which
  10701. ** they were attached to the session object).
  10702. */
  10703. SQLITE_API int sqlite3session_patchset(
  10704. sqlite3_session *pSession, /* Session object */
  10705. int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
  10706. void **ppPatchset /* OUT: Buffer containing patchset */
  10707. );
  10708. /*
  10709. ** CAPI3REF: Test if a changeset has recorded any changes.
  10710. **
  10711. ** Return non-zero if no changes to attached tables have been recorded by
  10712. ** the session object passed as the first argument. Otherwise, if one or
  10713. ** more changes have been recorded, return zero.
  10714. **
  10715. ** Even if this function returns zero, it is possible that calling
  10716. ** [sqlite3session_changeset()] on the session handle may still return a
  10717. ** changeset that contains no changes. This can happen when a row in
  10718. ** an attached table is modified and then later on the original values
  10719. ** are restored. However, if this function returns non-zero, then it is
  10720. ** guaranteed that a call to sqlite3session_changeset() will return a
  10721. ** changeset containing zero changes.
  10722. */
  10723. SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
  10724. /*
  10725. ** CAPI3REF: Query for the amount of heap memory used by a session object.
  10726. **
  10727. ** This API returns the total amount of heap memory in bytes currently
  10728. ** used by the session object passed as the only argument.
  10729. */
  10730. SQLITE_API sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);
  10731. /*
  10732. ** CAPI3REF: Create An Iterator To Traverse A Changeset
  10733. ** CONSTRUCTOR: sqlite3_changeset_iter
  10734. **
  10735. ** Create an iterator used to iterate through the contents of a changeset.
  10736. ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
  10737. ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
  10738. ** SQLite error code is returned.
  10739. **
  10740. ** The following functions can be used to advance and query a changeset
  10741. ** iterator created by this function:
  10742. **
  10743. ** <ul>
  10744. ** <li> [sqlite3changeset_next()]
  10745. ** <li> [sqlite3changeset_op()]
  10746. ** <li> [sqlite3changeset_new()]
  10747. ** <li> [sqlite3changeset_old()]
  10748. ** </ul>
  10749. **
  10750. ** It is the responsibility of the caller to eventually destroy the iterator
  10751. ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
  10752. ** changeset (pChangeset) must remain valid until after the iterator is
  10753. ** destroyed.
  10754. **
  10755. ** Assuming the changeset blob was created by one of the
  10756. ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
  10757. ** [sqlite3changeset_invert()] functions, all changes within the changeset
  10758. ** that apply to a single table are grouped together. This means that when
  10759. ** an application iterates through a changeset using an iterator created by
  10760. ** this function, all changes that relate to a single table are visited
  10761. ** consecutively. There is no chance that the iterator will visit a change
  10762. ** the applies to table X, then one for table Y, and then later on visit
  10763. ** another change for table X.
  10764. **
  10765. ** The behavior of sqlite3changeset_start_v2() and its streaming equivalent
  10766. ** may be modified by passing a combination of
  10767. ** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter.
  10768. **
  10769. ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
  10770. ** and therefore subject to change.
  10771. */
  10772. SQLITE_API int sqlite3changeset_start(
  10773. sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
  10774. int nChangeset, /* Size of changeset blob in bytes */
  10775. void *pChangeset /* Pointer to blob containing changeset */
  10776. );
  10777. SQLITE_API int sqlite3changeset_start_v2(
  10778. sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
  10779. int nChangeset, /* Size of changeset blob in bytes */
  10780. void *pChangeset, /* Pointer to blob containing changeset */
  10781. int flags /* SESSION_CHANGESETSTART_* flags */
  10782. );
  10783. /*
  10784. ** CAPI3REF: Flags for sqlite3changeset_start_v2
  10785. **
  10786. ** The following flags may passed via the 4th parameter to
  10787. ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:
  10788. **
  10789. ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
  10790. ** Invert the changeset while iterating through it. This is equivalent to
  10791. ** inverting a changeset using sqlite3changeset_invert() before applying it.
  10792. ** It is an error to specify this flag with a patchset.
  10793. */
  10794. #define SQLITE_CHANGESETSTART_INVERT 0x0002
  10795. /*
  10796. ** CAPI3REF: Advance A Changeset Iterator
  10797. ** METHOD: sqlite3_changeset_iter
  10798. **
  10799. ** This function may only be used with iterators created by the function
  10800. ** [sqlite3changeset_start()]. If it is called on an iterator passed to
  10801. ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
  10802. ** is returned and the call has no effect.
  10803. **
  10804. ** Immediately after an iterator is created by sqlite3changeset_start(), it
  10805. ** does not point to any change in the changeset. Assuming the changeset
  10806. ** is not empty, the first call to this function advances the iterator to
  10807. ** point to the first change in the changeset. Each subsequent call advances
  10808. ** the iterator to point to the next change in the changeset (if any). If
  10809. ** no error occurs and the iterator points to a valid change after a call
  10810. ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
  10811. ** Otherwise, if all changes in the changeset have already been visited,
  10812. ** SQLITE_DONE is returned.
  10813. **
  10814. ** If an error occurs, an SQLite error code is returned. Possible error
  10815. ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
  10816. ** SQLITE_NOMEM.
  10817. */
  10818. SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
  10819. /*
  10820. ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
  10821. ** METHOD: sqlite3_changeset_iter
  10822. **
  10823. ** The pIter argument passed to this function may either be an iterator
  10824. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  10825. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  10826. ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
  10827. ** is not the case, this function returns [SQLITE_MISUSE].
  10828. **
  10829. ** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three
  10830. ** outputs are set through these pointers:
  10831. **
  10832. ** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
  10833. ** depending on the type of change that the iterator currently points to;
  10834. **
  10835. ** *pnCol is set to the number of columns in the table affected by the change; and
  10836. **
  10837. ** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
  10838. ** the name of the table affected by the current change. The buffer remains
  10839. ** valid until either sqlite3changeset_next() is called on the iterator
  10840. ** or until the conflict-handler function returns.
  10841. **
  10842. ** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
  10843. ** is an indirect change, or false (0) otherwise. See the documentation for
  10844. ** [sqlite3session_indirect()] for a description of direct and indirect
  10845. ** changes.
  10846. **
  10847. ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
  10848. ** SQLite error code is returned. The values of the output variables may not
  10849. ** be trusted in this case.
  10850. */
  10851. SQLITE_API int sqlite3changeset_op(
  10852. sqlite3_changeset_iter *pIter, /* Iterator object */
  10853. const char **pzTab, /* OUT: Pointer to table name */
  10854. int *pnCol, /* OUT: Number of columns in table */
  10855. int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
  10856. int *pbIndirect /* OUT: True for an 'indirect' change */
  10857. );
  10858. /*
  10859. ** CAPI3REF: Obtain The Primary Key Definition Of A Table
  10860. ** METHOD: sqlite3_changeset_iter
  10861. **
  10862. ** For each modified table, a changeset includes the following:
  10863. **
  10864. ** <ul>
  10865. ** <li> The number of columns in the table, and
  10866. ** <li> Which of those columns make up the tables PRIMARY KEY.
  10867. ** </ul>
  10868. **
  10869. ** This function is used to find which columns comprise the PRIMARY KEY of
  10870. ** the table modified by the change that iterator pIter currently points to.
  10871. ** If successful, *pabPK is set to point to an array of nCol entries, where
  10872. ** nCol is the number of columns in the table. Elements of *pabPK are set to
  10873. ** 0x01 if the corresponding column is part of the tables primary key, or
  10874. ** 0x00 if it is not.
  10875. **
  10876. ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
  10877. ** in the table.
  10878. **
  10879. ** If this function is called when the iterator does not point to a valid
  10880. ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
  10881. ** SQLITE_OK is returned and the output variables populated as described
  10882. ** above.
  10883. */
  10884. SQLITE_API int sqlite3changeset_pk(
  10885. sqlite3_changeset_iter *pIter, /* Iterator object */
  10886. unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
  10887. int *pnCol /* OUT: Number of entries in output array */
  10888. );
  10889. /*
  10890. ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
  10891. ** METHOD: sqlite3_changeset_iter
  10892. **
  10893. ** The pIter argument passed to this function may either be an iterator
  10894. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  10895. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  10896. ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
  10897. ** Furthermore, it may only be called if the type of change that the iterator
  10898. ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
  10899. ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
  10900. **
  10901. ** Argument iVal must be greater than or equal to 0, and less than the number
  10902. ** of columns in the table affected by the current change. Otherwise,
  10903. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  10904. **
  10905. ** If successful, this function sets *ppValue to point to a protected
  10906. ** sqlite3_value object containing the iVal'th value from the vector of
  10907. ** original row values stored as part of the UPDATE or DELETE change and
  10908. ** returns SQLITE_OK. The name of the function comes from the fact that this
  10909. ** is similar to the "old.*" columns available to update or delete triggers.
  10910. **
  10911. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  10912. ** is returned and *ppValue is set to NULL.
  10913. */
  10914. SQLITE_API int sqlite3changeset_old(
  10915. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  10916. int iVal, /* Column number */
  10917. sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
  10918. );
  10919. /*
  10920. ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
  10921. ** METHOD: sqlite3_changeset_iter
  10922. **
  10923. ** The pIter argument passed to this function may either be an iterator
  10924. ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
  10925. ** created by [sqlite3changeset_start()]. In the latter case, the most recent
  10926. ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
  10927. ** Furthermore, it may only be called if the type of change that the iterator
  10928. ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
  10929. ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
  10930. **
  10931. ** Argument iVal must be greater than or equal to 0, and less than the number
  10932. ** of columns in the table affected by the current change. Otherwise,
  10933. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  10934. **
  10935. ** If successful, this function sets *ppValue to point to a protected
  10936. ** sqlite3_value object containing the iVal'th value from the vector of
  10937. ** new row values stored as part of the UPDATE or INSERT change and
  10938. ** returns SQLITE_OK. If the change is an UPDATE and does not include
  10939. ** a new value for the requested column, *ppValue is set to NULL and
  10940. ** SQLITE_OK returned. The name of the function comes from the fact that
  10941. ** this is similar to the "new.*" columns available to update or delete
  10942. ** triggers.
  10943. **
  10944. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  10945. ** is returned and *ppValue is set to NULL.
  10946. */
  10947. SQLITE_API int sqlite3changeset_new(
  10948. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  10949. int iVal, /* Column number */
  10950. sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
  10951. );
  10952. /*
  10953. ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
  10954. ** METHOD: sqlite3_changeset_iter
  10955. **
  10956. ** This function should only be used with iterator objects passed to a
  10957. ** conflict-handler callback by [sqlite3changeset_apply()] with either
  10958. ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
  10959. ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
  10960. ** is set to NULL.
  10961. **
  10962. ** Argument iVal must be greater than or equal to 0, and less than the number
  10963. ** of columns in the table affected by the current change. Otherwise,
  10964. ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
  10965. **
  10966. ** If successful, this function sets *ppValue to point to a protected
  10967. ** sqlite3_value object containing the iVal'th value from the
  10968. ** "conflicting row" associated with the current conflict-handler callback
  10969. ** and returns SQLITE_OK.
  10970. **
  10971. ** If some other error occurs (e.g. an OOM condition), an SQLite error code
  10972. ** is returned and *ppValue is set to NULL.
  10973. */
  10974. SQLITE_API int sqlite3changeset_conflict(
  10975. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  10976. int iVal, /* Column number */
  10977. sqlite3_value **ppValue /* OUT: Value from conflicting row */
  10978. );
  10979. /*
  10980. ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
  10981. ** METHOD: sqlite3_changeset_iter
  10982. **
  10983. ** This function may only be called with an iterator passed to an
  10984. ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
  10985. ** it sets the output variable to the total number of known foreign key
  10986. ** violations in the destination database and returns SQLITE_OK.
  10987. **
  10988. ** In all other cases this function returns SQLITE_MISUSE.
  10989. */
  10990. SQLITE_API int sqlite3changeset_fk_conflicts(
  10991. sqlite3_changeset_iter *pIter, /* Changeset iterator */
  10992. int *pnOut /* OUT: Number of FK violations */
  10993. );
  10994. /*
  10995. ** CAPI3REF: Finalize A Changeset Iterator
  10996. ** METHOD: sqlite3_changeset_iter
  10997. **
  10998. ** This function is used to finalize an iterator allocated with
  10999. ** [sqlite3changeset_start()].
  11000. **
  11001. ** This function should only be called on iterators created using the
  11002. ** [sqlite3changeset_start()] function. If an application calls this
  11003. ** function with an iterator passed to a conflict-handler by
  11004. ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
  11005. ** call has no effect.
  11006. **
  11007. ** If an error was encountered within a call to an sqlite3changeset_xxx()
  11008. ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
  11009. ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
  11010. ** to that error is returned by this function. Otherwise, SQLITE_OK is
  11011. ** returned. This is to allow the following pattern (pseudo-code):
  11012. **
  11013. ** <pre>
  11014. ** sqlite3changeset_start();
  11015. ** while( SQLITE_ROW==sqlite3changeset_next() ){
  11016. ** // Do something with change.
  11017. ** }
  11018. ** rc = sqlite3changeset_finalize();
  11019. ** if( rc!=SQLITE_OK ){
  11020. ** // An error has occurred
  11021. ** }
  11022. ** </pre>
  11023. */
  11024. SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
  11025. /*
  11026. ** CAPI3REF: Invert A Changeset
  11027. **
  11028. ** This function is used to "invert" a changeset object. Applying an inverted
  11029. ** changeset to a database reverses the effects of applying the uninverted
  11030. ** changeset. Specifically:
  11031. **
  11032. ** <ul>
  11033. ** <li> Each DELETE change is changed to an INSERT, and
  11034. ** <li> Each INSERT change is changed to a DELETE, and
  11035. ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
  11036. ** </ul>
  11037. **
  11038. ** This function does not change the order in which changes appear within
  11039. ** the changeset. It merely reverses the sense of each individual change.
  11040. **
  11041. ** If successful, a pointer to a buffer containing the inverted changeset
  11042. ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
  11043. ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
  11044. ** zeroed and an SQLite error code returned.
  11045. **
  11046. ** It is the responsibility of the caller to eventually call sqlite3_free()
  11047. ** on the *ppOut pointer to free the buffer allocation following a successful
  11048. ** call to this function.
  11049. **
  11050. ** WARNING/TODO: This function currently assumes that the input is a valid
  11051. ** changeset. If it is not, the results are undefined.
  11052. */
  11053. SQLITE_API int sqlite3changeset_invert(
  11054. int nIn, const void *pIn, /* Input changeset */
  11055. int *pnOut, void **ppOut /* OUT: Inverse of input */
  11056. );
  11057. /*
  11058. ** CAPI3REF: Concatenate Two Changeset Objects
  11059. **
  11060. ** This function is used to concatenate two changesets, A and B, into a
  11061. ** single changeset. The result is a changeset equivalent to applying
  11062. ** changeset A followed by changeset B.
  11063. **
  11064. ** This function combines the two input changesets using an
  11065. ** sqlite3_changegroup object. Calling it produces similar results as the
  11066. ** following code fragment:
  11067. **
  11068. ** <pre>
  11069. ** sqlite3_changegroup *pGrp;
  11070. ** rc = sqlite3_changegroup_new(&pGrp);
  11071. ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
  11072. ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
  11073. ** if( rc==SQLITE_OK ){
  11074. ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
  11075. ** }else{
  11076. ** *ppOut = 0;
  11077. ** *pnOut = 0;
  11078. ** }
  11079. ** </pre>
  11080. **
  11081. ** Refer to the sqlite3_changegroup documentation below for details.
  11082. */
  11083. SQLITE_API int sqlite3changeset_concat(
  11084. int nA, /* Number of bytes in buffer pA */
  11085. void *pA, /* Pointer to buffer containing changeset A */
  11086. int nB, /* Number of bytes in buffer pB */
  11087. void *pB, /* Pointer to buffer containing changeset B */
  11088. int *pnOut, /* OUT: Number of bytes in output changeset */
  11089. void **ppOut /* OUT: Buffer containing output changeset */
  11090. );
  11091. /*
  11092. ** CAPI3REF: Changegroup Handle
  11093. **
  11094. ** A changegroup is an object used to combine two or more
  11095. ** [changesets] or [patchsets]
  11096. */
  11097. typedef struct sqlite3_changegroup sqlite3_changegroup;
  11098. /*
  11099. ** CAPI3REF: Create A New Changegroup Object
  11100. ** CONSTRUCTOR: sqlite3_changegroup
  11101. **
  11102. ** An sqlite3_changegroup object is used to combine two or more changesets
  11103. ** (or patchsets) into a single changeset (or patchset). A single changegroup
  11104. ** object may combine changesets or patchsets, but not both. The output is
  11105. ** always in the same format as the input.
  11106. **
  11107. ** If successful, this function returns SQLITE_OK and populates (*pp) with
  11108. ** a pointer to a new sqlite3_changegroup object before returning. The caller
  11109. ** should eventually free the returned object using a call to
  11110. ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
  11111. ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
  11112. **
  11113. ** The usual usage pattern for an sqlite3_changegroup object is as follows:
  11114. **
  11115. ** <ul>
  11116. ** <li> It is created using a call to sqlite3changegroup_new().
  11117. **
  11118. ** <li> Zero or more changesets (or patchsets) are added to the object
  11119. ** by calling sqlite3changegroup_add().
  11120. **
  11121. ** <li> The result of combining all input changesets together is obtained
  11122. ** by the application via a call to sqlite3changegroup_output().
  11123. **
  11124. ** <li> The object is deleted using a call to sqlite3changegroup_delete().
  11125. ** </ul>
  11126. **
  11127. ** Any number of calls to add() and output() may be made between the calls to
  11128. ** new() and delete(), and in any order.
  11129. **
  11130. ** As well as the regular sqlite3changegroup_add() and
  11131. ** sqlite3changegroup_output() functions, also available are the streaming
  11132. ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
  11133. */
  11134. SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
  11135. /*
  11136. ** CAPI3REF: Add A Changeset To A Changegroup
  11137. ** METHOD: sqlite3_changegroup
  11138. **
  11139. ** Add all changes within the changeset (or patchset) in buffer pData (size
  11140. ** nData bytes) to the changegroup.
  11141. **
  11142. ** If the buffer contains a patchset, then all prior calls to this function
  11143. ** on the same changegroup object must also have specified patchsets. Or, if
  11144. ** the buffer contains a changeset, so must have the earlier calls to this
  11145. ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
  11146. ** to the changegroup.
  11147. **
  11148. ** Rows within the changeset and changegroup are identified by the values in
  11149. ** their PRIMARY KEY columns. A change in the changeset is considered to
  11150. ** apply to the same row as a change already present in the changegroup if
  11151. ** the two rows have the same primary key.
  11152. **
  11153. ** Changes to rows that do not already appear in the changegroup are
  11154. ** simply copied into it. Or, if both the new changeset and the changegroup
  11155. ** contain changes that apply to a single row, the final contents of the
  11156. ** changegroup depends on the type of each change, as follows:
  11157. **
  11158. ** <table border=1 style="margin-left:8ex;margin-right:8ex">
  11159. ** <tr><th style="white-space:pre">Existing Change </th>
  11160. ** <th style="white-space:pre">New Change </th>
  11161. ** <th>Output Change
  11162. ** <tr><td>INSERT <td>INSERT <td>
  11163. ** The new change is ignored. This case does not occur if the new
  11164. ** changeset was recorded immediately after the changesets already
  11165. ** added to the changegroup.
  11166. ** <tr><td>INSERT <td>UPDATE <td>
  11167. ** The INSERT change remains in the changegroup. The values in the
  11168. ** INSERT change are modified as if the row was inserted by the
  11169. ** existing change and then updated according to the new change.
  11170. ** <tr><td>INSERT <td>DELETE <td>
  11171. ** The existing INSERT is removed from the changegroup. The DELETE is
  11172. ** not added.
  11173. ** <tr><td>UPDATE <td>INSERT <td>
  11174. ** The new change is ignored. This case does not occur if the new
  11175. ** changeset was recorded immediately after the changesets already
  11176. ** added to the changegroup.
  11177. ** <tr><td>UPDATE <td>UPDATE <td>
  11178. ** The existing UPDATE remains within the changegroup. It is amended
  11179. ** so that the accompanying values are as if the row was updated once
  11180. ** by the existing change and then again by the new change.
  11181. ** <tr><td>UPDATE <td>DELETE <td>
  11182. ** The existing UPDATE is replaced by the new DELETE within the
  11183. ** changegroup.
  11184. ** <tr><td>DELETE <td>INSERT <td>
  11185. ** If one or more of the column values in the row inserted by the
  11186. ** new change differ from those in the row deleted by the existing
  11187. ** change, the existing DELETE is replaced by an UPDATE within the
  11188. ** changegroup. Otherwise, if the inserted row is exactly the same
  11189. ** as the deleted row, the existing DELETE is simply discarded.
  11190. ** <tr><td>DELETE <td>UPDATE <td>
  11191. ** The new change is ignored. This case does not occur if the new
  11192. ** changeset was recorded immediately after the changesets already
  11193. ** added to the changegroup.
  11194. ** <tr><td>DELETE <td>DELETE <td>
  11195. ** The new change is ignored. This case does not occur if the new
  11196. ** changeset was recorded immediately after the changesets already
  11197. ** added to the changegroup.
  11198. ** </table>
  11199. **
  11200. ** If the new changeset contains changes to a table that is already present
  11201. ** in the changegroup, then the number of columns and the position of the
  11202. ** primary key columns for the table must be consistent. If this is not the
  11203. ** case, this function fails with SQLITE_SCHEMA. If the input changeset
  11204. ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
  11205. ** returned. Or, if an out-of-memory condition occurs during processing, this
  11206. ** function returns SQLITE_NOMEM. In all cases, if an error occurs the state
  11207. ** of the final contents of the changegroup is undefined.
  11208. **
  11209. ** If no error occurs, SQLITE_OK is returned.
  11210. */
  11211. SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
  11212. /*
  11213. ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
  11214. ** METHOD: sqlite3_changegroup
  11215. **
  11216. ** Obtain a buffer containing a changeset (or patchset) representing the
  11217. ** current contents of the changegroup. If the inputs to the changegroup
  11218. ** were themselves changesets, the output is a changeset. Or, if the
  11219. ** inputs were patchsets, the output is also a patchset.
  11220. **
  11221. ** As with the output of the sqlite3session_changeset() and
  11222. ** sqlite3session_patchset() functions, all changes related to a single
  11223. ** table are grouped together in the output of this function. Tables appear
  11224. ** in the same order as for the very first changeset added to the changegroup.
  11225. ** If the second or subsequent changesets added to the changegroup contain
  11226. ** changes for tables that do not appear in the first changeset, they are
  11227. ** appended onto the end of the output changeset, again in the order in
  11228. ** which they are first encountered.
  11229. **
  11230. ** If an error occurs, an SQLite error code is returned and the output
  11231. ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
  11232. ** is returned and the output variables are set to the size of and a
  11233. ** pointer to the output buffer, respectively. In this case it is the
  11234. ** responsibility of the caller to eventually free the buffer using a
  11235. ** call to sqlite3_free().
  11236. */
  11237. SQLITE_API int sqlite3changegroup_output(
  11238. sqlite3_changegroup*,
  11239. int *pnData, /* OUT: Size of output buffer in bytes */
  11240. void **ppData /* OUT: Pointer to output buffer */
  11241. );
  11242. /*
  11243. ** CAPI3REF: Delete A Changegroup Object
  11244. ** DESTRUCTOR: sqlite3_changegroup
  11245. */
  11246. SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
  11247. /*
  11248. ** CAPI3REF: Apply A Changeset To A Database
  11249. **
  11250. ** Apply a changeset or patchset to a database. These functions attempt to
  11251. ** update the "main" database attached to handle db with the changes found in
  11252. ** the changeset passed via the second and third arguments.
  11253. **
  11254. ** The fourth argument (xFilter) passed to these functions is the "filter
  11255. ** callback". If it is not NULL, then for each table affected by at least one
  11256. ** change in the changeset, the filter callback is invoked with
  11257. ** the table name as the second argument, and a copy of the context pointer
  11258. ** passed as the sixth argument as the first. If the "filter callback"
  11259. ** returns zero, then no attempt is made to apply any changes to the table.
  11260. ** Otherwise, if the return value is non-zero or the xFilter argument to
  11261. ** is NULL, all changes related to the table are attempted.
  11262. **
  11263. ** For each table that is not excluded by the filter callback, this function
  11264. ** tests that the target database contains a compatible table. A table is
  11265. ** considered compatible if all of the following are true:
  11266. **
  11267. ** <ul>
  11268. ** <li> The table has the same name as the name recorded in the
  11269. ** changeset, and
  11270. ** <li> The table has at least as many columns as recorded in the
  11271. ** changeset, and
  11272. ** <li> The table has primary key columns in the same position as
  11273. ** recorded in the changeset.
  11274. ** </ul>
  11275. **
  11276. ** If there is no compatible table, it is not an error, but none of the
  11277. ** changes associated with the table are applied. A warning message is issued
  11278. ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
  11279. ** one such warning is issued for each table in the changeset.
  11280. **
  11281. ** For each change for which there is a compatible table, an attempt is made
  11282. ** to modify the table contents according to the UPDATE, INSERT or DELETE
  11283. ** change. If a change cannot be applied cleanly, the conflict handler
  11284. ** function passed as the fifth argument to sqlite3changeset_apply() may be
  11285. ** invoked. A description of exactly when the conflict handler is invoked for
  11286. ** each type of change is below.
  11287. **
  11288. ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
  11289. ** of passing anything other than a valid function pointer as the xConflict
  11290. ** argument are undefined.
  11291. **
  11292. ** Each time the conflict handler function is invoked, it must return one
  11293. ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
  11294. ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
  11295. ** if the second argument passed to the conflict handler is either
  11296. ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
  11297. ** returns an illegal value, any changes already made are rolled back and
  11298. ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
  11299. ** actions are taken by sqlite3changeset_apply() depending on the value
  11300. ** returned by each invocation of the conflict-handler function. Refer to
  11301. ** the documentation for the three
  11302. ** [SQLITE_CHANGESET_OMIT|available return values] for details.
  11303. **
  11304. ** <dl>
  11305. ** <dt>DELETE Changes<dd>
  11306. ** For each DELETE change, the function checks if the target database
  11307. ** contains a row with the same primary key value (or values) as the
  11308. ** original row values stored in the changeset. If it does, and the values
  11309. ** stored in all non-primary key columns also match the values stored in
  11310. ** the changeset the row is deleted from the target database.
  11311. **
  11312. ** If a row with matching primary key values is found, but one or more of
  11313. ** the non-primary key fields contains a value different from the original
  11314. ** row value stored in the changeset, the conflict-handler function is
  11315. ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
  11316. ** database table has more columns than are recorded in the changeset,
  11317. ** only the values of those non-primary key fields are compared against
  11318. ** the current database contents - any trailing database table columns
  11319. ** are ignored.
  11320. **
  11321. ** If no row with matching primary key values is found in the database,
  11322. ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  11323. ** passed as the second argument.
  11324. **
  11325. ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
  11326. ** (which can only happen if a foreign key constraint is violated), the
  11327. ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
  11328. ** passed as the second argument. This includes the case where the DELETE
  11329. ** operation is attempted because an earlier call to the conflict handler
  11330. ** function returned [SQLITE_CHANGESET_REPLACE].
  11331. **
  11332. ** <dt>INSERT Changes<dd>
  11333. ** For each INSERT change, an attempt is made to insert the new row into
  11334. ** the database. If the changeset row contains fewer fields than the
  11335. ** database table, the trailing fields are populated with their default
  11336. ** values.
  11337. **
  11338. ** If the attempt to insert the row fails because the database already
  11339. ** contains a row with the same primary key values, the conflict handler
  11340. ** function is invoked with the second argument set to
  11341. ** [SQLITE_CHANGESET_CONFLICT].
  11342. **
  11343. ** If the attempt to insert the row fails because of some other constraint
  11344. ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
  11345. ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
  11346. ** This includes the case where the INSERT operation is re-attempted because
  11347. ** an earlier call to the conflict handler function returned
  11348. ** [SQLITE_CHANGESET_REPLACE].
  11349. **
  11350. ** <dt>UPDATE Changes<dd>
  11351. ** For each UPDATE change, the function checks if the target database
  11352. ** contains a row with the same primary key value (or values) as the
  11353. ** original row values stored in the changeset. If it does, and the values
  11354. ** stored in all modified non-primary key columns also match the values
  11355. ** stored in the changeset the row is updated within the target database.
  11356. **
  11357. ** If a row with matching primary key values is found, but one or more of
  11358. ** the modified non-primary key fields contains a value different from an
  11359. ** original row value stored in the changeset, the conflict-handler function
  11360. ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
  11361. ** UPDATE changes only contain values for non-primary key fields that are
  11362. ** to be modified, only those fields need to match the original values to
  11363. ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
  11364. **
  11365. ** If no row with matching primary key values is found in the database,
  11366. ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
  11367. ** passed as the second argument.
  11368. **
  11369. ** If the UPDATE operation is attempted, but SQLite returns
  11370. ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
  11371. ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
  11372. ** This includes the case where the UPDATE operation is attempted after
  11373. ** an earlier call to the conflict handler function returned
  11374. ** [SQLITE_CHANGESET_REPLACE].
  11375. ** </dl>
  11376. **
  11377. ** It is safe to execute SQL statements, including those that write to the
  11378. ** table that the callback related to, from within the xConflict callback.
  11379. ** This can be used to further customize the application's conflict
  11380. ** resolution strategy.
  11381. **
  11382. ** All changes made by these functions are enclosed in a savepoint transaction.
  11383. ** If any other error (aside from a constraint failure when attempting to
  11384. ** write to the target database) occurs, then the savepoint transaction is
  11385. ** rolled back, restoring the target database to its original state, and an
  11386. ** SQLite error code returned.
  11387. **
  11388. ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
  11389. ** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
  11390. ** may set (*ppRebase) to point to a "rebase" that may be used with the
  11391. ** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
  11392. ** is set to the size of the buffer in bytes. It is the responsibility of the
  11393. ** caller to eventually free any such buffer using sqlite3_free(). The buffer
  11394. ** is only allocated and populated if one or more conflicts were encountered
  11395. ** while applying the patchset. See comments surrounding the sqlite3_rebaser
  11396. ** APIs for further details.
  11397. **
  11398. ** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
  11399. ** may be modified by passing a combination of
  11400. ** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.
  11401. **
  11402. ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
  11403. ** and therefore subject to change.
  11404. */
  11405. SQLITE_API int sqlite3changeset_apply(
  11406. sqlite3 *db, /* Apply change to "main" db of this handle */
  11407. int nChangeset, /* Size of changeset in bytes */
  11408. void *pChangeset, /* Changeset blob */
  11409. int(*xFilter)(
  11410. void *pCtx, /* Copy of sixth arg to _apply() */
  11411. const char *zTab /* Table name */
  11412. ),
  11413. int(*xConflict)(
  11414. void *pCtx, /* Copy of sixth arg to _apply() */
  11415. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  11416. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  11417. ),
  11418. void *pCtx /* First argument passed to xConflict */
  11419. );
  11420. SQLITE_API int sqlite3changeset_apply_v2(
  11421. sqlite3 *db, /* Apply change to "main" db of this handle */
  11422. int nChangeset, /* Size of changeset in bytes */
  11423. void *pChangeset, /* Changeset blob */
  11424. int(*xFilter)(
  11425. void *pCtx, /* Copy of sixth arg to _apply() */
  11426. const char *zTab /* Table name */
  11427. ),
  11428. int(*xConflict)(
  11429. void *pCtx, /* Copy of sixth arg to _apply() */
  11430. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  11431. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  11432. ),
  11433. void *pCtx, /* First argument passed to xConflict */
  11434. void **ppRebase, int *pnRebase, /* OUT: Rebase data */
  11435. int flags /* SESSION_CHANGESETAPPLY_* flags */
  11436. );
  11437. /*
  11438. ** CAPI3REF: Flags for sqlite3changeset_apply_v2
  11439. **
  11440. ** The following flags may passed via the 9th parameter to
  11441. ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
  11442. **
  11443. ** <dl>
  11444. ** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
  11445. ** Usually, the sessions module encloses all operations performed by
  11446. ** a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The
  11447. ** SAVEPOINT is committed if the changeset or patchset is successfully
  11448. ** applied, or rolled back if an error occurs. Specifying this flag
  11449. ** causes the sessions module to omit this savepoint. In this case, if the
  11450. ** caller has an open transaction or savepoint when apply_v2() is called,
  11451. ** it may revert the partially applied changeset by rolling it back.
  11452. **
  11453. ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
  11454. ** Invert the changeset before applying it. This is equivalent to inverting
  11455. ** a changeset using sqlite3changeset_invert() before applying it. It is
  11456. ** an error to specify this flag with a patchset.
  11457. */
  11458. #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
  11459. #define SQLITE_CHANGESETAPPLY_INVERT 0x0002
  11460. /*
  11461. ** CAPI3REF: Constants Passed To The Conflict Handler
  11462. **
  11463. ** Values that may be passed as the second argument to a conflict-handler.
  11464. **
  11465. ** <dl>
  11466. ** <dt>SQLITE_CHANGESET_DATA<dd>
  11467. ** The conflict handler is invoked with CHANGESET_DATA as the second argument
  11468. ** when processing a DELETE or UPDATE change if a row with the required
  11469. ** PRIMARY KEY fields is present in the database, but one or more other
  11470. ** (non primary-key) fields modified by the update do not contain the
  11471. ** expected "before" values.
  11472. **
  11473. ** The conflicting row, in this case, is the database row with the matching
  11474. ** primary key.
  11475. **
  11476. ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
  11477. ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
  11478. ** argument when processing a DELETE or UPDATE change if a row with the
  11479. ** required PRIMARY KEY fields is not present in the database.
  11480. **
  11481. ** There is no conflicting row in this case. The results of invoking the
  11482. ** sqlite3changeset_conflict() API are undefined.
  11483. **
  11484. ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
  11485. ** CHANGESET_CONFLICT is passed as the second argument to the conflict
  11486. ** handler while processing an INSERT change if the operation would result
  11487. ** in duplicate primary key values.
  11488. **
  11489. ** The conflicting row in this case is the database row with the matching
  11490. ** primary key.
  11491. **
  11492. ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
  11493. ** If foreign key handling is enabled, and applying a changeset leaves the
  11494. ** database in a state containing foreign key violations, the conflict
  11495. ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
  11496. ** exactly once before the changeset is committed. If the conflict handler
  11497. ** returns CHANGESET_OMIT, the changes, including those that caused the
  11498. ** foreign key constraint violation, are committed. Or, if it returns
  11499. ** CHANGESET_ABORT, the changeset is rolled back.
  11500. **
  11501. ** No current or conflicting row information is provided. The only function
  11502. ** it is possible to call on the supplied sqlite3_changeset_iter handle
  11503. ** is sqlite3changeset_fk_conflicts().
  11504. **
  11505. ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
  11506. ** If any other constraint violation occurs while applying a change (i.e.
  11507. ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
  11508. ** invoked with CHANGESET_CONSTRAINT as the second argument.
  11509. **
  11510. ** There is no conflicting row in this case. The results of invoking the
  11511. ** sqlite3changeset_conflict() API are undefined.
  11512. **
  11513. ** </dl>
  11514. */
  11515. #define SQLITE_CHANGESET_DATA 1
  11516. #define SQLITE_CHANGESET_NOTFOUND 2
  11517. #define SQLITE_CHANGESET_CONFLICT 3
  11518. #define SQLITE_CHANGESET_CONSTRAINT 4
  11519. #define SQLITE_CHANGESET_FOREIGN_KEY 5
  11520. /*
  11521. ** CAPI3REF: Constants Returned By The Conflict Handler
  11522. **
  11523. ** A conflict handler callback must return one of the following three values.
  11524. **
  11525. ** <dl>
  11526. ** <dt>SQLITE_CHANGESET_OMIT<dd>
  11527. ** If a conflict handler returns this value no special action is taken. The
  11528. ** change that caused the conflict is not applied. The session module
  11529. ** continues to the next change in the changeset.
  11530. **
  11531. ** <dt>SQLITE_CHANGESET_REPLACE<dd>
  11532. ** This value may only be returned if the second argument to the conflict
  11533. ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
  11534. ** is not the case, any changes applied so far are rolled back and the
  11535. ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
  11536. **
  11537. ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
  11538. ** handler, then the conflicting row is either updated or deleted, depending
  11539. ** on the type of change.
  11540. **
  11541. ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
  11542. ** handler, then the conflicting row is removed from the database and a
  11543. ** second attempt to apply the change is made. If this second attempt fails,
  11544. ** the original row is restored to the database before continuing.
  11545. **
  11546. ** <dt>SQLITE_CHANGESET_ABORT<dd>
  11547. ** If this value is returned, any changes applied so far are rolled back
  11548. ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
  11549. ** </dl>
  11550. */
  11551. #define SQLITE_CHANGESET_OMIT 0
  11552. #define SQLITE_CHANGESET_REPLACE 1
  11553. #define SQLITE_CHANGESET_ABORT 2
  11554. /*
  11555. ** CAPI3REF: Rebasing changesets
  11556. ** EXPERIMENTAL
  11557. **
  11558. ** Suppose there is a site hosting a database in state S0. And that
  11559. ** modifications are made that move that database to state S1 and a
  11560. ** changeset recorded (the "local" changeset). Then, a changeset based
  11561. ** on S0 is received from another site (the "remote" changeset) and
  11562. ** applied to the database. The database is then in state
  11563. ** (S1+"remote"), where the exact state depends on any conflict
  11564. ** resolution decisions (OMIT or REPLACE) made while applying "remote".
  11565. ** Rebasing a changeset is to update it to take those conflict
  11566. ** resolution decisions into account, so that the same conflicts
  11567. ** do not have to be resolved elsewhere in the network.
  11568. **
  11569. ** For example, if both the local and remote changesets contain an
  11570. ** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
  11571. **
  11572. ** local: INSERT INTO t1 VALUES(1, 'v1');
  11573. ** remote: INSERT INTO t1 VALUES(1, 'v2');
  11574. **
  11575. ** and the conflict resolution is REPLACE, then the INSERT change is
  11576. ** removed from the local changeset (it was overridden). Or, if the
  11577. ** conflict resolution was "OMIT", then the local changeset is modified
  11578. ** to instead contain:
  11579. **
  11580. ** UPDATE t1 SET b = 'v2' WHERE a=1;
  11581. **
  11582. ** Changes within the local changeset are rebased as follows:
  11583. **
  11584. ** <dl>
  11585. ** <dt>Local INSERT<dd>
  11586. ** This may only conflict with a remote INSERT. If the conflict
  11587. ** resolution was OMIT, then add an UPDATE change to the rebased
  11588. ** changeset. Or, if the conflict resolution was REPLACE, add
  11589. ** nothing to the rebased changeset.
  11590. **
  11591. ** <dt>Local DELETE<dd>
  11592. ** This may conflict with a remote UPDATE or DELETE. In both cases the
  11593. ** only possible resolution is OMIT. If the remote operation was a
  11594. ** DELETE, then add no change to the rebased changeset. If the remote
  11595. ** operation was an UPDATE, then the old.* fields of change are updated
  11596. ** to reflect the new.* values in the UPDATE.
  11597. **
  11598. ** <dt>Local UPDATE<dd>
  11599. ** This may conflict with a remote UPDATE or DELETE. If it conflicts
  11600. ** with a DELETE, and the conflict resolution was OMIT, then the update
  11601. ** is changed into an INSERT. Any undefined values in the new.* record
  11602. ** from the update change are filled in using the old.* values from
  11603. ** the conflicting DELETE. Or, if the conflict resolution was REPLACE,
  11604. ** the UPDATE change is simply omitted from the rebased changeset.
  11605. **
  11606. ** If conflict is with a remote UPDATE and the resolution is OMIT, then
  11607. ** the old.* values are rebased using the new.* values in the remote
  11608. ** change. Or, if the resolution is REPLACE, then the change is copied
  11609. ** into the rebased changeset with updates to columns also updated by
  11610. ** the conflicting remote UPDATE removed. If this means no columns would
  11611. ** be updated, the change is omitted.
  11612. ** </dl>
  11613. **
  11614. ** A local change may be rebased against multiple remote changes
  11615. ** simultaneously. If a single key is modified by multiple remote
  11616. ** changesets, they are combined as follows before the local changeset
  11617. ** is rebased:
  11618. **
  11619. ** <ul>
  11620. ** <li> If there has been one or more REPLACE resolutions on a
  11621. ** key, it is rebased according to a REPLACE.
  11622. **
  11623. ** <li> If there have been no REPLACE resolutions on a key, then
  11624. ** the local changeset is rebased according to the most recent
  11625. ** of the OMIT resolutions.
  11626. ** </ul>
  11627. **
  11628. ** Note that conflict resolutions from multiple remote changesets are
  11629. ** combined on a per-field basis, not per-row. This means that in the
  11630. ** case of multiple remote UPDATE operations, some fields of a single
  11631. ** local change may be rebased for REPLACE while others are rebased for
  11632. ** OMIT.
  11633. **
  11634. ** In order to rebase a local changeset, the remote changeset must first
  11635. ** be applied to the local database using sqlite3changeset_apply_v2() and
  11636. ** the buffer of rebase information captured. Then:
  11637. **
  11638. ** <ol>
  11639. ** <li> An sqlite3_rebaser object is created by calling
  11640. ** sqlite3rebaser_create().
  11641. ** <li> The new object is configured with the rebase buffer obtained from
  11642. ** sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
  11643. ** If the local changeset is to be rebased against multiple remote
  11644. ** changesets, then sqlite3rebaser_configure() should be called
  11645. ** multiple times, in the same order that the multiple
  11646. ** sqlite3changeset_apply_v2() calls were made.
  11647. ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
  11648. ** <li> The sqlite3_rebaser object is deleted by calling
  11649. ** sqlite3rebaser_delete().
  11650. ** </ol>
  11651. */
  11652. typedef struct sqlite3_rebaser sqlite3_rebaser;
  11653. /*
  11654. ** CAPI3REF: Create a changeset rebaser object.
  11655. ** EXPERIMENTAL
  11656. **
  11657. ** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
  11658. ** point to the new object and return SQLITE_OK. Otherwise, if an error
  11659. ** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
  11660. ** to NULL.
  11661. */
  11662. SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
  11663. /*
  11664. ** CAPI3REF: Configure a changeset rebaser object.
  11665. ** EXPERIMENTAL
  11666. **
  11667. ** Configure the changeset rebaser object to rebase changesets according
  11668. ** to the conflict resolutions described by buffer pRebase (size nRebase
  11669. ** bytes), which must have been obtained from a previous call to
  11670. ** sqlite3changeset_apply_v2().
  11671. */
  11672. SQLITE_API int sqlite3rebaser_configure(
  11673. sqlite3_rebaser*,
  11674. int nRebase, const void *pRebase
  11675. );
  11676. /*
  11677. ** CAPI3REF: Rebase a changeset
  11678. ** EXPERIMENTAL
  11679. **
  11680. ** Argument pIn must point to a buffer containing a changeset nIn bytes
  11681. ** in size. This function allocates and populates a buffer with a copy
  11682. ** of the changeset rebased according to the configuration of the
  11683. ** rebaser object passed as the first argument. If successful, (*ppOut)
  11684. ** is set to point to the new buffer containing the rebased changeset and
  11685. ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
  11686. ** responsibility of the caller to eventually free the new buffer using
  11687. ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
  11688. ** are set to zero and an SQLite error code returned.
  11689. */
  11690. SQLITE_API int sqlite3rebaser_rebase(
  11691. sqlite3_rebaser*,
  11692. int nIn, const void *pIn,
  11693. int *pnOut, void **ppOut
  11694. );
  11695. /*
  11696. ** CAPI3REF: Delete a changeset rebaser object.
  11697. ** EXPERIMENTAL
  11698. **
  11699. ** Delete the changeset rebaser object and all associated resources. There
  11700. ** should be one call to this function for each successful invocation
  11701. ** of sqlite3rebaser_create().
  11702. */
  11703. SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p);
  11704. /*
  11705. ** CAPI3REF: Streaming Versions of API functions.
  11706. **
  11707. ** The six streaming API xxx_strm() functions serve similar purposes to the
  11708. ** corresponding non-streaming API functions:
  11709. **
  11710. ** <table border=1 style="margin-left:8ex;margin-right:8ex">
  11711. ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
  11712. ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
  11713. ** <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2]
  11714. ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
  11715. ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
  11716. ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
  11717. ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
  11718. ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
  11719. ** </table>
  11720. **
  11721. ** Non-streaming functions that accept changesets (or patchsets) as input
  11722. ** require that the entire changeset be stored in a single buffer in memory.
  11723. ** Similarly, those that return a changeset or patchset do so by returning
  11724. ** a pointer to a single large buffer allocated using sqlite3_malloc().
  11725. ** Normally this is convenient. However, if an application running in a
  11726. ** low-memory environment is required to handle very large changesets, the
  11727. ** large contiguous memory allocations required can become onerous.
  11728. **
  11729. ** In order to avoid this problem, instead of a single large buffer, input
  11730. ** is passed to a streaming API functions by way of a callback function that
  11731. ** the sessions module invokes to incrementally request input data as it is
  11732. ** required. In all cases, a pair of API function parameters such as
  11733. **
  11734. ** <pre>
  11735. ** &nbsp; int nChangeset,
  11736. ** &nbsp; void *pChangeset,
  11737. ** </pre>
  11738. **
  11739. ** Is replaced by:
  11740. **
  11741. ** <pre>
  11742. ** &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
  11743. ** &nbsp; void *pIn,
  11744. ** </pre>
  11745. **
  11746. ** Each time the xInput callback is invoked by the sessions module, the first
  11747. ** argument passed is a copy of the supplied pIn context pointer. The second
  11748. ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
  11749. ** error occurs the xInput method should copy up to (*pnData) bytes of data
  11750. ** into the buffer and set (*pnData) to the actual number of bytes copied
  11751. ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
  11752. ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
  11753. ** error code should be returned. In all cases, if an xInput callback returns
  11754. ** an error, all processing is abandoned and the streaming API function
  11755. ** returns a copy of the error code to the caller.
  11756. **
  11757. ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
  11758. ** invoked by the sessions module at any point during the lifetime of the
  11759. ** iterator. If such an xInput callback returns an error, the iterator enters
  11760. ** an error state, whereby all subsequent calls to iterator functions
  11761. ** immediately fail with the same error code as returned by xInput.
  11762. **
  11763. ** Similarly, streaming API functions that return changesets (or patchsets)
  11764. ** return them in chunks by way of a callback function instead of via a
  11765. ** pointer to a single large buffer. In this case, a pair of parameters such
  11766. ** as:
  11767. **
  11768. ** <pre>
  11769. ** &nbsp; int *pnChangeset,
  11770. ** &nbsp; void **ppChangeset,
  11771. ** </pre>
  11772. **
  11773. ** Is replaced by:
  11774. **
  11775. ** <pre>
  11776. ** &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
  11777. ** &nbsp; void *pOut
  11778. ** </pre>
  11779. **
  11780. ** The xOutput callback is invoked zero or more times to return data to
  11781. ** the application. The first parameter passed to each call is a copy of the
  11782. ** pOut pointer supplied by the application. The second parameter, pData,
  11783. ** points to a buffer nData bytes in size containing the chunk of output
  11784. ** data being returned. If the xOutput callback successfully processes the
  11785. ** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
  11786. ** it should return some other SQLite error code. In this case processing
  11787. ** is immediately abandoned and the streaming API function returns a copy
  11788. ** of the xOutput error code to the application.
  11789. **
  11790. ** The sessions module never invokes an xOutput callback with the third
  11791. ** parameter set to a value less than or equal to zero. Other than this,
  11792. ** no guarantees are made as to the size of the chunks of data returned.
  11793. */
  11794. SQLITE_API int sqlite3changeset_apply_strm(
  11795. sqlite3 *db, /* Apply change to "main" db of this handle */
  11796. int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  11797. void *pIn, /* First arg for xInput */
  11798. int(*xFilter)(
  11799. void *pCtx, /* Copy of sixth arg to _apply() */
  11800. const char *zTab /* Table name */
  11801. ),
  11802. int(*xConflict)(
  11803. void *pCtx, /* Copy of sixth arg to _apply() */
  11804. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  11805. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  11806. ),
  11807. void *pCtx /* First argument passed to xConflict */
  11808. );
  11809. SQLITE_API int sqlite3changeset_apply_v2_strm(
  11810. sqlite3 *db, /* Apply change to "main" db of this handle */
  11811. int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  11812. void *pIn, /* First arg for xInput */
  11813. int(*xFilter)(
  11814. void *pCtx, /* Copy of sixth arg to _apply() */
  11815. const char *zTab /* Table name */
  11816. ),
  11817. int(*xConflict)(
  11818. void *pCtx, /* Copy of sixth arg to _apply() */
  11819. int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
  11820. sqlite3_changeset_iter *p /* Handle describing change and conflict */
  11821. ),
  11822. void *pCtx, /* First argument passed to xConflict */
  11823. void **ppRebase, int *pnRebase,
  11824. int flags
  11825. );
  11826. SQLITE_API int sqlite3changeset_concat_strm(
  11827. int (*xInputA)(void *pIn, void *pData, int *pnData),
  11828. void *pInA,
  11829. int (*xInputB)(void *pIn, void *pData, int *pnData),
  11830. void *pInB,
  11831. int (*xOutput)(void *pOut, const void *pData, int nData),
  11832. void *pOut
  11833. );
  11834. SQLITE_API int sqlite3changeset_invert_strm(
  11835. int (*xInput)(void *pIn, void *pData, int *pnData),
  11836. void *pIn,
  11837. int (*xOutput)(void *pOut, const void *pData, int nData),
  11838. void *pOut
  11839. );
  11840. SQLITE_API int sqlite3changeset_start_strm(
  11841. sqlite3_changeset_iter **pp,
  11842. int (*xInput)(void *pIn, void *pData, int *pnData),
  11843. void *pIn
  11844. );
  11845. SQLITE_API int sqlite3changeset_start_v2_strm(
  11846. sqlite3_changeset_iter **pp,
  11847. int (*xInput)(void *pIn, void *pData, int *pnData),
  11848. void *pIn,
  11849. int flags
  11850. );
  11851. SQLITE_API int sqlite3session_changeset_strm(
  11852. sqlite3_session *pSession,
  11853. int (*xOutput)(void *pOut, const void *pData, int nData),
  11854. void *pOut
  11855. );
  11856. SQLITE_API int sqlite3session_patchset_strm(
  11857. sqlite3_session *pSession,
  11858. int (*xOutput)(void *pOut, const void *pData, int nData),
  11859. void *pOut
  11860. );
  11861. SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
  11862. int (*xInput)(void *pIn, void *pData, int *pnData),
  11863. void *pIn
  11864. );
  11865. SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
  11866. int (*xOutput)(void *pOut, const void *pData, int nData),
  11867. void *pOut
  11868. );
  11869. SQLITE_API int sqlite3rebaser_rebase_strm(
  11870. sqlite3_rebaser *pRebaser,
  11871. int (*xInput)(void *pIn, void *pData, int *pnData),
  11872. void *pIn,
  11873. int (*xOutput)(void *pOut, const void *pData, int nData),
  11874. void *pOut
  11875. );
  11876. /*
  11877. ** CAPI3REF: Configure global parameters
  11878. **
  11879. ** The sqlite3session_config() interface is used to make global configuration
  11880. ** changes to the sessions module in order to tune it to the specific needs
  11881. ** of the application.
  11882. **
  11883. ** The sqlite3session_config() interface is not threadsafe. If it is invoked
  11884. ** while any other thread is inside any other sessions method then the
  11885. ** results are undefined. Furthermore, if it is invoked after any sessions
  11886. ** related objects have been created, the results are also undefined.
  11887. **
  11888. ** The first argument to the sqlite3session_config() function must be one
  11889. ** of the SQLITE_SESSION_CONFIG_XXX constants defined below. The
  11890. ** interpretation of the (void*) value passed as the second parameter and
  11891. ** the effect of calling this function depends on the value of the first
  11892. ** parameter.
  11893. **
  11894. ** <dl>
  11895. ** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>
  11896. ** By default, the sessions module streaming interfaces attempt to input
  11897. ** and output data in approximately 1 KiB chunks. This operand may be used
  11898. ** to set and query the value of this configuration setting. The pointer
  11899. ** passed as the second argument must point to a value of type (int).
  11900. ** If this value is greater than 0, it is used as the new streaming data
  11901. ** chunk size for both input and output. Before returning, the (int) value
  11902. ** pointed to by pArg is set to the final value of the streaming interface
  11903. ** chunk size.
  11904. ** </dl>
  11905. **
  11906. ** This function returns SQLITE_OK if successful, or an SQLite error code
  11907. ** otherwise.
  11908. */
  11909. SQLITE_API int sqlite3session_config(int op, void *pArg);
  11910. /*
  11911. ** CAPI3REF: Values for sqlite3session_config().
  11912. */
  11913. #define SQLITE_SESSION_CONFIG_STRMSIZE 1
  11914. /*
  11915. ** Make sure we can call this stuff from C++.
  11916. */
  11917. #ifdef __cplusplus
  11918. }
  11919. #endif
  11920. #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */
  11921. /******** End of sqlite3session.h *********/
  11922. /******** Begin file fts5.h *********/
  11923. /*
  11924. ** 2014 May 31
  11925. **
  11926. ** The author disclaims copyright to this source code. In place of
  11927. ** a legal notice, here is a blessing:
  11928. **
  11929. ** May you do good and not evil.
  11930. ** May you find forgiveness for yourself and forgive others.
  11931. ** May you share freely, never taking more than you give.
  11932. **
  11933. ******************************************************************************
  11934. **
  11935. ** Interfaces to extend FTS5. Using the interfaces defined in this file,
  11936. ** FTS5 may be extended with:
  11937. **
  11938. ** * custom tokenizers, and
  11939. ** * custom auxiliary functions.
  11940. */
  11941. #ifndef _FTS5_H
  11942. #define _FTS5_H
  11943. #ifdef __cplusplus
  11944. extern "C" {
  11945. #endif
  11946. /*************************************************************************
  11947. ** CUSTOM AUXILIARY FUNCTIONS
  11948. **
  11949. ** Virtual table implementations may overload SQL functions by implementing
  11950. ** the sqlite3_module.xFindFunction() method.
  11951. */
  11952. typedef struct Fts5ExtensionApi Fts5ExtensionApi;
  11953. typedef struct Fts5Context Fts5Context;
  11954. typedef struct Fts5PhraseIter Fts5PhraseIter;
  11955. typedef void (*fts5_extension_function)(
  11956. const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
  11957. Fts5Context *pFts, /* First arg to pass to pApi functions */
  11958. sqlite3_context *pCtx, /* Context for returning result/error */
  11959. int nVal, /* Number of values in apVal[] array */
  11960. sqlite3_value **apVal /* Array of trailing arguments */
  11961. );
  11962. struct Fts5PhraseIter {
  11963. const unsigned char *a;
  11964. const unsigned char *b;
  11965. };
  11966. /*
  11967. ** EXTENSION API FUNCTIONS
  11968. **
  11969. ** xUserData(pFts):
  11970. ** Return a copy of the context pointer the extension function was
  11971. ** registered with.
  11972. **
  11973. ** xColumnTotalSize(pFts, iCol, pnToken):
  11974. ** If parameter iCol is less than zero, set output variable *pnToken
  11975. ** to the total number of tokens in the FTS5 table. Or, if iCol is
  11976. ** non-negative but less than the number of columns in the table, return
  11977. ** the total number of tokens in column iCol, considering all rows in
  11978. ** the FTS5 table.
  11979. **
  11980. ** If parameter iCol is greater than or equal to the number of columns
  11981. ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
  11982. ** an OOM condition or IO error), an appropriate SQLite error code is
  11983. ** returned.
  11984. **
  11985. ** xColumnCount(pFts):
  11986. ** Return the number of columns in the table.
  11987. **
  11988. ** xColumnSize(pFts, iCol, pnToken):
  11989. ** If parameter iCol is less than zero, set output variable *pnToken
  11990. ** to the total number of tokens in the current row. Or, if iCol is
  11991. ** non-negative but less than the number of columns in the table, set
  11992. ** *pnToken to the number of tokens in column iCol of the current row.
  11993. **
  11994. ** If parameter iCol is greater than or equal to the number of columns
  11995. ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
  11996. ** an OOM condition or IO error), an appropriate SQLite error code is
  11997. ** returned.
  11998. **
  11999. ** This function may be quite inefficient if used with an FTS5 table
  12000. ** created with the "columnsize=0" option.
  12001. **
  12002. ** xColumnText:
  12003. ** This function attempts to retrieve the text of column iCol of the
  12004. ** current document. If successful, (*pz) is set to point to a buffer
  12005. ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
  12006. ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
  12007. ** if an error occurs, an SQLite error code is returned and the final values
  12008. ** of (*pz) and (*pn) are undefined.
  12009. **
  12010. ** xPhraseCount:
  12011. ** Returns the number of phrases in the current query expression.
  12012. **
  12013. ** xPhraseSize:
  12014. ** Returns the number of tokens in phrase iPhrase of the query. Phrases
  12015. ** are numbered starting from zero.
  12016. **
  12017. ** xInstCount:
  12018. ** Set *pnInst to the total number of occurrences of all phrases within
  12019. ** the query within the current row. Return SQLITE_OK if successful, or
  12020. ** an error code (i.e. SQLITE_NOMEM) if an error occurs.
  12021. **
  12022. ** This API can be quite slow if used with an FTS5 table created with the
  12023. ** "detail=none" or "detail=column" option. If the FTS5 table is created
  12024. ** with either "detail=none" or "detail=column" and "content=" option
  12025. ** (i.e. if it is a contentless table), then this API always returns 0.
  12026. **
  12027. ** xInst:
  12028. ** Query for the details of phrase match iIdx within the current row.
  12029. ** Phrase matches are numbered starting from zero, so the iIdx argument
  12030. ** should be greater than or equal to zero and smaller than the value
  12031. ** output by xInstCount().
  12032. **
  12033. ** Usually, output parameter *piPhrase is set to the phrase number, *piCol
  12034. ** to the column in which it occurs and *piOff the token offset of the
  12035. ** first token of the phrase. Returns SQLITE_OK if successful, or an error
  12036. ** code (i.e. SQLITE_NOMEM) if an error occurs.
  12037. **
  12038. ** This API can be quite slow if used with an FTS5 table created with the
  12039. ** "detail=none" or "detail=column" option.
  12040. **
  12041. ** xRowid:
  12042. ** Returns the rowid of the current row.
  12043. **
  12044. ** xTokenize:
  12045. ** Tokenize text using the tokenizer belonging to the FTS5 table.
  12046. **
  12047. ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):
  12048. ** This API function is used to query the FTS table for phrase iPhrase
  12049. ** of the current query. Specifically, a query equivalent to:
  12050. **
  12051. ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid
  12052. **
  12053. ** with $p set to a phrase equivalent to the phrase iPhrase of the
  12054. ** current query is executed. Any column filter that applies to
  12055. ** phrase iPhrase of the current query is included in $p. For each
  12056. ** row visited, the callback function passed as the fourth argument
  12057. ** is invoked. The context and API objects passed to the callback
  12058. ** function may be used to access the properties of each matched row.
  12059. ** Invoking Api.xUserData() returns a copy of the pointer passed as
  12060. ** the third argument to pUserData.
  12061. **
  12062. ** If the callback function returns any value other than SQLITE_OK, the
  12063. ** query is abandoned and the xQueryPhrase function returns immediately.
  12064. ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
  12065. ** Otherwise, the error code is propagated upwards.
  12066. **
  12067. ** If the query runs to completion without incident, SQLITE_OK is returned.
  12068. ** Or, if some error occurs before the query completes or is aborted by
  12069. ** the callback, an SQLite error code is returned.
  12070. **
  12071. **
  12072. ** xSetAuxdata(pFts5, pAux, xDelete)
  12073. **
  12074. ** Save the pointer passed as the second argument as the extension function's
  12075. ** "auxiliary data". The pointer may then be retrieved by the current or any
  12076. ** future invocation of the same fts5 extension function made as part of
  12077. ** the same MATCH query using the xGetAuxdata() API.
  12078. **
  12079. ** Each extension function is allocated a single auxiliary data slot for
  12080. ** each FTS query (MATCH expression). If the extension function is invoked
  12081. ** more than once for a single FTS query, then all invocations share a
  12082. ** single auxiliary data context.
  12083. **
  12084. ** If there is already an auxiliary data pointer when this function is
  12085. ** invoked, then it is replaced by the new pointer. If an xDelete callback
  12086. ** was specified along with the original pointer, it is invoked at this
  12087. ** point.
  12088. **
  12089. ** The xDelete callback, if one is specified, is also invoked on the
  12090. ** auxiliary data pointer after the FTS5 query has finished.
  12091. **
  12092. ** If an error (e.g. an OOM condition) occurs within this function,
  12093. ** the auxiliary data is set to NULL and an error code returned. If the
  12094. ** xDelete parameter was not NULL, it is invoked on the auxiliary data
  12095. ** pointer before returning.
  12096. **
  12097. **
  12098. ** xGetAuxdata(pFts5, bClear)
  12099. **
  12100. ** Returns the current auxiliary data pointer for the fts5 extension
  12101. ** function. See the xSetAuxdata() method for details.
  12102. **
  12103. ** If the bClear argument is non-zero, then the auxiliary data is cleared
  12104. ** (set to NULL) before this function returns. In this case the xDelete,
  12105. ** if any, is not invoked.
  12106. **
  12107. **
  12108. ** xRowCount(pFts5, pnRow)
  12109. **
  12110. ** This function is used to retrieve the total number of rows in the table.
  12111. ** In other words, the same value that would be returned by:
  12112. **
  12113. ** SELECT count(*) FROM ftstable;
  12114. **
  12115. ** xPhraseFirst()
  12116. ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
  12117. ** method, to iterate through all instances of a single query phrase within
  12118. ** the current row. This is the same information as is accessible via the
  12119. ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient
  12120. ** to use, this API may be faster under some circumstances. To iterate
  12121. ** through instances of phrase iPhrase, use the following code:
  12122. **
  12123. ** Fts5PhraseIter iter;
  12124. ** int iCol, iOff;
  12125. ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
  12126. ** iCol>=0;
  12127. ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
  12128. ** ){
  12129. ** // An instance of phrase iPhrase at offset iOff of column iCol
  12130. ** }
  12131. **
  12132. ** The Fts5PhraseIter structure is defined above. Applications should not
  12133. ** modify this structure directly - it should only be used as shown above
  12134. ** with the xPhraseFirst() and xPhraseNext() API methods (and by
  12135. ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
  12136. **
  12137. ** This API can be quite slow if used with an FTS5 table created with the
  12138. ** "detail=none" or "detail=column" option. If the FTS5 table is created
  12139. ** with either "detail=none" or "detail=column" and "content=" option
  12140. ** (i.e. if it is a contentless table), then this API always iterates
  12141. ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
  12142. **
  12143. ** xPhraseNext()
  12144. ** See xPhraseFirst above.
  12145. **
  12146. ** xPhraseFirstColumn()
  12147. ** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
  12148. ** and xPhraseNext() APIs described above. The difference is that instead
  12149. ** of iterating through all instances of a phrase in the current row, these
  12150. ** APIs are used to iterate through the set of columns in the current row
  12151. ** that contain one or more instances of a specified phrase. For example:
  12152. **
  12153. ** Fts5PhraseIter iter;
  12154. ** int iCol;
  12155. ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
  12156. ** iCol>=0;
  12157. ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
  12158. ** ){
  12159. ** // Column iCol contains at least one instance of phrase iPhrase
  12160. ** }
  12161. **
  12162. ** This API can be quite slow if used with an FTS5 table created with the
  12163. ** "detail=none" option. If the FTS5 table is created with either
  12164. ** "detail=none" "content=" option (i.e. if it is a contentless table),
  12165. ** then this API always iterates through an empty set (all calls to
  12166. ** xPhraseFirstColumn() set iCol to -1).
  12167. **
  12168. ** The information accessed using this API and its companion
  12169. ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
  12170. ** (or xInst/xInstCount). The chief advantage of this API is that it is
  12171. ** significantly more efficient than those alternatives when used with
  12172. ** "detail=column" tables.
  12173. **
  12174. ** xPhraseNextColumn()
  12175. ** See xPhraseFirstColumn above.
  12176. */
  12177. struct Fts5ExtensionApi {
  12178. int iVersion; /* Currently always set to 3 */
  12179. void *(*xUserData)(Fts5Context*);
  12180. int (*xColumnCount)(Fts5Context*);
  12181. int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
  12182. int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
  12183. int (*xTokenize)(Fts5Context*,
  12184. const char *pText, int nText, /* Text to tokenize */
  12185. void *pCtx, /* Context passed to xToken() */
  12186. int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
  12187. );
  12188. int (*xPhraseCount)(Fts5Context*);
  12189. int (*xPhraseSize)(Fts5Context*, int iPhrase);
  12190. int (*xInstCount)(Fts5Context*, int *pnInst);
  12191. int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
  12192. sqlite3_int64 (*xRowid)(Fts5Context*);
  12193. int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
  12194. int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
  12195. int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
  12196. int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
  12197. );
  12198. int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
  12199. void *(*xGetAuxdata)(Fts5Context*, int bClear);
  12200. int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
  12201. void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
  12202. int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
  12203. void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
  12204. };
  12205. /*
  12206. ** CUSTOM AUXILIARY FUNCTIONS
  12207. *************************************************************************/
  12208. /*************************************************************************
  12209. ** CUSTOM TOKENIZERS
  12210. **
  12211. ** Applications may also register custom tokenizer types. A tokenizer
  12212. ** is registered by providing fts5 with a populated instance of the
  12213. ** following structure. All structure methods must be defined, setting
  12214. ** any member of the fts5_tokenizer struct to NULL leads to undefined
  12215. ** behaviour. The structure methods are expected to function as follows:
  12216. **
  12217. ** xCreate:
  12218. ** This function is used to allocate and initialize a tokenizer instance.
  12219. ** A tokenizer instance is required to actually tokenize text.
  12220. **
  12221. ** The first argument passed to this function is a copy of the (void*)
  12222. ** pointer provided by the application when the fts5_tokenizer object
  12223. ** was registered with FTS5 (the third argument to xCreateTokenizer()).
  12224. ** The second and third arguments are an array of nul-terminated strings
  12225. ** containing the tokenizer arguments, if any, specified following the
  12226. ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used
  12227. ** to create the FTS5 table.
  12228. **
  12229. ** The final argument is an output variable. If successful, (*ppOut)
  12230. ** should be set to point to the new tokenizer handle and SQLITE_OK
  12231. ** returned. If an error occurs, some value other than SQLITE_OK should
  12232. ** be returned. In this case, fts5 assumes that the final value of *ppOut
  12233. ** is undefined.
  12234. **
  12235. ** xDelete:
  12236. ** This function is invoked to delete a tokenizer handle previously
  12237. ** allocated using xCreate(). Fts5 guarantees that this function will
  12238. ** be invoked exactly once for each successful call to xCreate().
  12239. **
  12240. ** xTokenize:
  12241. ** This function is expected to tokenize the nText byte string indicated
  12242. ** by argument pText. pText may or may not be nul-terminated. The first
  12243. ** argument passed to this function is a pointer to an Fts5Tokenizer object
  12244. ** returned by an earlier call to xCreate().
  12245. **
  12246. ** The second argument indicates the reason that FTS5 is requesting
  12247. ** tokenization of the supplied text. This is always one of the following
  12248. ** four values:
  12249. **
  12250. ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
  12251. ** or removed from the FTS table. The tokenizer is being invoked to
  12252. ** determine the set of tokens to add to (or delete from) the
  12253. ** FTS index.
  12254. **
  12255. ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
  12256. ** against the FTS index. The tokenizer is being called to tokenize
  12257. ** a bareword or quoted string specified as part of the query.
  12258. **
  12259. ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
  12260. ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
  12261. ** followed by a "*" character, indicating that the last token
  12262. ** returned by the tokenizer will be treated as a token prefix.
  12263. **
  12264. ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
  12265. ** satisfy an fts5_api.xTokenize() request made by an auxiliary
  12266. ** function. Or an fts5_api.xColumnSize() request made by the same
  12267. ** on a columnsize=0 database.
  12268. ** </ul>
  12269. **
  12270. ** For each token in the input string, the supplied callback xToken() must
  12271. ** be invoked. The first argument to it should be a copy of the pointer
  12272. ** passed as the second argument to xTokenize(). The third and fourth
  12273. ** arguments are a pointer to a buffer containing the token text, and the
  12274. ** size of the token in bytes. The 4th and 5th arguments are the byte offsets
  12275. ** of the first byte of and first byte immediately following the text from
  12276. ** which the token is derived within the input.
  12277. **
  12278. ** The second argument passed to the xToken() callback ("tflags") should
  12279. ** normally be set to 0. The exception is if the tokenizer supports
  12280. ** synonyms. In this case see the discussion below for details.
  12281. **
  12282. ** FTS5 assumes the xToken() callback is invoked for each token in the
  12283. ** order that they occur within the input text.
  12284. **
  12285. ** If an xToken() callback returns any value other than SQLITE_OK, then
  12286. ** the tokenization should be abandoned and the xTokenize() method should
  12287. ** immediately return a copy of the xToken() return value. Or, if the
  12288. ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
  12289. ** if an error occurs with the xTokenize() implementation itself, it
  12290. ** may abandon the tokenization and return any error code other than
  12291. ** SQLITE_OK or SQLITE_DONE.
  12292. **
  12293. ** SYNONYM SUPPORT
  12294. **
  12295. ** Custom tokenizers may also support synonyms. Consider a case in which a
  12296. ** user wishes to query for a phrase such as "first place". Using the
  12297. ** built-in tokenizers, the FTS5 query 'first + place' will match instances
  12298. ** of "first place" within the document set, but not alternative forms
  12299. ** such as "1st place". In some applications, it would be better to match
  12300. ** all instances of "first place" or "1st place" regardless of which form
  12301. ** the user specified in the MATCH query text.
  12302. **
  12303. ** There are several ways to approach this in FTS5:
  12304. **
  12305. ** <ol><li> By mapping all synonyms to a single token. In this case, using
  12306. ** the above example, this means that the tokenizer returns the
  12307. ** same token for inputs "first" and "1st". Say that token is in
  12308. ** fact "first", so that when the user inserts the document "I won
  12309. ** 1st place" entries are added to the index for tokens "i", "won",
  12310. ** "first" and "place". If the user then queries for '1st + place',
  12311. ** the tokenizer substitutes "first" for "1st" and the query works
  12312. ** as expected.
  12313. **
  12314. ** <li> By querying the index for all synonyms of each query term
  12315. ** separately. In this case, when tokenizing query text, the
  12316. ** tokenizer may provide multiple synonyms for a single term
  12317. ** within the document. FTS5 then queries the index for each
  12318. ** synonym individually. For example, faced with the query:
  12319. **
  12320. ** <codeblock>
  12321. ** ... MATCH 'first place'</codeblock>
  12322. **
  12323. ** the tokenizer offers both "1st" and "first" as synonyms for the
  12324. ** first token in the MATCH query and FTS5 effectively runs a query
  12325. ** similar to:
  12326. **
  12327. ** <codeblock>
  12328. ** ... MATCH '(first OR 1st) place'</codeblock>
  12329. **
  12330. ** except that, for the purposes of auxiliary functions, the query
  12331. ** still appears to contain just two phrases - "(first OR 1st)"
  12332. ** being treated as a single phrase.
  12333. **
  12334. ** <li> By adding multiple synonyms for a single term to the FTS index.
  12335. ** Using this method, when tokenizing document text, the tokenizer
  12336. ** provides multiple synonyms for each token. So that when a
  12337. ** document such as "I won first place" is tokenized, entries are
  12338. ** added to the FTS index for "i", "won", "first", "1st" and
  12339. ** "place".
  12340. **
  12341. ** This way, even if the tokenizer does not provide synonyms
  12342. ** when tokenizing query text (it should not - to do so would be
  12343. ** inefficient), it doesn't matter if the user queries for
  12344. ** 'first + place' or '1st + place', as there are entries in the
  12345. ** FTS index corresponding to both forms of the first token.
  12346. ** </ol>
  12347. **
  12348. ** Whether it is parsing document or query text, any call to xToken that
  12349. ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
  12350. ** is considered to supply a synonym for the previous token. For example,
  12351. ** when parsing the document "I won first place", a tokenizer that supports
  12352. ** synonyms would call xToken() 5 times, as follows:
  12353. **
  12354. ** <codeblock>
  12355. ** xToken(pCtx, 0, "i", 1, 0, 1);
  12356. ** xToken(pCtx, 0, "won", 3, 2, 5);
  12357. ** xToken(pCtx, 0, "first", 5, 6, 11);
  12358. ** xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3, 6, 11);
  12359. ** xToken(pCtx, 0, "place", 5, 12, 17);
  12360. **</codeblock>
  12361. **
  12362. ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
  12363. ** xToken() is called. Multiple synonyms may be specified for a single token
  12364. ** by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.
  12365. ** There is no limit to the number of synonyms that may be provided for a
  12366. ** single token.
  12367. **
  12368. ** In many cases, method (1) above is the best approach. It does not add
  12369. ** extra data to the FTS index or require FTS5 to query for multiple terms,
  12370. ** so it is efficient in terms of disk space and query speed. However, it
  12371. ** does not support prefix queries very well. If, as suggested above, the
  12372. ** token "first" is substituted for "1st" by the tokenizer, then the query:
  12373. **
  12374. ** <codeblock>
  12375. ** ... MATCH '1s*'</codeblock>
  12376. **
  12377. ** will not match documents that contain the token "1st" (as the tokenizer
  12378. ** will probably not map "1s" to any prefix of "first").
  12379. **
  12380. ** For full prefix support, method (3) may be preferred. In this case,
  12381. ** because the index contains entries for both "first" and "1st", prefix
  12382. ** queries such as 'fi*' or '1s*' will match correctly. However, because
  12383. ** extra entries are added to the FTS index, this method uses more space
  12384. ** within the database.
  12385. **
  12386. ** Method (2) offers a midpoint between (1) and (3). Using this method,
  12387. ** a query such as '1s*' will match documents that contain the literal
  12388. ** token "1st", but not "first" (assuming the tokenizer is not able to
  12389. ** provide synonyms for prefixes). However, a non-prefix query like '1st'
  12390. ** will match against "1st" and "first". This method does not require
  12391. ** extra disk space, as no extra entries are added to the FTS index.
  12392. ** On the other hand, it may require more CPU cycles to run MATCH queries,
  12393. ** as separate queries of the FTS index are required for each synonym.
  12394. **
  12395. ** When using methods (2) or (3), it is important that the tokenizer only
  12396. ** provide synonyms when tokenizing document text (method (2)) or query
  12397. ** text (method (3)), not both. Doing so will not cause any errors, but is
  12398. ** inefficient.
  12399. */
  12400. typedef struct Fts5Tokenizer Fts5Tokenizer;
  12401. typedef struct fts5_tokenizer fts5_tokenizer;
  12402. struct fts5_tokenizer {
  12403. int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
  12404. void (*xDelete)(Fts5Tokenizer*);
  12405. int (*xTokenize)(Fts5Tokenizer*,
  12406. void *pCtx,
  12407. int flags, /* Mask of FTS5_TOKENIZE_* flags */
  12408. const char *pText, int nText,
  12409. int (*xToken)(
  12410. void *pCtx, /* Copy of 2nd argument to xTokenize() */
  12411. int tflags, /* Mask of FTS5_TOKEN_* flags */
  12412. const char *pToken, /* Pointer to buffer containing token */
  12413. int nToken, /* Size of token in bytes */
  12414. int iStart, /* Byte offset of token within input text */
  12415. int iEnd /* Byte offset of end of token within input text */
  12416. )
  12417. );
  12418. };
  12419. /* Flags that may be passed as the third argument to xTokenize() */
  12420. #define FTS5_TOKENIZE_QUERY 0x0001
  12421. #define FTS5_TOKENIZE_PREFIX 0x0002
  12422. #define FTS5_TOKENIZE_DOCUMENT 0x0004
  12423. #define FTS5_TOKENIZE_AUX 0x0008
  12424. /* Flags that may be passed by the tokenizer implementation back to FTS5
  12425. ** as the third argument to the supplied xToken callback. */
  12426. #define FTS5_TOKEN_COLOCATED 0x0001 /* Same position as prev. token */
  12427. /*
  12428. ** END OF CUSTOM TOKENIZERS
  12429. *************************************************************************/
  12430. /*************************************************************************
  12431. ** FTS5 EXTENSION REGISTRATION API
  12432. */
  12433. typedef struct fts5_api fts5_api;
  12434. struct fts5_api {
  12435. int iVersion; /* Currently always set to 2 */
  12436. /* Create a new tokenizer */
  12437. int (*xCreateTokenizer)(
  12438. fts5_api *pApi,
  12439. const char *zName,
  12440. void *pContext,
  12441. fts5_tokenizer *pTokenizer,
  12442. void (*xDestroy)(void*)
  12443. );
  12444. /* Find an existing tokenizer */
  12445. int (*xFindTokenizer)(
  12446. fts5_api *pApi,
  12447. const char *zName,
  12448. void **ppContext,
  12449. fts5_tokenizer *pTokenizer
  12450. );
  12451. /* Create a new auxiliary function */
  12452. int (*xCreateFunction)(
  12453. fts5_api *pApi,
  12454. const char *zName,
  12455. void *pContext,
  12456. fts5_extension_function xFunction,
  12457. void (*xDestroy)(void*)
  12458. );
  12459. };
  12460. /*
  12461. ** END OF REGISTRATION API
  12462. *************************************************************************/
  12463. #ifdef __cplusplus
  12464. } /* end of the 'extern "C"' block */
  12465. #endif
  12466. #endif /* _FTS5_H */
  12467. /******** End of fts5.h *********/