SQLite Android Bindings
Changes On Branch android-studio
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Changes In Branch android-studio Excluding Merge-Ins

This is equivalent to a diff from cf6a31d2c9 to c44bb26627

2016-05-20
18:43
Update to Android Studio and gradle build system. check-in: 345de238a6 user: dan tags: trunk
18:40
Create a branch that supports API level 15 and up. Closed-Leaf check-in: da94157b9a user: dan tags: android-studio-15
17:31
Update the SQLite version bundled with this module to 3.13.0. Closed-Leaf check-in: c44bb26627 user: dan tags: android-studio
17:27
Documentation updates to take the changes on this branch into account. check-in: 546c601489 user: dan tags: android-studio
2016-05-19
15:24
Upgrade this module so that it takes the form of an Android Studio project. check-in: b5fcf9e7da user: dan tags: android-studio
2015-04-09
18:15
Add an extra test for SQLiteOpenHelper. check-in: cf6a31d2c9 user: dan tags: trunk
2015-04-04
08:19
Update this code to support 64-bit pointers. See also: https://android.googlesource.com/platform/frameworks/base.git/+/738702d28ab7e0e89e3c6e18fd46cc1361917eb9 check-in: 3e4327dc6e user: dan tags: trunk

Deleted AndroidManifest.xml.

     1         -<?xml version="1.0" encoding="utf-8"?>
     2         -<manifest xmlns:android="http://schemas.android.com/apk/res/android"
     3         -      package="org.sqlite.app.customsqlite"
     4         -      android:versionCode="1"
     5         -      android:versionName="1.0">
     6         -    <application android:label="@string/app_name" android:icon="@drawable/ic_launcher">
     7         -        <activity android:name="CustomSqlite"
     8         -                  android:label="@string/app_name">
     9         -            <intent-filter>
    10         -                <action android:name="android.intent.action.MAIN" />
    11         -                <category android:name="android.intent.category.LAUNCHER" />
    12         -            </intent-filter>
    13         -        </activity>
    14         -    </application>
    15         -</manifest>

Added Customsqlite.iml.

            1  +<?xml version="1.0" encoding="UTF-8"?>
            2  +<module external.linked.project.id="Customsqlite" external.linked.project.path="$MODULE_DIR$" external.root.project.path="$MODULE_DIR$" external.system.id="GRADLE" external.system.module.group="" external.system.module.version="unspecified" type="JAVA_MODULE" version="4">
            3  +  <component name="FacetManager">
            4  +    <facet type="java-gradle" name="Java-Gradle">
            5  +      <configuration>
            6  +        <option name="BUILD_FOLDER_PATH" value="$MODULE_DIR$/build" />
            7  +        <option name="BUILDABLE" value="false" />
            8  +      </configuration>
            9  +    </facet>
           10  +  </component>
           11  +  <component name="NewModuleRootManager" LANGUAGE_LEVEL="JDK_1_7" inherit-compiler-output="true">
           12  +    <exclude-output />
           13  +    <content url="file://$MODULE_DIR$">
           14  +      <excludeFolder url="file://$MODULE_DIR$/.gradle" />
           15  +    </content>
           16  +    <orderEntry type="inheritedJdk" />
           17  +    <orderEntry type="sourceFolder" forTests="false" />
           18  +  </component>
           19  +</module>

Deleted ant.properties.

     1         -# This file is used to override default values used by the Ant build system.
     2         -#
     3         -# This file must be checked into Version Control Systems, as it is
     4         -# integral to the build system of your project.
     5         -
     6         -# This file is only used by the Ant script.
     7         -
     8         -# You can use this to override default values such as
     9         -#  'source.dir' for the location of your java source folder and
    10         -#  'out.dir' for the location of your output folder.
    11         -
    12         -# You can also use it define how the release builds are signed by declaring
    13         -# the following properties:
    14         -#  'key.store' for the location of your keystore and
    15         -#  'key.alias' for the name of the key to use.
    16         -# The password will be asked during the build when you use the 'release' target.
    17         -

Added build.gradle.

            1  +// Top-level build file where you can add configuration options common to all sub-projects/modules.
            2  +
            3  +buildscript {
            4  +    repositories {
            5  +        jcenter()
            6  +    }
            7  +    dependencies {
            8  +        classpath 'com.android.tools.build:gradle:2.1.0'
            9  +
           10  +        // NOTE: Do not place your application dependencies here; they belong
           11  +        // in the individual module build.gradle files
           12  +    }
           13  +}
           14  +
           15  +allprojects {
           16  +    repositories {
           17  +        jcenter()
           18  +    }
           19  +}
           20  +
           21  +task clean(type: Delete) {
           22  +    delete rootProject.buildDir
           23  +}

Deleted build.xml.

     1         -<?xml version="1.0" encoding="UTF-8"?>
     2         -<project name="CustomSqlite" default="help">
     3         -
     4         -    <!-- The local.properties file is created and updated by the 'android' tool.
     5         -         It contains the path to the SDK. It should *NOT* be checked into
     6         -         Version Control Systems. -->
     7         -    <property file="local.properties" />
     8         -
     9         -    <!-- The ant.properties file can be created by you. It is only edited by the
    10         -         'android' tool to add properties to it.
    11         -         This is the place to change some Ant specific build properties.
    12         -         Here are some properties you may want to change/update:
    13         -
    14         -         source.dir
    15         -             The name of the source directory. Default is 'src'.
    16         -         out.dir
    17         -             The name of the output directory. Default is 'bin'.
    18         -
    19         -         For other overridable properties, look at the beginning of the rules
    20         -         files in the SDK, at tools/ant/build.xml
    21         -
    22         -         Properties related to the SDK location or the project target should
    23         -         be updated using the 'android' tool with the 'update' action.
    24         -
    25         -         This file is an integral part of the build system for your
    26         -         application and should be checked into Version Control Systems.
    27         -
    28         -         -->
    29         -    <property file="ant.properties" />
    30         -
    31         -    <!-- if sdk.dir was not set from one of the property file, then
    32         -         get it from the ANDROID_HOME env var.
    33         -         This must be done before we load project.properties since
    34         -         the proguard config can use sdk.dir -->
    35         -    <property environment="env" />
    36         -    <condition property="sdk.dir" value="${env.ANDROID_HOME}">
    37         -        <isset property="env.ANDROID_HOME" />
    38         -    </condition>
    39         -
    40         -    <!-- The project.properties file is created and updated by the 'android'
    41         -         tool, as well as ADT.
    42         -
    43         -         This contains project specific properties such as project target, and library
    44         -         dependencies. Lower level build properties are stored in ant.properties
    45         -         (or in .classpath for Eclipse projects).
    46         -
    47         -         This file is an integral part of the build system for your
    48         -         application and should be checked into Version Control Systems. -->
    49         -    <loadproperties srcFile="project.properties" />
    50         -
    51         -    <!-- quick check on sdk.dir -->
    52         -    <fail
    53         -            message="sdk.dir is missing. Make sure to generate local.properties using 'android update project' or to inject it through the ANDROID_HOME environment variable."
    54         -            unless="sdk.dir"
    55         -    />
    56         -
    57         -    <!--
    58         -        Import per project custom build rules if present at the root of the project.
    59         -        This is the place to put custom intermediary targets such as:
    60         -            -pre-build
    61         -            -pre-compile
    62         -            -post-compile (This is typically used for code obfuscation.
    63         -                           Compiled code location: ${out.classes.absolute.dir}
    64         -                           If this is not done in place, override ${out.dex.input.absolute.dir})
    65         -            -post-package
    66         -            -post-build
    67         -            -pre-clean
    68         -    -->
    69         -    <import file="custom_rules.xml" optional="true" />
    70         -
    71         -    <!-- Import the actual build file.
    72         -
    73         -         To customize existing targets, there are two options:
    74         -         - Customize only one target:
    75         -             - copy/paste the target into this file, *before* the
    76         -               <import> task.
    77         -             - customize it to your needs.
    78         -         - Customize the whole content of build.xml
    79         -             - copy/paste the content of the rules files (minus the top node)
    80         -               into this file, replacing the <import> task.
    81         -             - customize to your needs.
    82         -
    83         -         ***********************
    84         -         ****** IMPORTANT ******
    85         -         ***********************
    86         -         In all cases you must update the value of version-tag below to read 'custom' instead of an integer,
    87         -         in order to avoid having your file be overridden by tools such as "android update project"
    88         -    -->
    89         -    <!-- version-tag: 1 -->
    90         -    <import file="${sdk.dir}/tools/ant/build.xml" />
    91         -
    92         -</project>

Added gradle.properties.

            1  +# Project-wide Gradle settings.
            2  +
            3  +# IDE (e.g. Android Studio) users:
            4  +# Gradle settings configured through the IDE *will override*
            5  +# any settings specified in this file.
            6  +
            7  +# For more details on how to configure your build environment visit
            8  +# http://www.gradle.org/docs/current/userguide/build_environment.html
            9  +
           10  +# Specifies the JVM arguments used for the daemon process.
           11  +# The setting is particularly useful for tweaking memory settings.
           12  +# Default value: -Xmx10248m -XX:MaxPermSize=256m
           13  +# org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
           14  +
           15  +# When configured, Gradle will run in incubating parallel mode.
           16  +# This option should only be used with decoupled projects. More details, visit
           17  +# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
           18  +# org.gradle.parallel=true
           19  +
           20  +android.useDeprecatedNdk true

Added gradle/wrapper/gradle-wrapper.jar.

cannot compute difference between binary files

Added gradle/wrapper/gradle-wrapper.properties.

            1  +#Mon Dec 28 10:00:20 PST 2015
            2  +distributionBase=GRADLE_USER_HOME
            3  +distributionPath=wrapper/dists
            4  +zipStoreBase=GRADLE_USER_HOME
            5  +zipStorePath=wrapper/dists
            6  +distributionUrl=https\://services.gradle.org/distributions/gradle-2.10-all.zip

Added gradlew.

            1  +#!/usr/bin/env bash
            2  +
            3  +##############################################################################
            4  +##
            5  +##  Gradle start up script for UN*X
            6  +##
            7  +##############################################################################
            8  +
            9  +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
           10  +DEFAULT_JVM_OPTS=""
           11  +
           12  +APP_NAME="Gradle"
           13  +APP_BASE_NAME=`basename "$0"`
           14  +
           15  +# Use the maximum available, or set MAX_FD != -1 to use that value.
           16  +MAX_FD="maximum"
           17  +
           18  +warn ( ) {
           19  +    echo "$*"
           20  +}
           21  +
           22  +die ( ) {
           23  +    echo
           24  +    echo "$*"
           25  +    echo
           26  +    exit 1
           27  +}
           28  +
           29  +# OS specific support (must be 'true' or 'false').
           30  +cygwin=false
           31  +msys=false
           32  +darwin=false
           33  +case "`uname`" in
           34  +  CYGWIN* )
           35  +    cygwin=true
           36  +    ;;
           37  +  Darwin* )
           38  +    darwin=true
           39  +    ;;
           40  +  MINGW* )
           41  +    msys=true
           42  +    ;;
           43  +esac
           44  +
           45  +# Attempt to set APP_HOME
           46  +# Resolve links: $0 may be a link
           47  +PRG="$0"
           48  +# Need this for relative symlinks.
           49  +while [ -h "$PRG" ] ; do
           50  +    ls=`ls -ld "$PRG"`
           51  +    link=`expr "$ls" : '.*-> \(.*\)$'`
           52  +    if expr "$link" : '/.*' > /dev/null; then
           53  +        PRG="$link"
           54  +    else
           55  +        PRG=`dirname "$PRG"`"/$link"
           56  +    fi
           57  +done
           58  +SAVED="`pwd`"
           59  +cd "`dirname \"$PRG\"`/" >/dev/null
           60  +APP_HOME="`pwd -P`"
           61  +cd "$SAVED" >/dev/null
           62  +
           63  +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
           64  +
           65  +# Determine the Java command to use to start the JVM.
           66  +if [ -n "$JAVA_HOME" ] ; then
           67  +    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
           68  +        # IBM's JDK on AIX uses strange locations for the executables
           69  +        JAVACMD="$JAVA_HOME/jre/sh/java"
           70  +    else
           71  +        JAVACMD="$JAVA_HOME/bin/java"
           72  +    fi
           73  +    if [ ! -x "$JAVACMD" ] ; then
           74  +        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
           75  +
           76  +Please set the JAVA_HOME variable in your environment to match the
           77  +location of your Java installation."
           78  +    fi
           79  +else
           80  +    JAVACMD="java"
           81  +    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
           82  +
           83  +Please set the JAVA_HOME variable in your environment to match the
           84  +location of your Java installation."
           85  +fi
           86  +
           87  +# Increase the maximum file descriptors if we can.
           88  +if [ "$cygwin" = "false" -a "$darwin" = "false" ] ; then
           89  +    MAX_FD_LIMIT=`ulimit -H -n`
           90  +    if [ $? -eq 0 ] ; then
           91  +        if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
           92  +            MAX_FD="$MAX_FD_LIMIT"
           93  +        fi
           94  +        ulimit -n $MAX_FD
           95  +        if [ $? -ne 0 ] ; then
           96  +            warn "Could not set maximum file descriptor limit: $MAX_FD"
           97  +        fi
           98  +    else
           99  +        warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
          100  +    fi
          101  +fi
          102  +
          103  +# For Darwin, add options to specify how the application appears in the dock
          104  +if $darwin; then
          105  +    GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
          106  +fi
          107  +
          108  +# For Cygwin, switch paths to Windows format before running java
          109  +if $cygwin ; then
          110  +    APP_HOME=`cygpath --path --mixed "$APP_HOME"`
          111  +    CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
          112  +    JAVACMD=`cygpath --unix "$JAVACMD"`
          113  +
          114  +    # We build the pattern for arguments to be converted via cygpath
          115  +    ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
          116  +    SEP=""
          117  +    for dir in $ROOTDIRSRAW ; do
          118  +        ROOTDIRS="$ROOTDIRS$SEP$dir"
          119  +        SEP="|"
          120  +    done
          121  +    OURCYGPATTERN="(^($ROOTDIRS))"
          122  +    # Add a user-defined pattern to the cygpath arguments
          123  +    if [ "$GRADLE_CYGPATTERN" != "" ] ; then
          124  +        OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
          125  +    fi
          126  +    # Now convert the arguments - kludge to limit ourselves to /bin/sh
          127  +    i=0
          128  +    for arg in "$@" ; do
          129  +        CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
          130  +        CHECK2=`echo "$arg"|egrep -c "^-"`                                 ### Determine if an option
          131  +
          132  +        if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then                    ### Added a condition
          133  +            eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
          134  +        else
          135  +            eval `echo args$i`="\"$arg\""
          136  +        fi
          137  +        i=$((i+1))
          138  +    done
          139  +    case $i in
          140  +        (0) set -- ;;
          141  +        (1) set -- "$args0" ;;
          142  +        (2) set -- "$args0" "$args1" ;;
          143  +        (3) set -- "$args0" "$args1" "$args2" ;;
          144  +        (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
          145  +        (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
          146  +        (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
          147  +        (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
          148  +        (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
          149  +        (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
          150  +    esac
          151  +fi
          152  +
          153  +# Split up the JVM_OPTS And GRADLE_OPTS values into an array, following the shell quoting and substitution rules
          154  +function splitJvmOpts() {
          155  +    JVM_OPTS=("$@")
          156  +}
          157  +eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
          158  +JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
          159  +
          160  +exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

Added gradlew.bat.

            1  +@if "%DEBUG%" == "" @echo off
            2  +@rem ##########################################################################
            3  +@rem
            4  +@rem  Gradle startup script for Windows
            5  +@rem
            6  +@rem ##########################################################################
            7  +
            8  +@rem Set local scope for the variables with windows NT shell
            9  +if "%OS%"=="Windows_NT" setlocal
           10  +
           11  +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
           12  +set DEFAULT_JVM_OPTS=
           13  +
           14  +set DIRNAME=%~dp0
           15  +if "%DIRNAME%" == "" set DIRNAME=.
           16  +set APP_BASE_NAME=%~n0
           17  +set APP_HOME=%DIRNAME%
           18  +
           19  +@rem Find java.exe
           20  +if defined JAVA_HOME goto findJavaFromJavaHome
           21  +
           22  +set JAVA_EXE=java.exe
           23  +%JAVA_EXE% -version >NUL 2>&1
           24  +if "%ERRORLEVEL%" == "0" goto init
           25  +
           26  +echo.
           27  +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
           28  +echo.
           29  +echo Please set the JAVA_HOME variable in your environment to match the
           30  +echo location of your Java installation.
           31  +
           32  +goto fail
           33  +
           34  +:findJavaFromJavaHome
           35  +set JAVA_HOME=%JAVA_HOME:"=%
           36  +set JAVA_EXE=%JAVA_HOME%/bin/java.exe
           37  +
           38  +if exist "%JAVA_EXE%" goto init
           39  +
           40  +echo.
           41  +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
           42  +echo.
           43  +echo Please set the JAVA_HOME variable in your environment to match the
           44  +echo location of your Java installation.
           45  +
           46  +goto fail
           47  +
           48  +:init
           49  +@rem Get command-line arguments, handling Windowz variants
           50  +
           51  +if not "%OS%" == "Windows_NT" goto win9xME_args
           52  +if "%@eval[2+2]" == "4" goto 4NT_args
           53  +
           54  +:win9xME_args
           55  +@rem Slurp the command line arguments.
           56  +set CMD_LINE_ARGS=
           57  +set _SKIP=2
           58  +
           59  +:win9xME_args_slurp
           60  +if "x%~1" == "x" goto execute
           61  +
           62  +set CMD_LINE_ARGS=%*
           63  +goto execute
           64  +
           65  +:4NT_args
           66  +@rem Get arguments from the 4NT Shell from JP Software
           67  +set CMD_LINE_ARGS=%$
           68  +
           69  +:execute
           70  +@rem Setup the command line
           71  +
           72  +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
           73  +
           74  +@rem Execute Gradle
           75  +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
           76  +
           77  +:end
           78  +@rem End local scope for the variables with windows NT shell
           79  +if "%ERRORLEVEL%"=="0" goto mainEnd
           80  +
           81  +:fail
           82  +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
           83  +rem the _cmd.exe /c_ return code!
           84  +if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
           85  +exit /b 1
           86  +
           87  +:mainEnd
           88  +if "%OS%"=="Windows_NT" endlocal
           89  +
           90  +:omega

Deleted jni/Android.mk.

     1         -
     2         -LOCAL_PATH:= $(call my-dir)
     3         -include $(LOCAL_PATH)/sqlite/Android.mk
     4         -

Deleted jni/Application.mk.

     1         -APP_STL:=stlport_static

Deleted jni/sqlite/ALog-priv.h.

     1         -/*
     2         - * Copyright 2013 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#ifndef NATIVEHELPER_ALOGPRIV_H_
    22         -#define NATIVEHELPER_ALOGPRIV_H_
    23         -
    24         -#include <android/log.h>
    25         -
    26         -#ifndef LOG_NDEBUG
    27         -#ifdef NDEBUG
    28         -#define LOG_NDEBUG 1
    29         -#else
    30         -#define LOG_NDEBUG 0
    31         -#endif
    32         -#endif
    33         -
    34         -
    35         -/*
    36         - * Basic log message macros intended to emulate the behavior of log/log.h
    37         - * in system core.  This should be dependent only on ndk exposed logging
    38         - * functionality.
    39         - */
    40         -
    41         -#ifndef ALOG
    42         -#define ALOG(priority, tag, fmt...) \
    43         -    __android_log_print(ANDROID_##priority, tag, fmt)
    44         -#endif
    45         -
    46         -#ifndef ALOGV
    47         -#if LOG_NDEBUG
    48         -#define ALOGV(...)   ((void)0)
    49         -#else
    50         -#define ALOGV(...) ((void)ALOG(LOG_VERBOSE, LOG_TAG, __VA_ARGS__))
    51         -#endif
    52         -#endif
    53         -
    54         -#ifndef ALOGD
    55         -#define ALOGD(...) ((void)ALOG(LOG_DEBUG, LOG_TAG, __VA_ARGS__))
    56         -#endif
    57         -
    58         -#ifndef ALOGI
    59         -#define ALOGI(...) ((void)ALOG(LOG_INFO, LOG_TAG, __VA_ARGS__))
    60         -#endif
    61         -
    62         -#ifndef ALOGW
    63         -#define ALOGW(...) ((void)ALOG(LOG_WARN, LOG_TAG, __VA_ARGS__))
    64         -#endif
    65         -
    66         -#ifndef ALOGE
    67         -#define ALOGE(...) ((void)ALOG(LOG_ERROR, LOG_TAG, __VA_ARGS__))
    68         -#endif
    69         -
    70         -/*
    71         -** Not quite the same as the core android LOG_FATAL_IF (which also
    72         -** sends a SIGTRAP), but close enough.
    73         -*/
    74         -#define LOG_FATAL_IF(bCond, zErr) if( bCond ) ALOGE(zErr);
    75         -
    76         -#endif

Deleted jni/sqlite/Android.mk.

     1         -
     2         -LOCAL_PATH:= $(call my-dir)
     3         -include $(CLEAR_VARS)
     4         -
     5         -# If using SEE, uncomment the following:
     6         -# LOCAL_CFLAGS += -DSQLITE_HAS_CODEC
     7         -
     8         -# This is important - it causes SQLite to use memory for temp files. Since 
     9         -# Android has no globally writable temp directory, if this is not defined the
    10         -# application throws an exception when it tries to create a temp file.
    11         -#
    12         -LOCAL_CFLAGS += -DSQLITE_TEMP_STORE=3
    13         -
    14         -LOCAL_CFLAGS += -DHAVE_CONFIG_H -DKHTML_NO_EXCEPTIONS -DGKWQ_NO_JAVA
    15         -LOCAL_CFLAGS += -DNO_SUPPORT_JS_BINDING -DQT_NO_WHEELEVENT -DKHTML_NO_XBL
    16         -LOCAL_CFLAGS += -U__APPLE__
    17         -LOCAL_CFLAGS += -DHAVE_STRCHRNUL=0
    18         -LOCAL_CFLAGS += -Wno-unused-parameter -Wno-int-to-pointer-cast
    19         -LOCAL_CFLAGS += -Wno-maybe-uninitialized -Wno-parentheses
    20         -LOCAL_CPPFLAGS += -Wno-conversion-null
    21         -
    22         -
    23         -ifeq ($(TARGET_ARCH), arm)
    24         -	LOCAL_CFLAGS += -DPACKED="__attribute__ ((packed))"
    25         -else
    26         -	LOCAL_CFLAGS += -DPACKED=""
    27         -endif
    28         -
    29         -LOCAL_SRC_FILES:=                             \
    30         -	android_database_SQLiteCommon.cpp     \
    31         -	android_database_SQLiteConnection.cpp \
    32         -	android_database_SQLiteGlobal.cpp     \
    33         -	android_database_SQLiteDebug.cpp      \
    34         -	JNIHelp.cpp JniConstants.cpp
    35         -
    36         -LOCAL_SRC_FILES += sqlite3.c
    37         -
    38         -LOCAL_C_INCLUDES += $(LOCAL_PATH) $(LOCAL_PATH)/nativehelper/
    39         -
    40         -LOCAL_MODULE:= libsqliteX
    41         -LOCAL_LDLIBS += -ldl -llog 
    42         -
    43         -include $(BUILD_SHARED_LIBRARY)
    44         -

Deleted jni/sqlite/JNIHelp.cpp.

     1         -/*
     2         - * Copyright (C) 2006 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -#define LOG_TAG "JNIHelp"
    18         -
    19         -#include "JniConstants.h"
    20         -#include "JNIHelp.h"
    21         -#include "ALog-priv.h"
    22         -
    23         -#include <stdio.h>
    24         -#include <stdlib.h>
    25         -#include <string.h>
    26         -#include <assert.h>
    27         -
    28         -#include <string>
    29         -
    30         -/**
    31         - * Equivalent to ScopedLocalRef, but for C_JNIEnv instead. (And slightly more powerful.)
    32         - */
    33         -template<typename T>
    34         -class scoped_local_ref {
    35         -public:
    36         -    scoped_local_ref(C_JNIEnv* env, T localRef = NULL)
    37         -    : mEnv(env), mLocalRef(localRef)
    38         -    {
    39         -    }
    40         -
    41         -    ~scoped_local_ref() {
    42         -        reset();
    43         -    }
    44         -
    45         -    void reset(T localRef = NULL) {
    46         -        if (mLocalRef != NULL) {
    47         -            (*mEnv)->DeleteLocalRef(reinterpret_cast<JNIEnv*>(mEnv), mLocalRef);
    48         -            mLocalRef = localRef;
    49         -        }
    50         -    }
    51         -
    52         -    T get() const {
    53         -        return mLocalRef;
    54         -    }
    55         -
    56         -private:
    57         -    C_JNIEnv* mEnv;
    58         -    T mLocalRef;
    59         -
    60         -    // Disallow copy and assignment.
    61         -    scoped_local_ref(const scoped_local_ref&);
    62         -    void operator=(const scoped_local_ref&);
    63         -};
    64         -
    65         -static jclass findClass(C_JNIEnv* env, const char* className) {
    66         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
    67         -    return (*env)->FindClass(e, className);
    68         -}
    69         -
    70         -extern "C" int jniRegisterNativeMethods(C_JNIEnv* env, const char* className,
    71         -    const JNINativeMethod* gMethods, int numMethods)
    72         -{
    73         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
    74         -
    75         -    ALOGV("Registering %s's %d native methods...", className, numMethods);
    76         -
    77         -    scoped_local_ref<jclass> c(env, findClass(env, className));
    78         -    if (c.get() == NULL) {
    79         -        char* msg;
    80         -        asprintf(&msg, "Native registration unable to find class '%s'; aborting...", className);
    81         -        e->FatalError(msg);
    82         -    }
    83         -
    84         -    if ((*env)->RegisterNatives(e, c.get(), gMethods, numMethods) < 0) {
    85         -        char* msg;
    86         -        asprintf(&msg, "RegisterNatives failed for '%s'; aborting...", className);
    87         -        e->FatalError(msg);
    88         -    }
    89         -
    90         -    return 0;
    91         -}
    92         -
    93         -/*
    94         - * Returns a human-readable summary of an exception object.  The buffer will
    95         - * be populated with the "binary" class name and, if present, the
    96         - * exception message.
    97         - */
    98         -static bool getExceptionSummary(C_JNIEnv* env, jthrowable exception, std::string& result) {
    99         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   100         -
   101         -    /* get the name of the exception's class */
   102         -    scoped_local_ref<jclass> exceptionClass(env, (*env)->GetObjectClass(e, exception)); // can't fail
   103         -    scoped_local_ref<jclass> classClass(env,
   104         -            (*env)->GetObjectClass(e, exceptionClass.get())); // java.lang.Class, can't fail
   105         -    jmethodID classGetNameMethod =
   106         -            (*env)->GetMethodID(e, classClass.get(), "getName", "()Ljava/lang/String;");
   107         -    scoped_local_ref<jstring> classNameStr(env,
   108         -            (jstring) (*env)->CallObjectMethod(e, exceptionClass.get(), classGetNameMethod));
   109         -    if (classNameStr.get() == NULL) {
   110         -        (*env)->ExceptionClear(e);
   111         -        result = "<error getting class name>";
   112         -        return false;
   113         -    }
   114         -    const char* classNameChars = (*env)->GetStringUTFChars(e, classNameStr.get(), NULL);
   115         -    if (classNameChars == NULL) {
   116         -        (*env)->ExceptionClear(e);
   117         -        result = "<error getting class name UTF-8>";
   118         -        return false;
   119         -    }
   120         -    result += classNameChars;
   121         -    (*env)->ReleaseStringUTFChars(e, classNameStr.get(), classNameChars);
   122         -
   123         -    /* if the exception has a detail message, get that */
   124         -    jmethodID getMessage =
   125         -            (*env)->GetMethodID(e, exceptionClass.get(), "getMessage", "()Ljava/lang/String;");
   126         -    scoped_local_ref<jstring> messageStr(env,
   127         -            (jstring) (*env)->CallObjectMethod(e, exception, getMessage));
   128         -    if (messageStr.get() == NULL) {
   129         -        return true;
   130         -    }
   131         -
   132         -    result += ": ";
   133         -
   134         -    const char* messageChars = (*env)->GetStringUTFChars(e, messageStr.get(), NULL);
   135         -    if (messageChars != NULL) {
   136         -        result += messageChars;
   137         -        (*env)->ReleaseStringUTFChars(e, messageStr.get(), messageChars);
   138         -    } else {
   139         -        result += "<error getting message>";
   140         -        (*env)->ExceptionClear(e); // clear OOM
   141         -    }
   142         -
   143         -    return true;
   144         -}
   145         -
   146         -/*
   147         - * Returns an exception (with stack trace) as a string.
   148         - */
   149         -static bool getStackTrace(C_JNIEnv* env, jthrowable exception, std::string& result) {
   150         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   151         -
   152         -    scoped_local_ref<jclass> stringWriterClass(env, findClass(env, "java/io/StringWriter"));
   153         -    if (stringWriterClass.get() == NULL) {
   154         -        return false;
   155         -    }
   156         -
   157         -    jmethodID stringWriterCtor = (*env)->GetMethodID(e, stringWriterClass.get(), "<init>", "()V");
   158         -    jmethodID stringWriterToStringMethod =
   159         -            (*env)->GetMethodID(e, stringWriterClass.get(), "toString", "()Ljava/lang/String;");
   160         -
   161         -    scoped_local_ref<jclass> printWriterClass(env, findClass(env, "java/io/PrintWriter"));
   162         -    if (printWriterClass.get() == NULL) {
   163         -        return false;
   164         -    }
   165         -
   166         -    jmethodID printWriterCtor =
   167         -            (*env)->GetMethodID(e, printWriterClass.get(), "<init>", "(Ljava/io/Writer;)V");
   168         -
   169         -    scoped_local_ref<jobject> stringWriter(env,
   170         -            (*env)->NewObject(e, stringWriterClass.get(), stringWriterCtor));
   171         -    if (stringWriter.get() == NULL) {
   172         -        return false;
   173         -    }
   174         -
   175         -    jobject printWriter =
   176         -            (*env)->NewObject(e, printWriterClass.get(), printWriterCtor, stringWriter.get());
   177         -    if (printWriter == NULL) {
   178         -        return false;
   179         -    }
   180         -
   181         -    scoped_local_ref<jclass> exceptionClass(env, (*env)->GetObjectClass(e, exception)); // can't fail
   182         -    jmethodID printStackTraceMethod =
   183         -            (*env)->GetMethodID(e, exceptionClass.get(), "printStackTrace", "(Ljava/io/PrintWriter;)V");
   184         -    (*env)->CallVoidMethod(e, exception, printStackTraceMethod, printWriter);
   185         -
   186         -    if ((*env)->ExceptionCheck(e)) {
   187         -        return false;
   188         -    }
   189         -
   190         -    scoped_local_ref<jstring> messageStr(env,
   191         -            (jstring) (*env)->CallObjectMethod(e, stringWriter.get(), stringWriterToStringMethod));
   192         -    if (messageStr.get() == NULL) {
   193         -        return false;
   194         -    }
   195         -
   196         -    const char* utfChars = (*env)->GetStringUTFChars(e, messageStr.get(), NULL);
   197         -    if (utfChars == NULL) {
   198         -        return false;
   199         -    }
   200         -
   201         -    result = utfChars;
   202         -
   203         -    (*env)->ReleaseStringUTFChars(e, messageStr.get(), utfChars);
   204         -    return true;
   205         -}
   206         -
   207         -extern "C" int jniThrowException(C_JNIEnv* env, const char* className, const char* msg) {
   208         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   209         -
   210         -    if ((*env)->ExceptionCheck(e)) {
   211         -        /* TODO: consider creating the new exception with this as "cause" */
   212         -        scoped_local_ref<jthrowable> exception(env, (*env)->ExceptionOccurred(e));
   213         -        (*env)->ExceptionClear(e);
   214         -
   215         -        if (exception.get() != NULL) {
   216         -            std::string text;
   217         -            getExceptionSummary(env, exception.get(), text);
   218         -            ALOGW("Discarding pending exception (%s) to throw %s", text.c_str(), className);
   219         -        }
   220         -    }
   221         -
   222         -    scoped_local_ref<jclass> exceptionClass(env, findClass(env, className));
   223         -    if (exceptionClass.get() == NULL) {
   224         -        ALOGE("Unable to find exception class %s", className);
   225         -        /* ClassNotFoundException now pending */
   226         -        return -1;
   227         -    }
   228         -
   229         -    if ((*env)->ThrowNew(e, exceptionClass.get(), msg) != JNI_OK) {
   230         -        ALOGE("Failed throwing '%s' '%s'", className, msg);
   231         -        /* an exception, most likely OOM, will now be pending */
   232         -        return -1;
   233         -    }
   234         -
   235         -    return 0;
   236         -}
   237         -
   238         -int jniThrowExceptionFmt(C_JNIEnv* env, const char* className, const char* fmt, va_list args) {
   239         -    char msgBuf[512];
   240         -    vsnprintf(msgBuf, sizeof(msgBuf), fmt, args);
   241         -    return jniThrowException(env, className, msgBuf);
   242         -}
   243         -
   244         -int jniThrowNullPointerException(C_JNIEnv* env, const char* msg) {
   245         -    return jniThrowException(env, "java/lang/NullPointerException", msg);
   246         -}
   247         -
   248         -int jniThrowRuntimeException(C_JNIEnv* env, const char* msg) {
   249         -    return jniThrowException(env, "java/lang/RuntimeException", msg);
   250         -}
   251         -
   252         -int jniThrowIOException(C_JNIEnv* env, int errnum) {
   253         -    char buffer[80];
   254         -    const char* message = jniStrError(errnum, buffer, sizeof(buffer));
   255         -    return jniThrowException(env, "java/io/IOException", message);
   256         -}
   257         -
   258         -static std::string jniGetStackTrace(C_JNIEnv* env, jthrowable exception) {
   259         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   260         -
   261         -    scoped_local_ref<jthrowable> currentException(env, (*env)->ExceptionOccurred(e));
   262         -    if (exception == NULL) {
   263         -        exception = currentException.get();
   264         -        if (exception == NULL) {
   265         -          return "<no pending exception>";
   266         -        }
   267         -    }
   268         -
   269         -    if (currentException.get() != NULL) {
   270         -        (*env)->ExceptionClear(e);
   271         -    }
   272         -
   273         -    std::string trace;
   274         -    if (!getStackTrace(env, exception, trace)) {
   275         -        (*env)->ExceptionClear(e);
   276         -        getExceptionSummary(env, exception, trace);
   277         -    }
   278         -
   279         -    if (currentException.get() != NULL) {
   280         -        (*env)->Throw(e, currentException.get()); // rethrow
   281         -    }
   282         -
   283         -    return trace;
   284         -}
   285         -
   286         -void jniLogException(C_JNIEnv* env, int priority, const char* tag, jthrowable exception) {
   287         -    std::string trace(jniGetStackTrace(env, exception));
   288         -    __android_log_write(priority, tag, trace.c_str());
   289         -}
   290         -
   291         -const char* jniStrError(int errnum, char* buf, size_t buflen) {
   292         -#if __GLIBC__
   293         -    // Note: glibc has a nonstandard strerror_r that returns char* rather than POSIX's int.
   294         -    // char *strerror_r(int errnum, char *buf, size_t n);
   295         -    return strerror_r(errnum, buf, buflen);
   296         -#else
   297         -    int rc = strerror_r(errnum, buf, buflen);
   298         -    if (rc != 0) {
   299         -        // (POSIX only guarantees a value other than 0. The safest
   300         -        // way to implement this function is to use C++ and overload on the
   301         -        // type of strerror_r to accurately distinguish GNU from POSIX.)
   302         -        snprintf(buf, buflen, "errno %d", errnum);
   303         -    }
   304         -    return buf;
   305         -#endif
   306         -}
   307         -
   308         -jobject jniCreateFileDescriptor(C_JNIEnv* env, int fd) {
   309         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   310         -    static jmethodID ctor = e->GetMethodID(JniConstants::fileDescriptorClass, "<init>", "()V");
   311         -    jobject fileDescriptor = (*env)->NewObject(e, JniConstants::fileDescriptorClass, ctor);
   312         -    // NOTE: NewObject ensures that an OutOfMemoryError will be seen by the Java
   313         -    // caller if the alloc fails, so we just return NULL when that happens.
   314         -    if (fileDescriptor != NULL)  {
   315         -        jniSetFileDescriptorOfFD(env, fileDescriptor, fd);
   316         -    }
   317         -    return fileDescriptor;
   318         -}
   319         -
   320         -int jniGetFDFromFileDescriptor(C_JNIEnv* env, jobject fileDescriptor) {
   321         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   322         -    static jfieldID fid = e->GetFieldID(JniConstants::fileDescriptorClass, "descriptor", "I");
   323         -    if (fileDescriptor != NULL) {
   324         -        return (*env)->GetIntField(e, fileDescriptor, fid);
   325         -    } else {
   326         -        return -1;
   327         -    }
   328         -}
   329         -
   330         -void jniSetFileDescriptorOfFD(C_JNIEnv* env, jobject fileDescriptor, int value) {
   331         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   332         -    static jfieldID fid = e->GetFieldID(JniConstants::fileDescriptorClass, "descriptor", "I");
   333         -    (*env)->SetIntField(e, fileDescriptor, fid, value);
   334         -}
   335         -
   336         -jobject jniGetReferent(C_JNIEnv* env, jobject ref) {
   337         -    JNIEnv* e = reinterpret_cast<JNIEnv*>(env);
   338         -    static jmethodID get = e->GetMethodID(JniConstants::referenceClass, "get", "()Ljava/lang/Object;");
   339         -    return (*env)->CallObjectMethod(e, ref, get);
   340         -}
   341         -

Deleted jni/sqlite/JniConstants.cpp.

     1         -/*
     2         - * Copyright (C) 2010 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -#define LOG_TAG "JniConstants"
    18         -
    19         -#include "ALog-priv.h"
    20         -#include "JniConstants.h"
    21         -#include "ScopedLocalRef.h"
    22         -
    23         -#include <stdlib.h>
    24         -
    25         -jclass JniConstants::bidiRunClass;
    26         -jclass JniConstants::bigDecimalClass;
    27         -jclass JniConstants::booleanClass;
    28         -jclass JniConstants::byteArrayClass;
    29         -jclass JniConstants::byteClass;
    30         -jclass JniConstants::calendarClass;
    31         -jclass JniConstants::characterClass;
    32         -jclass JniConstants::charsetICUClass;
    33         -jclass JniConstants::constructorClass;
    34         -jclass JniConstants::deflaterClass;
    35         -jclass JniConstants::doubleClass;
    36         -jclass JniConstants::errnoExceptionClass;
    37         -jclass JniConstants::fieldClass;
    38         -jclass JniConstants::fieldPositionIteratorClass;
    39         -jclass JniConstants::fileDescriptorClass;
    40         -jclass JniConstants::floatClass;
    41         -jclass JniConstants::gaiExceptionClass;
    42         -jclass JniConstants::inet6AddressClass;
    43         -jclass JniConstants::inetAddressClass;
    44         -jclass JniConstants::inetSocketAddressClass;
    45         -jclass JniConstants::inetUnixAddressClass;
    46         -jclass JniConstants::inflaterClass;
    47         -jclass JniConstants::inputStreamClass;
    48         -jclass JniConstants::integerClass;
    49         -jclass JniConstants::localeDataClass;
    50         -jclass JniConstants::longClass;
    51         -jclass JniConstants::methodClass;
    52         -jclass JniConstants::mutableIntClass;
    53         -jclass JniConstants::mutableLongClass;
    54         -jclass JniConstants::objectClass;
    55         -jclass JniConstants::objectArrayClass;
    56         -jclass JniConstants::outputStreamClass;
    57         -jclass JniConstants::parsePositionClass;
    58         -jclass JniConstants::patternSyntaxExceptionClass;
    59         -jclass JniConstants::realToStringClass;
    60         -jclass JniConstants::referenceClass;
    61         -jclass JniConstants::shortClass;
    62         -jclass JniConstants::socketClass;
    63         -jclass JniConstants::socketImplClass;
    64         -jclass JniConstants::stringClass;
    65         -jclass JniConstants::structAddrinfoClass;
    66         -jclass JniConstants::structFlockClass;
    67         -jclass JniConstants::structGroupReqClass;
    68         -jclass JniConstants::structLingerClass;
    69         -jclass JniConstants::structPasswdClass;
    70         -jclass JniConstants::structPollfdClass;
    71         -jclass JniConstants::structStatClass;
    72         -jclass JniConstants::structStatVfsClass;
    73         -jclass JniConstants::structTimevalClass;
    74         -jclass JniConstants::structUcredClass;
    75         -jclass JniConstants::structUtsnameClass;
    76         -
    77         -static jclass findClass(JNIEnv* env, const char* name) {
    78         -    ScopedLocalRef<jclass> localClass(env, env->FindClass(name));
    79         -    jclass result = reinterpret_cast<jclass>(env->NewGlobalRef(localClass.get()));
    80         -    if (result == NULL) {
    81         -        ALOGE("failed to find class '%s'", name);
    82         -        abort();
    83         -    }
    84         -    return result;
    85         -}
    86         -
    87         -void JniConstants::init(JNIEnv* env) {
    88         -    bidiRunClass = findClass(env, "java/text/Bidi$Run");
    89         -    bigDecimalClass = findClass(env, "java/math/BigDecimal");
    90         -    booleanClass = findClass(env, "java/lang/Boolean");
    91         -    byteClass = findClass(env, "java/lang/Byte");
    92         -    byteArrayClass = findClass(env, "[B");
    93         -    calendarClass = findClass(env, "java/util/Calendar");
    94         -    characterClass = findClass(env, "java/lang/Character");
    95         -    charsetICUClass = findClass(env, "java/nio/charset/CharsetICU");
    96         -    constructorClass = findClass(env, "java/lang/reflect/Constructor");
    97         -    floatClass = findClass(env, "java/lang/Float");
    98         -    deflaterClass = findClass(env, "java/util/zip/Deflater");
    99         -    doubleClass = findClass(env, "java/lang/Double");
   100         -    errnoExceptionClass = findClass(env, "libcore/io/ErrnoException");
   101         -    fieldClass = findClass(env, "java/lang/reflect/Field");
   102         -    fieldPositionIteratorClass = findClass(env, "libcore/icu/NativeDecimalFormat$FieldPositionIterator");
   103         -    fileDescriptorClass = findClass(env, "java/io/FileDescriptor");
   104         -    gaiExceptionClass = findClass(env, "libcore/io/GaiException");
   105         -    inet6AddressClass = findClass(env, "java/net/Inet6Address");
   106         -    inetAddressClass = findClass(env, "java/net/InetAddress");
   107         -    inetSocketAddressClass = findClass(env, "java/net/InetSocketAddress");
   108         -    inetUnixAddressClass = findClass(env, "java/net/InetUnixAddress");
   109         -    inflaterClass = findClass(env, "java/util/zip/Inflater");
   110         -    inputStreamClass = findClass(env, "java/io/InputStream");
   111         -    integerClass = findClass(env, "java/lang/Integer");
   112         -    localeDataClass = findClass(env, "libcore/icu/LocaleData");
   113         -    longClass = findClass(env, "java/lang/Long");
   114         -    methodClass = findClass(env, "java/lang/reflect/Method");
   115         -    mutableIntClass = findClass(env, "libcore/util/MutableInt");
   116         -    mutableLongClass = findClass(env, "libcore/util/MutableLong");
   117         -    objectClass = findClass(env, "java/lang/Object");
   118         -    objectArrayClass = findClass(env, "[Ljava/lang/Object;");
   119         -    outputStreamClass = findClass(env, "java/io/OutputStream");
   120         -    parsePositionClass = findClass(env, "java/text/ParsePosition");
   121         -    patternSyntaxExceptionClass = findClass(env, "java/util/regex/PatternSyntaxException");
   122         -    realToStringClass = findClass(env, "java/lang/RealToString");
   123         -    referenceClass = findClass(env, "java/lang/ref/Reference");
   124         -    shortClass = findClass(env, "java/lang/Short");
   125         -    socketClass = findClass(env, "java/net/Socket");
   126         -    socketImplClass = findClass(env, "java/net/SocketImpl");
   127         -    stringClass = findClass(env, "java/lang/String");
   128         -    structAddrinfoClass = findClass(env, "libcore/io/StructAddrinfo");
   129         -    structFlockClass = findClass(env, "libcore/io/StructFlock");
   130         -    structGroupReqClass = findClass(env, "libcore/io/StructGroupReq");
   131         -    structLingerClass = findClass(env, "libcore/io/StructLinger");
   132         -    structPasswdClass = findClass(env, "libcore/io/StructPasswd");
   133         -    structPollfdClass = findClass(env, "libcore/io/StructPollfd");
   134         -    structStatClass = findClass(env, "libcore/io/StructStat");
   135         -    structStatVfsClass = findClass(env, "libcore/io/StructStatVfs");
   136         -    structTimevalClass = findClass(env, "libcore/io/StructTimeval");
   137         -    structUcredClass = findClass(env, "libcore/io/StructUcred");
   138         -    structUtsnameClass = findClass(env, "libcore/io/StructUtsname");
   139         -}

Deleted jni/sqlite/README.

     1         -
     2         -All the files in this directory are copied from stock android. The following
     3         -files:
     4         -
     5         -JniConstants.cpp
     6         -JNIHelp.cpp
     7         -ALog-priv.h
     8         -
     9         -are copied in from Android's libnativehelper module (altogether less than 1000
    10         -lines of code). The remainder are from the core framework (directory
    11         -/frameworks/base/core/jni).
    12         -
    13         -Notes on changes:
    14         -
    15         -The ashmem_XXX() interfaces are used for the various "xxxForBlobDescriptor()"
    16         -API functions. The code in libcutils for this seems to be platform
    17         -dependent - some platforms have kernel support, others have a user space
    18         -implementation. So these functions are not supported for now.
    19         -
    20         -The original SQLiteConnection.cpp uses AndroidRuntime::genJNIEnv() to obtain a
    21         -pointer to the current threads environment. Changed to store a pointer to the
    22         -process JavaVM (Android allows only one) as a global variable. Then retrieve
    23         -the JNIEnv as needed using GetEnv().
    24         -
    25         -Replaced uses of class String8 with std::string in SQLiteConnection.cpp and a
    26         -few other places.
    27         -
    28         -The stock Android code to populate CursorWindow containers with the results of
    29         -a SELECT statement uses a C++ interface that is not available to NDK builds. So
    30         -this code is rewritten to call the CursorWindow java interface via JNI methods.
    31         -This is the largest source code change. See function 
    32         -nativeExecuteForCursorWindow() in file android_database_SQLiteConnection.cpp
    33         -for details.
    34         -
    35         -The "LOCALIZED" collation and some miscellaneous user-functions added by the
    36         -sqlite3_android.cpp module are not included. A collation called LOCALIZED
    37         -that is equivalent to BINARY is added instead to keep various things working.
    38         -This should not cause serious problems - class SQLiteConnection always
    39         -runs "REINDEX LOCALIZED" immediately after opening a connection.
    40         -

Deleted jni/sqlite/android_database_SQLiteCommon.cpp.

     1         -/*
     2         - * Copyright (C) 2011 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#include "android_database_SQLiteCommon.h"
    22         -
    23         -namespace android {
    24         -
    25         -/* throw a SQLiteException with a message appropriate for the error in handle */
    26         -void throw_sqlite3_exception(JNIEnv* env, sqlite3* handle) {
    27         -    throw_sqlite3_exception(env, handle, NULL);
    28         -}
    29         -
    30         -/* throw a SQLiteException with the given message */
    31         -void throw_sqlite3_exception(JNIEnv* env, const char* message) {
    32         -    throw_sqlite3_exception(env, NULL, message);
    33         -}
    34         -
    35         -/* throw a SQLiteException with a message appropriate for the error in handle
    36         -   concatenated with the given message
    37         - */
    38         -void throw_sqlite3_exception(JNIEnv* env, sqlite3* handle, const char* message) {
    39         -    if (handle) {
    40         -        // get the error code and message from the SQLite connection
    41         -        // the error message may contain more information than the error code
    42         -        // because it is based on the extended error code rather than the simplified
    43         -        // error code that SQLite normally returns.
    44         -        throw_sqlite3_exception(env, sqlite3_extended_errcode(handle),
    45         -                sqlite3_errmsg(handle), message);
    46         -    } else {
    47         -        // we use SQLITE_OK so that a generic SQLiteException is thrown;
    48         -        // any code not specified in the switch statement below would do.
    49         -        throw_sqlite3_exception(env, SQLITE_OK, "unknown error", message);
    50         -    }
    51         -}
    52         -
    53         -/* throw a SQLiteException for a given error code
    54         - * should only be used when the database connection is not available because the
    55         - * error information will not be quite as rich */
    56         -void throw_sqlite3_exception_errcode(JNIEnv* env, int errcode, const char* message) {
    57         -    throw_sqlite3_exception(env, errcode, "unknown error", message);
    58         -}
    59         -
    60         -/* throw a SQLiteException for a given error code, sqlite3message, and
    61         -   user message
    62         - */
    63         -void throw_sqlite3_exception(JNIEnv* env, int errcode,
    64         -                             const char* sqlite3Message, const char* message) {
    65         -    const char* exceptionClass;
    66         -    switch (errcode & 0xff) { /* mask off extended error code */
    67         -        case SQLITE_IOERR:
    68         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteDiskIOException";
    69         -            break;
    70         -        case SQLITE_CORRUPT:
    71         -        case SQLITE_NOTADB: // treat "unsupported file format" error as corruption also
    72         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteDatabaseCorruptException";
    73         -            break;
    74         -        case SQLITE_CONSTRAINT:
    75         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteConstraintException";
    76         -            break;
    77         -        case SQLITE_ABORT:
    78         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteAbortException";
    79         -            break;
    80         -        case SQLITE_DONE:
    81         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteDoneException";
    82         -            sqlite3Message = NULL; // SQLite error message is irrelevant in this case
    83         -            break;
    84         -        case SQLITE_FULL:
    85         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteFullException";
    86         -            break;
    87         -        case SQLITE_MISUSE:
    88         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteMisuseException";
    89         -            break;
    90         -        case SQLITE_PERM:
    91         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteAccessPermException";
    92         -            break;
    93         -        case SQLITE_BUSY:
    94         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteDatabaseLockedException";
    95         -            break;
    96         -        case SQLITE_LOCKED:
    97         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteTableLockedException";
    98         -            break;
    99         -        case SQLITE_READONLY:
   100         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteReadOnlyDatabaseException";
   101         -            break;
   102         -        case SQLITE_CANTOPEN:
   103         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteCantOpenDatabaseException";
   104         -            break;
   105         -        case SQLITE_TOOBIG:
   106         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteBlobTooBigException";
   107         -            break;
   108         -        case SQLITE_RANGE:
   109         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteBindOrColumnIndexOutOfRangeException";
   110         -            break;
   111         -        case SQLITE_NOMEM:
   112         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteOutOfMemoryException";
   113         -            break;
   114         -        case SQLITE_MISMATCH:
   115         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteDatatypeMismatchException";
   116         -            break;
   117         -        case SQLITE_INTERRUPT:
   118         -            exceptionClass = "android/os/OperationCanceledException";
   119         -            break;
   120         -        default:
   121         -            exceptionClass = "org/sqlite/database/sqlite/SQLiteException";
   122         -            break;
   123         -    }
   124         -
   125         -    if (sqlite3Message) {
   126         -        char *zFullmsg = sqlite3_mprintf(
   127         -            "%s (code %d)%s%s", sqlite3Message, errcode, 
   128         -            (message ? ": " : ""), (message ? message : "")
   129         -        );
   130         -        jniThrowException(env, exceptionClass, zFullmsg);
   131         -        sqlite3_free(zFullmsg);
   132         -    } else {
   133         -        jniThrowException(env, exceptionClass, message);
   134         -    }
   135         -}
   136         -
   137         -
   138         -} // namespace android

Deleted jni/sqlite/android_database_SQLiteCommon.h.

     1         -/*
     2         - * Copyright (C) 2007 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#ifndef _ANDROID_DATABASE_SQLITE_COMMON_H
    22         -#define _ANDROID_DATABASE_SQLITE_COMMON_H
    23         -
    24         -#include <jni.h>
    25         -#include <JNIHelp.h>
    26         -
    27         -#include <sqlite3.h>
    28         -
    29         -// Special log tags defined in SQLiteDebug.java.
    30         -#define SQLITE_LOG_TAG "SQLiteLog"
    31         -#define SQLITE_TRACE_TAG "SQLiteStatements"
    32         -#define SQLITE_PROFILE_TAG "SQLiteTime"
    33         -
    34         -namespace android {
    35         -
    36         -/* throw a SQLiteException with a message appropriate for the error in handle */
    37         -void throw_sqlite3_exception(JNIEnv* env, sqlite3* handle);
    38         -
    39         -/* throw a SQLiteException with the given message */
    40         -void throw_sqlite3_exception(JNIEnv* env, const char* message);
    41         -
    42         -/* throw a SQLiteException with a message appropriate for the error in handle
    43         -   concatenated with the given message
    44         - */
    45         -void throw_sqlite3_exception(JNIEnv* env, sqlite3* handle, const char* message);
    46         -
    47         -/* throw a SQLiteException for a given error code */
    48         -void throw_sqlite3_exception_errcode(JNIEnv* env, int errcode, const char* message);
    49         -
    50         -void throw_sqlite3_exception(JNIEnv* env, int errcode,
    51         -        const char* sqlite3Message, const char* message);
    52         -
    53         -}
    54         -
    55         -#endif // _ANDROID_DATABASE_SQLITE_COMMON_H

Deleted jni/sqlite/android_database_SQLiteConnection.cpp.

     1         -/*
     2         - * Copyright (C) 2011 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#define LOG_TAG "SQLiteConnection"
    22         -
    23         -#include <jni.h>
    24         -#include <JNIHelp.h>
    25         -#include "ALog-priv.h"
    26         -
    27         -
    28         -#include <sys/mman.h>
    29         -#include <string.h>
    30         -#include <unistd.h>
    31         -#include <assert.h>
    32         -
    33         -#if 0
    34         -#include <androidfw/CursorWindow.h>
    35         -#endif
    36         -
    37         -#include <sqlite3.h>
    38         -#if 0
    39         -#include <sqlite3_android.h>
    40         -#endif
    41         -
    42         -#include "android_database_SQLiteCommon.h"
    43         -
    44         -#include <string>
    45         -
    46         -// Set to 1 to use UTF16 storage for localized indexes.
    47         -#define UTF16_STORAGE 0
    48         -
    49         -namespace android {
    50         -
    51         -/* Busy timeout in milliseconds.
    52         - * If another connection (possibly in another process) has the database locked for
    53         - * longer than this amount of time then SQLite will generate a SQLITE_BUSY error.
    54         - * The SQLITE_BUSY error is then raised as a SQLiteDatabaseLockedException.
    55         - *
    56         - * In ordinary usage, busy timeouts are quite rare.  Most databases only ever
    57         - * have a single open connection at a time unless they are using WAL.  When using
    58         - * WAL, a timeout could occur if one connection is busy performing an auto-checkpoint
    59         - * operation.  The busy timeout needs to be long enough to tolerate slow I/O write
    60         - * operations but not so long as to cause the application to hang indefinitely if
    61         - * there is a problem acquiring a database lock.
    62         - */
    63         -static const int BUSY_TIMEOUT_MS = 2500;
    64         -
    65         -static JavaVM *gpJavaVM = 0;
    66         -
    67         -static struct {
    68         -    jfieldID name;
    69         -    jfieldID numArgs;
    70         -    jmethodID dispatchCallback;
    71         -} gSQLiteCustomFunctionClassInfo;
    72         -
    73         -static struct {
    74         -    jclass clazz;
    75         -} gStringClassInfo;
    76         -
    77         -struct SQLiteConnection {
    78         -    // Open flags.
    79         -    // Must be kept in sync with the constants defined in SQLiteDatabase.java.
    80         -    enum {
    81         -        OPEN_READWRITE          = 0x00000000,
    82         -        OPEN_READONLY           = 0x00000001,
    83         -        OPEN_READ_MASK          = 0x00000001,
    84         -        NO_LOCALIZED_COLLATORS  = 0x00000010,
    85         -        CREATE_IF_NECESSARY     = 0x10000000,
    86         -    };
    87         -
    88         -    sqlite3* const db;
    89         -    const int openFlags;
    90         -    std::string path;
    91         -    std::string label;
    92         -
    93         -    volatile bool canceled;
    94         -
    95         -    SQLiteConnection(sqlite3* db, int openFlags, const std::string& path, const std::string& label) :
    96         -        db(db), openFlags(openFlags), path(path), label(label), canceled(false) { }
    97         -};
    98         -
    99         -// Called each time a statement begins execution, when tracing is enabled.
   100         -static void sqliteTraceCallback(void *data, const char *sql) {
   101         -    SQLiteConnection* connection = static_cast<SQLiteConnection*>(data);
   102         -    ALOG(LOG_VERBOSE, SQLITE_TRACE_TAG, "%s: \"%s\"\n",
   103         -            connection->label.c_str(), sql);
   104         -}
   105         -
   106         -// Called each time a statement finishes execution, when profiling is enabled.
   107         -static void sqliteProfileCallback(void *data, const char *sql, sqlite3_uint64 tm) {
   108         -    SQLiteConnection* connection = static_cast<SQLiteConnection*>(data);
   109         -    ALOG(LOG_VERBOSE, SQLITE_PROFILE_TAG, "%s: \"%s\" took %0.3f ms\n",
   110         -            connection->label.c_str(), sql, tm * 0.000001f);
   111         -}
   112         -
   113         -// Called after each SQLite VM instruction when cancelation is enabled.
   114         -static int sqliteProgressHandlerCallback(void* data) {
   115         -    SQLiteConnection* connection = static_cast<SQLiteConnection*>(data);
   116         -    return connection->canceled;
   117         -}
   118         -
   119         -/*
   120         -** This function is a collation sequence callback equivalent to the built-in
   121         -** BINARY sequence. 
   122         -**
   123         -** Stock Android uses a modified version of sqlite3.c that calls out to a module
   124         -** named "sqlite3_android" to add extra built-in collations and functions to
   125         -** all database handles. Specifically, collation sequence "LOCALIZED". For now,
   126         -** this module does not include sqlite3_android (since it is difficult to build
   127         -** with the NDK only). Instead, this function is registered as "LOCALIZED" for all
   128         -** new database handles. 
   129         -*/
   130         -static int coll_localized(
   131         -  void *not_used,
   132         -  int nKey1, const void *pKey1,
   133         -  int nKey2, const void *pKey2
   134         -){
   135         -  int rc, n;
   136         -  n = nKey1<nKey2 ? nKey1 : nKey2;
   137         -  rc = memcmp(pKey1, pKey2, n);
   138         -  if( rc==0 ){
   139         -    rc = nKey1 - nKey2;
   140         -  }
   141         -  return rc;
   142         -}
   143         -
   144         -static jlong nativeOpen(JNIEnv* env, jclass clazz, jstring pathStr, jint openFlags,
   145         -        jstring labelStr, jboolean enableTrace, jboolean enableProfile) {
   146         -    int sqliteFlags;
   147         -    if (openFlags & SQLiteConnection::CREATE_IF_NECESSARY) {
   148         -        sqliteFlags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
   149         -    } else if (openFlags & SQLiteConnection::OPEN_READONLY) {
   150         -        sqliteFlags = SQLITE_OPEN_READONLY;
   151         -    } else {
   152         -        sqliteFlags = SQLITE_OPEN_READWRITE;
   153         -    }
   154         -
   155         -    const char* pathChars = env->GetStringUTFChars(pathStr, NULL);
   156         -    std::string path(pathChars);
   157         -    env->ReleaseStringUTFChars(pathStr, pathChars);
   158         -
   159         -    const char* labelChars = env->GetStringUTFChars(labelStr, NULL);
   160         -    std::string label(labelChars);
   161         -    env->ReleaseStringUTFChars(labelStr, labelChars);
   162         -
   163         -    sqlite3* db;
   164         -    int err = sqlite3_open_v2(path.c_str(), &db, sqliteFlags, NULL);
   165         -    if (err != SQLITE_OK) {
   166         -        throw_sqlite3_exception_errcode(env, err, "Could not open database");
   167         -        return 0;
   168         -    }
   169         -    err = sqlite3_create_collation(db, "localized", SQLITE_UTF8, 0, coll_localized);
   170         -    if (err != SQLITE_OK) {
   171         -        throw_sqlite3_exception_errcode(env, err, "Could not register collation");
   172         -        sqlite3_close(db);
   173         -        return 0;
   174         -    }
   175         -
   176         -    // Check that the database is really read/write when that is what we asked for.
   177         -    if ((sqliteFlags & SQLITE_OPEN_READWRITE) && sqlite3_db_readonly(db, NULL)) {
   178         -        throw_sqlite3_exception(env, db, "Could not open the database in read/write mode.");
   179         -        sqlite3_close(db);
   180         -        return 0;
   181         -    }
   182         -
   183         -    // Set the default busy handler to retry automatically before returning SQLITE_BUSY.
   184         -    err = sqlite3_busy_timeout(db, BUSY_TIMEOUT_MS);
   185         -    if (err != SQLITE_OK) {
   186         -        throw_sqlite3_exception(env, db, "Could not set busy timeout");
   187         -        sqlite3_close(db);
   188         -        return 0;
   189         -    }
   190         -
   191         -    // Register custom Android functions.
   192         -#if 0
   193         -    err = register_android_functions(db, UTF16_STORAGE);
   194         -    if (err) {
   195         -        throw_sqlite3_exception(env, db, "Could not register Android SQL functions.");
   196         -        sqlite3_close(db);
   197         -        return 0;
   198         -    }
   199         -#endif
   200         -
   201         -    // Create wrapper object.
   202         -    SQLiteConnection* connection = new SQLiteConnection(db, openFlags, path, label);
   203         -
   204         -    // Enable tracing and profiling if requested.
   205         -    if (enableTrace) {
   206         -        sqlite3_trace(db, &sqliteTraceCallback, connection);
   207         -    }
   208         -    if (enableProfile) {
   209         -        sqlite3_profile(db, &sqliteProfileCallback, connection);
   210         -    }
   211         -
   212         -    ALOGV("Opened connection %p with label '%s'", db, label.c_str());
   213         -    return reinterpret_cast<jlong>(connection);
   214         -}
   215         -
   216         -static void nativeClose(JNIEnv* env, jclass clazz, jlong connectionPtr) {
   217         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   218         -
   219         -    if (connection) {
   220         -        ALOGV("Closing connection %p", connection->db);
   221         -        int err = sqlite3_close(connection->db);
   222         -        if (err != SQLITE_OK) {
   223         -            // This can happen if sub-objects aren't closed first.  Make sure the caller knows.
   224         -            ALOGE("sqlite3_close(%p) failed: %d", connection->db, err);
   225         -            throw_sqlite3_exception(env, connection->db, "Count not close db.");
   226         -            return;
   227         -        }
   228         -
   229         -        delete connection;
   230         -    }
   231         -}
   232         -
   233         -// Called each time a custom function is evaluated.
   234         -static void sqliteCustomFunctionCallback(sqlite3_context *context,
   235         -        int argc, sqlite3_value **argv) {
   236         -
   237         -    JNIEnv* env = 0;
   238         -    gpJavaVM->GetEnv((void**)&env, JNI_VERSION_1_4);
   239         -
   240         -    // Get the callback function object.
   241         -    // Create a new local reference to it in case the callback tries to do something
   242         -    // dumb like unregister the function (thereby destroying the global ref) while it is running.
   243         -    jobject functionObjGlobal = reinterpret_cast<jobject>(sqlite3_user_data(context));
   244         -    jobject functionObj = env->NewLocalRef(functionObjGlobal);
   245         -
   246         -    jobjectArray argsArray = env->NewObjectArray(argc, gStringClassInfo.clazz, NULL);
   247         -    if (argsArray) {
   248         -        for (int i = 0; i < argc; i++) {
   249         -            const jchar* arg = static_cast<const jchar*>(sqlite3_value_text16(argv[i]));
   250         -            if (!arg) {
   251         -                ALOGW("NULL argument in custom_function_callback.  This should not happen.");
   252         -            } else {
   253         -                size_t argLen = sqlite3_value_bytes16(argv[i]) / sizeof(jchar);
   254         -                jstring argStr = env->NewString(arg, argLen);
   255         -                if (!argStr) {
   256         -                    goto error; // out of memory error
   257         -                }
   258         -                env->SetObjectArrayElement(argsArray, i, argStr);
   259         -                env->DeleteLocalRef(argStr);
   260         -            }
   261         -        }
   262         -
   263         -        // TODO: Support functions that return values.
   264         -        env->CallVoidMethod(functionObj,
   265         -                gSQLiteCustomFunctionClassInfo.dispatchCallback, argsArray);
   266         -
   267         -error:
   268         -        env->DeleteLocalRef(argsArray);
   269         -    }
   270         -
   271         -    env->DeleteLocalRef(functionObj);
   272         -
   273         -    if (env->ExceptionCheck()) {
   274         -        ALOGE("An exception was thrown by custom SQLite function.");
   275         -        /* LOGE_EX(env); */
   276         -        env->ExceptionClear();
   277         -    }
   278         -}
   279         -
   280         -// Called when a custom function is destroyed.
   281         -static void sqliteCustomFunctionDestructor(void* data) {
   282         -    jobject functionObjGlobal = reinterpret_cast<jobject>(data);
   283         -    JNIEnv* env = 0;
   284         -    gpJavaVM->GetEnv((void**)&env, JNI_VERSION_1_4);
   285         -    env->DeleteGlobalRef(functionObjGlobal);
   286         -}
   287         -
   288         -static void nativeRegisterCustomFunction(JNIEnv* env, jclass clazz, jlong connectionPtr,
   289         -        jobject functionObj) {
   290         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   291         -
   292         -    jstring nameStr = jstring(env->GetObjectField(
   293         -            functionObj, gSQLiteCustomFunctionClassInfo.name));
   294         -    jint numArgs = env->GetIntField(functionObj, gSQLiteCustomFunctionClassInfo.numArgs);
   295         -
   296         -    jobject functionObjGlobal = env->NewGlobalRef(functionObj);
   297         -
   298         -    const char* name = env->GetStringUTFChars(nameStr, NULL);
   299         -    int err = sqlite3_create_function_v2(connection->db, name, numArgs, SQLITE_UTF16,
   300         -            reinterpret_cast<void*>(functionObjGlobal),
   301         -            &sqliteCustomFunctionCallback, NULL, NULL, &sqliteCustomFunctionDestructor);
   302         -    env->ReleaseStringUTFChars(nameStr, name);
   303         -
   304         -    if (err != SQLITE_OK) {
   305         -        ALOGE("sqlite3_create_function returned %d", err);
   306         -        env->DeleteGlobalRef(functionObjGlobal);
   307         -        throw_sqlite3_exception(env, connection->db);
   308         -        return;
   309         -    }
   310         -}
   311         -
   312         -static void nativeRegisterLocalizedCollators(JNIEnv* env, jclass clazz, jlong connectionPtr,
   313         -        jstring localeStr) {
   314         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   315         -
   316         -    const char* locale = env->GetStringUTFChars(localeStr, NULL);
   317         -#if 0
   318         -    int err = register_localized_collators(connection->db, locale, UTF16_STORAGE);
   319         -    env->ReleaseStringUTFChars(localeStr, locale);
   320         -
   321         -    if (err != SQLITE_OK) {
   322         -        throw_sqlite3_exception(env, connection->db);
   323         -    }
   324         -#endif
   325         -}
   326         -
   327         -static jlong nativePrepareStatement(JNIEnv* env, jclass clazz, jlong connectionPtr,
   328         -        jstring sqlString) {
   329         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   330         -
   331         -    jsize sqlLength = env->GetStringLength(sqlString);
   332         -    const jchar* sql = env->GetStringCritical(sqlString, NULL);
   333         -    sqlite3_stmt* statement;
   334         -    int err = sqlite3_prepare16_v2(connection->db,
   335         -            sql, sqlLength * sizeof(jchar), &statement, NULL);
   336         -    env->ReleaseStringCritical(sqlString, sql);
   337         -
   338         -    if (err != SQLITE_OK) {
   339         -        // Error messages like 'near ")": syntax error' are not
   340         -        // always helpful enough, so construct an error string that
   341         -        // includes the query itself.
   342         -        const char *query = env->GetStringUTFChars(sqlString, NULL);
   343         -        char *message = (char*) malloc(strlen(query) + 50);
   344         -        if (message) {
   345         -            strcpy(message, ", while compiling: "); // less than 50 chars
   346         -            strcat(message, query);
   347         -        }
   348         -        env->ReleaseStringUTFChars(sqlString, query);
   349         -        throw_sqlite3_exception(env, connection->db, message);
   350         -        free(message);
   351         -        return 0;
   352         -    }
   353         -
   354         -    ALOGV("Prepared statement %p on connection %p", statement, connection->db);
   355         -    return reinterpret_cast<jlong>(statement);
   356         -}
   357         -
   358         -static void nativeFinalizeStatement(JNIEnv* env, jclass clazz, jlong connectionPtr,
   359         -        jlong statementPtr) {
   360         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   361         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   362         -
   363         -    // We ignore the result of sqlite3_finalize because it is really telling us about
   364         -    // whether any errors occurred while executing the statement.  The statement itself
   365         -    // is always finalized regardless.
   366         -    ALOGV("Finalized statement %p on connection %p", statement, connection->db);
   367         -    sqlite3_finalize(statement);
   368         -}
   369         -
   370         -static jint nativeGetParameterCount(JNIEnv* env, jclass clazz, jlong connectionPtr,
   371         -        jlong statementPtr) {
   372         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   373         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   374         -
   375         -    return sqlite3_bind_parameter_count(statement);
   376         -}
   377         -
   378         -static jboolean nativeIsReadOnly(JNIEnv* env, jclass clazz, jlong connectionPtr,
   379         -        jlong statementPtr) {
   380         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   381         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   382         -
   383         -    return sqlite3_stmt_readonly(statement) != 0;
   384         -}
   385         -
   386         -static jint nativeGetColumnCount(JNIEnv* env, jclass clazz, jlong connectionPtr,
   387         -        jlong statementPtr) {
   388         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   389         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   390         -
   391         -    return sqlite3_column_count(statement);
   392         -}
   393         -
   394         -static jstring nativeGetColumnName(JNIEnv* env, jclass clazz, jlong connectionPtr,
   395         -        jlong statementPtr, jint index) {
   396         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   397         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   398         -
   399         -    const jchar* name = static_cast<const jchar*>(sqlite3_column_name16(statement, index));
   400         -    if (name) {
   401         -        size_t length = 0;
   402         -        while (name[length]) {
   403         -            length += 1;
   404         -        }
   405         -        return env->NewString(name, length);
   406         -    }
   407         -    return NULL;
   408         -}
   409         -
   410         -static void nativeBindNull(JNIEnv* env, jclass clazz, jlong connectionPtr,
   411         -        jlong statementPtr, jint index) {
   412         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   413         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   414         -
   415         -    int err = sqlite3_bind_null(statement, index);
   416         -    if (err != SQLITE_OK) {
   417         -        throw_sqlite3_exception(env, connection->db, NULL);
   418         -    }
   419         -}
   420         -
   421         -static void nativeBindLong(JNIEnv* env, jclass clazz, jlong connectionPtr,
   422         -        jlong statementPtr, jint index, jlong value) {
   423         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   424         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   425         -
   426         -    int err = sqlite3_bind_int64(statement, index, value);
   427         -    if (err != SQLITE_OK) {
   428         -        throw_sqlite3_exception(env, connection->db, NULL);
   429         -    }
   430         -}
   431         -
   432         -static void nativeBindDouble(JNIEnv* env, jclass clazz, jlong connectionPtr,
   433         -        jlong statementPtr, jint index, jdouble value) {
   434         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   435         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   436         -
   437         -    int err = sqlite3_bind_double(statement, index, value);
   438         -    if (err != SQLITE_OK) {
   439         -        throw_sqlite3_exception(env, connection->db, NULL);
   440         -    }
   441         -}
   442         -
   443         -static void nativeBindString(JNIEnv* env, jclass clazz, jlong connectionPtr,
   444         -        jlong statementPtr, jint index, jstring valueString) {
   445         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   446         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   447         -
   448         -    jsize valueLength = env->GetStringLength(valueString);
   449         -    const jchar* value = env->GetStringCritical(valueString, NULL);
   450         -    int err = sqlite3_bind_text16(statement, index, value, valueLength * sizeof(jchar),
   451         -            SQLITE_TRANSIENT);
   452         -    env->ReleaseStringCritical(valueString, value);
   453         -    if (err != SQLITE_OK) {
   454         -        throw_sqlite3_exception(env, connection->db, NULL);
   455         -    }
   456         -}
   457         -
   458         -static void nativeBindBlob(JNIEnv* env, jclass clazz, jlong connectionPtr,
   459         -        jlong statementPtr, jint index, jbyteArray valueArray) {
   460         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   461         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   462         -
   463         -    jsize valueLength = env->GetArrayLength(valueArray);
   464         -    jbyte* value = static_cast<jbyte*>(env->GetPrimitiveArrayCritical(valueArray, NULL));
   465         -    int err = sqlite3_bind_blob(statement, index, value, valueLength, SQLITE_TRANSIENT);
   466         -    env->ReleasePrimitiveArrayCritical(valueArray, value, JNI_ABORT);
   467         -    if (err != SQLITE_OK) {
   468         -        throw_sqlite3_exception(env, connection->db, NULL);
   469         -    }
   470         -}
   471         -
   472         -static void nativeResetStatementAndClearBindings(JNIEnv* env, jclass clazz, jlong connectionPtr,
   473         -        jlong statementPtr) {
   474         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   475         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   476         -
   477         -    int err = sqlite3_reset(statement);
   478         -    if (err == SQLITE_OK) {
   479         -        err = sqlite3_clear_bindings(statement);
   480         -    }
   481         -    if (err != SQLITE_OK) {
   482         -        throw_sqlite3_exception(env, connection->db, NULL);
   483         -    }
   484         -}
   485         -
   486         -static int executeNonQuery(JNIEnv* env, SQLiteConnection* connection, sqlite3_stmt* statement) {
   487         -    int err = sqlite3_step(statement);
   488         -    if (err == SQLITE_ROW) {
   489         -        throw_sqlite3_exception(env,
   490         -                "Queries can be performed using SQLiteDatabase query or rawQuery methods only.");
   491         -    } else if (err != SQLITE_DONE) {
   492         -        throw_sqlite3_exception(env, connection->db);
   493         -    }
   494         -    return err;
   495         -}
   496         -
   497         -static void nativeExecute(JNIEnv* env, jclass clazz, jlong connectionPtr,
   498         -        jlong statementPtr) {
   499         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   500         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   501         -
   502         -    executeNonQuery(env, connection, statement);
   503         -}
   504         -
   505         -static jint nativeExecuteForChangedRowCount(JNIEnv* env, jclass clazz,
   506         -        jlong connectionPtr, jlong statementPtr) {
   507         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   508         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   509         -
   510         -    int err = executeNonQuery(env, connection, statement);
   511         -    return err == SQLITE_DONE ? sqlite3_changes(connection->db) : -1;
   512         -}
   513         -
   514         -static jlong nativeExecuteForLastInsertedRowId(JNIEnv* env, jclass clazz,
   515         -        jlong connectionPtr, jlong statementPtr) {
   516         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   517         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   518         -
   519         -    int err = executeNonQuery(env, connection, statement);
   520         -    return err == SQLITE_DONE && sqlite3_changes(connection->db) > 0
   521         -            ? sqlite3_last_insert_rowid(connection->db) : -1;
   522         -}
   523         -
   524         -static int executeOneRowQuery(JNIEnv* env, SQLiteConnection* connection, sqlite3_stmt* statement) {
   525         -    int err = sqlite3_step(statement);
   526         -    if (err != SQLITE_ROW) {
   527         -        throw_sqlite3_exception(env, connection->db);
   528         -    }
   529         -    return err;
   530         -}
   531         -
   532         -static jlong nativeExecuteForLong(JNIEnv* env, jclass clazz,
   533         -        jlong connectionPtr, jlong statementPtr) {
   534         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   535         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   536         -
   537         -    int err = executeOneRowQuery(env, connection, statement);
   538         -    if (err == SQLITE_ROW && sqlite3_column_count(statement) >= 1) {
   539         -        return sqlite3_column_int64(statement, 0);
   540         -    }
   541         -    return -1;
   542         -}
   543         -
   544         -static jstring nativeExecuteForString(JNIEnv* env, jclass clazz,
   545         -        jlong connectionPtr, jlong statementPtr) {
   546         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   547         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   548         -
   549         -    int err = executeOneRowQuery(env, connection, statement);
   550         -    if (err == SQLITE_ROW && sqlite3_column_count(statement) >= 1) {
   551         -        const jchar* text = static_cast<const jchar*>(sqlite3_column_text16(statement, 0));
   552         -        if (text) {
   553         -            size_t length = sqlite3_column_bytes16(statement, 0) / sizeof(jchar);
   554         -            return env->NewString(text, length);
   555         -        }
   556         -    }
   557         -    return NULL;
   558         -}
   559         -
   560         -static int createAshmemRegionWithData(JNIEnv* env, const void* data, size_t length) {
   561         -#if 0
   562         -    int error = 0;
   563         -    int fd = ashmem_create_region(NULL, length);
   564         -    if (fd < 0) {
   565         -        error = errno;
   566         -        ALOGE("ashmem_create_region failed: %s", strerror(error));
   567         -    } else {
   568         -        if (length > 0) {
   569         -            void* ptr = mmap(NULL, length, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
   570         -            if (ptr == MAP_FAILED) {
   571         -                error = errno;
   572         -                ALOGE("mmap failed: %s", strerror(error));
   573         -            } else {
   574         -                memcpy(ptr, data, length);
   575         -                munmap(ptr, length);
   576         -            }
   577         -        }
   578         -
   579         -        if (!error) {
   580         -            if (ashmem_set_prot_region(fd, PROT_READ) < 0) {
   581         -                error = errno;
   582         -                ALOGE("ashmem_set_prot_region failed: %s", strerror(errno));
   583         -            } else {
   584         -                return fd;
   585         -            }
   586         -        }
   587         -
   588         -        close(fd);
   589         -    }
   590         -
   591         -#endif
   592         -    jniThrowIOException(env, -1);
   593         -    return -1;
   594         -}
   595         -
   596         -static jint nativeExecuteForBlobFileDescriptor(JNIEnv* env, jclass clazz,
   597         -        jlong connectionPtr, jlong statementPtr) {
   598         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   599         -    sqlite3_stmt* statement = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   600         -
   601         -    int err = executeOneRowQuery(env, connection, statement);
   602         -    if (err == SQLITE_ROW && sqlite3_column_count(statement) >= 1) {
   603         -        const void* blob = sqlite3_column_blob(statement, 0);
   604         -        if (blob) {
   605         -            int length = sqlite3_column_bytes(statement, 0);
   606         -            if (length >= 0) {
   607         -                return createAshmemRegionWithData(env, blob, length);
   608         -            }
   609         -        }
   610         -    }
   611         -    return -1;
   612         -}
   613         -
   614         -/*
   615         -** Note: The following symbols must be in the same order as the corresponding
   616         -** elements in the aMethod[] array in function nativeExecuteForCursorWindow().
   617         -*/
   618         -enum CWMethodNames {
   619         -  CW_CLEAR         = 0,
   620         -  CW_SETNUMCOLUMNS = 1,
   621         -  CW_ALLOCROW      = 2,
   622         -  CW_FREELASTROW   = 3,
   623         -  CW_PUTNULL       = 4,
   624         -  CW_PUTLONG       = 5,
   625         -  CW_PUTDOUBLE     = 6,
   626         -  CW_PUTSTRING     = 7,
   627         -  CW_PUTBLOB       = 8
   628         -};
   629         -
   630         -/*
   631         -** An instance of this structure represents a single CursorWindow java method.
   632         -*/
   633         -struct CWMethod {
   634         -  jmethodID id;                   /* Method id */
   635         -  const char *zName;              /* Method name */
   636         -  const char *zSig;               /* Method JNI signature */
   637         -};
   638         -
   639         -/*
   640         -** Append the contents of the row that SQL statement pStmt currently points to
   641         -** to the CursorWindow object passed as the second argument. The CursorWindow
   642         -** currently contains iRow rows. Return true on success or false if an error
   643         -** occurs.
   644         -*/
   645         -static jboolean copyRowToWindow(
   646         -  JNIEnv *pEnv,
   647         -  jobject win,
   648         -  int iRow,
   649         -  sqlite3_stmt *pStmt,
   650         -  CWMethod *aMethod
   651         -){
   652         -  int nCol = sqlite3_column_count(pStmt);
   653         -  int i;
   654         -  jboolean bOk;
   655         -
   656         -  bOk = pEnv->CallBooleanMethod(win, aMethod[CW_ALLOCROW].id);
   657         -  for(i=0; bOk && i<nCol; i++){
   658         -    switch( sqlite3_column_type(pStmt, i) ){
   659         -      case SQLITE_NULL: {
   660         -        bOk = pEnv->CallBooleanMethod(win, aMethod[CW_PUTNULL].id, iRow, i);
   661         -        break;
   662         -      }
   663         -
   664         -      case SQLITE_INTEGER: {
   665         -        jlong val = sqlite3_column_int64(pStmt, i);
   666         -        bOk = pEnv->CallBooleanMethod(win, aMethod[CW_PUTLONG].id, val, iRow, i);
   667         -        break;
   668         -      }
   669         -
   670         -      case SQLITE_FLOAT: {
   671         -        jdouble val = sqlite3_column_double(pStmt, i);
   672         -        bOk = pEnv->CallBooleanMethod(win, aMethod[CW_PUTDOUBLE].id, val, iRow, i);
   673         -        break;
   674         -      }
   675         -
   676         -      case SQLITE_TEXT: {
   677         -        jchar *pStr = (jchar*)sqlite3_column_text16(pStmt, i);
   678         -        int nStr = sqlite3_column_bytes16(pStmt, i) / sizeof(jchar);
   679         -        jstring val = pEnv->NewString(pStr, nStr);
   680         -        bOk = pEnv->CallBooleanMethod(win, aMethod[CW_PUTSTRING].id, val, iRow, i);
   681         -        pEnv->DeleteLocalRef(val);
   682         -        break;
   683         -      }
   684         -
   685         -      default: {
   686         -        assert( sqlite3_column_type(pStmt, i)==SQLITE_BLOB );
   687         -        const jbyte *p = (const jbyte*)sqlite3_column_blob(pStmt, i);
   688         -        int n = sqlite3_column_bytes(pStmt, i);
   689         -        jbyteArray val = pEnv->NewByteArray(n);
   690         -        pEnv->SetByteArrayRegion(val, 0, n, p);
   691         -        bOk = pEnv->CallBooleanMethod(win, aMethod[CW_PUTBLOB].id, val, iRow, i);
   692         -        pEnv->DeleteLocalRef(val);
   693         -        break;
   694         -      }
   695         -    }
   696         -
   697         -    if( bOk==0 ){
   698         -      pEnv->CallVoidMethod(win, aMethod[CW_FREELASTROW].id);
   699         -    }
   700         -  }
   701         -
   702         -  return bOk;
   703         -}
   704         -
   705         -static jboolean setWindowNumColumns(
   706         -  JNIEnv *pEnv,
   707         -  jobject win,
   708         -  sqlite3_stmt *pStmt,
   709         -  CWMethod *aMethod
   710         -){
   711         -  int nCol;
   712         -
   713         -  pEnv->CallVoidMethod(win, aMethod[CW_CLEAR].id);
   714         -  nCol = sqlite3_column_count(pStmt);
   715         -  return pEnv->CallBooleanMethod(win, aMethod[CW_SETNUMCOLUMNS].id, (jint)nCol);
   716         -}
   717         -
   718         -/*
   719         -** This method has been rewritten for org.sqlite.database.*. The original 
   720         -** android implementation used the C++ interface to populate a CursorWindow
   721         -** object. Since the NDK does not export this interface, we invoke the Java
   722         -** interface using standard JNI methods to do the same thing.
   723         -**
   724         -** This function executes the SQLite statement object passed as the 4th 
   725         -** argument and copies one or more returned rows into the CursorWindow
   726         -** object passed as the 5th argument. The set of rows copied into the 
   727         -** CursorWindow is always contiguous.
   728         -**
   729         -** The only row that *must* be copied into the CursorWindow is row 
   730         -** iRowRequired. Ideally, all rows from iRowStart through to the end
   731         -** of the query are copied into the CursorWindow. If this is not possible
   732         -** (CursorWindow objects have a finite capacity), some compromise position
   733         -** is found (see comments embedded in the code below for details).
   734         -**
   735         -** The return value is a 64-bit integer calculated as follows:
   736         -**
   737         -**      (iStart << 32) | nRow
   738         -**
   739         -** where iStart is the index of the first row copied into the CursorWindow.
   740         -** If the countAllRows argument is true, nRow is the total number of rows
   741         -** returned by the query. Otherwise, nRow is one greater than the index of 
   742         -** the last row copied into the CursorWindow.
   743         -*/
   744         -static jlong nativeExecuteForCursorWindow(
   745         -  JNIEnv *pEnv, 
   746         -  jclass clazz,
   747         -  jlong connectionPtr,            /* Pointer to SQLiteConnection C++ object */
   748         -  jlong statementPtr,             /* Pointer to sqlite3_stmt object */
   749         -  jobject win,                    /* The CursorWindow object to populate */
   750         -  jint startPos,                  /* First row to add (advisory) */
   751         -  jint iRowRequired,              /* Required row */
   752         -  jboolean countAllRows
   753         -) {
   754         -  SQLiteConnection *pConnection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   755         -  sqlite3_stmt *pStmt = reinterpret_cast<sqlite3_stmt*>(statementPtr);
   756         -
   757         -  CWMethod aMethod[] = {
   758         -    {0, "clear",         "()V"},
   759         -    {0, "setNumColumns", "(I)Z"},
   760         -    {0, "allocRow",      "()Z"},
   761         -    {0, "freeLastRow",   "()V"},
   762         -    {0, "putNull",       "(II)Z"},
   763         -    {0, "putLong",       "(JII)Z"},
   764         -    {0, "putDouble",     "(DII)Z"},
   765         -    {0, "putString",     "(Ljava/lang/String;II)Z"},
   766         -    {0, "putBlob",       "([BII)Z"},
   767         -  };
   768         -  jclass cls;                     /* Class android.database.CursorWindow */
   769         -  int i;                          /* Iterator variable */
   770         -  int nCol;                       /* Number of columns returned by pStmt */
   771         -  int nRow;
   772         -  jboolean bOk;
   773         -  int iStart;                     /* First row copied to CursorWindow */
   774         -
   775         -  /* Locate all required CursorWindow methods. */
   776         -  cls = pEnv->FindClass("android/database/CursorWindow");
   777         -  for(i=0; i<(sizeof(aMethod)/sizeof(struct CWMethod)); i++){
   778         -    aMethod[i].id = pEnv->GetMethodID(cls, aMethod[i].zName, aMethod[i].zSig);
   779         -    if( aMethod[i].id==NULL ){
   780         -      jniThrowExceptionFmt(pEnv, "java/lang/Exception", 
   781         -          "Failed to find method CursorWindow.%s()", aMethod[i].zName
   782         -      );
   783         -      return 0;
   784         -    }
   785         -  }
   786         -
   787         -
   788         -  /* Set the number of columns in the window */
   789         -  bOk = setWindowNumColumns(pEnv, win, pStmt, aMethod);
   790         -  if( bOk==0 ) return 0;
   791         -
   792         -  nRow = 0;
   793         -  iStart = startPos;
   794         -  while( sqlite3_step(pStmt)==SQLITE_ROW ){
   795         -    /* Only copy in rows that occur at or after row index iStart. */
   796         -    if( nRow>=iStart && bOk ){
   797         -      bOk = copyRowToWindow(pEnv, win, (nRow - iStart), pStmt, aMethod);
   798         -      if( bOk==0 ){
   799         -        /* The CursorWindow object ran out of memory. If row iRowRequired was
   800         -        ** not successfully added before this happened, clear the CursorWindow
   801         -        ** and try to add the current row again.  */
   802         -        if( nRow<=iRowRequired ){
   803         -          bOk = setWindowNumColumns(pEnv, win, pStmt, aMethod);
   804         -          if( bOk==0 ){
   805         -            sqlite3_reset(pStmt);
   806         -            return 0;
   807         -          }
   808         -          iStart = nRow;
   809         -          bOk = copyRowToWindow(pEnv, win, (nRow - iStart), pStmt, aMethod);
   810         -        }
   811         -
   812         -        /* If the CursorWindow is still full and the countAllRows flag is not
   813         -        ** set, break out of the loop here. If countAllRows is set, continue
   814         -        ** so as to set variable nRow correctly.  */
   815         -        if( bOk==0 && countAllRows==0 ) break;
   816         -      }
   817         -    }
   818         -
   819         -    nRow++;
   820         -  }
   821         -
   822         -  /* Finalize the statement. If this indicates an error occurred, throw an
   823         -  ** SQLiteException exception.  */
   824         -  int rc = sqlite3_reset(pStmt);
   825         -  if( rc!=SQLITE_OK ){
   826         -    throw_sqlite3_exception(pEnv, sqlite3_db_handle(pStmt));
   827         -    return 0;
   828         -  }
   829         -
   830         -  jlong lRet = jlong(iStart) << 32 | jlong(nRow);
   831         -  return lRet;
   832         -}
   833         -
   834         -static jint nativeGetDbLookaside(JNIEnv* env, jobject clazz, jlong connectionPtr) {
   835         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   836         -
   837         -    int cur = -1;
   838         -    int unused;
   839         -    sqlite3_db_status(connection->db, SQLITE_DBSTATUS_LOOKASIDE_USED, &cur, &unused, 0);
   840         -    return cur;
   841         -}
   842         -
   843         -static void nativeCancel(JNIEnv* env, jobject clazz, jlong connectionPtr) {
   844         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   845         -    connection->canceled = true;
   846         -}
   847         -
   848         -static void nativeResetCancel(JNIEnv* env, jobject clazz, jlong connectionPtr,
   849         -        jboolean cancelable) {
   850         -    SQLiteConnection* connection = reinterpret_cast<SQLiteConnection*>(connectionPtr);
   851         -    connection->canceled = false;
   852         -
   853         -    if (cancelable) {
   854         -        sqlite3_progress_handler(connection->db, 4, sqliteProgressHandlerCallback,
   855         -                connection);
   856         -    } else {
   857         -        sqlite3_progress_handler(connection->db, 0, NULL, NULL);
   858         -    }
   859         -}
   860         -
   861         -static jboolean nativeHasCodec(JNIEnv* env, jobject clazz){
   862         -#ifdef SQLITE_HAS_CODEC
   863         -  return true;
   864         -#else
   865         -  return false;
   866         -#endif
   867         -}
   868         -
   869         -
   870         -static JNINativeMethod sMethods[] =
   871         -{
   872         -    /* name, signature, funcPtr */
   873         -    { "nativeOpen", "(Ljava/lang/String;ILjava/lang/String;ZZ)J",
   874         -            (void*)nativeOpen },
   875         -    { "nativeClose", "(J)V",
   876         -            (void*)nativeClose },
   877         -    { "nativeRegisterCustomFunction", "(JLorg/sqlite/database/sqlite/SQLiteCustomFunction;)V",
   878         -            (void*)nativeRegisterCustomFunction },
   879         -    { "nativeRegisterLocalizedCollators", "(JLjava/lang/String;)V",
   880         -            (void*)nativeRegisterLocalizedCollators },
   881         -    { "nativePrepareStatement", "(JLjava/lang/String;)J",
   882         -            (void*)nativePrepareStatement },
   883         -    { "nativeFinalizeStatement", "(JJ)V",
   884         -            (void*)nativeFinalizeStatement },
   885         -    { "nativeGetParameterCount", "(JJ)I",
   886         -            (void*)nativeGetParameterCount },
   887         -    { "nativeIsReadOnly", "(JJ)Z",
   888         -            (void*)nativeIsReadOnly },
   889         -    { "nativeGetColumnCount", "(JJ)I",
   890         -            (void*)nativeGetColumnCount },
   891         -    { "nativeGetColumnName", "(JJI)Ljava/lang/String;",
   892         -            (void*)nativeGetColumnName },
   893         -    { "nativeBindNull", "(JJI)V",
   894         -            (void*)nativeBindNull },
   895         -    { "nativeBindLong", "(JJIJ)V",
   896         -            (void*)nativeBindLong },
   897         -    { "nativeBindDouble", "(JJID)V",
   898         -            (void*)nativeBindDouble },
   899         -    { "nativeBindString", "(JJILjava/lang/String;)V",
   900         -            (void*)nativeBindString },
   901         -    { "nativeBindBlob", "(JJI[B)V",
   902         -            (void*)nativeBindBlob },
   903         -    { "nativeResetStatementAndClearBindings", "(JJ)V",
   904         -            (void*)nativeResetStatementAndClearBindings },
   905         -    { "nativeExecute", "(JJ)V",
   906         -            (void*)nativeExecute },
   907         -    { "nativeExecuteForLong", "(JJ)J",
   908         -            (void*)nativeExecuteForLong },
   909         -    { "nativeExecuteForString", "(JJ)Ljava/lang/String;",
   910         -            (void*)nativeExecuteForString },
   911         -    { "nativeExecuteForBlobFileDescriptor", "(JJ)I",
   912         -            (void*)nativeExecuteForBlobFileDescriptor },
   913         -    { "nativeExecuteForChangedRowCount", "(JJ)I",
   914         -            (void*)nativeExecuteForChangedRowCount },
   915         -    { "nativeExecuteForLastInsertedRowId", "(JJ)J",
   916         -            (void*)nativeExecuteForLastInsertedRowId },
   917         -    { "nativeExecuteForCursorWindow", "(JJLandroid/database/CursorWindow;IIZ)J",
   918         -            (void*)nativeExecuteForCursorWindow },
   919         -    { "nativeGetDbLookaside", "(J)I",
   920         -            (void*)nativeGetDbLookaside },
   921         -    { "nativeCancel", "(J)V",
   922         -            (void*)nativeCancel },
   923         -    { "nativeResetCancel", "(JZ)V",
   924         -            (void*)nativeResetCancel },
   925         -
   926         -    { "nativeHasCodec", "()Z", (void*)nativeHasCodec },
   927         -};
   928         -
   929         -#define FIND_CLASS(var, className) \
   930         -        var = env->FindClass(className); \
   931         -        LOG_FATAL_IF(! var, "Unable to find class " className);
   932         -
   933         -#define GET_METHOD_ID(var, clazz, methodName, fieldDescriptor) \
   934         -        var = env->GetMethodID(clazz, methodName, fieldDescriptor); \
   935         -        LOG_FATAL_IF(! var, "Unable to find method" methodName);
   936         -
   937         -#define GET_FIELD_ID(var, clazz, fieldName, fieldDescriptor) \
   938         -        var = env->GetFieldID(clazz, fieldName, fieldDescriptor); \
   939         -        LOG_FATAL_IF(! var, "Unable to find field " fieldName);
   940         -
   941         -int register_android_database_SQLiteConnection(JNIEnv *env)
   942         -{
   943         -    jclass clazz;
   944         -    FIND_CLASS(clazz, "org/sqlite/database/sqlite/SQLiteCustomFunction");
   945         -
   946         -    GET_FIELD_ID(gSQLiteCustomFunctionClassInfo.name, clazz,
   947         -            "name", "Ljava/lang/String;");
   948         -    GET_FIELD_ID(gSQLiteCustomFunctionClassInfo.numArgs, clazz,
   949         -            "numArgs", "I");
   950         -    GET_METHOD_ID(gSQLiteCustomFunctionClassInfo.dispatchCallback,
   951         -            clazz, "dispatchCallback", "([Ljava/lang/String;)V");
   952         -
   953         -    FIND_CLASS(clazz, "java/lang/String");
   954         -    gStringClassInfo.clazz = jclass(env->NewGlobalRef(clazz));
   955         -
   956         -    return jniRegisterNativeMethods(env, 
   957         -        "org/sqlite/database/sqlite/SQLiteConnection",
   958         -        sMethods, NELEM(sMethods)
   959         -    );
   960         -}
   961         -
   962         -extern int register_android_database_SQLiteGlobal(JNIEnv *env);
   963         -extern int register_android_database_SQLiteDebug(JNIEnv *env);
   964         -
   965         -} // namespace android
   966         -
   967         -extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
   968         -  JNIEnv *env = 0;
   969         -
   970         -  android::gpJavaVM = vm;
   971         -  vm->GetEnv((void**)&env, JNI_VERSION_1_4);
   972         -
   973         -  android::register_android_database_SQLiteConnection(env);
   974         -  android::register_android_database_SQLiteDebug(env);
   975         -  android::register_android_database_SQLiteGlobal(env);
   976         -
   977         -  return JNI_VERSION_1_4;
   978         -}
   979         -
   980         -
   981         -

Deleted jni/sqlite/android_database_SQLiteDebug.cpp.

     1         -/*
     2         - * Copyright (C) 2007 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#define LOG_TAG "SQLiteDebug"
    22         -
    23         -#include <jni.h>
    24         -#include <JNIHelp.h>
    25         -#include <ALog-priv.h>
    26         -
    27         -#include <stdio.h>
    28         -#include <stdlib.h>
    29         -#include <string.h>
    30         -#include <unistd.h>
    31         -
    32         -#include <sqlite3.h>
    33         -
    34         -namespace android {
    35         -
    36         -static struct {
    37         -    jfieldID memoryUsed;
    38         -    jfieldID pageCacheOverflow;
    39         -    jfieldID largestMemAlloc;
    40         -} gSQLiteDebugPagerStatsClassInfo;
    41         -
    42         -static void nativeGetPagerStats(JNIEnv *env, jobject clazz, jobject statsObj)
    43         -{
    44         -    int memoryUsed;
    45         -    int pageCacheOverflow;
    46         -    int largestMemAlloc;
    47         -    int unused;
    48         -
    49         -    sqlite3_status(SQLITE_STATUS_MEMORY_USED, &memoryUsed, &unused, 0);
    50         -    sqlite3_status(SQLITE_STATUS_MALLOC_SIZE, &unused, &largestMemAlloc, 0);
    51         -    sqlite3_status(SQLITE_STATUS_PAGECACHE_OVERFLOW, &pageCacheOverflow, &unused, 0);
    52         -    env->SetIntField(statsObj, gSQLiteDebugPagerStatsClassInfo.memoryUsed, memoryUsed);
    53         -    env->SetIntField(statsObj, gSQLiteDebugPagerStatsClassInfo.pageCacheOverflow,
    54         -            pageCacheOverflow);
    55         -    env->SetIntField(statsObj, gSQLiteDebugPagerStatsClassInfo.largestMemAlloc, largestMemAlloc);
    56         -}
    57         -
    58         -/*
    59         - * JNI registration.
    60         - */
    61         -
    62         -static JNINativeMethod gMethods[] =
    63         -{
    64         -    { "nativeGetPagerStats", "(Lorg/sqlite/database/sqlite/SQLiteDebug$PagerStats;)V",
    65         -            (void*) nativeGetPagerStats },
    66         -};
    67         -
    68         -#define FIND_CLASS(var, className) \
    69         -        var = env->FindClass(className); \
    70         -        LOG_FATAL_IF(! var, "Unable to find class " className);
    71         -
    72         -#define GET_FIELD_ID(var, clazz, fieldName, fieldDescriptor) \
    73         -        var = env->GetFieldID(clazz, fieldName, fieldDescriptor); \
    74         -        LOG_FATAL_IF(! var, "Unable to find field " fieldName);
    75         -
    76         -int register_android_database_SQLiteDebug(JNIEnv *env)
    77         -{
    78         -    jclass clazz;
    79         -    FIND_CLASS(clazz, "org/sqlite/database/sqlite/SQLiteDebug$PagerStats");
    80         -
    81         -    GET_FIELD_ID(gSQLiteDebugPagerStatsClassInfo.memoryUsed, clazz,
    82         -            "memoryUsed", "I");
    83         -    GET_FIELD_ID(gSQLiteDebugPagerStatsClassInfo.largestMemAlloc, clazz,
    84         -            "largestMemAlloc", "I");
    85         -    GET_FIELD_ID(gSQLiteDebugPagerStatsClassInfo.pageCacheOverflow, clazz,
    86         -            "pageCacheOverflow", "I");
    87         -
    88         -    return jniRegisterNativeMethods(env, "org/sqlite/database/sqlite/SQLiteDebug",
    89         -            gMethods, NELEM(gMethods));
    90         -}
    91         -
    92         -} // namespace android

Deleted jni/sqlite/android_database_SQLiteGlobal.cpp.

     1         -/*
     2         - * Copyright (C) 2011 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -/*
    17         -** Modified to support SQLite extensions by the SQLite developers: 
    18         -** sqlite-dev@sqlite.org.
    19         -*/
    20         -
    21         -#define LOG_TAG "SQLiteGlobal"
    22         -
    23         -#include <jni.h>
    24         -#include <JNIHelp.h>
    25         -#include "ALog-priv.h"
    26         -
    27         -
    28         -#include <sqlite3.h>
    29         -#if 0
    30         -#include <sqlite3_android.h>
    31         -#endif
    32         -
    33         -
    34         -#include "android_database_SQLiteCommon.h"
    35         -
    36         -namespace android {
    37         -
    38         -// Limit heap to 8MB for now.  This is 4 times the maximum cursor window
    39         -// size, as has been used by the original code in SQLiteDatabase for
    40         -// a long time.
    41         -static const int SOFT_HEAP_LIMIT = 8 * 1024 * 1024;
    42         -
    43         -
    44         -// Called each time a message is logged.
    45         -static void sqliteLogCallback(void* data, int iErrCode, const char* zMsg) {
    46         -    bool verboseLog = !!data;
    47         -    if (iErrCode == 0 || iErrCode == SQLITE_CONSTRAINT || iErrCode == SQLITE_SCHEMA) {
    48         -        if (verboseLog) {
    49         -            ALOG(LOG_VERBOSE, SQLITE_LOG_TAG, "(%d) %s\n", iErrCode, zMsg);
    50         -        }
    51         -    } else {
    52         -        ALOG(LOG_ERROR, SQLITE_LOG_TAG, "(%d) %s\n", iErrCode, zMsg);
    53         -    }
    54         -}
    55         -
    56         -// Sets the global SQLite configuration.
    57         -// This must be called before any other SQLite functions are called.
    58         -static void sqliteInitialize() {
    59         -    // Enable multi-threaded mode.  In this mode, SQLite is safe to use by multiple
    60         -    // threads as long as no two threads use the same database connection at the same
    61         -    // time (which we guarantee in the SQLite database wrappers).
    62         -    sqlite3_config(SQLITE_CONFIG_MULTITHREAD);
    63         -
    64         -    // Redirect SQLite log messages to the Android log.
    65         -#if 0
    66         -    bool verboseLog = android_util_Log_isVerboseLogEnabled(SQLITE_LOG_TAG);
    67         -#endif
    68         -    bool verboseLog = false;
    69         -    sqlite3_config(SQLITE_CONFIG_LOG, &sqliteLogCallback, verboseLog ? (void*)1 : NULL);
    70         -
    71         -    // The soft heap limit prevents the page cache allocations from growing
    72         -    // beyond the given limit, no matter what the max page cache sizes are
    73         -    // set to. The limit does not, as of 3.5.0, affect any other allocations.
    74         -    sqlite3_soft_heap_limit(SOFT_HEAP_LIMIT);
    75         -
    76         -    // Initialize SQLite.
    77         -    sqlite3_initialize();
    78         -}
    79         -
    80         -static jint nativeReleaseMemory(JNIEnv* env, jclass clazz) {
    81         -    return sqlite3_release_memory(SOFT_HEAP_LIMIT);
    82         -}
    83         -
    84         -static JNINativeMethod sMethods[] =
    85         -{
    86         -    /* name, signature, funcPtr */
    87         -    { "nativeReleaseMemory", "()I",
    88         -            (void*)nativeReleaseMemory },
    89         -};
    90         -
    91         -int register_android_database_SQLiteGlobal(JNIEnv *env)
    92         -{
    93         -    sqliteInitialize();
    94         -
    95         -    return jniRegisterNativeMethods(env, "org/sqlite/database/sqlite/SQLiteGlobal",
    96         -            sMethods, NELEM(sMethods));
    97         -}
    98         -
    99         -} // namespace android

Deleted jni/sqlite/nativehelper/JNIHelp.h.

     1         -/*
     2         - * Copyright (C) 2007 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -/*
    18         - * JNI helper functions.
    19         - *
    20         - * This file may be included by C or C++ code, which is trouble because jni.h
    21         - * uses different typedefs for JNIEnv in each language.
    22         - *
    23         - * TODO: remove C support.
    24         - */
    25         -#ifndef NATIVEHELPER_JNIHELP_H_
    26         -#define NATIVEHELPER_JNIHELP_H_
    27         -
    28         -#include "jni.h"
    29         -#include <unistd.h>
    30         -
    31         -#ifndef NELEM
    32         -# define NELEM(x) ((int) (sizeof(x) / sizeof((x)[0])))
    33         -#endif
    34         -
    35         -#ifdef __cplusplus
    36         -extern "C" {
    37         -#endif
    38         -
    39         -/*
    40         - * Register one or more native methods with a particular class.
    41         - * "className" looks like "java/lang/String". Aborts on failure.
    42         - * TODO: fix all callers and change the return type to void.
    43         - */
    44         -int jniRegisterNativeMethods(C_JNIEnv* env, const char* className, const JNINativeMethod* gMethods, int numMethods);
    45         -
    46         -/*
    47         - * Throw an exception with the specified class and an optional message.
    48         - *
    49         - * The "className" argument will be passed directly to FindClass, which
    50         - * takes strings with slashes (e.g. "java/lang/Object").
    51         - *
    52         - * If an exception is currently pending, we log a warning message and
    53         - * clear it.
    54         - *
    55         - * Returns 0 on success, nonzero if something failed (e.g. the exception
    56         - * class couldn't be found, so *an* exception will still be pending).
    57         - *
    58         - * Currently aborts the VM if it can't throw the exception.
    59         - */
    60         -int jniThrowException(C_JNIEnv* env, const char* className, const char* msg);
    61         -
    62         -/*
    63         - * Throw a java.lang.NullPointerException, with an optional message.
    64         - */
    65         -int jniThrowNullPointerException(C_JNIEnv* env, const char* msg);
    66         -
    67         -/*
    68         - * Throw a java.lang.RuntimeException, with an optional message.
    69         - */
    70         -int jniThrowRuntimeException(C_JNIEnv* env, const char* msg);
    71         -
    72         -/*
    73         - * Throw a java.io.IOException, generating the message from errno.
    74         - */
    75         -int jniThrowIOException(C_JNIEnv* env, int errnum);
    76         -
    77         -/*
    78         - * Return a pointer to a locale-dependent error string explaining errno
    79         - * value 'errnum'. The returned pointer may or may not be equal to 'buf'.
    80         - * This function is thread-safe (unlike strerror) and portable (unlike
    81         - * strerror_r).
    82         - */
    83         -const char* jniStrError(int errnum, char* buf, size_t buflen);
    84         -
    85         -/*
    86         - * Returns a new java.io.FileDescriptor for the given int fd.
    87         - */
    88         -jobject jniCreateFileDescriptor(C_JNIEnv* env, int fd);
    89         -
    90         -/*
    91         - * Returns the int fd from a java.io.FileDescriptor.
    92         - */
    93         -int jniGetFDFromFileDescriptor(C_JNIEnv* env, jobject fileDescriptor);
    94         -
    95         -/*
    96         - * Sets the int fd in a java.io.FileDescriptor.
    97         - */
    98         -void jniSetFileDescriptorOfFD(C_JNIEnv* env, jobject fileDescriptor, int value);
    99         -
   100         -/*
   101         - * Returns the reference from a java.lang.ref.Reference.
   102         - */
   103         -jobject jniGetReferent(C_JNIEnv* env, jobject ref);
   104         -
   105         -/*
   106         - * Log a message and an exception.
   107         - * If exception is NULL, logs the current exception in the JNI environment.
   108         - */
   109         -void jniLogException(C_JNIEnv* env, int priority, const char* tag, jthrowable exception);
   110         -
   111         -#ifdef __cplusplus
   112         -}
   113         -#endif
   114         -
   115         -
   116         -/*
   117         - * For C++ code, we provide inlines that map to the C functions.  g++ always
   118         - * inlines these, even on non-optimized builds.
   119         - */
   120         -#if defined(__cplusplus)
   121         -inline int jniRegisterNativeMethods(JNIEnv* env, const char* className, const JNINativeMethod* gMethods, int numMethods) {
   122         -    return jniRegisterNativeMethods(&env->functions, className, gMethods, numMethods);
   123         -}
   124         -
   125         -inline int jniThrowException(JNIEnv* env, const char* className, const char* msg) {
   126         -    return jniThrowException(&env->functions, className, msg);
   127         -}
   128         -
   129         -extern "C" int jniThrowExceptionFmt(C_JNIEnv* env, const char* className, const char* fmt, va_list args);
   130         -
   131         -/*
   132         - * Equivalent to jniThrowException but with a printf-like format string and
   133         - * variable-length argument list. This is only available in C++.
   134         - */
   135         -inline int jniThrowExceptionFmt(JNIEnv* env, const char* className, const char* fmt, ...) {
   136         -    va_list args;
   137         -    va_start(args, fmt);
   138         -    return jniThrowExceptionFmt(&env->functions, className, fmt, args);
   139         -    va_end(args);
   140         -}
   141         -
   142         -inline int jniThrowNullPointerException(JNIEnv* env, const char* msg) {
   143         -    return jniThrowNullPointerException(&env->functions, msg);
   144         -}
   145         -
   146         -inline int jniThrowRuntimeException(JNIEnv* env, const char* msg) {
   147         -    return jniThrowRuntimeException(&env->functions, msg);
   148         -}
   149         -
   150         -inline int jniThrowIOException(JNIEnv* env, int errnum) {
   151         -    return jniThrowIOException(&env->functions, errnum);
   152         -}
   153         -
   154         -inline jobject jniCreateFileDescriptor(JNIEnv* env, int fd) {
   155         -    return jniCreateFileDescriptor(&env->functions, fd);
   156         -}
   157         -
   158         -inline int jniGetFDFromFileDescriptor(JNIEnv* env, jobject fileDescriptor) {
   159         -    return jniGetFDFromFileDescriptor(&env->functions, fileDescriptor);
   160         -}
   161         -
   162         -inline void jniSetFileDescriptorOfFD(JNIEnv* env, jobject fileDescriptor, int value) {
   163         -    jniSetFileDescriptorOfFD(&env->functions, fileDescriptor, value);
   164         -}
   165         -
   166         -inline jobject jniGetReferent(JNIEnv* env, jobject ref) {
   167         -    return jniGetReferent(&env->functions, ref);
   168         -}
   169         -
   170         -inline void jniLogException(JNIEnv* env, int priority, const char* tag, jthrowable exception = NULL) {
   171         -    jniLogException(&env->functions, priority, tag, exception);
   172         -}
   173         -
   174         -#endif
   175         -
   176         -/*
   177         - * TEMP_FAILURE_RETRY is defined by some, but not all, versions of
   178         - * <unistd.h>. (Alas, it is not as standard as we'd hoped!) So, if it's
   179         - * not already defined, then define it here.
   180         - */
   181         -#ifndef TEMP_FAILURE_RETRY
   182         -/* Used to retry syscalls that can return EINTR. */
   183         -#define TEMP_FAILURE_RETRY(exp) ({         \
   184         -    typeof (exp) _rc;                      \
   185         -    do {                                   \
   186         -        _rc = (exp);                       \
   187         -    } while (_rc == -1 && errno == EINTR); \
   188         -    _rc; })
   189         -#endif
   190         -
   191         -#endif  /* NATIVEHELPER_JNIHELP_H_ */

Deleted jni/sqlite/nativehelper/JniConstants.h.

     1         -/*
     2         - * Copyright (C) 2010 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -#ifndef JNI_CONSTANTS_H_included
    18         -#define JNI_CONSTANTS_H_included
    19         -
    20         -#include "JNIHelp.h"
    21         -
    22         -/**
    23         - * A cache to avoid calling FindClass at runtime.
    24         - *
    25         - * Class lookup is relatively expensive (2.5us on passion-eng at the time of writing), so we do
    26         - * all such lookups eagerly at startup. This means that code that never uses, say,
    27         - * java.util.zip.Deflater still has to pay for the lookup, but it means that on a device the cost
    28         - * is definitely paid during boot and amortized. A central cache also removes the temptation to
    29         - * dynamically call FindClass rather than add a small cache to each file that needs one. Another
    30         - * cost is that each class cached here requires a global reference, though in practice we save
    31         - * enough by not having a global reference for each file that uses a class such as java.lang.String
    32         - * which is used in several files.
    33         - *
    34         - * FindClass is still called in a couple of situations: when throwing exceptions, and in some of
    35         - * the serialization code. The former is clearly not a performance case, and we're currently
    36         - * assuming that neither is the latter.
    37         - *
    38         - * TODO: similar arguments hold for field and method IDs; we should cache them centrally too.
    39         - */
    40         -struct JniConstants {
    41         -    static void init(JNIEnv* env);
    42         -
    43         -    static jclass bidiRunClass;
    44         -    static jclass bigDecimalClass;
    45         -    static jclass booleanClass;
    46         -    static jclass byteArrayClass;
    47         -    static jclass byteClass;
    48         -    static jclass calendarClass;
    49         -    static jclass characterClass;
    50         -    static jclass charsetICUClass;
    51         -    static jclass constructorClass;
    52         -    static jclass deflaterClass;
    53         -    static jclass doubleClass;
    54         -    static jclass errnoExceptionClass;
    55         -    static jclass fieldClass;
    56         -    static jclass fieldPositionIteratorClass;
    57         -    static jclass fileDescriptorClass;
    58         -    static jclass floatClass;
    59         -    static jclass gaiExceptionClass;
    60         -    static jclass inet6AddressClass;
    61         -    static jclass inetAddressClass;
    62         -    static jclass inetSocketAddressClass;
    63         -    static jclass inetUnixAddressClass;
    64         -    static jclass inflaterClass;
    65         -    static jclass inputStreamClass;
    66         -    static jclass integerClass;
    67         -    static jclass localeDataClass;
    68         -    static jclass longClass;
    69         -    static jclass methodClass;
    70         -    static jclass mutableIntClass;
    71         -    static jclass mutableLongClass;
    72         -    static jclass objectClass;
    73         -    static jclass objectArrayClass;
    74         -    static jclass outputStreamClass;
    75         -    static jclass parsePositionClass;
    76         -    static jclass patternSyntaxExceptionClass;
    77         -    static jclass realToStringClass;
    78         -    static jclass referenceClass;
    79         -    static jclass shortClass;
    80         -    static jclass socketClass;
    81         -    static jclass socketImplClass;
    82         -    static jclass stringClass;
    83         -    static jclass structAddrinfoClass;
    84         -    static jclass structFlockClass;
    85         -    static jclass structGroupReqClass;
    86         -    static jclass structLingerClass;
    87         -    static jclass structPasswdClass;
    88         -    static jclass structPollfdClass;
    89         -    static jclass structStatClass;
    90         -    static jclass structStatVfsClass;
    91         -    static jclass structTimevalClass;
    92         -    static jclass structUcredClass;
    93         -    static jclass structUtsnameClass;
    94         -};
    95         -
    96         -#define NATIVE_METHOD(className, functionName, signature) \
    97         -    { #functionName, signature, reinterpret_cast<void*>(className ## _ ## functionName) }
    98         -
    99         -#endif  // JNI_CONSTANTS_H_included

Deleted jni/sqlite/nativehelper/ScopedLocalRef.h.

     1         -/*
     2         - * Copyright (C) 2010 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -#ifndef SCOPED_LOCAL_REF_H_included
    18         -#define SCOPED_LOCAL_REF_H_included
    19         -
    20         -#include "jni.h"
    21         -
    22         -#include <stddef.h>
    23         -
    24         -// A smart pointer that deletes a JNI local reference when it goes out of scope.
    25         -template<typename T>
    26         -class ScopedLocalRef {
    27         -public:
    28         -    ScopedLocalRef(JNIEnv* env, T localRef) : mEnv(env), mLocalRef(localRef) {
    29         -    }
    30         -
    31         -    ~ScopedLocalRef() {
    32         -        reset();
    33         -    }
    34         -
    35         -    void reset(T ptr = NULL) {
    36         -        if (ptr != mLocalRef) {
    37         -            if (mLocalRef != NULL) {
    38         -                mEnv->DeleteLocalRef(mLocalRef);
    39         -            }
    40         -            mLocalRef = ptr;
    41         -        }
    42         -    }
    43         -
    44         -    T release() __attribute__((warn_unused_result)) {
    45         -        T localRef = mLocalRef;
    46         -        mLocalRef = NULL;
    47         -        return localRef;
    48         -    }
    49         -
    50         -    T get() const {
    51         -        return mLocalRef;
    52         -    }
    53         -
    54         -private:
    55         -    JNIEnv* mEnv;
    56         -    T mLocalRef;
    57         -
    58         -    // Disallow copy and assignment.
    59         -    ScopedLocalRef(const ScopedLocalRef&);
    60         -    void operator=(const ScopedLocalRef&);
    61         -};
    62         -
    63         -#endif  // SCOPED_LOCAL_REF_H_included

Deleted jni/sqlite/nativehelper/jni.h.

     1         -/*
     2         - * Copyright (C) 2006 The Android Open Source Project
     3         - *
     4         - * Licensed under the Apache License, Version 2.0 (the "License");
     5         - * you may not use this file except in compliance with the License.
     6         - * You may obtain a copy of the License at
     7         - *
     8         - *      http://www.apache.org/licenses/LICENSE-2.0
     9         - *
    10         - * Unless required by applicable law or agreed to in writing, software
    11         - * distributed under the License is distributed on an "AS IS" BASIS,
    12         - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13         - * See the License for the specific language governing permissions and
    14         - * limitations under the License.
    15         - */
    16         -
    17         -/*
    18         - * JNI specification, as defined by Sun:
    19         - * http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html
    20         - *
    21         - * Everything here is expected to be VM-neutral.
    22         - */
    23         -
    24         -#ifndef JNI_H_
    25         -#define JNI_H_
    26         -
    27         -#include <stdarg.h>
    28         -#include <stdint.h>
    29         -
    30         -/* Primitive types that match up with Java equivalents. */
    31         -typedef uint8_t  jboolean; /* unsigned 8 bits */
    32         -typedef int8_t   jbyte;    /* signed 8 bits */
    33         -typedef uint16_t jchar;    /* unsigned 16 bits */
    34         -typedef int16_t  jshort;   /* signed 16 bits */
    35         -typedef int32_t  jint;     /* signed 32 bits */
    36         -typedef int64_t  jlong;    /* signed 64 bits */
    37         -typedef float    jfloat;   /* 32-bit IEEE 754 */
    38         -typedef double   jdouble;  /* 64-bit IEEE 754 */
    39         -
    40         -/* "cardinal indices and sizes" */
    41         -typedef jint     jsize;
    42         -
    43         -#ifdef __cplusplus
    44         -/*
    45         - * Reference types, in C++
    46         - */
    47         -class _jobject {};
    48         -class _jclass : public _jobject {};
    49         -class _jstring : public _jobject {};
    50         -class _jarray : public _jobject {};
    51         -class _jobjectArray : public _jarray {};
    52         -class _jbooleanArray : public _jarray {};
    53         -class _jbyteArray : public _jarray {};
    54         -class _jcharArray : public _jarray {};
    55         -class _jshortArray : public _jarray {};
    56         -class _jintArray : public _jarray {};
    57         -class _jlongArray : public _jarray {};
    58         -class _jfloatArray : public _jarray {};
    59         -class _jdoubleArray : public _jarray {};
    60         -class _jthrowable : public _jobject {};
    61         -
    62         -typedef _jobject*       jobject;
    63         -typedef _jclass*        jclass;
    64         -typedef _jstring*       jstring;
    65         -typedef _jarray*        jarray;
    66         -typedef _jobjectArray*  jobjectArray;
    67         -typedef _jbooleanArray* jbooleanArray;
    68         -typedef _jbyteArray*    jbyteArray;
    69         -typedef _jcharArray*    jcharArray;
    70         -typedef _jshortArray*   jshortArray;
    71         -typedef _jintArray*     jintArray;
    72         -typedef _jlongArray*    jlongArray;
    73         -typedef _jfloatArray*   jfloatArray;
    74         -typedef _jdoubleArray*  jdoubleArray;
    75         -typedef _jthrowable*    jthrowable;
    76         -typedef _jobject*       jweak;
    77         -
    78         -
    79         -#else /* not __cplusplus */
    80         -
    81         -/*
    82         - * Reference types, in C.
    83         - */
    84         -typedef void*           jobject;
    85         -typedef jobject         jclass;
    86         -typedef jobject         jstring;
    87         -typedef jobject         jarray;
    88         -typedef jarray          jobjectArray;
    89         -typedef jarray          jbooleanArray;
    90         -typedef jarray          jbyteArray;
    91         -typedef jarray          jcharArray;
    92         -typedef jarray          jshortArray;
    93         -typedef jarray          jintArray;
    94         -typedef jarray          jlongArray;
    95         -typedef jarray          jfloatArray;
    96         -typedef jarray          jdoubleArray;
    97         -typedef jobject         jthrowable;
    98         -typedef jobject         jweak;
    99         -
   100         -#endif /* not __cplusplus */
   101         -
   102         -struct _jfieldID;                       /* opaque structure */
   103         -typedef struct _jfieldID* jfieldID;     /* field IDs */
   104         -
   105         -struct _jmethodID;                      /* opaque structure */
   106         -typedef struct _jmethodID* jmethodID;   /* method IDs */
   107         -
   108         -struct JNIInvokeInterface;
   109         -
   110         -typedef union jvalue {
   111         -    jboolean    z;
   112         -    jbyte       b;
   113         -    jchar       c;
   114         -    jshort      s;
   115         -    jint        i;
   116         -    jlong       j;
   117         -    jfloat      f;
   118         -    jdouble     d;
   119         -    jobject     l;
   120         -} jvalue;
   121         -
   122         -typedef enum jobjectRefType {
   123         -    JNIInvalidRefType = 0,
   124         -    JNILocalRefType = 1,
   125         -    JNIGlobalRefType = 2,
   126         -    JNIWeakGlobalRefType = 3
   127         -} jobjectRefType;
   128         -
   129         -typedef struct {
   130         -    const char* name;
   131         -    const char* signature;
   132         -    void*       fnPtr;
   133         -} JNINativeMethod;
   134         -
   135         -struct _JNIEnv;
   136         -struct _JavaVM;
   137         -typedef const struct JNINativeInterface* C_JNIEnv;
   138         -
   139         -#if defined(__cplusplus)
   140         -typedef _JNIEnv JNIEnv;
   141         -typedef _JavaVM JavaVM;
   142         -#else
   143         -typedef const struct JNINativeInterface* JNIEnv;
   144         -typedef const struct JNIInvokeInterface* JavaVM;
   145         -#endif
   146         -
   147         -/*
   148         - * Table of interface function pointers.
   149         - */
   150         -struct JNINativeInterface {
   151         -    void*       reserved0;
   152         -    void*       reserved1;
   153         -    void*       reserved2;
   154         -    void*       reserved3;
   155         -
   156         -    jint        (*GetVersion)(JNIEnv *);
   157         -
   158         -    jclass      (*DefineClass)(JNIEnv*, const char*, jobject, const jbyte*,
   159         -                        jsize);
   160         -    jclass      (*FindClass)(JNIEnv*, const char*);
   161         -
   162         -    jmethodID   (*FromReflectedMethod)(JNIEnv*, jobject);
   163         -    jfieldID    (*FromReflectedField)(JNIEnv*, jobject);
   164         -    /* spec doesn't show jboolean parameter */
   165         -    jobject     (*ToReflectedMethod)(JNIEnv*, jclass, jmethodID, jboolean);
   166         -
   167         -    jclass      (*GetSuperclass)(JNIEnv*, jclass);
   168         -    jboolean    (*IsAssignableFrom)(JNIEnv*, jclass, jclass);
   169         -
   170         -    /* spec doesn't show jboolean parameter */
   171         -    jobject     (*ToReflectedField)(JNIEnv*, jclass, jfieldID, jboolean);
   172         -
   173         -    jint        (*Throw)(JNIEnv*, jthrowable);
   174         -    jint        (*ThrowNew)(JNIEnv *, jclass, const char *);
   175         -    jthrowable  (*ExceptionOccurred)(JNIEnv*);
   176         -    void        (*ExceptionDescribe)(JNIEnv*);
   177         -    void        (*ExceptionClear)(JNIEnv*);
   178         -    void        (*FatalError)(JNIEnv*, const char*);
   179         -
   180         -    jint        (*PushLocalFrame)(JNIEnv*, jint);
   181         -    jobject     (*PopLocalFrame)(JNIEnv*, jobject);
   182         -
   183         -    jobject     (*NewGlobalRef)(JNIEnv*, jobject);
   184         -    void        (*DeleteGlobalRef)(JNIEnv*, jobject);
   185         -    void        (*DeleteLocalRef)(JNIEnv*, jobject);
   186         -    jboolean    (*IsSameObject)(JNIEnv*, jobject, jobject);
   187         -
   188         -    jobject     (*NewLocalRef)(JNIEnv*, jobject);
   189         -    jint        (*EnsureLocalCapacity)(JNIEnv*, jint);
   190         -
   191         -    jobject     (*AllocObject)(JNIEnv*, jclass);
   192         -    jobject     (*NewObject)(JNIEnv*, jclass, jmethodID, ...);
   193         -    jobject     (*NewObjectV)(JNIEnv*, jclass, jmethodID, va_list);
   194         -    jobject     (*NewObjectA)(JNIEnv*, jclass, jmethodID, jvalue*);
   195         -
   196         -    jclass      (*GetObjectClass)(JNIEnv*, jobject);
   197         -    jboolean    (*IsInstanceOf)(JNIEnv*, jobject, jclass);
   198         -    jmethodID   (*GetMethodID)(JNIEnv*, jclass, const char*, const char*);
   199         -
   200         -    jobject     (*CallObjectMethod)(JNIEnv*, jobject, jmethodID, ...);
   201         -    jobject     (*CallObjectMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   202         -    jobject     (*CallObjectMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   203         -    jboolean    (*CallBooleanMethod)(JNIEnv*, jobject, jmethodID, ...);
   204         -    jboolean    (*CallBooleanMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   205         -    jboolean    (*CallBooleanMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   206         -    jbyte       (*CallByteMethod)(JNIEnv*, jobject, jmethodID, ...);
   207         -    jbyte       (*CallByteMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   208         -    jbyte       (*CallByteMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   209         -    jchar       (*CallCharMethod)(JNIEnv*, jobject, jmethodID, ...);
   210         -    jchar       (*CallCharMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   211         -    jchar       (*CallCharMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   212         -    jshort      (*CallShortMethod)(JNIEnv*, jobject, jmethodID, ...);
   213         -    jshort      (*CallShortMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   214         -    jshort      (*CallShortMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   215         -    jint        (*CallIntMethod)(JNIEnv*, jobject, jmethodID, ...);
   216         -    jint        (*CallIntMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   217         -    jint        (*CallIntMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   218         -    jlong       (*CallLongMethod)(JNIEnv*, jobject, jmethodID, ...);
   219         -    jlong       (*CallLongMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   220         -    jlong       (*CallLongMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   221         -    jfloat      (*CallFloatMethod)(JNIEnv*, jobject, jmethodID, ...);
   222         -    jfloat      (*CallFloatMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   223         -    jfloat      (*CallFloatMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   224         -    jdouble     (*CallDoubleMethod)(JNIEnv*, jobject, jmethodID, ...);
   225         -    jdouble     (*CallDoubleMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   226         -    jdouble     (*CallDoubleMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   227         -    void        (*CallVoidMethod)(JNIEnv*, jobject, jmethodID, ...);
   228         -    void        (*CallVoidMethodV)(JNIEnv*, jobject, jmethodID, va_list);
   229         -    void        (*CallVoidMethodA)(JNIEnv*, jobject, jmethodID, jvalue*);
   230         -
   231         -    jobject     (*CallNonvirtualObjectMethod)(JNIEnv*, jobject, jclass,
   232         -                        jmethodID, ...);
   233         -    jobject     (*CallNonvirtualObjectMethodV)(JNIEnv*, jobject, jclass,
   234         -                        jmethodID, va_list);
   235         -    jobject     (*CallNonvirtualObjectMethodA)(JNIEnv*, jobject, jclass,
   236         -                        jmethodID, jvalue*);
   237         -    jboolean    (*CallNonvirtualBooleanMethod)(JNIEnv*, jobject, jclass,
   238         -                        jmethodID, ...);
   239         -    jboolean    (*CallNonvirtualBooleanMethodV)(JNIEnv*, jobject, jclass,
   240         -                         jmethodID, va_list);
   241         -    jboolean    (*CallNonvirtualBooleanMethodA)(JNIEnv*, jobject, jclass,
   242         -                         jmethodID, jvalue*);
   243         -    jbyte       (*CallNonvirtualByteMethod)(JNIEnv*, jobject, jclass,
   244         -                        jmethodID, ...);
   245         -    jbyte       (*CallNonvirtualByteMethodV)(JNIEnv*, jobject, jclass,
   246         -                        jmethodID, va_list);
   247         -    jbyte       (*CallNonvirtualByteMethodA)(JNIEnv*, jobject, jclass,
   248         -                        jmethodID, jvalue*);
   249         -    jchar       (*CallNonvirtualCharMethod)(JNIEnv*, jobject, jclass,
   250         -                        jmethodID, ...);
   251         -    jchar       (*CallNonvirtualCharMethodV)(JNIEnv*, jobject, jclass,
   252         -                        jmethodID, va_list);
   253         -    jchar       (*CallNonvirtualCharMethodA)(JNIEnv*, jobject, jclass,
   254         -                        jmethodID, jvalue*);
   255         -    jshort      (*CallNonvirtualShortMethod)(JNIEnv*, jobject, jclass,
   256         -                        jmethodID, ...);
   257         -    jshort      (*CallNonvirtualShortMethodV)(JNIEnv*, jobject, jclass,
   258         -                        jmethodID, va_list);
   259         -    jshort      (*CallNonvirtualShortMethodA)(JNIEnv*, jobject, jclass,
   260         -                        jmethodID, jvalue*);
   261         -    jint        (*CallNonvirtualIntMethod)(JNIEnv*, jobject, jclass,
   262         -                        jmethodID, ...);
   263         -    jint        (*CallNonvirtualIntMethodV)(JNIEnv*, jobject, jclass,
   264         -                        jmethodID, va_list);
   265         -    jint        (*CallNonvirtualIntMethodA)(JNIEnv*, jobject, jclass,
   266         -                        jmethodID, jvalue*);
   267         -    jlong       (*CallNonvirtualLongMethod)(JNIEnv*, jobject, jclass,
   268         -                        jmethodID, ...);
   269         -    jlong       (*CallNonvirtualLongMethodV)(JNIEnv*, jobject, jclass,
   270         -                        jmethodID, va_list);
   271         -    jlong       (*CallNonvirtualLongMethodA)(JNIEnv*, jobject, jclass,
   272         -                        jmethodID, jvalue*);
   273         -    jfloat      (*CallNonvirtualFloatMethod)(JNIEnv*, jobject, jclass,
   274         -                        jmethodID, ...);
   275         -    jfloat      (*CallNonvirtualFloatMethodV)(JNIEnv*, jobject, jclass,
   276         -                        jmethodID, va_list);
   277         -    jfloat      (*CallNonvirtualFloatMethodA)(JNIEnv*, jobject, jclass,
   278         -                        jmethodID, jvalue*);
   279         -    jdouble     (*CallNonvirtualDoubleMethod)(JNIEnv*, jobject, jclass,
   280         -                        jmethodID, ...);
   281         -    jdouble     (*CallNonvirtualDoubleMethodV)(JNIEnv*, jobject, jclass,
   282         -                        jmethodID, va_list);
   283         -    jdouble     (*CallNonvirtualDoubleMethodA)(JNIEnv*, jobject, jclass,
   284         -                        jmethodID, jvalue*);
   285         -    void        (*CallNonvirtualVoidMethod)(JNIEnv*, jobject, jclass,
   286         -                        jmethodID, ...);
   287         -    void        (*CallNonvirtualVoidMethodV)(JNIEnv*, jobject, jclass,
   288         -                        jmethodID, va_list);
   289         -    void        (*CallNonvirtualVoidMethodA)(JNIEnv*, jobject, jclass,
   290         -                        jmethodID, jvalue*);
   291         -
   292         -    jfieldID    (*GetFieldID)(JNIEnv*, jclass, const char*, const char*);
   293         -
   294         -    jobject     (*GetObjectField)(JNIEnv*, jobject, jfieldID);
   295         -    jboolean    (*GetBooleanField)(JNIEnv*, jobject, jfieldID);
   296         -    jbyte       (*GetByteField)(JNIEnv*, jobject, jfieldID);
   297         -    jchar       (*GetCharField)(JNIEnv*, jobject, jfieldID);
   298         -    jshort      (*GetShortField)(JNIEnv*, jobject, jfieldID);
   299         -    jint        (*GetIntField)(JNIEnv*, jobject, jfieldID);
   300         -    jlong       (*GetLongField)(JNIEnv*, jobject, jfieldID);
   301         -    jfloat      (*GetFloatField)(JNIEnv*, jobject, jfieldID);
   302         -    jdouble     (*GetDoubleField)(JNIEnv*, jobject, jfieldID);
   303         -
   304         -    void        (*SetObjectField)(JNIEnv*, jobject, jfieldID, jobject);
   305         -    void        (*SetBooleanField)(JNIEnv*, jobject, jfieldID, jboolean);
   306         -    void        (*SetByteField)(JNIEnv*, jobject, jfieldID, jbyte);
   307         -    void        (*SetCharField)(JNIEnv*, jobject, jfieldID, jchar);
   308         -    void        (*SetShortField)(JNIEnv*, jobject, jfieldID, jshort);
   309         -    void        (*SetIntField)(JNIEnv*, jobject, jfieldID, jint);
   310         -    void        (*SetLongField)(JNIEnv*, jobject, jfieldID, jlong);
   311         -    void        (*SetFloatField)(JNIEnv*, jobject, jfieldID, jfloat);
   312         -    void        (*SetDoubleField)(JNIEnv*, jobject, jfieldID, jdouble);
   313         -
   314         -    jmethodID   (*GetStaticMethodID)(JNIEnv*, jclass, const char*, const char*);
   315         -
   316         -    jobject     (*CallStaticObjectMethod)(JNIEnv*, jclass, jmethodID, ...);
   317         -    jobject     (*CallStaticObjectMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   318         -    jobject     (*CallStaticObjectMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   319         -    jboolean    (*CallStaticBooleanMethod)(JNIEnv*, jclass, jmethodID, ...);
   320         -    jboolean    (*CallStaticBooleanMethodV)(JNIEnv*, jclass, jmethodID,
   321         -                        va_list);
   322         -    jboolean    (*CallStaticBooleanMethodA)(JNIEnv*, jclass, jmethodID,
   323         -                        jvalue*);
   324         -    jbyte       (*CallStaticByteMethod)(JNIEnv*, jclass, jmethodID, ...);
   325         -    jbyte       (*CallStaticByteMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   326         -    jbyte       (*CallStaticByteMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   327         -    jchar       (*CallStaticCharMethod)(JNIEnv*, jclass, jmethodID, ...);
   328         -    jchar       (*CallStaticCharMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   329         -    jchar       (*CallStaticCharMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   330         -    jshort      (*CallStaticShortMethod)(JNIEnv*, jclass, jmethodID, ...);
   331         -    jshort      (*CallStaticShortMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   332         -    jshort      (*CallStaticShortMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   333         -    jint        (*CallStaticIntMethod)(JNIEnv*, jclass, jmethodID, ...);
   334         -    jint        (*CallStaticIntMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   335         -    jint        (*CallStaticIntMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   336         -    jlong       (*CallStaticLongMethod)(JNIEnv*, jclass, jmethodID, ...);
   337         -    jlong       (*CallStaticLongMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   338         -    jlong       (*CallStaticLongMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   339         -    jfloat      (*CallStaticFloatMethod)(JNIEnv*, jclass, jmethodID, ...);
   340         -    jfloat      (*CallStaticFloatMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   341         -    jfloat      (*CallStaticFloatMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   342         -    jdouble     (*CallStaticDoubleMethod)(JNIEnv*, jclass, jmethodID, ...);
   343         -    jdouble     (*CallStaticDoubleMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   344         -    jdouble     (*CallStaticDoubleMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   345         -    void        (*CallStaticVoidMethod)(JNIEnv*, jclass, jmethodID, ...);
   346         -    void        (*CallStaticVoidMethodV)(JNIEnv*, jclass, jmethodID, va_list);
   347         -    void        (*CallStaticVoidMethodA)(JNIEnv*, jclass, jmethodID, jvalue*);
   348         -
   349         -    jfieldID    (*GetStaticFieldID)(JNIEnv*, jclass, const char*,
   350         -                        const char*);
   351         -
   352         -    jobject     (*GetStaticObjectField)(JNIEnv*, jclass, jfieldID);
   353         -    jboolean    (*GetStaticBooleanField)(JNIEnv*, jclass, jfieldID);
   354         -    jbyte       (*GetStaticByteField)(JNIEnv*, jclass, jfieldID);
   355         -    jchar       (*GetStaticCharField)(JNIEnv*, jclass, jfieldID);
   356         -    jshort      (*GetStaticShortField)(JNIEnv*, jclass, jfieldID);
   357         -    jint        (*GetStaticIntField)(JNIEnv*, jclass, jfieldID);
   358         -    jlong       (*GetStaticLongField)(JNIEnv*, jclass, jfieldID);
   359         -    jfloat      (*GetStaticFloatField)(JNIEnv*, jclass, jfieldID);
   360         -    jdouble     (*GetStaticDoubleField)(JNIEnv*, jclass, jfieldID);
   361         -
   362         -    void        (*SetStaticObjectField)(JNIEnv*, jclass, jfieldID, jobject);
   363         -    void        (*SetStaticBooleanField)(JNIEnv*, jclass, jfieldID, jboolean);
   364         -    void        (*SetStaticByteField)(JNIEnv*, jclass, jfieldID, jbyte);
   365         -    void        (*SetStaticCharField)(JNIEnv*, jclass, jfieldID, jchar);
   366         -    void        (*SetStaticShortField)(JNIEnv*, jclass, jfieldID, jshort);
   367         -    void        (*SetStaticIntField)(JNIEnv*, jclass, jfieldID, jint);
   368         -    void        (*SetStaticLongField)(JNIEnv*, jclass, jfieldID, jlong);
   369         -    void        (*SetStaticFloatField)(JNIEnv*, jclass, jfieldID, jfloat);
   370         -    void        (*SetStaticDoubleField)(JNIEnv*, jclass, jfieldID, jdouble);
   371         -
   372         -    jstring     (*NewString)(JNIEnv*, const jchar*, jsize);
   373         -    jsize       (*GetStringLength)(JNIEnv*, jstring);
   374         -    const jchar* (*GetStringChars)(JNIEnv*, jstring, jboolean*);
   375         -    void        (*ReleaseStringChars)(JNIEnv*, jstring, const jchar*);
   376         -    jstring     (*NewStringUTF)(JNIEnv*, const char*);
   377         -    jsize       (*GetStringUTFLength)(JNIEnv*, jstring);
   378         -    /* JNI spec says this returns const jbyte*, but that's inconsistent */
   379         -    const char* (*GetStringUTFChars)(JNIEnv*, jstring, jboolean*);
   380         -    void        (*ReleaseStringUTFChars)(JNIEnv*, jstring, const char*);
   381         -    jsize       (*GetArrayLength)(JNIEnv*, jarray);
   382         -    jobjectArray (*NewObjectArray)(JNIEnv*, jsize, jclass, jobject);
   383         -    jobject     (*GetObjectArrayElement)(JNIEnv*, jobjectArray, jsize);
   384         -    void        (*SetObjectArrayElement)(JNIEnv*, jobjectArray, jsize, jobject);
   385         -
   386         -    jbooleanArray (*NewBooleanArray)(JNIEnv*, jsize);
   387         -    jbyteArray    (*NewByteArray)(JNIEnv*, jsize);
   388         -    jcharArray    (*NewCharArray)(JNIEnv*, jsize);
   389         -    jshortArray   (*NewShortArray)(JNIEnv*, jsize);
   390         -    jintArray     (*NewIntArray)(JNIEnv*, jsize);
   391         -    jlongArray    (*NewLongArray)(JNIEnv*, jsize);
   392         -    jfloatArray   (*NewFloatArray)(JNIEnv*, jsize);
   393         -    jdoubleArray  (*NewDoubleArray)(JNIEnv*, jsize);
   394         -
   395         -    jboolean*   (*GetBooleanArrayElements)(JNIEnv*, jbooleanArray, jboolean*);
   396         -    jbyte*      (*GetByteArrayElements)(JNIEnv*, jbyteArray, jboolean*);
   397         -    jchar*      (*GetCharArrayElements)(JNIEnv*, jcharArray, jboolean*);
   398         -    jshort*     (*GetShortArrayElements)(JNIEnv*, jshortArray, jboolean*);
   399         -    jint*       (*GetIntArrayElements)(JNIEnv*, jintArray, jboolean*);
   400         -    jlong*      (*GetLongArrayElements)(JNIEnv*, jlongArray, jboolean*);
   401         -    jfloat*     (*GetFloatArrayElements)(JNIEnv*, jfloatArray, jboolean*);
   402         -    jdouble*    (*GetDoubleArrayElements)(JNIEnv*, jdoubleArray, jboolean*);
   403         -
   404         -    void        (*ReleaseBooleanArrayElements)(JNIEnv*, jbooleanArray,
   405         -                        jboolean*, jint);
   406         -    void        (*ReleaseByteArrayElements)(JNIEnv*, jbyteArray,
   407         -                        jbyte*, jint);
   408         -    void        (*ReleaseCharArrayElements)(JNIEnv*, jcharArray,
   409         -                        jchar*, jint);
   410         -    void        (*ReleaseShortArrayElements)(JNIEnv*, jshortArray,
   411         -                        jshort*, jint);
   412         -    void        (*ReleaseIntArrayElements)(JNIEnv*, jintArray,
   413         -                        jint*, jint);
   414         -    void        (*ReleaseLongArrayElements)(JNIEnv*, jlongArray,
   415         -                        jlong*, jint);
   416         -    void        (*ReleaseFloatArrayElements)(JNIEnv*, jfloatArray,
   417         -                        jfloat*, jint);
   418         -    void        (*ReleaseDoubleArrayElements)(JNIEnv*, jdoubleArray,
   419         -                        jdouble*, jint);
   420         -
   421         -    void        (*GetBooleanArrayRegion)(JNIEnv*, jbooleanArray,
   422         -                        jsize, jsize, jboolean*);
   423         -    void        (*GetByteArrayRegion)(JNIEnv*, jbyteArray,
   424         -                        jsize, jsize, jbyte*);
   425         -    void        (*GetCharArrayRegion)(JNIEnv*, jcharArray,
   426         -                        jsize, jsize, jchar*);
   427         -    void        (*GetShortArrayRegion)(JNIEnv*, jshortArray,
   428         -                        jsize, jsize, jshort*);
   429         -    void        (*GetIntArrayRegion)(JNIEnv*, jintArray,
   430         -                        jsize, jsize, jint*);
   431         -    void        (*GetLongArrayRegion)(JNIEnv*, jlongArray,
   432         -                        jsize, jsize, jlong*);
   433         -    void        (*GetFloatArrayRegion)(JNIEnv*, jfloatArray,
   434         -                        jsize, jsize, jfloat*);
   435         -    void        (*GetDoubleArrayRegion)(JNIEnv*, jdoubleArray,
   436         -                        jsize, jsize, jdouble*);
   437         -
   438         -    /* spec shows these without const; some jni.h do, some don't */
   439         -    void        (*SetBooleanArrayRegion)(JNIEnv*, jbooleanArray,
   440         -                        jsize, jsize, const jboolean*);
   441         -    void        (*SetByteArrayRegion)(JNIEnv*, jbyteArray,
   442         -                        jsize, jsize, const jbyte*);
   443         -    void        (*SetCharArrayRegion)(JNIEnv*, jcharArray,
   444         -                        jsize, jsize, const jchar*);
   445         -    void        (*SetShortArrayRegion)(JNIEnv*, jshortArray,
   446         -                        jsize, jsize, const jshort*);
   447         -    void        (*SetIntArrayRegion)(JNIEnv*, jintArray,
   448         -                        jsize, jsize, const jint*);
   449         -    void        (*SetLongArrayRegion)(JNIEnv*, jlongArray,
   450         -                        jsize, jsize, const jlong*);
   451         -    void        (*SetFloatArrayRegion)(JNIEnv*, jfloatArray,
   452         -                        jsize, jsize, const jfloat*);
   453         -    void        (*SetDoubleArrayRegion)(JNIEnv*, jdoubleArray,
   454         -                        jsize, jsize, const jdouble*);
   455         -
   456         -    jint        (*RegisterNatives)(JNIEnv*, jclass, const JNINativeMethod*,
   457         -                        jint);
   458         -    jint        (*UnregisterNatives)(JNIEnv*, jclass);
   459         -    jint        (*MonitorEnter)(JNIEnv*, jobject);
   460         -    jint        (*MonitorExit)(JNIEnv*, jobject);
   461         -    jint        (*GetJavaVM)(JNIEnv*, JavaVM**);
   462         -
   463         -    void        (*GetStringRegion)(JNIEnv*, jstring, jsize, jsize, jchar*);
   464         -    void        (*GetStringUTFRegion)(JNIEnv*, jstring, jsize, jsize, char*);
   465         -
   466         -    void*       (*GetPrimitiveArrayCritical)(JNIEnv*, jarray, jboolean*);
   467         -    void        (*ReleasePrimitiveArrayCritical)(JNIEnv*, jarray, void*, jint);
   468         -
   469         -    const jchar* (*GetStringCritical)(JNIEnv*, jstring, jboolean*);
   470         -    void        (*ReleaseStringCritical)(JNIEnv*, jstring, const jchar*);
   471         -
   472         -    jweak       (*NewWeakGlobalRef)(JNIEnv*, jobject);
   473         -    void        (*DeleteWeakGlobalRef)(JNIEnv*, jweak);
   474         -
   475         -    jboolean    (*ExceptionCheck)(JNIEnv*);
   476         -
   477         -    jobject     (*NewDirectByteBuffer)(JNIEnv*, void*, jlong);
   478         -    void*       (*GetDirectBufferAddress)(JNIEnv*, jobject);
   479         -    jlong       (*GetDirectBufferCapacity)(JNIEnv*, jobject);
   480         -
   481         -    /* added in JNI 1.6 */
   482         -    jobjectRefType (*GetObjectRefType)(JNIEnv*, jobject);
   483         -};
   484         -
   485         -/*
   486         - * C++ object wrapper.
   487         - *
   488         - * This is usually overlaid on a C struct whose first element is a
   489         - * JNINativeInterface*.  We rely somewhat on compiler behavior.
   490         - */
   491         -struct _JNIEnv {
   492         -    /* do not rename this; it does not seem to be entirely opaque */
   493         -    const struct JNINativeInterface* functions;
   494         -
   495         -#if defined(__cplusplus)
   496         -
   497         -    jint GetVersion()
   498         -    { return functions->GetVersion(this); }
   499         -
   500         -    jclass DefineClass(const char *name, jobject loader, const jbyte* buf,
   501         -        jsize bufLen)
   502         -    { return functions->DefineClass(this, name, loader, buf, bufLen); }
   503         -
   504         -    jclass FindClass(const char* name)
   505         -    { return functions->FindClass(this, name); }
   506         -
   507         -    jmethodID FromReflectedMethod(jobject method)
   508         -    { return functions->FromReflectedMethod(this, method); }
   509         -
   510         -    jfieldID FromReflectedField(jobject field)
   511         -    { return functions->FromReflectedField(this, field); }
   512         -
   513         -    jobject ToReflectedMethod(jclass cls, jmethodID methodID, jboolean isStatic)
   514         -    { return functions->ToReflectedMethod(this, cls, methodID, isStatic); }
   515         -
   516         -    jclass GetSuperclass(jclass clazz)
   517         -    { return functions->GetSuperclass(this, clazz); }
   518         -
   519         -    jboolean IsAssignableFrom(jclass clazz1, jclass clazz2)
   520         -    { return functions->IsAssignableFrom(this, clazz1, clazz2); }
   521         -
   522         -    jobject ToReflectedField(jclass cls, jfieldID fieldID, jboolean isStatic)
   523         -    { return functions->ToReflectedField(this, cls, fieldID, isStatic); }
   524         -
   525         -    jint Throw(jthrowable obj)
   526         -    { return functions->Throw(this, obj); }
   527         -
   528         -    jint ThrowNew(jclass clazz, const char* message)
   529         -    { return functions->ThrowNew(this, clazz, message); }
   530         -
   531         -    jthrowable ExceptionOccurred()
   532         -    { return functions->ExceptionOccurred(this); }
   533         -
   534         -    void ExceptionDescribe()
   535         -    { functions->ExceptionDescribe(this); }
   536         -
   537         -    void ExceptionClear()
   538         -    { functions->ExceptionClear(this); }
   539         -
   540         -    void FatalError(const char* msg)
   541         -    { functions->FatalError(this, msg); }
   542         -
   543         -    jint PushLocalFrame(jint capacity)
   544         -    { return functions->PushLocalFrame(this, capacity); }
   545         -
   546         -    jobject PopLocalFrame(jobject result)
   547         -    { return functions->PopLocalFrame(this, result); }
   548         -
   549         -    jobject NewGlobalRef(jobject obj)
   550         -    { return functions->NewGlobalRef(this, obj); }
   551         -
   552         -    void DeleteGlobalRef(jobject globalRef)
   553         -    { functions->DeleteGlobalRef(this, globalRef); }
   554         -
   555         -    void DeleteLocalRef(jobject localRef)
   556         -    { functions->DeleteLocalRef(this, localRef); }
   557         -
   558         -    jboolean IsSameObject(jobject ref1, jobject ref2)
   559         -    { return functions->IsSameObject(this, ref1, ref2); }
   560         -
   561         -    jobject NewLocalRef(jobject ref)
   562         -    { return functions->NewLocalRef(this, ref); }
   563         -
   564         -    jint EnsureLocalCapacity(jint capacity)
   565         -    { return functions->EnsureLocalCapacity(this, capacity); }
   566         -
   567         -    jobject AllocObject(jclass clazz)
   568         -    { return functions->AllocObject(this, clazz); }
   569         -
   570         -    jobject NewObject(jclass clazz, jmethodID methodID, ...)
   571         -    {
   572         -        va_list args;
   573         -        va_start(args, methodID);
   574         -        jobject result = functions->NewObjectV(this, clazz, methodID, args);
   575         -        va_end(args);
   576         -        return result;
   577         -    }
   578         -
   579         -    jobject NewObjectV(jclass clazz, jmethodID methodID, va_list args)
   580         -    { return functions->NewObjectV(this, clazz, methodID, args); }
   581         -
   582         -    jobject NewObjectA(jclass clazz, jmethodID methodID, jvalue* args)
   583         -    { return functions->NewObjectA(this, clazz, methodID, args); }
   584         -
   585         -    jclass GetObjectClass(jobject obj)
   586         -    { return functions->GetObjectClass(this, obj); }
   587         -
   588         -    jboolean IsInstanceOf(jobject obj, jclass clazz)
   589         -    { return functions->IsInstanceOf(this, obj, clazz); }
   590         -
   591         -    jmethodID GetMethodID(jclass clazz, const char* name, const char* sig)
   592         -    { return functions->GetMethodID(this, clazz, name, sig); }
   593         -
   594         -#define CALL_TYPE_METHOD(_jtype, _jname)                                    \
   595         -    _jtype Call##_jname##Method(jobject obj, jmethodID methodID, ...)       \
   596         -    {                                                                       \
   597         -        _jtype result;                                                      \
   598         -        va_list args;                                                       \
   599         -        va_start(args, methodID);                                           \
   600         -        result = functions->Call##_jname##MethodV(this, obj, methodID,      \
   601         -                    args);                                                  \
   602         -        va_end(args);                                                       \
   603         -        return result;                                                      \
   604         -    }
   605         -#define CALL_TYPE_METHODV(_jtype, _jname)                                   \
   606         -    _jtype Call##_jname##MethodV(jobject obj, jmethodID methodID,           \
   607         -        va_list args)                                                       \
   608         -    { return functions->Call##_jname##MethodV(this, obj, methodID, args); }
   609         -#define CALL_TYPE_METHODA(_jtype, _jname)                                   \
   610         -    _jtype Call##_jname##MethodA(jobject obj, jmethodID methodID,           \
   611         -        jvalue* args)                                                       \
   612         -    { return functions->Call##_jname##MethodA(this, obj, methodID, args); }
   613         -
   614         -#define CALL_TYPE(_jtype, _jname)                                           \
   615         -    CALL_TYPE_METHOD(_jtype, _jname)                                        \
   616         -    CALL_TYPE_METHODV(_jtype, _jname)                                       \
   617         -    CALL_TYPE_METHODA(_jtype, _jname)
   618         -
   619         -    CALL_TYPE(jobject, Object)
   620         -    CALL_TYPE(jboolean, Boolean)
   621         -    CALL_TYPE(jbyte, Byte)
   622         -    CALL_TYPE(jchar, Char)
   623         -    CALL_TYPE(jshort, Short)
   624         -    CALL_TYPE(jint, Int)
   625         -    CALL_TYPE(jlong, Long)
   626         -    CALL_TYPE(jfloat, Float)
   627         -    CALL_TYPE(jdouble, Double)
   628         -
   629         -    void CallVoidMethod(jobject obj, jmethodID methodID, ...)
   630         -    {
   631         -        va_list args;
   632         -        va_start(args, methodID);
   633         -        functions->CallVoidMethodV(this, obj, methodID, args);
   634         -        va_end(args);
   635         -    }
   636         -    void CallVoidMethodV(jobject obj, jmethodID methodID, va_list args)
   637         -    { functions->CallVoidMethodV(this, obj, methodID, args); }
   638         -    void CallVoidMethodA(jobject obj, jmethodID methodID, jvalue* args)
   639         -    { functions->CallVoidMethodA(this, obj, methodID, args); }
   640         -
   641         -#define CALL_NONVIRT_TYPE_METHOD(_jtype, _jname)                            \
   642         -    _jtype CallNonvirtual##_jname##Method(jobject obj, jclass clazz,        \
   643         -        jmethodID methodID, ...)                                            \
   644         -    {                                                                       \
   645         -        _jtype result;                                                      \
   646         -        va_list args;                                                       \
   647         -        va_start(args, methodID);                                           \
   648         -        result = functions->CallNonvirtual##_jname##MethodV(this, obj,      \
   649         -                    clazz, methodID, args);                                 \
   650         -        va_end(args);                                                       \
   651         -        return result;                                                      \
   652         -    }
   653         -#define CALL_NONVIRT_TYPE_METHODV(_jtype, _jname)                           \
   654         -    _jtype CallNonvirtual##_jname##MethodV(jobject obj, jclass clazz,       \
   655         -        jmethodID methodID, va_list args)                                   \
   656         -    { return functions->CallNonvirtual##_jname##MethodV(this, obj, clazz,   \
   657         -        methodID, args); }
   658         -#define CALL_NONVIRT_TYPE_METHODA(_jtype, _jname)                           \
   659         -    _jtype CallNonvirtual##_jname##MethodA(jobject obj, jclass clazz,       \
   660         -        jmethodID methodID, jvalue* args)                                   \
   661         -    { return functions->CallNonvirtual##_jname##MethodA(this, obj, clazz,   \
   662         -        methodID, args); }
   663         -
   664         -#define CALL_NONVIRT_TYPE(_jtype, _jname)                                   \
   665         -    CALL_NONVIRT_TYPE_METHOD(_jtype, _jname)                                \
   666         -    CALL_NONVIRT_TYPE_METHODV(_jtype, _jname)                               \
   667         -    CALL_NONVIRT_TYPE_METHODA(_jtype, _jname)
   668         -
   669         -    CALL_NONVIRT_TYPE(jobject, Object)
   670         -    CALL_NONVIRT_TYPE(jboolean, Boolean)
   671         -    CALL_NONVIRT_TYPE(jbyte, Byte)
   672         -    CALL_NONVIRT_TYPE(jchar, Char)
   673         -    CALL_NONVIRT_TYPE(jshort, Short)
   674         -    CALL_NONVIRT_TYPE(jint, Int)
   675         -    CALL_NONVIRT_TYPE(jlong, Long)
   676         -    CALL_NONVIRT_TYPE(jfloat, Float)
   677         -    CALL_NONVIRT_TYPE(jdouble, Double)
   678         -
   679         -    void CallNonvirtualVoidMethod(jobject obj, jclass clazz,
   680         -        jmethodID methodID, ...)
   681         -    {
   682         -        va_list args;
   683         -        va_start(args, methodID);
   684         -        functions->CallNonvirtualVoidMethodV(this, obj, clazz, methodID, args);
   685         -        va_end(args);
   686         -    }
   687         -    void CallNonvirtualVoidMethodV(jobject obj, jclass clazz,
   688         -        jmethodID methodID, va_list args)
   689         -    { functions->CallNonvirtualVoidMethodV(this, obj, clazz, methodID, args); }
   690         -    void CallNonvirtualVoidMethodA(jobject obj, jclass clazz,
   691         -        jmethodID methodID, jvalue* args)
   692         -    { functions->CallNonvirtualVoidMethodA(this, obj, clazz, methodID, args); }
   693         -
   694         -    jfieldID GetFieldID(jclass clazz, const char* name, const char* sig)
   695         -    { return functions->GetFieldID(this, clazz, name, sig); }
   696         -
   697         -    jobject GetObjectField(jobject obj, jfieldID fieldID)
   698         -    { return functions->GetObjectField(this, obj, fieldID); }
   699         -    jboolean GetBooleanField(jobject obj, jfieldID fieldID)
   700         -    { return functions->GetBooleanField(this, obj, fieldID); }
   701         -    jbyte GetByteField(jobject obj, jfieldID fieldID)
   702         -    { return functions->GetByteField(this, obj, fieldID); }
   703         -    jchar GetCharField(jobject obj, jfieldID fieldID)
   704         -    { return functions->GetCharField(this, obj, fieldID); }
   705         -    jshort GetShortField(jobject obj, jfieldID fieldID)
   706         -    { return functions->GetShortField(this, obj, fieldID); }
   707         -    jint GetIntField(jobject obj, jfieldID fieldID)
   708         -    { return functions->GetIntField(this, obj, fieldID); }
   709         -    jlong GetLongField(jobject obj, jfieldID fieldID)
   710         -    { return functions->GetLongField(this, obj, fieldID); }
   711         -    jfloat GetFloatField(jobject obj, jfieldID fieldID)
   712         -    { return functions->GetFloatField(this, obj, fieldID); }
   713         -    jdouble GetDoubleField(jobject obj, jfieldID fieldID)
   714         -    { return functions->GetDoubleField(this, obj, fieldID); }
   715         -
   716         -    void SetObjectField(jobject obj, jfieldID fieldID, jobject value)
   717         -    { functions->SetObjectField(this, obj, fieldID, value); }
   718         -    void SetBooleanField(jobject obj, jfieldID fieldID, jboolean value)
   719         -    { functions->SetBooleanField(this, obj, fieldID, value); }
   720         -    void SetByteField(jobject obj, jfieldID fieldID, jbyte value)
   721         -    { functions->SetByteField(this, obj, fieldID, value); }
   722         -    void SetCharField(jobject obj, jfieldID fieldID, jchar value)
   723         -    { functions->SetCharField(this, obj, fieldID, value); }
   724         -    void SetShortField(jobject obj, jfieldID fieldID, jshort value)
   725         -    { functions->SetShortField(this, obj, fieldID, value); }
   726         -    void SetIntField(jobject obj, jfieldID fieldID, jint value)
   727         -    { functions->SetIntField(this, obj, fieldID, value); }
   728         -    void SetLongField(jobject obj, jfieldID fieldID, jlong value)
   729         -    { functions->SetLongField(this, obj, fieldID, value); }
   730         -    void SetFloatField(jobject obj, jfieldID fieldID, jfloat value)
   731         -    { functions->SetFloatField(this, obj, fieldID, value); }
   732         -    void SetDoubleField(jobject obj, jfieldID fieldID, jdouble value)
   733         -    { functions->SetDoubleField(this, obj, fieldID, value); }
   734         -
   735         -    jmethodID GetStaticMethodID(jclass clazz, const char* name, const char* sig)
   736         -    { return functions->GetStaticMethodID(this, clazz, name, sig); }
   737         -
   738         -#define CALL_STATIC_TYPE_METHOD(_jtype, _jname)                             \
   739         -    _jtype CallStatic##_jname##Method(jclass clazz, jmethodID methodID,     \
   740         -        ...)                                                                \
   741         -    {                                                                       \
   742         -        _jtype result;                                                      \
   743         -        va_list args;                                                       \
   744         -        va_start(args, methodID);                                           \
   745         -        result = functions->CallStatic##_jname##MethodV(this, clazz,        \
   746         -                    methodID, args);                                        \
   747         -        va_end(args);                                                       \
   748         -        return result;                                                      \
   749         -    }
   750         -#define CALL_STATIC_TYPE_METHODV(_jtype, _jname)                            \
   751         -    _jtype CallStatic##_jname##MethodV(jclass clazz, jmethodID methodID,    \
   752         -        va_list args)                                                       \
   753         -    { return functions->CallStatic##_jname##MethodV(this, clazz, methodID,  \
   754         -        args); }
   755         -#define CALL_STATIC_TYPE_METHODA(_jtype, _jname)                            \
   756         -    _jtype CallStatic##_jname##MethodA(jclass clazz, jmethodID methodID,    \
   757         -        jvalue* args)                                                       \
   758         -    { return functions->CallStatic##_jname##MethodA(this, clazz, methodID,  \
   759         -        args); }
   760         -
   761         -#define CALL_STATIC_TYPE(_jtype, _jname)                                    \
   762         -    CALL_STATIC_TYPE_METHOD(_jtype, _jname)                                 \
   763         -    CALL_STATIC_TYPE_METHODV(_jtype, _jname)                                \
   764         -    CALL_STATIC_TYPE_METHODA(_jtype, _jname)
   765         -
   766         -    CALL_STATIC_TYPE(jobject, Object)
   767         -    CALL_STATIC_TYPE(jboolean, Boolean)
   768         -    CALL_STATIC_TYPE(jbyte, Byte)
   769         -    CALL_STATIC_TYPE(jchar, Char)
   770         -    CALL_STATIC_TYPE(jshort, Short)
   771         -    CALL_STATIC_TYPE(jint, Int)
   772         -    CALL_STATIC_TYPE(jlong, Long)
   773         -    CALL_STATIC_TYPE(jfloat, Float)
   774         -    CALL_STATIC_TYPE(jdouble, Double)
   775         -
   776         -    void CallStaticVoidMethod(jclass clazz, jmethodID methodID, ...)
   777         -    {
   778         -        va_list args;
   779         -        va_start(args, methodID);
   780         -        functions->CallStaticVoidMethodV(this, clazz, methodID, args);
   781         -        va_end(args);
   782         -    }
   783         -    void CallStaticVoidMethodV(jclass clazz, jmethodID methodID, va_list args)
   784         -    { functions->CallStaticVoidMethodV(this, clazz, methodID, args); }
   785         -    void CallStaticVoidMethodA(jclass clazz, jmethodID methodID, jvalue* args)
   786         -    { functions->CallStaticVoidMethodA(this, clazz, methodID, args); }
   787         -
   788         -    jfieldID GetStaticFieldID(jclass clazz, const char* name, const char* sig)
   789         -    { return functions->GetStaticFieldID(this, clazz, name, sig); }
   790         -
   791         -    jobject GetStaticObjectField(jclass clazz, jfieldID fieldID)
   792         -    { return functions->GetStaticObjectField(this, clazz, fieldID); }
   793         -    jboolean GetStaticBooleanField(jclass clazz, jfieldID fieldID)
   794         -    { return functions->GetStaticBooleanField(this, clazz, fieldID); }
   795         -    jbyte GetStaticByteField(jclass clazz, jfieldID fieldID)
   796         -    { return functions->GetStaticByteField(this, clazz, fieldID); }
   797         -    jchar GetStaticCharField(jclass clazz, jfieldID fieldID)
   798         -    { return functions->GetStaticCharField(this, clazz, fieldID); }
   799         -    jshort GetStaticShortField(jclass clazz, jfieldID fieldID)
   800         -    { return functions->GetStaticShortField(this, clazz, fieldID); }
   801         -    jint GetStaticIntField(jclass clazz, jfieldID fieldID)
   802         -    { return functions->GetStaticIntField(this, clazz, fieldID); }
   803         -    jlong GetStaticLongField(jclass clazz, jfieldID fieldID)
   804         -    { return functions->GetStaticLongField(this, clazz, fieldID); }
   805         -    jfloat GetStaticFloatField(jclass clazz, jfieldID fieldID)
   806         -    { return functions->GetStaticFloatField(this, clazz, fieldID); }
   807         -    jdouble GetStaticDoubleField(jclass clazz, jfieldID fieldID)
   808         -    { return functions->GetStaticDoubleField(this, clazz, fieldID); }
   809         -
   810         -    void SetStaticObjectField(jclass clazz, jfieldID fieldID, jobject value)
   811         -    { functions->SetStaticObjectField(this, clazz, fieldID, value); }
   812         -    void SetStaticBooleanField(jclass clazz, jfieldID fieldID, jboolean value)
   813         -    { functions->SetStaticBooleanField(this, clazz, fieldID, value); }
   814         -    void SetStaticByteField(jclass clazz, jfieldID fieldID, jbyte value)
   815         -    { functions->SetStaticByteField(this, clazz, fieldID, value); }
   816         -    void SetStaticCharField(jclass clazz, jfieldID fieldID, jchar value)
   817         -    { functions->SetStaticCharField(this, clazz, fieldID, value); }
   818         -    void SetStaticShortField(jclass clazz, jfieldID fieldID, jshort value)
   819         -    { functions->SetStaticShortField(this, clazz, fieldID, value); }
   820         -    void SetStaticIntField(jclass clazz, jfieldID fieldID, jint value)
   821         -    { functions->SetStaticIntField(this, clazz, fieldID, value); }
   822         -    void SetStaticLongField(jclass clazz, jfieldID fieldID, jlong value)
   823         -    { functions->SetStaticLongField(this, clazz, fieldID, value); }
   824         -    void SetStaticFloatField(jclass clazz, jfieldID fieldID, jfloat value)
   825         -    { functions->SetStaticFloatField(this, clazz, fieldID, value); }
   826         -    void SetStaticDoubleField(jclass clazz, jfieldID fieldID, jdouble value)
   827         -    { functions->SetStaticDoubleField(this, clazz, fieldID, value); }
   828         -
   829         -    jstring NewString(const jchar* unicodeChars, jsize len)
   830         -    { return functions->NewString(this, unicodeChars, len); }
   831         -
   832         -    jsize GetStringLength(jstring string)
   833         -    { return functions->GetStringLength(this, string); }
   834         -
   835         -    const jchar* GetStringChars(jstring string, jboolean* isCopy)
   836         -    { return functions->GetStringChars(this, string, isCopy); }
   837         -
   838         -    void ReleaseStringChars(jstring string, const jchar* chars)
   839         -    { functions->ReleaseStringChars(this, string, chars); }
   840         -
   841         -    jstring NewStringUTF(const char* bytes)
   842         -    { return functions->NewStringUTF(this, bytes); }
   843         -
   844         -    jsize GetStringUTFLength(jstring string)
   845         -    { return functions->GetStringUTFLength(this, string); }
   846         -
   847         -    const char* GetStringUTFChars(jstring string, jboolean* isCopy)
   848         -    { return functions->GetStringUTFChars(this, string, isCopy); }
   849         -
   850         -    void ReleaseStringUTFChars(jstring string, const char* utf)
   851         -    { functions->ReleaseStringUTFChars(this, string, utf); }
   852         -
   853         -    jsize GetArrayLength(jarray array)
   854         -    { return functions->GetArrayLength(this, array); }
   855         -
   856         -    jobjectArray NewObjectArray(jsize length, jclass elementClass,
   857         -        jobject initialElement)
   858         -    { return functions->NewObjectArray(this, length, elementClass,
   859         -        initialElement); }
   860         -
   861         -    jobject GetObjectArrayElement(jobjectArray array, jsize index)
   862         -    { return functions->GetObjectArrayElement(this, array, index); }
   863         -
   864         -    void SetObjectArrayElement(jobjectArray array, jsize index, jobject value)
   865         -    { functions->SetObjectArrayElement(this, array, index, value); }
   866         -
   867         -    jbooleanArray NewBooleanArray(jsize length)
   868         -    { return functions->NewBooleanArray(this, length); }
   869         -    jbyteArray NewByteArray(jsize length)
   870         -    { return functions->NewByteArray(this, length); }
   871         -    jcharArray NewCharArray(jsize length)
   872         -    { return functions->NewCharArray(this, length); }
   873         -    jshortArray NewShortArray(jsize length)
   874         -    { return functions->NewShortArray(this, length); }
   875         -    jintArray NewIntArray(jsize length)
   876         -    { return functions->NewIntArray(this, length); }
   877         -    jlongArray NewLongArray(jsize length)
   878         -    { return functions->NewLongArray(this, length); }
   879         -    jfloatArray NewFloatArray(jsize length)
   880         -    { return functions->NewFloatArray(this, length); }
   881         -    jdoubleArray NewDoubleArray(jsize length)
   882         -    { return functions->NewDoubleArray(this, length); }
   883         -
   884         -    jboolean* GetBooleanArrayElements(jbooleanArray array, jboolean* isCopy)
   885         -    { return functions->GetBooleanArrayElements(this, array, isCopy); }
   886         -    jbyte* GetByteArrayElements(jbyteArray array, jboolean* isCopy)
   887         -    { return functions->GetByteArrayElements(this, array, isCopy); }
   888         -    jchar* GetCharArrayElements(jcharArray array, jboolean* isCopy)
   889         -    { return functions->GetCharArrayElements(this, array, isCopy); }
   890         -    jshort* GetShortArrayElements(jshortArray array, jboolean* isCopy)
   891         -    { return functions->GetShortArrayElements(this, array, isCopy); }
   892         -    jint* GetIntArrayElements(jintArray array, jboolean* isCopy)
   893         -    { return functions->GetIntArrayElements(this, array, isCopy); }
   894         -    jlong* GetLongArrayElements(jlongArray array, jboolean* isCopy)
   895         -    { return functions->GetLongArrayElements(this, array, isCopy); }
   896         -    jfloat* GetFloatArrayElements(jfloatArray array, jboolean* isCopy)
   897         -    { return functions->GetFloatArrayElements(this, array, isCopy); }
   898         -    jdouble* GetDoubleArrayElements(jdoubleArray array, jboolean* isCopy)
   899         -    { return functions->GetDoubleArrayElements(this, array, isCopy); }
   900         -
   901         -    void ReleaseBooleanArrayElements(jbooleanArray array, jboolean* elems,
   902         -        jint mode)
   903         -    { functions->ReleaseBooleanArrayElements(this, array, elems, mode); }
   904         -    void ReleaseByteArrayElements(jbyteArray array, jbyte* elems,
   905         -        jint mode)
   906         -    { functions->ReleaseByteArrayElements(this, array, elems, mode); }
   907         -    void ReleaseCharArrayElements(jcharArray array, jchar* elems,
   908         -        jint mode)
   909         -    { functions->ReleaseCharArrayElements(this, array, elems, mode); }
   910         -    void ReleaseShortArrayElements(jshortArray array, jshort* elems,
   911         -        jint mode)
   912         -    { functions->ReleaseShortArrayElements(this, array, elems, mode); }
   913         -    void ReleaseIntArrayElements(jintArray array, jint* elems,
   914         -        jint mode)
   915         -    { functions->ReleaseIntArrayElements(this, array, elems, mode); }
   916         -    void ReleaseLongArrayElements(jlongArray array, jlong* elems,
   917         -        jint mode)
   918         -    { functions->ReleaseLongArrayElements(this, array, elems, mode); }
   919         -    void ReleaseFloatArrayElements(jfloatArray array, jfloat* elems,
   920         -        jint mode)
   921         -    { functions->ReleaseFloatArrayElements(this, array, elems, mode); }
   922         -    void ReleaseDoubleArrayElements(jdoubleArray array, jdouble* elems,
   923         -        jint mode)
   924         -    { functions->ReleaseDoubleArrayElements(this, array, elems, mode); }
   925         -
   926         -    void GetBooleanArrayRegion(jbooleanArray array, jsize start, jsize len,
   927         -        jboolean* buf)
   928         -    { functions->GetBooleanArrayRegion(this, array, start, len, buf); }
   929         -    void GetByteArrayRegion(jbyteArray array, jsize start, jsize len,
   930         -        jbyte* buf)
   931         -    { functions->GetByteArrayRegion(this, array, start, len, buf); }
   932         -    void GetCharArrayRegion(jcharArray array, jsize start, jsize len,
   933         -        jchar* buf)
   934         -    { functions->GetCharArrayRegion(this, array, start, len, buf); }
   935         -    void GetShortArrayRegion(jshortArray array, jsize start, jsize len,
   936         -        jshort* buf)
   937         -    { functions->GetShortArrayRegion(this, array, start, len, buf); }
   938         -    void GetIntArrayRegion(jintArray array, jsize start, jsize len,
   939         -        jint* buf)
   940         -    { functions->GetIntArrayRegion(this, array, start, len, buf); }
   941         -    void GetLongArrayRegion(jlongArray array, jsize start, jsize len,
   942         -        jlong* buf)
   943         -    { functions->GetLongArrayRegion(this, array, start, len, buf); }
   944         -    void GetFloatArrayRegion(jfloatArray array, jsize start, jsize len,
   945         -        jfloat* buf)
   946         -    { functions->GetFloatArrayRegion(this, array, start, len, buf); }
   947         -    void GetDoubleArrayRegion(jdoubleArray array, jsize start, jsize len,
   948         -        jdouble* buf)
   949         -    { functions->GetDoubleArrayRegion(this, array, start, len, buf); }
   950         -
   951         -    void SetBooleanArrayRegion(jbooleanArray array, jsize start, jsize len,
   952         -        const jboolean* buf)
   953         -    { functions->SetBooleanArrayRegion(this, array, start, len, buf); }
   954         -    void SetByteArrayRegion(jbyteArray array, jsize start, jsize len,
   955         -        const jbyte* buf)
   956         -    { functions->SetByteArrayRegion(this, array, start, len, buf); }
   957         -    void SetCharArrayRegion(jcharArray array, jsize start, jsize len,
   958         -        const jchar* buf)
   959         -    { functions->SetCharArrayRegion(this, array, start, len, buf); }
   960         -    void SetShortArrayRegion(jshortArray array, jsize start, jsize len,
   961         -        const jshort* buf)
   962         -    { functions->SetShortArrayRegion(this, array, start, len, buf); }
   963         -    void SetIntArrayRegion(jintArray array, jsize start, jsize len,
   964         -        const jint* buf)
   965         -    { functions->SetIntArrayRegion(this, array, start, len, buf); }
   966         -    void SetLongArrayRegion(jlongArray array, jsize start, jsize len,
   967         -        const jlong* buf)
   968         -    { functions->SetLongArrayRegion(this, array, start, len, buf); }
   969         -    void SetFloatArrayRegion(jfloatArray array, jsize start, jsize len,
   970         -        const jfloat* buf)
   971         -    { functions->SetFloatArrayRegion(this, array, start, len, buf); }
   972         -    void SetDoubleArrayRegion(jdoubleArray array, jsize start, jsize len,
   973         -        const jdouble* buf)
   974         -    { functions->SetDoubleArrayRegion(this, array, start, len, buf); }
   975         -
   976         -    jint RegisterNatives(jclass clazz, const JNINativeMethod* methods,
   977         -        jint nMethods)
   978         -    { return functions->RegisterNatives(this, clazz, methods, nMethods); }
   979         -
   980         -    jint UnregisterNatives(jclass clazz)
   981         -    { return functions->UnregisterNatives(this, clazz); }
   982         -
   983         -    jint MonitorEnter(jobject obj)
   984         -    { return functions->MonitorEnter(this, obj); }
   985         -
   986         -    jint MonitorExit(jobject obj)
   987         -    { return functions->MonitorExit(this, obj); }
   988         -
   989         -    jint GetJavaVM(JavaVM** vm)
   990         -    { return functions->GetJavaVM(this, vm); }
   991         -
   992         -    void GetStringRegion(jstring str, jsize start, jsize len, jchar* buf)
   993         -    { functions->GetStringRegion(this, str, start, len, buf); }
   994         -
   995         -    void GetStringUTFRegion(jstring str, jsize start, jsize len, char* buf)
   996         -    { return functions->GetStringUTFRegion(this, str, start, len, buf); }
   997         -
   998         -    void* GetPrimitiveArrayCritical(jarray array, jboolean* isCopy)
   999         -    { return functions->GetPrimitiveArrayCritical(this, array, isCopy); }
  1000         -
  1001         -    void ReleasePrimitiveArrayCritical(jarray array, void* carray, jint mode)
  1002         -    { functions->ReleasePrimitiveArrayCritical(this, array, carray, mode); }
  1003         -
  1004         -    const jchar* GetStringCritical(jstring string, jboolean* isCopy)
  1005         -    { return functions->GetStringCritical(this, string, isCopy); }
  1006         -
  1007         -    void ReleaseStringCritical(jstring string, const jchar* carray)
  1008         -    { functions->ReleaseStringCritical(this, string, carray); }
  1009         -
  1010         -    jweak NewWeakGlobalRef(jobject obj)
  1011         -    { return functions->NewWeakGlobalRef(this, obj); }
  1012         -
  1013         -    void DeleteWeakGlobalRef(jweak obj)
  1014         -    { functions->DeleteWeakGlobalRef(this, obj); }
  1015         -
  1016         -    jboolean ExceptionCheck()
  1017         -    { return functions->ExceptionCheck(this); }
  1018         -
  1019         -    jobject NewDirectByteBuffer(void* address, jlong capacity)
  1020         -    { return functions->NewDirectByteBuffer(this, address, capacity); }
  1021         -
  1022         -    void* GetDirectBufferAddress(jobject buf)
  1023         -    { return functions->GetDirectBufferAddress(this, buf); }
  1024         -
  1025         -    jlong GetDirectBufferCapacity(jobject buf)
  1026         -    { return functions->GetDirectBufferCapacity(this, buf); }
  1027         -
  1028         -    /* added in JNI 1.6 */
  1029         -    jobjectRefType GetObjectRefType(jobject obj)
  1030         -    { return functions->GetObjectRefType(this, obj); }
  1031         -#endif /*__cplusplus*/
  1032         -};
  1033         -
  1034         -
  1035         -/*
  1036         - * JNI invocation interface.
  1037         - */
  1038         -struct JNIInvokeInterface {
  1039         -    void*       reserved0;
  1040         -    void*       reserved1;
  1041         -    void*       reserved2;
  1042         -
  1043         -    jint        (*DestroyJavaVM)(JavaVM*);
  1044         -    jint        (*AttachCurrentThread)(JavaVM*, JNIEnv**, void*);
  1045         -    jint        (*DetachCurrentThread)(JavaVM*);
  1046         -    jint        (*GetEnv)(JavaVM*, void**, jint);
  1047         -    jint        (*AttachCurrentThreadAsDaemon)(JavaVM*, JNIEnv**, void*);
  1048         -};
  1049         -
  1050         -/*
  1051         - * C++ version.
  1052         - */
  1053         -struct _JavaVM {
  1054         -    const struct JNIInvokeInterface* functions;
  1055         -
  1056         -#if defined(__cplusplus)
  1057         -    jint DestroyJavaVM()
  1058         -    { return functions->DestroyJavaVM(this); }
  1059         -    jint AttachCurrentThread(JNIEnv** p_env, void* thr_args)
  1060         -    { return functions->AttachCurrentThread(this, p_env, thr_args); }
  1061         -    jint DetachCurrentThread()
  1062         -    { return functions->DetachCurrentThread(this); }
  1063         -    jint GetEnv(void** env, jint version)
  1064         -    { return functions->GetEnv(this, env, version); }
  1065         -    jint AttachCurrentThreadAsDaemon(JNIEnv** p_env, void* thr_args)
  1066         -    { return functions->AttachCurrentThreadAsDaemon(this, p_env, thr_args); }
  1067         -#endif /*__cplusplus*/
  1068         -};
  1069         -
  1070         -struct JavaVMAttachArgs {
  1071         -    jint        version;    /* must be >= JNI_VERSION_1_2 */
  1072         -    const char* name;       /* NULL or name of thread as modified UTF-8 str */
  1073         -    jobject     group;      /* global ref of a ThreadGroup object, or NULL */
  1074         -};
  1075         -typedef struct JavaVMAttachArgs JavaVMAttachArgs;
  1076         -
  1077         -/*
  1078         - * JNI 1.2+ initialization.  (As of 1.6, the pre-1.2 structures are no
  1079         - * longer supported.)
  1080         - */
  1081         -typedef struct JavaVMOption {
  1082         -    const char* optionString;
  1083         -    void*       extraInfo;
  1084         -} JavaVMOption;
  1085         -
  1086         -typedef struct JavaVMInitArgs {
  1087         -    jint        version;    /* use JNI_VERSION_1_2 or later */
  1088         -
  1089         -    jint        nOptions;
  1090         -    JavaVMOption* options;
  1091         -    jboolean    ignoreUnrecognized;
  1092         -} JavaVMInitArgs;
  1093         -
  1094         -#ifdef __cplusplus
  1095         -extern "C" {
  1096         -#endif
  1097         -/*
  1098         - * VM initialization functions.
  1099         - *
  1100         - * Note these are the only symbols exported for JNI by the VM.
  1101         - */
  1102         -jint JNI_GetDefaultJavaVMInitArgs(void*);
  1103         -jint JNI_CreateJavaVM(JavaVM**, JNIEnv**, void*);
  1104         -jint JNI_GetCreatedJavaVMs(JavaVM**, jsize, jsize*);
  1105         -
  1106         -#define JNIIMPORT
  1107         -#define JNIEXPORT  __attribute__ ((visibility ("default")))
  1108         -#define JNICALL
  1109         -
  1110         -/*
  1111         - * Prototypes for functions exported by loadable shared libs.  These are
  1112         - * called by JNI, not provided by JNI.
  1113         - */
  1114         -JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved);
  1115         -JNIEXPORT void JNI_OnUnload(JavaVM* vm, void* reserved);
  1116         -
  1117         -#ifdef __cplusplus
  1118         -}
  1119         -#endif
  1120         -
  1121         -
  1122         -/*
  1123         - * Manifest constants.
  1124         - */
  1125         -#define JNI_FALSE   0
  1126         -#define JNI_TRUE    1
  1127         -
  1128         -#define JNI_VERSION_1_1 0x00010001
  1129         -#define JNI_VERSION_1_2 0x00010002
  1130         -#define JNI_VERSION_1_4 0x00010004
  1131         -#define JNI_VERSION_1_6 0x00010006
  1132         -
  1133         -#define JNI_OK          (0)         /* no error */
  1134         -#define JNI_ERR         (-1)        /* generic error */
  1135         -#define JNI_EDETACHED   (-2)        /* thread detached from the VM */
  1136         -#define JNI_EVERSION    (-3)        /* JNI version error */
  1137         -
  1138         -#define JNI_COMMIT      1           /* copy content, do not free buffer */
  1139         -#define JNI_ABORT       2           /* free buffer w/o copying back */
  1140         -
  1141         -#endif  /* JNI_H_ */

Deleted jni/sqlite/sqlite3.c.

more than 10,000 changes

Deleted jni/sqlite/sqlite3.h.

     1         -/*
     2         -** 2001 September 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 suppose 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         -/*
    38         -** Make sure we can call this stuff from C++.
    39         -*/
    40         -#ifdef __cplusplus
    41         -extern "C" {
    42         -#endif
    43         -
    44         -
    45         -/*
    46         -** Add the ability to override 'extern'
    47         -*/
    48         -#ifndef SQLITE_EXTERN
    49         -# define SQLITE_EXTERN extern
    50         -#endif
    51         -
    52         -#ifndef SQLITE_API
    53         -# define SQLITE_API
    54         -#endif
    55         -
    56         -
    57         -/*
    58         -** These no-op macros are used in front of interfaces to mark those
    59         -** interfaces as either deprecated or experimental.  New applications
    60         -** should not use deprecated interfaces - they are support for backwards
    61         -** compatibility only.  Application writers should be aware that
    62         -** experimental interfaces are subject to change in point releases.
    63         -**
    64         -** These macros used to resolve to various kinds of compiler magic that
    65         -** would generate warning messages when they were used.  But that
    66         -** compiler magic ended up generating such a flurry of bug reports
    67         -** that we have taken it all out and gone back to using simple
    68         -** noop macros.
    69         -*/
    70         -#define SQLITE_DEPRECATED
    71         -#define SQLITE_EXPERIMENTAL
    72         -
    73         -/*
    74         -** Ensure these symbols were not defined by some previous header file.
    75         -*/
    76         -#ifdef SQLITE_VERSION
    77         -# undef SQLITE_VERSION
    78         -#endif
    79         -#ifdef SQLITE_VERSION_NUMBER
    80         -# undef SQLITE_VERSION_NUMBER
    81         -#endif
    82         -
    83         -/*
    84         -** CAPI3REF: Compile-Time Library Version Numbers
    85         -**
    86         -** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
    87         -** evaluates to a string literal that is the SQLite version in the
    88         -** format "X.Y.Z" where X is the major version number (always 3 for
    89         -** SQLite3) and Y is the minor version number and Z is the release number.)^
    90         -** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
    91         -** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
    92         -** numbers used in [SQLITE_VERSION].)^
    93         -** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
    94         -** be larger than the release from which it is derived.  Either Y will
    95         -** be held constant and Z will be incremented or else Y will be incremented
    96         -** and Z will be reset to zero.
    97         -**
    98         -** Since version 3.6.18, SQLite source code has been stored in the
    99         -** <a href="http://www.fossil-scm.org/">Fossil configuration management
   100         -** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
   101         -** a string which identifies a particular check-in of SQLite
   102         -** within its configuration management system.  ^The SQLITE_SOURCE_ID
   103         -** string contains the date and time of the check-in (UTC) and an SHA1
   104         -** hash of the entire source tree.
   105         -**
   106         -** See also: [sqlite3_libversion()],
   107         -** [sqlite3_libversion_number()], [sqlite3_sourceid()],
   108         -** [sqlite_version()] and [sqlite_source_id()].
   109         -*/
   110         -#define SQLITE_VERSION        "3.8.7"
   111         -#define SQLITE_VERSION_NUMBER 3008007
   112         -#define SQLITE_SOURCE_ID      "2014-10-16 18:34:50 1418c006e377d7915a50577d4ccb21125b750bae"
   113         -
   114         -/*
   115         -** CAPI3REF: Run-Time Library Version Numbers
   116         -** KEYWORDS: sqlite3_version, sqlite3_sourceid
   117         -**
   118         -** These interfaces provide the same information as the [SQLITE_VERSION],
   119         -** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
   120         -** but are associated with the library instead of the header file.  ^(Cautious
   121         -** programmers might include assert() statements in their application to
   122         -** verify that values returned by these interfaces match the macros in
   123         -** the header, and thus insure that the application is
   124         -** compiled with matching library and header files.
   125         -**
   126         -** <blockquote><pre>
   127         -** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
   128         -** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
   129         -** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
   130         -** </pre></blockquote>)^
   131         -**
   132         -** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
   133         -** macro.  ^The sqlite3_libversion() function returns a pointer to the
   134         -** to the sqlite3_version[] string constant.  The sqlite3_libversion()
   135         -** function is provided for use in DLLs since DLL users usually do not have
   136         -** direct access to string constants within the DLL.  ^The
   137         -** sqlite3_libversion_number() function returns an integer equal to
   138         -** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 
   139         -** a pointer to a string constant whose value is the same as the 
   140         -** [SQLITE_SOURCE_ID] C preprocessor macro.
   141         -**
   142         -** See also: [sqlite_version()] and [sqlite_source_id()].
   143         -*/
   144         -SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
   145         -SQLITE_API const char *sqlite3_libversion(void);
   146         -SQLITE_API const char *sqlite3_sourceid(void);
   147         -SQLITE_API int sqlite3_libversion_number(void);
   148         -
   149         -/*
   150         -** CAPI3REF: Run-Time Library Compilation Options Diagnostics
   151         -**
   152         -** ^The sqlite3_compileoption_used() function returns 0 or 1 
   153         -** indicating whether the specified option was defined at 
   154         -** compile time.  ^The SQLITE_ prefix may be omitted from the 
   155         -** option name passed to sqlite3_compileoption_used().  
   156         -**
   157         -** ^The sqlite3_compileoption_get() function allows iterating
   158         -** over the list of options that were defined at compile time by
   159         -** returning the N-th compile time option string.  ^If N is out of range,
   160         -** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 
   161         -** prefix is omitted from any strings returned by 
   162         -** sqlite3_compileoption_get().
   163         -**
   164         -** ^Support for the diagnostic functions sqlite3_compileoption_used()
   165         -** and sqlite3_compileoption_get() may be omitted by specifying the 
   166         -** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
   167         -**
   168         -** See also: SQL functions [sqlite_compileoption_used()] and
   169         -** [sqlite_compileoption_get()] and the [compile_options pragma].
   170         -*/
   171         -#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
   172         -SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
   173         -SQLITE_API const char *sqlite3_compileoption_get(int N);
   174         -#endif
   175         -
   176         -/*
   177         -** CAPI3REF: Test To See If The Library Is Threadsafe
   178         -**
   179         -** ^The sqlite3_threadsafe() function returns zero if and only if
   180         -** SQLite was compiled with mutexing code omitted due to the
   181         -** [SQLITE_THREADSAFE] compile-time option being set to 0.
   182         -**
   183         -** SQLite can be compiled with or without mutexes.  When
   184         -** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
   185         -** are enabled and SQLite is threadsafe.  When the
   186         -** [SQLITE_THREADSAFE] macro is 0, 
   187         -** the mutexes are omitted.  Without the mutexes, it is not safe
   188         -** to use SQLite concurrently from more than one thread.
   189         -**
   190         -** Enabling mutexes incurs a measurable performance penalty.
   191         -** So if speed is of utmost importance, it makes sense to disable
   192         -** the mutexes.  But for maximum safety, mutexes should be enabled.
   193         -** ^The default behavior is for mutexes to be enabled.
   194         -**
   195         -** This interface can be used by an application to make sure that the
   196         -** version of SQLite that it is linking against was compiled with
   197         -** the desired setting of the [SQLITE_THREADSAFE] macro.
   198         -**
   199         -** This interface only reports on the compile-time mutex setting
   200         -** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
   201         -** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
   202         -** can be fully or partially disabled using a call to [sqlite3_config()]
   203         -** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
   204         -** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the
   205         -** sqlite3_threadsafe() function shows only the compile-time setting of
   206         -** thread safety, not any run-time changes to that setting made by
   207         -** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
   208         -** is unchanged by calls to sqlite3_config().)^
   209         -**
   210         -** See the [threading mode] documentation for additional information.
   211         -*/
   212         -SQLITE_API int sqlite3_threadsafe(void);
   213         -
   214         -/*
   215         -** CAPI3REF: Database Connection Handle
   216         -** KEYWORDS: {database connection} {database connections}
   217         -**
   218         -** Each open SQLite database is represented by a pointer to an instance of
   219         -** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
   220         -** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
   221         -** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
   222         -** and [sqlite3_close_v2()] are its destructors.  There are many other
   223         -** interfaces (such as
   224         -** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
   225         -** [sqlite3_busy_timeout()] to name but three) that are methods on an
   226         -** sqlite3 object.
   227         -*/
   228         -typedef struct sqlite3 sqlite3;
   229         -
   230         -/*
   231         -** CAPI3REF: 64-Bit Integer Types
   232         -** KEYWORDS: sqlite_int64 sqlite_uint64
   233         -**
   234         -** Because there is no cross-platform way to specify 64-bit integer types
   235         -** SQLite includes typedefs for 64-bit signed and unsigned integers.
   236         -**
   237         -** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
   238         -** The sqlite_int64 and sqlite_uint64 types are supported for backwards
   239         -** compatibility only.
   240         -**
   241         -** ^The sqlite3_int64 and sqlite_int64 types can store integer values
   242         -** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
   243         -** sqlite3_uint64 and sqlite_uint64 types can store integer values 
   244         -** between 0 and +18446744073709551615 inclusive.
   245         -*/
   246         -#ifdef SQLITE_INT64_TYPE
   247         -  typedef SQLITE_INT64_TYPE sqlite_int64;
   248         -  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
   249         -#elif defined(_MSC_VER) || defined(__BORLANDC__)
   250         -  typedef __int64 sqlite_int64;
   251         -  typedef unsigned __int64 sqlite_uint64;
   252         -#else
   253         -  typedef long long int sqlite_int64;
   254         -  typedef unsigned long long int sqlite_uint64;
   255         -#endif
   256         -typedef sqlite_int64 sqlite3_int64;
   257         -typedef sqlite_uint64 sqlite3_uint64;
   258         -
   259         -/*
   260         -** If compiling for a processor that lacks floating point support,
   261         -** substitute integer for floating-point.
   262         -*/
   263         -#ifdef SQLITE_OMIT_FLOATING_POINT
   264         -# define double sqlite3_int64
   265         -#endif
   266         -
   267         -/*
   268         -** CAPI3REF: Closing A Database Connection
   269         -**
   270         -** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
   271         -** for the [sqlite3] object.
   272         -** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
   273         -** the [sqlite3] object is successfully destroyed and all associated
   274         -** resources are deallocated.
   275         -**
   276         -** ^If the database connection is associated with unfinalized prepared
   277         -** statements or unfinished sqlite3_backup objects then sqlite3_close()
   278         -** will leave the database connection open and return [SQLITE_BUSY].
   279         -** ^If sqlite3_close_v2() is called with unfinalized prepared statements
   280         -** and/or unfinished sqlite3_backups, then the database connection becomes
   281         -** an unusable "zombie" which will automatically be deallocated when the
   282         -** last prepared statement is finalized or the last sqlite3_backup is
   283         -** finished.  The sqlite3_close_v2() interface is intended for use with
   284         -** host languages that are garbage collected, and where the order in which
   285         -** destructors are called is arbitrary.
   286         -**
   287         -** Applications should [sqlite3_finalize | finalize] all [prepared statements],
   288         -** [sqlite3_blob_close | close] all [BLOB handles], and 
   289         -** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
   290         -** with the [sqlite3] object prior to attempting to close the object.  ^If
   291         -** sqlite3_close_v2() is called on a [database connection] that still has
   292         -** outstanding [prepared statements], [BLOB handles], and/or
   293         -** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
   294         -** of resources is deferred until all [prepared statements], [BLOB handles],
   295         -** and [sqlite3_backup] objects are also destroyed.
   296         -**
   297         -** ^If an [sqlite3] object is destroyed while a transaction is open,
   298         -** the transaction is automatically rolled back.
   299         -**
   300         -** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
   301         -** must be either a NULL
   302         -** pointer or an [sqlite3] object pointer obtained
   303         -** from [sqlite3_open()], [sqlite3_open16()], or
   304         -** [sqlite3_open_v2()], and not previously closed.
   305         -** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
   306         -** argument is a harmless no-op.
   307         -*/
   308         -SQLITE_API int sqlite3_close(sqlite3*);
   309         -SQLITE_API int sqlite3_close_v2(sqlite3*);
   310         -
   311         -/*
   312         -** The type for a callback function.
   313         -** This is legacy and deprecated.  It is included for historical
   314         -** compatibility and is not documented.
   315         -*/
   316         -typedef int (*sqlite3_callback)(void*,int,char**, char**);
   317         -
   318         -/*
   319         -** CAPI3REF: One-Step Query Execution Interface
   320         -**
   321         -** The sqlite3_exec() interface is a convenience wrapper around
   322         -** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
   323         -** that allows an application to run multiple statements of SQL
   324         -** without having to use a lot of C code. 
   325         -**
   326         -** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
   327         -** semicolon-separate SQL statements passed into its 2nd argument,
   328         -** in the context of the [database connection] passed in as its 1st
   329         -** argument.  ^If the callback function of the 3rd argument to
   330         -** sqlite3_exec() is not NULL, then it is invoked for each result row
   331         -** coming out of the evaluated SQL statements.  ^The 4th argument to
   332         -** sqlite3_exec() is relayed through to the 1st argument of each
   333         -** callback invocation.  ^If the callback pointer to sqlite3_exec()
   334         -** is NULL, then no callback is ever invoked and result rows are
   335         -** ignored.
   336         -**
   337         -** ^If an error occurs while evaluating the SQL statements passed into
   338         -** sqlite3_exec(), then execution of the current statement stops and
   339         -** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
   340         -** is not NULL then any error message is written into memory obtained
   341         -** from [sqlite3_malloc()] and passed back through the 5th parameter.
   342         -** To avoid memory leaks, the application should invoke [sqlite3_free()]
   343         -** on error message strings returned through the 5th parameter of
   344         -** of sqlite3_exec() after the error message string is no longer needed.
   345         -** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
   346         -** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
   347         -** NULL before returning.
   348         -**
   349         -** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
   350         -** routine returns SQLITE_ABORT without invoking the callback again and
   351         -** without running any subsequent SQL statements.
   352         -**
   353         -** ^The 2nd argument to the sqlite3_exec() callback function is the
   354         -** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
   355         -** callback is an array of pointers to strings obtained as if from
   356         -** [sqlite3_column_text()], one for each column.  ^If an element of a
   357         -** result row is NULL then the corresponding string pointer for the
   358         -** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
   359         -** sqlite3_exec() callback is an array of pointers to strings where each
   360         -** entry represents the name of corresponding result column as obtained
   361         -** from [sqlite3_column_name()].
   362         -**
   363         -** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
   364         -** to an empty string, or a pointer that contains only whitespace and/or 
   365         -** SQL comments, then no SQL statements are evaluated and the database
   366         -** is not changed.
   367         -**
   368         -** Restrictions:
   369         -**
   370         -** <ul>
   371         -** <li> The application must insure that the 1st parameter to sqlite3_exec()
   372         -**      is a valid and open [database connection].
   373         -** <li> The application must not close the [database connection] specified by
   374         -**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
   375         -** <li> The application must not modify the SQL statement text passed into
   376         -**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
   377         -** </ul>
   378         -*/
   379         -SQLITE_API int sqlite3_exec(
   380         -  sqlite3*,                                  /* An open database */
   381         -  const char *sql,                           /* SQL to be evaluated */
   382         -  int (*callback)(void*,int,char**,char**),  /* Callback function */
   383         -  void *,                                    /* 1st argument to callback */
   384         -  char **errmsg                              /* Error msg written here */
   385         -);
   386         -
   387         -/*
   388         -** CAPI3REF: Result Codes
   389         -** KEYWORDS: {result code definitions}
   390         -**
   391         -** Many SQLite functions return an integer result code from the set shown
   392         -** here in order to indicate success or failure.
   393         -**
   394         -** New error codes may be added in future versions of SQLite.
   395         -**
   396         -** See also: [extended result code definitions]
   397         -*/
   398         -#define SQLITE_OK           0   /* Successful result */
   399         -/* beginning-of-error-codes */
   400         -#define SQLITE_ERROR        1   /* SQL error or missing database */
   401         -#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
   402         -#define SQLITE_PERM         3   /* Access permission denied */
   403         -#define SQLITE_ABORT        4   /* Callback routine requested an abort */
   404         -#define SQLITE_BUSY         5   /* The database file is locked */
   405         -#define SQLITE_LOCKED       6   /* A table in the database is locked */
   406         -#define SQLITE_NOMEM        7   /* A malloc() failed */
   407         -#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
   408         -#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
   409         -#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
   410         -#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
   411         -#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
   412         -#define SQLITE_FULL        13   /* Insertion failed because database is full */
   413         -#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
   414         -#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
   415         -#define SQLITE_EMPTY       16   /* Database is empty */
   416         -#define SQLITE_SCHEMA      17   /* The database schema changed */
   417         -#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
   418         -#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
   419         -#define SQLITE_MISMATCH    20   /* Data type mismatch */
   420         -#define SQLITE_MISUSE      21   /* Library used incorrectly */
   421         -#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
   422         -#define SQLITE_AUTH        23   /* Authorization denied */
   423         -#define SQLITE_FORMAT      24   /* Auxiliary database format error */
   424         -#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
   425         -#define SQLITE_NOTADB      26   /* File opened that is not a database file */
   426         -#define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
   427         -#define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
   428         -#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
   429         -#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
   430         -/* end-of-error-codes */
   431         -
   432         -/*
   433         -** CAPI3REF: Extended Result Codes
   434         -** KEYWORDS: {extended result code definitions}
   435         -**
   436         -** In its default configuration, SQLite API routines return one of 30 integer
   437         -** [result codes].  However, experience has shown that many of
   438         -** these result codes are too coarse-grained.  They do not provide as
   439         -** much information about problems as programmers might like.  In an effort to
   440         -** address this, newer versions of SQLite (version 3.3.8 and later) include
   441         -** support for additional result codes that provide more detailed information
   442         -** about errors. These [extended result codes] are enabled or disabled
   443         -** on a per database connection basis using the
   444         -** [sqlite3_extended_result_codes()] API.  Or, the extended code for
   445         -** the most recent error can be obtained using
   446         -** [sqlite3_extended_errcode()].
   447         -*/
   448         -#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
   449         -#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
   450         -#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
   451         -#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
   452         -#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
   453         -#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
   454         -#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
   455         -#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
   456         -#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
   457         -#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
   458         -#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
   459         -#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
   460         -#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
   461         -#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
   462         -#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
   463         -#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
   464         -#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
   465         -#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
   466         -#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
   467         -#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
   468         -#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
   469         -#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
   470         -#define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
   471         -#define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
   472         -#define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
   473         -#define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
   474         -#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
   475         -#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
   476         -#define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
   477         -#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
   478         -#define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
   479         -#define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
   480         -#define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
   481         -#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
   482         -#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
   483         -#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
   484         -#define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
   485         -#define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
   486         -#define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
   487         -#define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
   488         -#define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
   489         -#define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
   490         -#define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
   491         -#define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
   492         -#define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
   493         -#define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
   494         -#define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
   495         -#define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
   496         -#define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
   497         -#define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
   498         -#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
   499         -#define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
   500         -#define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))
   501         -
   502         -/*
   503         -** CAPI3REF: Flags For File Open Operations
   504         -**
   505         -** These bit values are intended for use in the
   506         -** 3rd parameter to the [sqlite3_open_v2()] interface and
   507         -** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
   508         -*/
   509         -#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
   510         -#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
   511         -#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
   512         -#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
   513         -#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
   514         -#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
   515         -#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
   516         -#define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
   517         -#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
   518         -#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
   519         -#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
   520         -#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
   521         -#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
   522         -#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
   523         -#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
   524         -#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
   525         -#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
   526         -#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
   527         -#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
   528         -#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
   529         -
   530         -/* Reserved:                         0x00F00000 */
   531         -
   532         -/*
   533         -** CAPI3REF: Device Characteristics
   534         -**
   535         -** The xDeviceCharacteristics method of the [sqlite3_io_methods]
   536         -** object returns an integer which is a vector of these
   537         -** bit values expressing I/O characteristics of the mass storage
   538         -** device that holds the file that the [sqlite3_io_methods]
   539         -** refers to.
   540         -**
   541         -** The SQLITE_IOCAP_ATOMIC property means that all writes of
   542         -** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
   543         -** mean that writes of blocks that are nnn bytes in size and
   544         -** are aligned to an address which is an integer multiple of
   545         -** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
   546         -** that when data is appended to a file, the data is appended
   547         -** first then the size of the file is extended, never the other
   548         -** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
   549         -** information is written to disk in the same order as calls
   550         -** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
   551         -** after reboot following a crash or power loss, the only bytes in a
   552         -** file that were written at the application level might have changed
   553         -** and that adjacent bytes, even bytes within the same sector are
   554         -** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
   555         -** flag indicate that a file cannot be deleted when open.  The
   556         -** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
   557         -** read-only media and cannot be changed even by processes with
   558         -** elevated privileges.
   559         -*/
   560         -#define SQLITE_IOCAP_ATOMIC                 0x00000001
   561         -#define SQLITE_IOCAP_ATOMIC512              0x00000002
   562         -#define SQLITE_IOCAP_ATOMIC1K               0x00000004
   563         -#define SQLITE_IOCAP_ATOMIC2K               0x00000008
   564         -#define SQLITE_IOCAP_ATOMIC4K               0x00000010
   565         -#define SQLITE_IOCAP_ATOMIC8K               0x00000020
   566         -#define SQLITE_IOCAP_ATOMIC16K              0x00000040
   567         -#define SQLITE_IOCAP_ATOMIC32K              0x00000080
   568         -#define SQLITE_IOCAP_ATOMIC64K              0x00000100
   569         -#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
   570         -#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
   571         -#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
   572         -#define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
   573         -#define SQLITE_IOCAP_IMMUTABLE              0x00002000
   574         -
   575         -/*
   576         -** CAPI3REF: File Locking Levels
   577         -**
   578         -** SQLite uses one of these integer values as the second
   579         -** argument to calls it makes to the xLock() and xUnlock() methods
   580         -** of an [sqlite3_io_methods] object.
   581         -*/
   582         -#define SQLITE_LOCK_NONE          0
   583         -#define SQLITE_LOCK_SHARED        1
   584         -#define SQLITE_LOCK_RESERVED      2
   585         -#define SQLITE_LOCK_PENDING       3
   586         -#define SQLITE_LOCK_EXCLUSIVE     4
   587         -
   588         -/*
   589         -** CAPI3REF: Synchronization Type Flags
   590         -**
   591         -** When SQLite invokes the xSync() method of an
   592         -** [sqlite3_io_methods] object it uses a combination of
   593         -** these integer values as the second argument.
   594         -**
   595         -** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
   596         -** sync operation only needs to flush data to mass storage.  Inode
   597         -** information need not be flushed. If the lower four bits of the flag
   598         -** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
   599         -** If the lower four bits equal SQLITE_SYNC_FULL, that means
   600         -** to use Mac OS X style fullsync instead of fsync().
   601         -**
   602         -** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
   603         -** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
   604         -** settings.  The [synchronous pragma] determines when calls to the
   605         -** xSync VFS method occur and applies uniformly across all platforms.
   606         -** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
   607         -** energetic or rigorous or forceful the sync operations are and
   608         -** only make a difference on Mac OSX for the default SQLite code.
   609         -** (Third-party VFS implementations might also make the distinction
   610         -** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
   611         -** operating systems natively supported by SQLite, only Mac OSX
   612         -** cares about the difference.)
   613         -*/
   614         -#define SQLITE_SYNC_NORMAL        0x00002
   615         -#define SQLITE_SYNC_FULL          0x00003
   616         -#define SQLITE_SYNC_DATAONLY      0x00010
   617         -
   618         -/*
   619         -** CAPI3REF: OS Interface Open File Handle
   620         -**
   621         -** An [sqlite3_file] object represents an open file in the 
   622         -** [sqlite3_vfs | OS interface layer].  Individual OS interface
   623         -** implementations will
   624         -** want to subclass this object by appending additional fields
   625         -** for their own use.  The pMethods entry is a pointer to an
   626         -** [sqlite3_io_methods] object that defines methods for performing
   627         -** I/O operations on the open file.
   628         -*/
   629         -typedef struct sqlite3_file sqlite3_file;
   630         -struct sqlite3_file {
   631         -  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
   632         -};
   633         -
   634         -/*
   635         -** CAPI3REF: OS Interface File Virtual Methods Object
   636         -**
   637         -** Every file opened by the [sqlite3_vfs.xOpen] method populates an
   638         -** [sqlite3_file] object (or, more commonly, a subclass of the
   639         -** [sqlite3_file] object) with a pointer to an instance of this object.
   640         -** This object defines the methods used to perform various operations
   641         -** against the open file represented by the [sqlite3_file] object.
   642         -**
   643         -** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 
   644         -** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
   645         -** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
   646         -** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
   647         -** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
   648         -** to NULL.
   649         -**
   650         -** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
   651         -** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
   652         -** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
   653         -** flag may be ORed in to indicate that only the data of the file
   654         -** and not its inode needs to be synced.
   655         -**
   656         -** The integer values to xLock() and xUnlock() are one of
   657         -** <ul>
   658         -** <li> [SQLITE_LOCK_NONE],
   659         -** <li> [SQLITE_LOCK_SHARED],
   660         -** <li> [SQLITE_LOCK_RESERVED],
   661         -** <li> [SQLITE_LOCK_PENDING], or
   662         -** <li> [SQLITE_LOCK_EXCLUSIVE].
   663         -** </ul>
   664         -** xLock() increases the lock. xUnlock() decreases the lock.
   665         -** The xCheckReservedLock() method checks whether any database connection,
   666         -** either in this process or in some other process, is holding a RESERVED,
   667         -** PENDING, or EXCLUSIVE lock on the file.  It returns true
   668         -** if such a lock exists and false otherwise.
   669         -**
   670         -** The xFileControl() method is a generic interface that allows custom
   671         -** VFS implementations to directly control an open file using the
   672         -** [sqlite3_file_control()] interface.  The second "op" argument is an
   673         -** integer opcode.  The third argument is a generic pointer intended to
   674         -** point to a structure that may contain arguments or space in which to
   675         -** write return values.  Potential uses for xFileControl() might be
   676         -** functions to enable blocking locks with timeouts, to change the
   677         -** locking strategy (for example to use dot-file locks), to inquire
   678         -** about the status of a lock, or to break stale locks.  The SQLite
   679         -** core reserves all opcodes less than 100 for its own use.
   680         -** A [file control opcodes | list of opcodes] less than 100 is available.
   681         -** Applications that define a custom xFileControl method should use opcodes
   682         -** greater than 100 to avoid conflicts.  VFS implementations should
   683         -** return [SQLITE_NOTFOUND] for file control opcodes that they do not
   684         -** recognize.
   685         -**
   686         -** The xSectorSize() method returns the sector size of the
   687         -** device that underlies the file.  The sector size is the
   688         -** minimum write that can be performed without disturbing
   689         -** other bytes in the file.  The xDeviceCharacteristics()
   690         -** method returns a bit vector describing behaviors of the
   691         -** underlying device:
   692         -**
   693         -** <ul>
   694         -** <li> [SQLITE_IOCAP_ATOMIC]
   695         -** <li> [SQLITE_IOCAP_ATOMIC512]
   696         -** <li> [SQLITE_IOCAP_ATOMIC1K]
   697         -** <li> [SQLITE_IOCAP_ATOMIC2K]
   698         -** <li> [SQLITE_IOCAP_ATOMIC4K]
   699         -** <li> [SQLITE_IOCAP_ATOMIC8K]
   700         -** <li> [SQLITE_IOCAP_ATOMIC16K]
   701         -** <li> [SQLITE_IOCAP_ATOMIC32K]
   702         -** <li> [SQLITE_IOCAP_ATOMIC64K]
   703         -** <li> [SQLITE_IOCAP_SAFE_APPEND]
   704         -** <li> [SQLITE_IOCAP_SEQUENTIAL]
   705         -** </ul>
   706         -**
   707         -** The SQLITE_IOCAP_ATOMIC property means that all writes of
   708         -** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
   709         -** mean that writes of blocks that are nnn bytes in size and
   710         -** are aligned to an address which is an integer multiple of
   711         -** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
   712         -** that when data is appended to a file, the data is appended
   713         -** first then the size of the file is extended, never the other
   714         -** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
   715         -** information is written to disk in the same order as calls
   716         -** to xWrite().
   717         -**
   718         -** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
   719         -** in the unread portions of the buffer with zeros.  A VFS that
   720         -** fails to zero-fill short reads might seem to work.  However,
   721         -** failure to zero-fill short reads will eventually lead to
   722         -** database corruption.
   723         -*/
   724         -typedef struct sqlite3_io_methods sqlite3_io_methods;
   725         -struct sqlite3_io_methods {
   726         -  int iVersion;
   727         -  int (*xClose)(sqlite3_file*);
   728         -  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
   729         -  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
   730         -  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
   731         -  int (*xSync)(sqlite3_file*, int flags);
   732         -  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
   733         -  int (*xLock)(sqlite3_file*, int);
   734         -  int (*xUnlock)(sqlite3_file*, int);
   735         -  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
   736         -  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
   737         -  int (*xSectorSize)(sqlite3_file*);
   738         -  int (*xDeviceCharacteristics)(sqlite3_file*);
   739         -  /* Methods above are valid for version 1 */
   740         -  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
   741         -  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
   742         -  void (*xShmBarrier)(sqlite3_file*);
   743         -  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
   744         -  /* Methods above are valid for version 2 */
   745         -  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
   746         -  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
   747         -  /* Methods above are valid for version 3 */
   748         -  /* Additional methods may be added in future releases */
   749         -};
   750         -
   751         -/*
   752         -** CAPI3REF: Standard File Control Opcodes
   753         -** KEYWORDS: {file control opcodes} {file control opcode}
   754         -**
   755         -** These integer constants are opcodes for the xFileControl method
   756         -** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
   757         -** interface.
   758         -**
   759         -** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
   760         -** opcode causes the xFileControl method to write the current state of
   761         -** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
   762         -** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
   763         -** into an integer that the pArg argument points to. This capability
   764         -** is used during testing and only needs to be supported when SQLITE_TEST
   765         -** is defined.
   766         -** <ul>
   767         -** <li>[[SQLITE_FCNTL_SIZE_HINT]]
   768         -** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
   769         -** layer a hint of how large the database file will grow to be during the
   770         -** current transaction.  This hint is not guaranteed to be accurate but it
   771         -** is often close.  The underlying VFS might choose to preallocate database
   772         -** file space based on this hint in order to help writes to the database
   773         -** file run faster.
   774         -**
   775         -** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
   776         -** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
   777         -** extends and truncates the database file in chunks of a size specified
   778         -** by the user. The fourth argument to [sqlite3_file_control()] should 
   779         -** point to an integer (type int) containing the new chunk-size to use
   780         -** for the nominated database. Allocating database file space in large
   781         -** chunks (say 1MB at a time), may reduce file-system fragmentation and
   782         -** improve performance on some systems.
   783         -**
   784         -** <li>[[SQLITE_FCNTL_FILE_POINTER]]
   785         -** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
   786         -** to the [sqlite3_file] object associated with a particular database
   787         -** connection.  See the [sqlite3_file_control()] documentation for
   788         -** additional information.
   789         -**
   790         -** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
   791         -** No longer in use.
   792         -**
   793         -** <li>[[SQLITE_FCNTL_SYNC]]
   794         -** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
   795         -** sent to the VFS immediately before the xSync method is invoked on a
   796         -** database file descriptor. Or, if the xSync method is not invoked 
   797         -** because the user has configured SQLite with 
   798         -** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place 
   799         -** of the xSync method. In most cases, the pointer argument passed with
   800         -** this file-control is NULL. However, if the database file is being synced
   801         -** as part of a multi-database commit, the argument points to a nul-terminated
   802         -** string containing the transactions master-journal file name. VFSes that 
   803         -** do not need this signal should silently ignore this opcode. Applications 
   804         -** should not call [sqlite3_file_control()] with this opcode as doing so may 
   805         -** disrupt the operation of the specialized VFSes that do require it.  
   806         -**
   807         -** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
   808         -** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
   809         -** and sent to the VFS after a transaction has been committed immediately
   810         -** but before the database is unlocked. VFSes that do not need this signal
   811         -** should silently ignore this opcode. Applications should not call
   812         -** [sqlite3_file_control()] with this opcode as doing so may disrupt the 
   813         -** operation of the specialized VFSes that do require it.  
   814         -**
   815         -** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
   816         -** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
   817         -** retry counts and intervals for certain disk I/O operations for the
   818         -** windows [VFS] in order to provide robustness in the presence of
   819         -** anti-virus programs.  By default, the windows VFS will retry file read,
   820         -** file write, and file delete operations up to 10 times, with a delay
   821         -** of 25 milliseconds before the first retry and with the delay increasing
   822         -** by an additional 25 milliseconds with each subsequent retry.  This
   823         -** opcode allows these two values (10 retries and 25 milliseconds of delay)
   824         -** to be adjusted.  The values are changed for all database connections
   825         -** within the same process.  The argument is a pointer to an array of two
   826         -** integers where the first integer i the new retry count and the second
   827         -** integer is the delay.  If either integer is negative, then the setting
   828         -** is not changed but instead the prior value of that setting is written
   829         -** into the array entry, allowing the current retry settings to be
   830         -** interrogated.  The zDbName parameter is ignored.
   831         -**
   832         -** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
   833         -** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
   834         -** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
   835         -** write ahead log and shared memory files used for transaction control
   836         -** are automatically deleted when the latest connection to the database
   837         -** closes.  Setting persistent WAL mode causes those files to persist after
   838         -** close.  Persisting the files is useful when other processes that do not
   839         -** have write permission on the directory containing the database file want
   840         -** to read the database file, as the WAL and shared memory files must exist
   841         -** in order for the database to be readable.  The fourth parameter to
   842         -** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
   843         -** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
   844         -** WAL mode.  If the integer is -1, then it is overwritten with the current
   845         -** WAL persistence setting.
   846         -**
   847         -** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
   848         -** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
   849         -** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
   850         -** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
   851         -** xDeviceCharacteristics methods. The fourth parameter to
   852         -** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
   853         -** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
   854         -** mode.  If the integer is -1, then it is overwritten with the current
   855         -** zero-damage mode setting.
   856         -**
   857         -** <li>[[SQLITE_FCNTL_OVERWRITE]]
   858         -** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
   859         -** a write transaction to indicate that, unless it is rolled back for some
   860         -** reason, the entire database file will be overwritten by the current 
   861         -** transaction. This is used by VACUUM operations.
   862         -**
   863         -** <li>[[SQLITE_FCNTL_VFSNAME]]
   864         -** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
   865         -** all [VFSes] in the VFS stack.  The names are of all VFS shims and the
   866         -** final bottom-level VFS are written into memory obtained from 
   867         -** [sqlite3_malloc()] and the result is stored in the char* variable
   868         -** that the fourth parameter of [sqlite3_file_control()] points to.
   869         -** The caller is responsible for freeing the memory when done.  As with
   870         -** all file-control actions, there is no guarantee that this will actually
   871         -** do anything.  Callers should initialize the char* variable to a NULL
   872         -** pointer in case this file-control is not implemented.  This file-control
   873         -** is intended for diagnostic use only.
   874         -**
   875         -** <li>[[SQLITE_FCNTL_PRAGMA]]
   876         -** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA] 
   877         -** file control is sent to the open [sqlite3_file] object corresponding
   878         -** to the database file to which the pragma statement refers. ^The argument
   879         -** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
   880         -** pointers to strings (char**) in which the second element of the array
   881         -** is the name of the pragma and the third element is the argument to the
   882         -** pragma or NULL if the pragma has no argument.  ^The handler for an
   883         -** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
   884         -** of the char** argument point to a string obtained from [sqlite3_mprintf()]
   885         -** or the equivalent and that string will become the result of the pragma or
   886         -** the error message if the pragma fails. ^If the
   887         -** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal 
   888         -** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
   889         -** file control returns [SQLITE_OK], then the parser assumes that the
   890         -** VFS has handled the PRAGMA itself and the parser generates a no-op
   891         -** prepared statement.  ^If the [SQLITE_FCNTL_PRAGMA] file control returns
   892         -** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
   893         -** that the VFS encountered an error while handling the [PRAGMA] and the
   894         -** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
   895         -** file control occurs at the beginning of pragma statement analysis and so
   896         -** it is able to override built-in [PRAGMA] statements.
   897         -**
   898         -** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
   899         -** ^The [SQLITE_FCNTL_BUSYHANDLER]
   900         -** file-control may be invoked by SQLite on the database file handle
   901         -** shortly after it is opened in order to provide a custom VFS with access
   902         -** to the connections busy-handler callback. The argument is of type (void **)
   903         -** - an array of two (void *) values. The first (void *) actually points
   904         -** to a function of type (int (*)(void *)). In order to invoke the connections
   905         -** busy-handler, this function should be invoked with the second (void *) in
   906         -** the array as the only argument. If it returns non-zero, then the operation
   907         -** should be retried. If it returns zero, the custom VFS should abandon the
   908         -** current operation.
   909         -**
   910         -** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
   911         -** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
   912         -** to have SQLite generate a
   913         -** temporary filename using the same algorithm that is followed to generate
   914         -** temporary filenames for TEMP tables and other internal uses.  The
   915         -** argument should be a char** which will be filled with the filename
   916         -** written into memory obtained from [sqlite3_malloc()].  The caller should
   917         -** invoke [sqlite3_free()] on the result to avoid a memory leak.
   918         -**
   919         -** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
   920         -** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
   921         -** maximum number of bytes that will be used for memory-mapped I/O.
   922         -** The argument is a pointer to a value of type sqlite3_int64 that
   923         -** is an advisory maximum number of bytes in the file to memory map.  The
   924         -** pointer is overwritten with the old value.  The limit is not changed if
   925         -** the value originally pointed to is negative, and so the current limit 
   926         -** can be queried by passing in a pointer to a negative number.  This
   927         -** file-control is used internally to implement [PRAGMA mmap_size].
   928         -**
   929         -** <li>[[SQLITE_FCNTL_TRACE]]
   930         -** The [SQLITE_FCNTL_TRACE] file control provides advisory information
   931         -** to the VFS about what the higher layers of the SQLite stack are doing.
   932         -** This file control is used by some VFS activity tracing [shims].
   933         -** The argument is a zero-terminated string.  Higher layers in the
   934         -** SQLite stack may generate instances of this file control if
   935         -** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
   936         -**
   937         -** <li>[[SQLITE_FCNTL_HAS_MOVED]]
   938         -** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
   939         -** pointer to an integer and it writes a boolean into that integer depending
   940         -** on whether or not the file has been renamed, moved, or deleted since it
   941         -** was first opened.
   942         -**
   943         -** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
   944         -** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging.  This
   945         -** opcode causes the xFileControl method to swap the file handle with the one
   946         -** pointed to by the pArg argument.  This capability is used during testing
   947         -** and only needs to be supported when SQLITE_TEST is defined.
   948         -**
   949         -** </ul>
   950         -*/
   951         -#define SQLITE_FCNTL_LOCKSTATE               1
   952         -#define SQLITE_GET_LOCKPROXYFILE             2
   953         -#define SQLITE_SET_LOCKPROXYFILE             3
   954         -#define SQLITE_LAST_ERRNO                    4
   955         -#define SQLITE_FCNTL_SIZE_HINT               5
   956         -#define SQLITE_FCNTL_CHUNK_SIZE              6
   957         -#define SQLITE_FCNTL_FILE_POINTER            7
   958         -#define SQLITE_FCNTL_SYNC_OMITTED            8
   959         -#define SQLITE_FCNTL_WIN32_AV_RETRY          9
   960         -#define SQLITE_FCNTL_PERSIST_WAL            10
   961         -#define SQLITE_FCNTL_OVERWRITE              11
   962         -#define SQLITE_FCNTL_VFSNAME                12
   963         -#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
   964         -#define SQLITE_FCNTL_PRAGMA                 14
   965         -#define SQLITE_FCNTL_BUSYHANDLER            15
   966         -#define SQLITE_FCNTL_TEMPFILENAME           16
   967         -#define SQLITE_FCNTL_MMAP_SIZE              18
   968         -#define SQLITE_FCNTL_TRACE                  19
   969         -#define SQLITE_FCNTL_HAS_MOVED              20
   970         -#define SQLITE_FCNTL_SYNC                   21
   971         -#define SQLITE_FCNTL_COMMIT_PHASETWO        22
   972         -#define SQLITE_FCNTL_WIN32_SET_HANDLE       23
   973         -
   974         -/*
   975         -** CAPI3REF: Mutex Handle
   976         -**
   977         -** The mutex module within SQLite defines [sqlite3_mutex] to be an
   978         -** abstract type for a mutex object.  The SQLite core never looks
   979         -** at the internal representation of an [sqlite3_mutex].  It only
   980         -** deals with pointers to the [sqlite3_mutex] object.
   981         -**
   982         -** Mutexes are created using [sqlite3_mutex_alloc()].
   983         -*/
   984         -typedef struct sqlite3_mutex sqlite3_mutex;
   985         -
   986         -/*
   987         -** CAPI3REF: OS Interface Object
   988         -**
   989         -** An instance of the sqlite3_vfs object defines the interface between
   990         -** the SQLite core and the underlying operating system.  The "vfs"
   991         -** in the name of the object stands for "virtual file system".  See
   992         -** the [VFS | VFS documentation] for further information.
   993         -**
   994         -** The value of the iVersion field is initially 1 but may be larger in
   995         -** future versions of SQLite.  Additional fields may be appended to this
   996         -** object when the iVersion value is increased.  Note that the structure
   997         -** of the sqlite3_vfs object changes in the transaction between
   998         -** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
   999         -** modified.
  1000         -**
  1001         -** The szOsFile field is the size of the subclassed [sqlite3_file]
  1002         -** structure used by this VFS.  mxPathname is the maximum length of
  1003         -** a pathname in this VFS.
  1004         -**
  1005         -** Registered sqlite3_vfs objects are kept on a linked list formed by
  1006         -** the pNext pointer.  The [sqlite3_vfs_register()]
  1007         -** and [sqlite3_vfs_unregister()] interfaces manage this list
  1008         -** in a thread-safe way.  The [sqlite3_vfs_find()] interface
  1009         -** searches the list.  Neither the application code nor the VFS
  1010         -** implementation should use the pNext pointer.
  1011         -**
  1012         -** The pNext field is the only field in the sqlite3_vfs
  1013         -** structure that SQLite will ever modify.  SQLite will only access
  1014         -** or modify this field while holding a particular static mutex.
  1015         -** The application should never modify anything within the sqlite3_vfs
  1016         -** object once the object has been registered.
  1017         -**
  1018         -** The zName field holds the name of the VFS module.  The name must
  1019         -** be unique across all VFS modules.
  1020         -**
  1021         -** [[sqlite3_vfs.xOpen]]
  1022         -** ^SQLite guarantees that the zFilename parameter to xOpen
  1023         -** is either a NULL pointer or string obtained
  1024         -** from xFullPathname() with an optional suffix added.
  1025         -** ^If a suffix is added to the zFilename parameter, it will
  1026         -** consist of a single "-" character followed by no more than
  1027         -** 11 alphanumeric and/or "-" characters.
  1028         -** ^SQLite further guarantees that
  1029         -** the string will be valid and unchanged until xClose() is
  1030         -** called. Because of the previous sentence,
  1031         -** the [sqlite3_file] can safely store a pointer to the
  1032         -** filename if it needs to remember the filename for some reason.
  1033         -** If the zFilename parameter to xOpen is a NULL pointer then xOpen
  1034         -** must invent its own temporary name for the file.  ^Whenever the 
  1035         -** xFilename parameter is NULL it will also be the case that the
  1036         -** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
  1037         -**
  1038         -** The flags argument to xOpen() includes all bits set in
  1039         -** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
  1040         -** or [sqlite3_open16()] is used, then flags includes at least
  1041         -** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
  1042         -** If xOpen() opens a file read-only then it sets *pOutFlags to
  1043         -** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
  1044         -**
  1045         -** ^(SQLite will also add one of the following flags to the xOpen()
  1046         -** call, depending on the object being opened:
  1047         -**
  1048         -** <ul>
  1049         -** <li>  [SQLITE_OPEN_MAIN_DB]
  1050         -** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
  1051         -** <li>  [SQLITE_OPEN_TEMP_DB]
  1052         -** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
  1053         -** <li>  [SQLITE_OPEN_TRANSIENT_DB]
  1054         -** <li>  [SQLITE_OPEN_SUBJOURNAL]
  1055         -** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
  1056         -** <li>  [SQLITE_OPEN_WAL]
  1057         -** </ul>)^
  1058         -**
  1059         -** The file I/O implementation can use the object type flags to
  1060         -** change the way it deals with files.  For example, an application
  1061         -** that does not care about crash recovery or rollback might make
  1062         -** the open of a journal file a no-op.  Writes to this journal would
  1063         -** also be no-ops, and any attempt to read the journal would return
  1064         -** SQLITE_IOERR.  Or the implementation might recognize that a database
  1065         -** file will be doing page-aligned sector reads and writes in a random
  1066         -** order and set up its I/O subsystem accordingly.
  1067         -**
  1068         -** SQLite might also add one of the following flags to the xOpen method:
  1069         -**
  1070         -** <ul>
  1071         -** <li> [SQLITE_OPEN_DELETEONCLOSE]
  1072         -** <li> [SQLITE_OPEN_EXCLUSIVE]
  1073         -** </ul>
  1074         -**
  1075         -** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
  1076         -** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
  1077         -** will be set for TEMP databases and their journals, transient
  1078         -** databases, and subjournals.
  1079         -**
  1080         -** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
  1081         -** with the [SQLITE_OPEN_CREATE] flag, which are both directly
  1082         -** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
  1083         -** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
  1084         -** SQLITE_OPEN_CREATE, is used to indicate that file should always
  1085         -** be created, and that it is an error if it already exists.
  1086         -** It is <i>not</i> used to indicate the file should be opened 
  1087         -** for exclusive access.
  1088         -**
  1089         -** ^At least szOsFile bytes of memory are allocated by SQLite
  1090         -** to hold the  [sqlite3_file] structure passed as the third
  1091         -** argument to xOpen.  The xOpen method does not have to
  1092         -** allocate the structure; it should just fill it in.  Note that
  1093         -** the xOpen method must set the sqlite3_file.pMethods to either
  1094         -** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
  1095         -** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
  1096         -** element will be valid after xOpen returns regardless of the success
  1097         -** or failure of the xOpen call.
  1098         -**
  1099         -** [[sqlite3_vfs.xAccess]]
  1100         -** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
  1101         -** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
  1102         -** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
  1103         -** to test whether a file is at least readable.   The file can be a
  1104         -** directory.
  1105         -**
  1106         -** ^SQLite will always allocate at least mxPathname+1 bytes for the
  1107         -** output buffer xFullPathname.  The exact size of the output buffer
  1108         -** is also passed as a parameter to both  methods. If the output buffer
  1109         -** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
  1110         -** handled as a fatal error by SQLite, vfs implementations should endeavor
  1111         -** to prevent this by setting mxPathname to a sufficiently large value.
  1112         -**
  1113         -** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
  1114         -** interfaces are not strictly a part of the filesystem, but they are
  1115         -** included in the VFS structure for completeness.
  1116         -** The xRandomness() function attempts to return nBytes bytes
  1117         -** of good-quality randomness into zOut.  The return value is
  1118         -** the actual number of bytes of randomness obtained.
  1119         -** The xSleep() method causes the calling thread to sleep for at
  1120         -** least the number of microseconds given.  ^The xCurrentTime()
  1121         -** method returns a Julian Day Number for the current date and time as
  1122         -** a floating point value.
  1123         -** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
  1124         -** Day Number multiplied by 86400000 (the number of milliseconds in 
  1125         -** a 24-hour day).  
  1126         -** ^SQLite will use the xCurrentTimeInt64() method to get the current
  1127         -** date and time if that method is available (if iVersion is 2 or 
  1128         -** greater and the function pointer is not NULL) and will fall back
  1129         -** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
  1130         -**
  1131         -** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
  1132         -** are not used by the SQLite core.  These optional interfaces are provided
  1133         -** by some VFSes to facilitate testing of the VFS code. By overriding 
  1134         -** system calls with functions under its control, a test program can
  1135         -** simulate faults and error conditions that would otherwise be difficult
  1136         -** or impossible to induce.  The set of system calls that can be overridden
  1137         -** varies from one VFS to another, and from one version of the same VFS to the
  1138         -** next.  Applications that use these interfaces must be prepared for any
  1139         -** or all of these interfaces to be NULL or for their behavior to change
  1140         -** from one release to the next.  Applications must not attempt to access
  1141         -** any of these methods if the iVersion of the VFS is less than 3.
  1142         -*/
  1143         -typedef struct sqlite3_vfs sqlite3_vfs;
  1144         -typedef void (*sqlite3_syscall_ptr)(void);
  1145         -struct sqlite3_vfs {
  1146         -  int iVersion;            /* Structure version number (currently 3) */
  1147         -  int szOsFile;            /* Size of subclassed sqlite3_file */
  1148         -  int mxPathname;          /* Maximum file pathname length */
  1149         -  sqlite3_vfs *pNext;      /* Next registered VFS */
  1150         -  const char *zName;       /* Name of this virtual file system */
  1151         -  void *pAppData;          /* Pointer to application-specific data */
  1152         -  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
  1153         -               int flags, int *pOutFlags);
  1154         -  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  1155         -  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  1156         -  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  1157         -  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  1158         -  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  1159         -  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  1160         -  void (*xDlClose)(sqlite3_vfs*, void*);
  1161         -  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  1162         -  int (*xSleep)(sqlite3_vfs*, int microseconds);
  1163         -  int (*xCurrentTime)(sqlite3_vfs*, double*);
  1164         -  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  1165         -  /*
  1166         -  ** The methods above are in version 1 of the sqlite_vfs object
  1167         -  ** definition.  Those that follow are added in version 2 or later
  1168         -  */
  1169         -  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  1170         -  /*
  1171         -  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  1172         -  ** Those below are for version 3 and greater.
  1173         -  */
  1174         -  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  1175         -  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  1176         -  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  1177         -  /*
  1178         -  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  1179         -  ** New fields may be appended in figure versions.  The iVersion
  1180         -  ** value will increment whenever this happens. 
  1181         -  */
  1182         -};
  1183         -
  1184         -/*
  1185         -** CAPI3REF: Flags for the xAccess VFS method
  1186         -**
  1187         -** These integer constants can be used as the third parameter to
  1188         -** the xAccess method of an [sqlite3_vfs] object.  They determine
  1189         -** what kind of permissions the xAccess method is looking for.
  1190         -** With SQLITE_ACCESS_EXISTS, the xAccess method
  1191         -** simply checks whether the file exists.
  1192         -** With SQLITE_ACCESS_READWRITE, the xAccess method
  1193         -** checks whether the named directory is both readable and writable
  1194         -** (in other words, if files can be added, removed, and renamed within
  1195         -** the directory).
  1196         -** The SQLITE_ACCESS_READWRITE constant is currently used only by the
  1197         -** [temp_store_directory pragma], though this could change in a future
  1198         -** release of SQLite.
  1199         -** With SQLITE_ACCESS_READ, the xAccess method
  1200         -** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
  1201         -** currently unused, though it might be used in a future release of
  1202         -** SQLite.
  1203         -*/
  1204         -#define SQLITE_ACCESS_EXISTS    0
  1205         -#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
  1206         -#define SQLITE_ACCESS_READ      2   /* Unused */
  1207         -
  1208         -/*
  1209         -** CAPI3REF: Flags for the xShmLock VFS method
  1210         -**
  1211         -** These integer constants define the various locking operations
  1212         -** allowed by the xShmLock method of [sqlite3_io_methods].  The
  1213         -** following are the only legal combinations of flags to the
  1214         -** xShmLock method:
  1215         -**
  1216         -** <ul>
  1217         -** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
  1218         -** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
  1219         -** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
  1220         -** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
  1221         -** </ul>
  1222         -**
  1223         -** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
  1224         -** was given no the corresponding lock.  
  1225         -**
  1226         -** The xShmLock method can transition between unlocked and SHARED or
  1227         -** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
  1228         -** and EXCLUSIVE.
  1229         -*/
  1230         -#define SQLITE_SHM_UNLOCK       1
  1231         -#define SQLITE_SHM_LOCK         2
  1232         -#define SQLITE_SHM_SHARED       4
  1233         -#define SQLITE_SHM_EXCLUSIVE    8
  1234         -
  1235         -/*
  1236         -** CAPI3REF: Maximum xShmLock index
  1237         -**
  1238         -** The xShmLock method on [sqlite3_io_methods] may use values
  1239         -** between 0 and this upper bound as its "offset" argument.
  1240         -** The SQLite core will never attempt to acquire or release a
  1241         -** lock outside of this range
  1242         -*/
  1243         -#define SQLITE_SHM_NLOCK        8
  1244         -
  1245         -
  1246         -/*
  1247         -** CAPI3REF: Initialize The SQLite Library
  1248         -**
  1249         -** ^The sqlite3_initialize() routine initializes the
  1250         -** SQLite library.  ^The sqlite3_shutdown() routine
  1251         -** deallocates any resources that were allocated by sqlite3_initialize().
  1252         -** These routines are designed to aid in process initialization and
  1253         -** shutdown on embedded systems.  Workstation applications using
  1254         -** SQLite normally do not need to invoke either of these routines.
  1255         -**
  1256         -** A call to sqlite3_initialize() is an "effective" call if it is
  1257         -** the first time sqlite3_initialize() is invoked during the lifetime of
  1258         -** the process, or if it is the first time sqlite3_initialize() is invoked
  1259         -** following a call to sqlite3_shutdown().  ^(Only an effective call
  1260         -** of sqlite3_initialize() does any initialization.  All other calls
  1261         -** are harmless no-ops.)^
  1262         -**
  1263         -** A call to sqlite3_shutdown() is an "effective" call if it is the first
  1264         -** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
  1265         -** an effective call to sqlite3_shutdown() does any deinitialization.
  1266         -** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
  1267         -**
  1268         -** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
  1269         -** is not.  The sqlite3_shutdown() interface must only be called from a
  1270         -** single thread.  All open [database connections] must be closed and all
  1271         -** other SQLite resources must be deallocated prior to invoking
  1272         -** sqlite3_shutdown().
  1273         -**
  1274         -** Among other things, ^sqlite3_initialize() will invoke
  1275         -** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
  1276         -** will invoke sqlite3_os_end().
  1277         -**
  1278         -** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
  1279         -** ^If for some reason, sqlite3_initialize() is unable to initialize
  1280         -** the library (perhaps it is unable to allocate a needed resource such
  1281         -** as a mutex) it returns an [error code] other than [SQLITE_OK].
  1282         -**
  1283         -** ^The sqlite3_initialize() routine is called internally by many other
  1284         -** SQLite interfaces so that an application usually does not need to
  1285         -** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
  1286         -** calls sqlite3_initialize() so the SQLite library will be automatically
  1287         -** initialized when [sqlite3_open()] is called if it has not be initialized
  1288         -** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
  1289         -** compile-time option, then the automatic calls to sqlite3_initialize()
  1290         -** are omitted and the application must call sqlite3_initialize() directly
  1291         -** prior to using any other SQLite interface.  For maximum portability,
  1292         -** it is recommended that applications always invoke sqlite3_initialize()
  1293         -** directly prior to using any other SQLite interface.  Future releases
  1294         -** of SQLite may require this.  In other words, the behavior exhibited
  1295         -** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
  1296         -** default behavior in some future release of SQLite.
  1297         -**
  1298         -** The sqlite3_os_init() routine does operating-system specific
  1299         -** initialization of the SQLite library.  The sqlite3_os_end()
  1300         -** routine undoes the effect of sqlite3_os_init().  Typical tasks
  1301         -** performed by these routines include allocation or deallocation
  1302         -** of static resources, initialization of global variables,
  1303         -** setting up a default [sqlite3_vfs] module, or setting up
  1304         -** a default configuration using [sqlite3_config()].
  1305         -**
  1306         -** The application should never invoke either sqlite3_os_init()
  1307         -** or sqlite3_os_end() directly.  The application should only invoke
  1308         -** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
  1309         -** interface is called automatically by sqlite3_initialize() and
  1310         -** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
  1311         -** implementations for sqlite3_os_init() and sqlite3_os_end()
  1312         -** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
  1313         -** When [custom builds | built for other platforms]
  1314         -** (using the [SQLITE_OS_OTHER=1] compile-time
  1315         -** option) the application must supply a suitable implementation for
  1316         -** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
  1317         -** implementation of sqlite3_os_init() or sqlite3_os_end()
  1318         -** must return [SQLITE_OK] on success and some other [error code] upon
  1319         -** failure.
  1320         -*/
  1321         -SQLITE_API int sqlite3_initialize(void);
  1322         -SQLITE_API int sqlite3_shutdown(void);
  1323         -SQLITE_API int sqlite3_os_init(void);
  1324         -SQLITE_API int sqlite3_os_end(void);
  1325         -
  1326         -/*
  1327         -** CAPI3REF: Configuring The SQLite Library
  1328         -**
  1329         -** The sqlite3_config() interface is used to make global configuration
  1330         -** changes to SQLite in order to tune SQLite to the specific needs of
  1331         -** the application.  The default configuration is recommended for most
  1332         -** applications and so this routine is usually not necessary.  It is
  1333         -** provided to support rare applications with unusual needs.
  1334         -**
  1335         -** The sqlite3_config() interface is not threadsafe.  The application
  1336         -** must insure that no other SQLite interfaces are invoked by other
  1337         -** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
  1338         -** may only be invoked prior to library initialization using
  1339         -** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
  1340         -** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
  1341         -** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
  1342         -** Note, however, that ^sqlite3_config() can be called as part of the
  1343         -** implementation of an application-defined [sqlite3_os_init()].
  1344         -**
  1345         -** The first argument to sqlite3_config() is an integer
  1346         -** [configuration option] that determines
  1347         -** what property of SQLite is to be configured.  Subsequent arguments
  1348         -** vary depending on the [configuration option]
  1349         -** in the first argument.
  1350         -**
  1351         -** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
  1352         -** ^If the option is unknown or SQLite is unable to set the option
  1353         -** then this routine returns a non-zero [error code].
  1354         -*/
  1355         -SQLITE_API int sqlite3_config(int, ...);
  1356         -
  1357         -/*
  1358         -** CAPI3REF: Configure database connections
  1359         -**
  1360         -** The sqlite3_db_config() interface is used to make configuration
  1361         -** changes to a [database connection].  The interface is similar to
  1362         -** [sqlite3_config()] except that the changes apply to a single
  1363         -** [database connection] (specified in the first argument).
  1364         -**
  1365         -** The second argument to sqlite3_db_config(D,V,...)  is the
  1366         -** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
  1367         -** that indicates what aspect of the [database connection] is being configured.
  1368         -** Subsequent arguments vary depending on the configuration verb.
  1369         -**
  1370         -** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
  1371         -** the call is considered successful.
  1372         -*/
  1373         -SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
  1374         -
  1375         -/*
  1376         -** CAPI3REF: Memory Allocation Routines
  1377         -**
  1378         -** An instance of this object defines the interface between SQLite
  1379         -** and low-level memory allocation routines.
  1380         -**
  1381         -** This object is used in only one place in the SQLite interface.
  1382         -** A pointer to an instance of this object is the argument to
  1383         -** [sqlite3_config()] when the configuration option is
  1384         -** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  
  1385         -** By creating an instance of this object
  1386         -** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
  1387         -** during configuration, an application can specify an alternative
  1388         -** memory allocation subsystem for SQLite to use for all of its
  1389         -** dynamic memory needs.
  1390         -**
  1391         -** Note that SQLite comes with several [built-in memory allocators]
  1392         -** that are perfectly adequate for the overwhelming majority of applications
  1393         -** and that this object is only useful to a tiny minority of applications
  1394         -** with specialized memory allocation requirements.  This object is
  1395         -** also used during testing of SQLite in order to specify an alternative
  1396         -** memory allocator that simulates memory out-of-memory conditions in
  1397         -** order to verify that SQLite recovers gracefully from such
  1398         -** conditions.
  1399         -**
  1400         -** The xMalloc, xRealloc, and xFree methods must work like the
  1401         -** malloc(), realloc() and free() functions from the standard C library.
  1402         -** ^SQLite guarantees that the second argument to
  1403         -** xRealloc is always a value returned by a prior call to xRoundup.
  1404         -**
  1405         -** xSize should return the allocated size of a memory allocation
  1406         -** previously obtained from xMalloc or xRealloc.  The allocated size
  1407         -** is always at least as big as the requested size but may be larger.
  1408         -**
  1409         -** The xRoundup method returns what would be the allocated size of
  1410         -** a memory allocation given a particular requested size.  Most memory
  1411         -** allocators round up memory allocations at least to the next multiple
  1412         -** of 8.  Some allocators round up to a larger multiple or to a power of 2.
  1413         -** Every memory allocation request coming in through [sqlite3_malloc()]
  1414         -** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, 
  1415         -** that causes the corresponding memory allocation to fail.
  1416         -**
  1417         -** The xInit method initializes the memory allocator.  For example,
  1418         -** it might allocate any require mutexes or initialize internal data
  1419         -** structures.  The xShutdown method is invoked (indirectly) by
  1420         -** [sqlite3_shutdown()] and should deallocate any resources acquired
  1421         -** by xInit.  The pAppData pointer is used as the only parameter to
  1422         -** xInit and xShutdown.
  1423         -**
  1424         -** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
  1425         -** the xInit method, so the xInit method need not be threadsafe.  The
  1426         -** xShutdown method is only called from [sqlite3_shutdown()] so it does
  1427         -** not need to be threadsafe either.  For all other methods, SQLite
  1428         -** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
  1429         -** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
  1430         -** it is by default) and so the methods are automatically serialized.
  1431         -** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
  1432         -** methods must be threadsafe or else make their own arrangements for
  1433         -** serialization.
  1434         -**
  1435         -** SQLite will never invoke xInit() more than once without an intervening
  1436         -** call to xShutdown().
  1437         -*/
  1438         -typedef struct sqlite3_mem_methods sqlite3_mem_methods;
  1439         -struct sqlite3_mem_methods {
  1440         -  void *(*xMalloc)(int);         /* Memory allocation function */
  1441         -  void (*xFree)(void*);          /* Free a prior allocation */
  1442         -  void *(*xRealloc)(void*,int);  /* Resize an allocation */
  1443         -  int (*xSize)(void*);           /* Return the size of an allocation */
  1444         -  int (*xRoundup)(int);          /* Round up request size to allocation size */
  1445         -  int (*xInit)(void*);           /* Initialize the memory allocator */
  1446         -  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  1447         -  void *pAppData;                /* Argument to xInit() and xShutdown() */
  1448         -};
  1449         -
  1450         -/*
  1451         -** CAPI3REF: Configuration Options
  1452         -** KEYWORDS: {configuration option}
  1453         -**
  1454         -** These constants are the available integer configuration options that
  1455         -** can be passed as the first argument to the [sqlite3_config()] interface.
  1456         -**
  1457         -** New configuration options may be added in future releases of SQLite.
  1458         -** Existing configuration options might be discontinued.  Applications
  1459         -** should check the return code from [sqlite3_config()] to make sure that
  1460         -** the call worked.  The [sqlite3_config()] interface will return a
  1461         -** non-zero [error code] if a discontinued or unsupported configuration option
  1462         -** is invoked.
  1463         -**
  1464         -** <dl>
  1465         -** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
  1466         -** <dd>There are no arguments to this option.  ^This option sets the
  1467         -** [threading mode] to Single-thread.  In other words, it disables
  1468         -** all mutexing and puts SQLite into a mode where it can only be used
  1469         -** by a single thread.   ^If SQLite is compiled with
  1470         -** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1471         -** it is not possible to change the [threading mode] from its default
  1472         -** value of Single-thread and so [sqlite3_config()] will return 
  1473         -** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
  1474         -** configuration option.</dd>
  1475         -**
  1476         -** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
  1477         -** <dd>There are no arguments to this option.  ^This option sets the
  1478         -** [threading mode] to Multi-thread.  In other words, it disables
  1479         -** mutexing on [database connection] and [prepared statement] objects.
  1480         -** The application is responsible for serializing access to
  1481         -** [database connections] and [prepared statements].  But other mutexes
  1482         -** are enabled so that SQLite will be safe to use in a multi-threaded
  1483         -** environment as long as no two threads attempt to use the same
  1484         -** [database connection] at the same time.  ^If SQLite is compiled with
  1485         -** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1486         -** it is not possible to set the Multi-thread [threading mode] and
  1487         -** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1488         -** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
  1489         -**
  1490         -** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
  1491         -** <dd>There are no arguments to this option.  ^This option sets the
  1492         -** [threading mode] to Serialized. In other words, this option enables
  1493         -** all mutexes including the recursive
  1494         -** mutexes on [database connection] and [prepared statement] objects.
  1495         -** In this mode (which is the default when SQLite is compiled with
  1496         -** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
  1497         -** to [database connections] and [prepared statements] so that the
  1498         -** application is free to use the same [database connection] or the
  1499         -** same [prepared statement] in different threads at the same time.
  1500         -** ^If SQLite is compiled with
  1501         -** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1502         -** it is not possible to set the Serialized [threading mode] and
  1503         -** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
  1504         -** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
  1505         -**
  1506         -** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
  1507         -** <dd> ^(This option takes a single argument which is a pointer to an
  1508         -** instance of the [sqlite3_mem_methods] structure.  The argument specifies
  1509         -** alternative low-level memory allocation routines to be used in place of
  1510         -** the memory allocation routines built into SQLite.)^ ^SQLite makes
  1511         -** its own private copy of the content of the [sqlite3_mem_methods] structure
  1512         -** before the [sqlite3_config()] call returns.</dd>
  1513         -**
  1514         -** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
  1515         -** <dd> ^(This option takes a single argument which is a pointer to an
  1516         -** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
  1517         -** structure is filled with the currently defined memory allocation routines.)^
  1518         -** This option can be used to overload the default memory allocation
  1519         -** routines with a wrapper that simulations memory allocation failure or
  1520         -** tracks memory usage, for example. </dd>
  1521         -**
  1522         -** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1523         -** <dd> ^This option takes single argument of type int, interpreted as a 
  1524         -** boolean, which enables or disables the collection of memory allocation 
  1525         -** statistics. ^(When memory allocation statistics are disabled, the 
  1526         -** following SQLite interfaces become non-operational:
  1527         -**   <ul>
  1528         -**   <li> [sqlite3_memory_used()]
  1529         -**   <li> [sqlite3_memory_highwater()]
  1530         -**   <li> [sqlite3_soft_heap_limit64()]
  1531         -**   <li> [sqlite3_status()]
  1532         -**   </ul>)^
  1533         -** ^Memory allocation statistics are enabled by default unless SQLite is
  1534         -** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
  1535         -** allocation statistics are disabled by default.
  1536         -** </dd>
  1537         -**
  1538         -** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
  1539         -** <dd> ^This option specifies a static memory buffer that SQLite can use for
  1540         -** scratch memory.  There are three arguments:  A pointer an 8-byte
  1541         -** aligned memory buffer from which the scratch allocations will be
  1542         -** drawn, the size of each scratch allocation (sz),
  1543         -** and the maximum number of scratch allocations (N).  The sz
  1544         -** argument must be a multiple of 16.
  1545         -** The first argument must be a pointer to an 8-byte aligned buffer
  1546         -** of at least sz*N bytes of memory.
  1547         -** ^SQLite will use no more than two scratch buffers per thread.  So
  1548         -** N should be set to twice the expected maximum number of threads.
  1549         -** ^SQLite will never require a scratch buffer that is more than 6
  1550         -** times the database page size. ^If SQLite needs needs additional
  1551         -** scratch memory beyond what is provided by this configuration option, then 
  1552         -** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
  1553         -**
  1554         -** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1555         -** <dd> ^This option specifies a static memory buffer that SQLite can use for
  1556         -** the database page cache with the default page cache implementation.  
  1557         -** This configuration should not be used if an application-define page
  1558         -** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
  1559         -** There are three arguments to this option: A pointer to 8-byte aligned
  1560         -** memory, the size of each page buffer (sz), and the number of pages (N).
  1561         -** The sz argument should be the size of the largest database page
  1562         -** (a power of two between 512 and 32768) plus a little extra for each
  1563         -** page header.  ^The page header size is 20 to 40 bytes depending on
  1564         -** the host architecture.  ^It is harmless, apart from the wasted memory,
  1565         -** to make sz a little too large.  The first
  1566         -** argument should point to an allocation of at least sz*N bytes of memory.
  1567         -** ^SQLite will use the memory provided by the first argument to satisfy its
  1568         -** memory needs for the first N pages that it adds to cache.  ^If additional
  1569         -** page cache memory is needed beyond what is provided by this option, then
  1570         -** SQLite goes to [sqlite3_malloc()] for the additional storage space.
  1571         -** The pointer in the first argument must
  1572         -** be aligned to an 8-byte boundary or subsequent behavior of SQLite
  1573         -** will be undefined.</dd>
  1574         -**
  1575         -** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
  1576         -** <dd> ^This option specifies a static memory buffer that SQLite will use
  1577         -** for all of its dynamic memory allocation needs beyond those provided
  1578         -** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
  1579         -** There are three arguments: An 8-byte aligned pointer to the memory,
  1580         -** the number of bytes in the memory buffer, and the minimum allocation size.
  1581         -** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
  1582         -** to using its default memory allocator (the system malloc() implementation),
  1583         -** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
  1584         -** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
  1585         -** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
  1586         -** allocator is engaged to handle all of SQLites memory allocation needs.
  1587         -** The first pointer (the memory pointer) must be aligned to an 8-byte
  1588         -** boundary or subsequent behavior of SQLite will be undefined.
  1589         -** The minimum allocation size is capped at 2**12. Reasonable values
  1590         -** for the minimum allocation size are 2**5 through 2**8.</dd>
  1591         -**
  1592         -** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
  1593         -** <dd> ^(This option takes a single argument which is a pointer to an
  1594         -** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
  1595         -** alternative low-level mutex routines to be used in place
  1596         -** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the
  1597         -** content of the [sqlite3_mutex_methods] structure before the call to
  1598         -** [sqlite3_config()] returns. ^If SQLite is compiled with
  1599         -** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1600         -** the entire mutexing subsystem is omitted from the build and hence calls to
  1601         -** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
  1602         -** return [SQLITE_ERROR].</dd>
  1603         -**
  1604         -** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
  1605         -** <dd> ^(This option takes a single argument which is a pointer to an
  1606         -** instance of the [sqlite3_mutex_methods] structure.  The
  1607         -** [sqlite3_mutex_methods]
  1608         -** structure is filled with the currently defined mutex routines.)^
  1609         -** This option can be used to overload the default mutex allocation
  1610         -** routines with a wrapper used to track mutex usage for performance
  1611         -** profiling or testing, for example.   ^If SQLite is compiled with
  1612         -** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1613         -** the entire mutexing subsystem is omitted from the build and hence calls to
  1614         -** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
  1615         -** return [SQLITE_ERROR].</dd>
  1616         -**
  1617         -** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
  1618         -** <dd> ^(This option takes two arguments that determine the default
  1619         -** memory allocation for the lookaside memory allocator on each
  1620         -** [database connection].  The first argument is the
  1621         -** size of each lookaside buffer slot and the second is the number of
  1622         -** slots allocated to each database connection.)^  ^(This option sets the
  1623         -** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1624         -** verb to [sqlite3_db_config()] can be used to change the lookaside
  1625         -** configuration on individual connections.)^ </dd>
  1626         -**
  1627         -** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
  1628         -** <dd> ^(This option takes a single argument which is a pointer to
  1629         -** an [sqlite3_pcache_methods2] object.  This object specifies the interface
  1630         -** to a custom page cache implementation.)^  ^SQLite makes a copy of the
  1631         -** object and uses it for page cache memory allocations.</dd>
  1632         -**
  1633         -** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
  1634         -** <dd> ^(This option takes a single argument which is a pointer to an
  1635         -** [sqlite3_pcache_methods2] object.  SQLite copies of the current
  1636         -** page cache implementation into that object.)^ </dd>
  1637         -**
  1638         -** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
  1639         -** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
  1640         -** global [error log].
  1641         -** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
  1642         -** function with a call signature of void(*)(void*,int,const char*), 
  1643         -** and a pointer to void. ^If the function pointer is not NULL, it is
  1644         -** invoked by [sqlite3_log()] to process each logging event.  ^If the
  1645         -** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
  1646         -** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
  1647         -** passed through as the first parameter to the application-defined logger
  1648         -** function whenever that function is invoked.  ^The second parameter to
  1649         -** the logger function is a copy of the first parameter to the corresponding
  1650         -** [sqlite3_log()] call and is intended to be a [result code] or an
  1651         -** [extended result code].  ^The third parameter passed to the logger is
  1652         -** log message after formatting via [sqlite3_snprintf()].
  1653         -** The SQLite logging interface is not reentrant; the logger function
  1654         -** supplied by the application must not invoke any SQLite interface.
  1655         -** In a multi-threaded application, the application-defined logger
  1656         -** function must be threadsafe. </dd>
  1657         -**
  1658         -** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
  1659         -** <dd>^(This option takes a single argument of type int. If non-zero, then
  1660         -** URI handling is globally enabled. If the parameter is zero, then URI handling
  1661         -** is globally disabled.)^ ^If URI handling is globally enabled, all filenames
  1662         -** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
  1663         -** specified as part of [ATTACH] commands are interpreted as URIs, regardless
  1664         -** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
  1665         -** connection is opened. ^If it is globally disabled, filenames are
  1666         -** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
  1667         -** database connection is opened. ^(By default, URI handling is globally
  1668         -** disabled. The default value may be changed by compiling with the
  1669         -** [SQLITE_USE_URI] symbol defined.)^
  1670         -**
  1671         -** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
  1672         -** <dd>^This option takes a single integer argument which is interpreted as
  1673         -** a boolean in order to enable or disable the use of covering indices for
  1674         -** full table scans in the query optimizer.  ^The default setting is determined
  1675         -** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
  1676         -** if that compile-time option is omitted.
  1677         -** The ability to disable the use of covering indices for full table scans
  1678         -** is because some incorrectly coded legacy applications might malfunction
  1679         -** when the optimization is enabled.  Providing the ability to
  1680         -** disable the optimization allows the older, buggy application code to work
  1681         -** without change even with newer versions of SQLite.
  1682         -**
  1683         -** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
  1684         -** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
  1685         -** <dd> These options are obsolete and should not be used by new code.
  1686         -** They are retained for backwards compatibility but are now no-ops.
  1687         -** </dd>
  1688         -**
  1689         -** [[SQLITE_CONFIG_SQLLOG]]
  1690         -** <dt>SQLITE_CONFIG_SQLLOG
  1691         -** <dd>This option is only available if sqlite is compiled with the
  1692         -** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
  1693         -** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
  1694         -** The second should be of type (void*). The callback is invoked by the library
  1695         -** in three separate circumstances, identified by the value passed as the
  1696         -** fourth parameter. If the fourth parameter is 0, then the database connection
  1697         -** passed as the second argument has just been opened. The third argument
  1698         -** points to a buffer containing the name of the main database file. If the
  1699         -** fourth parameter is 1, then the SQL statement that the third parameter
  1700         -** points to has just been executed. Or, if the fourth parameter is 2, then
  1701         -** the connection being passed as the second parameter is being closed. The
  1702         -** third parameter is passed NULL In this case.  An example of using this
  1703         -** configuration option can be seen in the "test_sqllog.c" source file in
  1704         -** the canonical SQLite source tree.</dd>
  1705         -**
  1706         -** [[SQLITE_CONFIG_MMAP_SIZE]]
  1707         -** <dt>SQLITE_CONFIG_MMAP_SIZE
  1708         -** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
  1709         -** that are the default mmap size limit (the default setting for
  1710         -** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
  1711         -** ^The default setting can be overridden by each database connection using
  1712         -** either the [PRAGMA mmap_size] command, or by using the
  1713         -** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size
  1714         -** cannot be changed at run-time.  Nor may the maximum allowed mmap size
  1715         -** exceed the compile-time maximum mmap size set by the
  1716         -** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
  1717         -** ^If either argument to this option is negative, then that argument is
  1718         -** changed to its compile-time default.
  1719         -**
  1720         -** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
  1721         -** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
  1722         -** <dd>^This option is only available if SQLite is compiled for Windows
  1723         -** with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
  1724         -** SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
  1725         -** that specifies the maximum size of the created heap.
  1726         -** </dl>
  1727         -*/
  1728         -#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
  1729         -#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
  1730         -#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
  1731         -#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
  1732         -#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
  1733         -#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
  1734         -#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
  1735         -#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
  1736         -#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
  1737         -#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
  1738         -#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
  1739         -/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
  1740         -#define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
  1741         -#define SQLITE_CONFIG_PCACHE       14  /* no-op */
  1742         -#define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
  1743         -#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
  1744         -#define SQLITE_CONFIG_URI          17  /* int */
  1745         -#define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
  1746         -#define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
  1747         -#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
  1748         -#define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
  1749         -#define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
  1750         -#define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
  1751         -
  1752         -/*
  1753         -** CAPI3REF: Database Connection Configuration Options
  1754         -**
  1755         -** These constants are the available integer configuration options that
  1756         -** can be passed as the second argument to the [sqlite3_db_config()] interface.
  1757         -**
  1758         -** New configuration options may be added in future releases of SQLite.
  1759         -** Existing configuration options might be discontinued.  Applications
  1760         -** should check the return code from [sqlite3_db_config()] to make sure that
  1761         -** the call worked.  ^The [sqlite3_db_config()] interface will return a
  1762         -** non-zero [error code] if a discontinued or unsupported configuration option
  1763         -** is invoked.
  1764         -**
  1765         -** <dl>
  1766         -** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
  1767         -** <dd> ^This option takes three additional arguments that determine the 
  1768         -** [lookaside memory allocator] configuration for the [database connection].
  1769         -** ^The first argument (the third parameter to [sqlite3_db_config()] is a
  1770         -** pointer to a memory buffer to use for lookaside memory.
  1771         -** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
  1772         -** may be NULL in which case SQLite will allocate the
  1773         -** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
  1774         -** size of each lookaside buffer slot.  ^The third argument is the number of
  1775         -** slots.  The size of the buffer in the first argument must be greater than
  1776         -** or equal to the product of the second and third arguments.  The buffer
  1777         -** must be aligned to an 8-byte boundary.  ^If the second argument to
  1778         -** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
  1779         -** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
  1780         -** configuration for a database connection can only be changed when that
  1781         -** connection is not currently using lookaside memory, or in other words
  1782         -** when the "current value" returned by
  1783         -** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
  1784         -** Any attempt to change the lookaside memory configuration when lookaside
  1785         -** memory is in use leaves the configuration unchanged and returns 
  1786         -** [SQLITE_BUSY].)^</dd>
  1787         -**
  1788         -** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
  1789         -** <dd> ^This option is used to enable or disable the enforcement of
  1790         -** [foreign key constraints].  There should be two additional arguments.
  1791         -** The first argument is an integer which is 0 to disable FK enforcement,
  1792         -** positive to enable FK enforcement or negative to leave FK enforcement
  1793         -** unchanged.  The second parameter is a pointer to an integer into which
  1794         -** is written 0 or 1 to indicate whether FK enforcement is off or on
  1795         -** following this call.  The second parameter may be a NULL pointer, in
  1796         -** which case the FK enforcement setting is not reported back. </dd>
  1797         -**
  1798         -** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
  1799         -** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
  1800         -** There should be two additional arguments.
  1801         -** The first argument is an integer which is 0 to disable triggers,
  1802         -** positive to enable triggers or negative to leave the setting unchanged.
  1803         -** The second parameter is a pointer to an integer into which
  1804         -** is written 0 or 1 to indicate whether triggers are disabled or enabled
  1805         -** following this call.  The second parameter may be a NULL pointer, in
  1806         -** which case the trigger setting is not reported back. </dd>
  1807         -**
  1808         -** </dl>
  1809         -*/
  1810         -#define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
  1811         -#define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
  1812         -#define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */
  1813         -
  1814         -
  1815         -/*
  1816         -** CAPI3REF: Enable Or Disable Extended Result Codes
  1817         -**
  1818         -** ^The sqlite3_extended_result_codes() routine enables or disables the
  1819         -** [extended result codes] feature of SQLite. ^The extended result
  1820         -** codes are disabled by default for historical compatibility.
  1821         -*/
  1822         -SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
  1823         -
  1824         -/*
  1825         -** CAPI3REF: Last Insert Rowid
  1826         -**
  1827         -** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
  1828         -** has a unique 64-bit signed
  1829         -** integer key called the [ROWID | "rowid"]. ^The rowid is always available
  1830         -** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  1831         -** names are not also used by explicitly declared columns. ^If
  1832         -** the table has a column of type [INTEGER PRIMARY KEY] then that column
  1833         -** is another alias for the rowid.
  1834         -**
  1835         -** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the 
  1836         -** most recent successful [INSERT] into a rowid table or [virtual table]
  1837         -** on database connection D.
  1838         -** ^Inserts into [WITHOUT ROWID] tables are not recorded.
  1839         -** ^If no successful [INSERT]s into rowid tables
  1840         -** have ever occurred on the database connection D, 
  1841         -** then sqlite3_last_insert_rowid(D) returns zero.
  1842         -**
  1843         -** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
  1844         -** method, then this routine will return the [rowid] of the inserted
  1845         -** row as long as the trigger or virtual table method is running.
  1846         -** But once the trigger or virtual table method ends, the value returned 
  1847         -** by this routine reverts to what it was before the trigger or virtual
  1848         -** table method began.)^
  1849         -**
  1850         -** ^An [INSERT] that fails due to a constraint violation is not a
  1851         -** successful [INSERT] and does not change the value returned by this
  1852         -** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  1853         -** and INSERT OR ABORT make no changes to the return value of this
  1854         -** routine when their insertion fails.  ^(When INSERT OR REPLACE
  1855         -** encounters a constraint violation, it does not fail.  The
  1856         -** INSERT continues to completion after deleting rows that caused
  1857         -** the constraint problem so INSERT OR REPLACE will always change
  1858         -** the return value of this interface.)^
  1859         -**
  1860         -** ^For the purposes of this routine, an [INSERT] is considered to
  1861         -** be successful even if it is subsequently rolled back.
  1862         -**
  1863         -** This function is accessible to SQL statements via the
  1864         -** [last_insert_rowid() SQL function].
  1865         -**
  1866         -** If a separate thread performs a new [INSERT] on the same
  1867         -** database connection while the [sqlite3_last_insert_rowid()]
  1868         -** function is running and thus changes the last insert [rowid],
  1869         -** then the value returned by [sqlite3_last_insert_rowid()] is
  1870         -** unpredictable and might not equal either the old or the new
  1871         -** last insert [rowid].
  1872         -*/
  1873         -SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  1874         -
  1875         -/*
  1876         -** CAPI3REF: Count The Number Of Rows Modified
  1877         -**
  1878         -** ^This function returns the number of database rows that were changed
  1879         -** or inserted or deleted by the most recently completed SQL statement
  1880         -** on the [database connection] specified by the first parameter.
  1881         -** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
  1882         -** or [DELETE] statement are counted.  Auxiliary changes caused by
  1883         -** triggers or [foreign key actions] are not counted.)^ Use the
  1884         -** [sqlite3_total_changes()] function to find the total number of changes
  1885         -** including changes caused by triggers and foreign key actions.
  1886         -**
  1887         -** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
  1888         -** are not counted.  Only real table changes are counted.
  1889         -**
  1890         -** ^(A "row change" is a change to a single row of a single table
  1891         -** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
  1892         -** are changed as side effects of [REPLACE] constraint resolution,
  1893         -** rollback, ABORT processing, [DROP TABLE], or by any other
  1894         -** mechanisms do not count as direct row changes.)^
  1895         -**
  1896         -** A "trigger context" is a scope of execution that begins and
  1897         -** ends with the script of a [CREATE TRIGGER | trigger]. 
  1898         -** Most SQL statements are
  1899         -** evaluated outside of any trigger.  This is the "top level"
  1900         -** trigger context.  If a trigger fires from the top level, a
  1901         -** new trigger context is entered for the duration of that one
  1902         -** trigger.  Subtriggers create subcontexts for their duration.
  1903         -**
  1904         -** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
  1905         -** not create a new trigger context.
  1906         -**
  1907         -** ^This function returns the number of direct row changes in the
  1908         -** most recent INSERT, UPDATE, or DELETE statement within the same
  1909         -** trigger context.
  1910         -**
  1911         -** ^Thus, when called from the top level, this function returns the
  1912         -** number of changes in the most recent INSERT, UPDATE, or DELETE
  1913         -** that also occurred at the top level.  ^(Within the body of a trigger,
  1914         -** the sqlite3_changes() interface can be called to find the number of
  1915         -** changes in the most recently completed INSERT, UPDATE, or DELETE
  1916         -** statement within the body of the same trigger.
  1917         -** However, the number returned does not include changes
  1918         -** caused by subtriggers since those have their own context.)^
  1919         -**
  1920         -** See also the [sqlite3_total_changes()] interface, the
  1921         -** [count_changes pragma], and the [changes() SQL function].
  1922         -**
  1923         -** If a separate thread makes changes on the same database connection
  1924         -** while [sqlite3_changes()] is running then the value returned
  1925         -** is unpredictable and not meaningful.
  1926         -*/
  1927         -SQLITE_API int sqlite3_changes(sqlite3*);
  1928         -
  1929         -/*
  1930         -** CAPI3REF: Total Number Of Rows Modified
  1931         -**
  1932         -** ^This function returns the number of row changes caused by [INSERT],
  1933         -** [UPDATE] or [DELETE] statements since the [database connection] was opened.
  1934         -** ^(The count returned by sqlite3_total_changes() includes all changes
  1935         -** from all [CREATE TRIGGER | trigger] contexts and changes made by
  1936         -** [foreign key actions]. However,
  1937         -** the count does not include changes used to implement [REPLACE] constraints,
  1938         -** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The
  1939         -** count does not include rows of views that fire an [INSTEAD OF trigger],
  1940         -** though if the INSTEAD OF trigger makes changes of its own, those changes 
  1941         -** are counted.)^
  1942         -** ^The sqlite3_total_changes() function counts the changes as soon as
  1943         -** the statement that makes them is completed (when the statement handle
  1944         -** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
  1945         -**
  1946         -** See also the [sqlite3_changes()] interface, the
  1947         -** [count_changes pragma], and the [total_changes() SQL function].
  1948         -**
  1949         -** If a separate thread makes changes on the same database connection
  1950         -** while [sqlite3_total_changes()] is running then the value
  1951         -** returned is unpredictable and not meaningful.
  1952         -*/
  1953         -SQLITE_API int sqlite3_total_changes(sqlite3*);
  1954         -
  1955         -/*
  1956         -** CAPI3REF: Interrupt A Long-Running Query
  1957         -**
  1958         -** ^This function causes any pending database operation to abort and
  1959         -** return at its earliest opportunity. This routine is typically
  1960         -** called in response to a user action such as pressing "Cancel"
  1961         -** or Ctrl-C where the user wants a long query operation to halt
  1962         -** immediately.
  1963         -**
  1964         -** ^It is safe to call this routine from a thread different from the
  1965         -** thread that is currently running the database operation.  But it
  1966         -** is not safe to call this routine with a [database connection] that
  1967         -** is closed or might close before sqlite3_interrupt() returns.
  1968         -**
  1969         -** ^If an SQL operation is very nearly finished at the time when
  1970         -** sqlite3_interrupt() is called, then it might not have an opportunity
  1971         -** to be interrupted and might continue to completion.
  1972         -**
  1973         -** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
  1974         -** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
  1975         -** that is inside an explicit transaction, then the entire transaction
  1976         -** will be rolled back automatically.
  1977         -**
  1978         -** ^The sqlite3_interrupt(D) call is in effect until all currently running
  1979         -** SQL statements on [database connection] D complete.  ^Any new SQL statements
  1980         -** that are started after the sqlite3_interrupt() call and before the 
  1981         -** running statements reaches zero are interrupted as if they had been
  1982         -** running prior to the sqlite3_interrupt() call.  ^New SQL statements
  1983         -** that are started after the running statement count reaches zero are
  1984         -** not effected by the sqlite3_interrupt().
  1985         -** ^A call to sqlite3_interrupt(D) that occurs when there are no running
  1986         -** SQL statements is a no-op and has no effect on SQL statements
  1987         -** that are started after the sqlite3_interrupt() call returns.
  1988         -**
  1989         -** If the database connection closes while [sqlite3_interrupt()]
  1990         -** is running then bad things will likely happen.
  1991         -*/
  1992         -SQLITE_API void sqlite3_interrupt(sqlite3*);
  1993         -
  1994         -/*
  1995         -** CAPI3REF: Determine If An SQL Statement Is Complete
  1996         -**
  1997         -** These routines are useful during command-line input to determine if the
  1998         -** currently entered text seems to form a complete SQL statement or
  1999         -** if additional input is needed before sending the text into
  2000         -** SQLite for parsing.  ^These routines return 1 if the input string
  2001         -** appears to be a complete SQL statement.  ^A statement is judged to be
  2002         -** complete if it ends with a semicolon token and is not a prefix of a
  2003         -** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
  2004         -** string literals or quoted identifier names or comments are not
  2005         -** independent tokens (they are part of the token in which they are
  2006         -** embedded) and thus do not count as a statement terminator.  ^Whitespace
  2007         -** and comments that follow the final semicolon are ignored.
  2008         -**
  2009         -** ^These routines return 0 if the statement is incomplete.  ^If a
  2010         -** memory allocation fails, then SQLITE_NOMEM is returned.
  2011         -**
  2012         -** ^These routines do not parse the SQL statements thus
  2013         -** will not detect syntactically incorrect SQL.
  2014         -**
  2015         -** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
  2016         -** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
  2017         -** automatically by sqlite3_complete16().  If that initialization fails,
  2018         -** then the return value from sqlite3_complete16() will be non-zero
  2019         -** regardless of whether or not the input SQL is complete.)^
  2020         -**
  2021         -** The input to [sqlite3_complete()] must be a zero-terminated
  2022         -** UTF-8 string.
  2023         -**
  2024         -** The input to [sqlite3_complete16()] must be a zero-terminated
  2025         -** UTF-16 string in native byte order.
  2026         -*/
  2027         -SQLITE_API int sqlite3_complete(const char *sql);
  2028         -SQLITE_API int sqlite3_complete16(const void *sql);
  2029         -
  2030         -/*
  2031         -** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
  2032         -**
  2033         -** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
  2034         -** that might be invoked with argument P whenever
  2035         -** an attempt is made to access a database table associated with
  2036         -** [database connection] D when another thread
  2037         -** or process has the table locked.
  2038         -** The sqlite3_busy_handler() interface is used to implement
  2039         -** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
  2040         -**
  2041         -** ^If the busy callback is NULL, then [SQLITE_BUSY]
  2042         -** is returned immediately upon encountering the lock.  ^If the busy callback
  2043         -** is not NULL, then the callback might be invoked with two arguments.
  2044         -**
  2045         -** ^The first argument to the busy handler is a copy of the void* pointer which
  2046         -** is the third argument to sqlite3_busy_handler().  ^The second argument to
  2047         -** the busy handler callback is the number of times that the busy handler has
  2048         -** been invoked for the same locking event.  ^If the
  2049         -** busy callback returns 0, then no additional attempts are made to
  2050         -** access the database and [SQLITE_BUSY] is returned
  2051         -** to the application.
  2052         -** ^If the callback returns non-zero, then another attempt
  2053         -** is made to access the database and the cycle repeats.
  2054         -**
  2055         -** The presence of a busy handler does not guarantee that it will be invoked
  2056         -** when there is lock contention. ^If SQLite determines that invoking the busy
  2057         -** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
  2058         -** to the application instead of invoking the 
  2059         -** busy handler.
  2060         -** Consider a scenario where one process is holding a read lock that
  2061         -** it is trying to promote to a reserved lock and
  2062         -** a second process is holding a reserved lock that it is trying
  2063         -** to promote to an exclusive lock.  The first process cannot proceed
  2064         -** because it is blocked by the second and the second process cannot
  2065         -** proceed because it is blocked by the first.  If both processes
  2066         -** invoke the busy handlers, neither will make any progress.  Therefore,
  2067         -** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
  2068         -** will induce the first process to release its read lock and allow
  2069         -** the second process to proceed.
  2070         -**
  2071         -** ^The default busy callback is NULL.
  2072         -**
  2073         -** ^(There can only be a single busy handler defined for each
  2074         -** [database connection].  Setting a new busy handler clears any
  2075         -** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
  2076         -** or evaluating [PRAGMA busy_timeout=N] will change the
  2077         -** busy handler and thus clear any previously set busy handler.
  2078         -**
  2079         -** The busy callback should not take any actions which modify the
  2080         -** database connection that invoked the busy handler.  In other words,
  2081         -** the busy handler is not reentrant.  Any such actions
  2082         -** result in undefined behavior.
  2083         -** 
  2084         -** A busy handler must not close the database connection
  2085         -** or [prepared statement] that invoked the busy handler.
  2086         -*/
  2087         -SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
  2088         -
  2089         -/*
  2090         -** CAPI3REF: Set A Busy Timeout
  2091         -**
  2092         -** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
  2093         -** for a specified amount of time when a table is locked.  ^The handler
  2094         -** will sleep multiple times until at least "ms" milliseconds of sleeping
  2095         -** have accumulated.  ^After at least "ms" milliseconds of sleeping,
  2096         -** the handler returns 0 which causes [sqlite3_step()] to return
  2097         -** [SQLITE_BUSY].
  2098         -**
  2099         -** ^Calling this routine with an argument less than or equal to zero
  2100         -** turns off all busy handlers.
  2101         -**
  2102         -** ^(There can only be a single busy handler for a particular
  2103         -** [database connection] at any given moment.  If another busy handler
  2104         -** was defined  (using [sqlite3_busy_handler()]) prior to calling
  2105         -** this routine, that other busy handler is cleared.)^
  2106         -**
  2107         -** See also:  [PRAGMA busy_timeout]
  2108         -*/
  2109         -SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
  2110         -
  2111         -/*
  2112         -** CAPI3REF: Convenience Routines For Running Queries
  2113         -**
  2114         -** This is a legacy interface that is preserved for backwards compatibility.
  2115         -** Use of this interface is not recommended.
  2116         -**
  2117         -** Definition: A <b>result table</b> is memory data structure created by the
  2118         -** [sqlite3_get_table()] interface.  A result table records the
  2119         -** complete query results from one or more queries.
  2120         -**
  2121         -** The table conceptually has a number of rows and columns.  But
  2122         -** these numbers are not part of the result table itself.  These
  2123         -** numbers are obtained separately.  Let N be the number of rows
  2124         -** and M be the number of columns.
  2125         -**
  2126         -** A result table is an array of pointers to zero-terminated UTF-8 strings.
  2127         -** There are (N+1)*M elements in the array.  The first M pointers point
  2128         -** to zero-terminated strings that  contain the names of the columns.
  2129         -** The remaining entries all point to query results.  NULL values result
  2130         -** in NULL pointers.  All other values are in their UTF-8 zero-terminated
  2131         -** string representation as returned by [sqlite3_column_text()].
  2132         -**
  2133         -** A result table might consist of one or more memory allocations.
  2134         -** It is not safe to pass a result table directly to [sqlite3_free()].
  2135         -** A result table should be deallocated using [sqlite3_free_table()].
  2136         -**
  2137         -** ^(As an example of the result table format, suppose a query result
  2138         -** is as follows:
  2139         -**
  2140         -** <blockquote><pre>
  2141         -**        Name        | Age
  2142         -**        -----------------------
  2143         -**        Alice       | 43
  2144         -**        Bob         | 28
  2145         -**        Cindy       | 21
  2146         -** </pre></blockquote>
  2147         -**
  2148         -** There are two column (M==2) and three rows (N==3).  Thus the
  2149         -** result table has 8 entries.  Suppose the result table is stored
  2150         -** in an array names azResult.  Then azResult holds this content:
  2151         -**
  2152         -** <blockquote><pre>
  2153         -**        azResult&#91;0] = "Name";
  2154         -**        azResult&#91;1] = "Age";
  2155         -**        azResult&#91;2] = "Alice";
  2156         -**        azResult&#91;3] = "43";
  2157         -**        azResult&#91;4] = "Bob";
  2158         -**        azResult&#91;5] = "28";
  2159         -**        azResult&#91;6] = "Cindy";
  2160         -**        azResult&#91;7] = "21";
  2161         -** </pre></blockquote>)^
  2162         -**
  2163         -** ^The sqlite3_get_table() function evaluates one or more
  2164         -** semicolon-separated SQL statements in the zero-terminated UTF-8
  2165         -** string of its 2nd parameter and returns a result table to the
  2166         -** pointer given in its 3rd parameter.
  2167         -**
  2168         -** After the application has finished with the result from sqlite3_get_table(),
  2169         -** it must pass the result table pointer to sqlite3_free_table() in order to
  2170         -** release the memory that was malloced.  Because of the way the
  2171         -** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  2172         -** function must not try to call [sqlite3_free()] directly.  Only
  2173         -** [sqlite3_free_table()] is able to release the memory properly and safely.
  2174         -**
  2175         -** The sqlite3_get_table() interface is implemented as a wrapper around
  2176         -** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
  2177         -** to any internal data structures of SQLite.  It uses only the public
  2178         -** interface defined here.  As a consequence, errors that occur in the
  2179         -** wrapper layer outside of the internal [sqlite3_exec()] call are not
  2180         -** reflected in subsequent calls to [sqlite3_errcode()] or
  2181         -** [sqlite3_errmsg()].
  2182         -*/
  2183         -SQLITE_API int sqlite3_get_table(
  2184         -  sqlite3 *db,          /* An open database */
  2185         -  const char *zSql,     /* SQL to be evaluated */
  2186         -  char ***pazResult,    /* Results of the query */
  2187         -  int *pnRow,           /* Number of result rows written here */
  2188         -  int *pnColumn,        /* Number of result columns written here */
  2189         -  char **pzErrmsg       /* Error msg written here */
  2190         -);
  2191         -SQLITE_API void sqlite3_free_table(char **result);
  2192         -
  2193         -/*
  2194         -** CAPI3REF: Formatted String Printing Functions
  2195         -**
  2196         -** These routines are work-alikes of the "printf()" family of functions
  2197         -** from the standard C library.
  2198         -**
  2199         -** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2200         -** results into memory obtained from [sqlite3_malloc()].
  2201         -** The strings returned by these two routines should be
  2202         -** released by [sqlite3_free()].  ^Both routines return a
  2203         -** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  2204         -** memory to hold the resulting string.
  2205         -**
  2206         -** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
  2207         -** the standard C library.  The result is written into the
  2208         -** buffer supplied as the second parameter whose size is given by
  2209         -** the first parameter. Note that the order of the
  2210         -** first two parameters is reversed from snprintf().)^  This is an
  2211         -** historical accident that cannot be fixed without breaking
  2212         -** backwards compatibility.  ^(Note also that sqlite3_snprintf()
  2213         -** returns a pointer to its buffer instead of the number of
  2214         -** characters actually written into the buffer.)^  We admit that
  2215         -** the number of characters written would be a more useful return
  2216         -** value but we cannot change the implementation of sqlite3_snprintf()
  2217         -** now without breaking compatibility.
  2218         -**
  2219         -** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
  2220         -** guarantees that the buffer is always zero-terminated.  ^The first
  2221         -** parameter "n" is the total size of the buffer, including space for
  2222         -** the zero terminator.  So the longest string that can be completely
  2223         -** written will be n-1 characters.
  2224         -**
  2225         -** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2226         -**
  2227         -** These routines all implement some additional formatting
  2228         -** options that are useful for constructing SQL statements.
  2229         -** All of the usual printf() formatting options apply.  In addition, there
  2230         -** is are "%q", "%Q", and "%z" options.
  2231         -**
  2232         -** ^(The %q option works like %s in that it substitutes a nul-terminated
  2233         -** string from the argument list.  But %q also doubles every '\'' character.
  2234         -** %q is designed for use inside a string literal.)^  By doubling each '\''
  2235         -** character it escapes that character and allows it to be inserted into
  2236         -** the string.
  2237         -**
  2238         -** For example, assume the string variable zText contains text as follows:
  2239         -**
  2240         -** <blockquote><pre>
  2241         -**  char *zText = "It's a happy day!";
  2242         -** </pre></blockquote>
  2243         -**
  2244         -** One can use this text in an SQL statement as follows:
  2245         -**
  2246         -** <blockquote><pre>
  2247         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
  2248         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2249         -**  sqlite3_free(zSQL);
  2250         -** </pre></blockquote>
  2251         -**
  2252         -** Because the %q format string is used, the '\'' character in zText
  2253         -** is escaped and the SQL generated is as follows:
  2254         -**
  2255         -** <blockquote><pre>
  2256         -**  INSERT INTO table1 VALUES('It''s a happy day!')
  2257         -** </pre></blockquote>
  2258         -**
  2259         -** This is correct.  Had we used %s instead of %q, the generated SQL
  2260         -** would have looked like this:
  2261         -**
  2262         -** <blockquote><pre>
  2263         -**  INSERT INTO table1 VALUES('It's a happy day!');
  2264         -** </pre></blockquote>
  2265         -**
  2266         -** This second example is an SQL syntax error.  As a general rule you should
  2267         -** always use %q instead of %s when inserting text into a string literal.
  2268         -**
  2269         -** ^(The %Q option works like %q except it also adds single quotes around
  2270         -** the outside of the total string.  Additionally, if the parameter in the
  2271         -** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
  2272         -** single quotes).)^  So, for example, one could say:
  2273         -**
  2274         -** <blockquote><pre>
  2275         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  2276         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2277         -**  sqlite3_free(zSQL);
  2278         -** </pre></blockquote>
  2279         -**
  2280         -** The code above will render a correct SQL statement in the zSQL
  2281         -** variable even if the zText variable is a NULL pointer.
  2282         -**
  2283         -** ^(The "%z" formatting option works like "%s" but with the
  2284         -** addition that after the string has been read and copied into
  2285         -** the result, [sqlite3_free()] is called on the input string.)^
  2286         -*/
  2287         -SQLITE_API char *sqlite3_mprintf(const char*,...);
  2288         -SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
  2289         -SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
  2290         -SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
  2291         -
  2292         -/*
  2293         -** CAPI3REF: Memory Allocation Subsystem
  2294         -**
  2295         -** The SQLite core uses these three routines for all of its own
  2296         -** internal memory allocation needs. "Core" in the previous sentence
  2297         -** does not include operating-system specific VFS implementation.  The
  2298         -** Windows VFS uses native malloc() and free() for some operations.
  2299         -**
  2300         -** ^The sqlite3_malloc() routine returns a pointer to a block
  2301         -** of memory at least N bytes in length, where N is the parameter.
  2302         -** ^If sqlite3_malloc() is unable to obtain sufficient free
  2303         -** memory, it returns a NULL pointer.  ^If the parameter N to
  2304         -** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  2305         -** a NULL pointer.
  2306         -**
  2307         -** ^The sqlite3_malloc64(N) routine works just like
  2308         -** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
  2309         -** of a signed 32-bit integer.
  2310         -**
  2311         -** ^Calling sqlite3_free() with a pointer previously returned
  2312         -** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  2313         -** that it might be reused.  ^The sqlite3_free() routine is
  2314         -** a no-op if is called with a NULL pointer.  Passing a NULL pointer
  2315         -** to sqlite3_free() is harmless.  After being freed, memory
  2316         -** should neither be read nor written.  Even reading previously freed
  2317         -** memory might result in a segmentation fault or other severe error.
  2318         -** Memory corruption, a segmentation fault, or other severe error
  2319         -** might result if sqlite3_free() is called with a non-NULL pointer that
  2320         -** was not obtained from sqlite3_malloc() or sqlite3_realloc().
  2321         -**
  2322         -** ^The sqlite3_realloc(X,N) interface attempts to resize a
  2323         -** prior memory allocation X to be at least N bytes.
  2324         -** ^If the X parameter to sqlite3_realloc(X,N)
  2325         -** is a NULL pointer then its behavior is identical to calling
  2326         -** sqlite3_malloc(N).
  2327         -** ^If the N parameter to sqlite3_realloc(X,N) is zero or
  2328         -** negative then the behavior is exactly the same as calling
  2329         -** sqlite3_free(X).
  2330         -** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
  2331         -** of at least N bytes in size or NULL if insufficient memory is available.
  2332         -** ^If M is the size of the prior allocation, then min(N,M) bytes
  2333         -** of the prior allocation are copied into the beginning of buffer returned
  2334         -** by sqlite3_realloc(X,N) and the prior allocation is freed.
  2335         -** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
  2336         -** prior allocation is not freed.
  2337         -**
  2338         -** ^The sqlite3_realloc64(X,N) interfaces works the same as
  2339         -** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
  2340         -** of a 32-bit signed integer.
  2341         -**
  2342         -** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
  2343         -** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
  2344         -** sqlite3_msize(X) returns the size of that memory allocation in bytes.
  2345         -** ^The value returned by sqlite3_msize(X) might be larger than the number
  2346         -** of bytes requested when X was allocated.  ^If X is a NULL pointer then
  2347         -** sqlite3_msize(X) returns zero.  If X points to something that is not
  2348         -** the beginning of memory allocation, or if it points to a formerly
  2349         -** valid memory allocation that has now been freed, then the behavior
  2350         -** of sqlite3_msize(X) is undefined and possibly harmful.
  2351         -**
  2352         -** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
  2353         -** sqlite3_malloc64(), and sqlite3_realloc64()
  2354         -** is always aligned to at least an 8 byte boundary, or to a
  2355         -** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
  2356         -** option is used.
  2357         -**
  2358         -** In SQLite version 3.5.0 and 3.5.1, it was possible to define
  2359         -** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
  2360         -** implementation of these routines to be omitted.  That capability
  2361         -** is no longer provided.  Only built-in memory allocators can be used.
  2362         -**
  2363         -** Prior to SQLite version 3.7.10, the Windows OS interface layer called
  2364         -** the system malloc() and free() directly when converting
  2365         -** filenames between the UTF-8 encoding used by SQLite
  2366         -** and whatever filename encoding is used by the particular Windows
  2367         -** installation.  Memory allocation errors were detected, but
  2368         -** they were reported back as [SQLITE_CANTOPEN] or
  2369         -** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
  2370         -**
  2371         -** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
  2372         -** must be either NULL or else pointers obtained from a prior
  2373         -** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
  2374         -** not yet been released.
  2375         -**
  2376         -** The application must not read or write any part of
  2377         -** a block of memory after it has been released using
  2378         -** [sqlite3_free()] or [sqlite3_realloc()].
  2379         -*/
  2380         -SQLITE_API void *sqlite3_malloc(int);
  2381         -SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
  2382         -SQLITE_API void *sqlite3_realloc(void*, int);
  2383         -SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
  2384         -SQLITE_API void sqlite3_free(void*);
  2385         -SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
  2386         -
  2387         -/*
  2388         -** CAPI3REF: Memory Allocator Statistics
  2389         -**
  2390         -** SQLite provides these two interfaces for reporting on the status
  2391         -** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
  2392         -** routines, which form the built-in memory allocation subsystem.
  2393         -**
  2394         -** ^The [sqlite3_memory_used()] routine returns the number of bytes
  2395         -** of memory currently outstanding (malloced but not freed).
  2396         -** ^The [sqlite3_memory_highwater()] routine returns the maximum
  2397         -** value of [sqlite3_memory_used()] since the high-water mark
  2398         -** was last reset.  ^The values returned by [sqlite3_memory_used()] and
  2399         -** [sqlite3_memory_highwater()] include any overhead
  2400         -** added by SQLite in its implementation of [sqlite3_malloc()],
  2401         -** but not overhead added by the any underlying system library
  2402         -** routines that [sqlite3_malloc()] may call.
  2403         -**
  2404         -** ^The memory high-water mark is reset to the current value of
  2405         -** [sqlite3_memory_used()] if and only if the parameter to
  2406         -** [sqlite3_memory_highwater()] is true.  ^The value returned
  2407         -** by [sqlite3_memory_highwater(1)] is the high-water mark
  2408         -** prior to the reset.
  2409         -*/
  2410         -SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
  2411         -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  2412         -
  2413         -/*
  2414         -** CAPI3REF: Pseudo-Random Number Generator
  2415         -**
  2416         -** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
  2417         -** select random [ROWID | ROWIDs] when inserting new records into a table that
  2418         -** already uses the largest possible [ROWID].  The PRNG is also used for
  2419         -** the build-in random() and randomblob() SQL functions.  This interface allows
  2420         -** applications to access the same PRNG for other purposes.
  2421         -**
  2422         -** ^A call to this routine stores N bytes of randomness into buffer P.
  2423         -** ^If N is less than one, then P can be a NULL pointer.
  2424         -**
  2425         -** ^If this routine has not been previously called or if the previous
  2426         -** call had N less than one, then the PRNG is seeded using randomness
  2427         -** obtained from the xRandomness method of the default [sqlite3_vfs] object.
  2428         -** ^If the previous call to this routine had an N of 1 or more then
  2429         -** the pseudo-randomness is generated
  2430         -** internally and without recourse to the [sqlite3_vfs] xRandomness
  2431         -** method.
  2432         -*/
  2433         -SQLITE_API void sqlite3_randomness(int N, void *P);
  2434         -
  2435         -/*
  2436         -** CAPI3REF: Compile-Time Authorization Callbacks
  2437         -**
  2438         -** ^This routine registers an authorizer callback with a particular
  2439         -** [database connection], supplied in the first argument.
  2440         -** ^The authorizer callback is invoked as SQL statements are being compiled
  2441         -** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  2442         -** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
  2443         -** points during the compilation process, as logic is being created
  2444         -** to perform various actions, the authorizer callback is invoked to
  2445         -** see if those actions are allowed.  ^The authorizer callback should
  2446         -** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  2447         -** specific action but allow the SQL statement to continue to be
  2448         -** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  2449         -** rejected with an error.  ^If the authorizer callback returns
  2450         -** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  2451         -** then the [sqlite3_prepare_v2()] or equivalent call that triggered
  2452         -** the authorizer will fail with an error message.
  2453         -**
  2454         -** When the callback returns [SQLITE_OK], that means the operation
  2455         -** requested is ok.  ^When the callback returns [SQLITE_DENY], the
  2456         -** [sqlite3_prepare_v2()] or equivalent call that triggered the
  2457         -** authorizer will fail with an error message explaining that
  2458         -** access is denied. 
  2459         -**
  2460         -** ^The first parameter to the authorizer callback is a copy of the third
  2461         -** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
  2462         -** to the callback is an integer [SQLITE_COPY | action code] that specifies
  2463         -** the particular action to be authorized. ^The third through sixth parameters
  2464         -** to the callback are zero-terminated strings that contain additional
  2465         -** details about the action to be authorized.
  2466         -**
  2467         -** ^If the action code is [SQLITE_READ]
  2468         -** and the callback returns [SQLITE_IGNORE] then the
  2469         -** [prepared statement] statement is constructed to substitute
  2470         -** a NULL value in place of the table column that would have
  2471         -** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
  2472         -** return can be used to deny an untrusted user access to individual
  2473         -** columns of a table.
  2474         -** ^If the action code is [SQLITE_DELETE] and the callback returns
  2475         -** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
  2476         -** [truncate optimization] is disabled and all rows are deleted individually.
  2477         -**
  2478         -** An authorizer is used when [sqlite3_prepare | preparing]
  2479         -** SQL statements from an untrusted source, to ensure that the SQL statements
  2480         -** do not try to access data they are not allowed to see, or that they do not
  2481         -** try to execute malicious statements that damage the database.  For
  2482         -** example, an application may allow a user to enter arbitrary
  2483         -** SQL queries for evaluation by a database.  But the application does
  2484         -** not want the user to be able to make arbitrary changes to the
  2485         -** database.  An authorizer could then be put in place while the
  2486         -** user-entered SQL is being [sqlite3_prepare | prepared] that
  2487         -** disallows everything except [SELECT] statements.
  2488         -**
  2489         -** Applications that need to process SQL from untrusted sources
  2490         -** might also consider lowering resource limits using [sqlite3_limit()]
  2491         -** and limiting database size using the [max_page_count] [PRAGMA]
  2492         -** in addition to using an authorizer.
  2493         -**
  2494         -** ^(Only a single authorizer can be in place on a database connection
  2495         -** at a time.  Each call to sqlite3_set_authorizer overrides the
  2496         -** previous call.)^  ^Disable the authorizer by installing a NULL callback.
  2497         -** The authorizer is disabled by default.
  2498         -**
  2499         -** The authorizer callback must not do anything that will modify
  2500         -** the database connection that invoked the authorizer callback.
  2501         -** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  2502         -** database connections for the meaning of "modify" in this paragraph.
  2503         -**
  2504         -** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
  2505         -** statement might be re-prepared during [sqlite3_step()] due to a 
  2506         -** schema change.  Hence, the application should ensure that the
  2507         -** correct authorizer callback remains in place during the [sqlite3_step()].
  2508         -**
  2509         -** ^Note that the authorizer callback is invoked only during
  2510         -** [sqlite3_prepare()] or its variants.  Authorization is not
  2511         -** performed during statement evaluation in [sqlite3_step()], unless
  2512         -** as stated in the previous paragraph, sqlite3_step() invokes
  2513         -** sqlite3_prepare_v2() to reprepare a statement after a schema change.
  2514         -*/
  2515         -SQLITE_API int sqlite3_set_authorizer(
  2516         -  sqlite3*,
  2517         -  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  2518         -  void *pUserData
  2519         -);
  2520         -
  2521         -/*
  2522         -** CAPI3REF: Authorizer Return Codes
  2523         -**
  2524         -** The [sqlite3_set_authorizer | authorizer callback function] must
  2525         -** return either [SQLITE_OK] or one of these two constants in order
  2526         -** to signal SQLite whether or not the action is permitted.  See the
  2527         -** [sqlite3_set_authorizer | authorizer documentation] for additional
  2528         -** information.
  2529         -**
  2530         -** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
  2531         -** returned from the [sqlite3_vtab_on_conflict()] interface.
  2532         -*/
  2533         -#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  2534         -#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  2535         -
  2536         -/*
  2537         -** CAPI3REF: Authorizer Action Codes
  2538         -**
  2539         -** The [sqlite3_set_authorizer()] interface registers a callback function
  2540         -** that is invoked to authorize certain SQL statement actions.  The
  2541         -** second parameter to the callback is an integer code that specifies
  2542         -** what action is being authorized.  These are the integer action codes that
  2543         -** the authorizer callback may be passed.
  2544         -**
  2545         -** These action code values signify what kind of operation is to be
  2546         -** authorized.  The 3rd and 4th parameters to the authorization
  2547         -** callback function will be parameters or NULL depending on which of these
  2548         -** codes is used as the second parameter.  ^(The 5th parameter to the
  2549         -** authorizer callback is the name of the database ("main", "temp",
  2550         -** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
  2551         -** is the name of the inner-most trigger or view that is responsible for
  2552         -** the access attempt or NULL if this access attempt is directly from
  2553         -** top-level SQL code.
  2554         -*/
  2555         -/******************************************* 3rd ************ 4th ***********/
  2556         -#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
  2557         -#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
  2558         -#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
  2559         -#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
  2560         -#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
  2561         -#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
  2562         -#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
  2563         -#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
  2564         -#define SQLITE_DELETE                9   /* Table Name      NULL            */
  2565         -#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
  2566         -#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
  2567         -#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
  2568         -#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
  2569         -#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
  2570         -#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
  2571         -#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
  2572         -#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
  2573         -#define SQLITE_INSERT               18   /* Table Name      NULL            */
  2574         -#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
  2575         -#define SQLITE_READ                 20   /* Table Name      Column Name     */
  2576         -#define SQLITE_SELECT               21   /* NULL            NULL            */
  2577         -#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
  2578         -#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
  2579         -#define SQLITE_ATTACH               24   /* Filename        NULL            */
  2580         -#define SQLITE_DETACH               25   /* Database Name   NULL            */
  2581         -#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
  2582         -#define SQLITE_REINDEX              27   /* Index Name      NULL            */
  2583         -#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
  2584         -#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
  2585         -#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
  2586         -#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
  2587         -#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
  2588         -#define SQLITE_COPY                  0   /* No longer used */
  2589         -#define SQLITE_RECURSIVE            33   /* NULL            NULL            */
  2590         -
  2591         -/*
  2592         -** CAPI3REF: Tracing And Profiling Functions
  2593         -**
  2594         -** These routines register callback functions that can be used for
  2595         -** tracing and profiling the execution of SQL statements.
  2596         -**
  2597         -** ^The callback function registered by sqlite3_trace() is invoked at
  2598         -** various times when an SQL statement is being run by [sqlite3_step()].
  2599         -** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
  2600         -** SQL statement text as the statement first begins executing.
  2601         -** ^(Additional sqlite3_trace() callbacks might occur
  2602         -** as each triggered subprogram is entered.  The callbacks for triggers
  2603         -** contain a UTF-8 SQL comment that identifies the trigger.)^
  2604         -**
  2605         -** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
  2606         -** the length of [bound parameter] expansion in the output of sqlite3_trace().
  2607         -**
  2608         -** ^The callback function registered by sqlite3_profile() is invoked
  2609         -** as each SQL statement finishes.  ^The profile callback contains
  2610         -** the original statement text and an estimate of wall-clock time
  2611         -** of how long that statement took to run.  ^The profile callback
  2612         -** time is in units of nanoseconds, however the current implementation
  2613         -** is only capable of millisecond resolution so the six least significant
  2614         -** digits in the time are meaningless.  Future versions of SQLite
  2615         -** might provide greater resolution on the profiler callback.  The
  2616         -** sqlite3_profile() function is considered experimental and is
  2617         -** subject to change in future versions of SQLite.
  2618         -*/
  2619         -SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
  2620         -SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
  2621         -   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  2622         -
  2623         -/*
  2624         -** CAPI3REF: Query Progress Callbacks
  2625         -**
  2626         -** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
  2627         -** function X to be invoked periodically during long running calls to
  2628         -** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
  2629         -** database connection D.  An example use for this
  2630         -** interface is to keep a GUI updated during a large query.
  2631         -**
  2632         -** ^The parameter P is passed through as the only parameter to the 
  2633         -** callback function X.  ^The parameter N is the approximate number of 
  2634         -** [virtual machine instructions] that are evaluated between successive
  2635         -** invocations of the callback X.  ^If N is less than one then the progress
  2636         -** handler is disabled.
  2637         -**
  2638         -** ^Only a single progress handler may be defined at one time per
  2639         -** [database connection]; setting a new progress handler cancels the
  2640         -** old one.  ^Setting parameter X to NULL disables the progress handler.
  2641         -** ^The progress handler is also disabled by setting N to a value less
  2642         -** than 1.
  2643         -**
  2644         -** ^If the progress callback returns non-zero, the operation is
  2645         -** interrupted.  This feature can be used to implement a
  2646         -** "Cancel" button on a GUI progress dialog box.
  2647         -**
  2648         -** The progress handler callback must not do anything that will modify
  2649         -** the database connection that invoked the progress handler.
  2650         -** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  2651         -** database connections for the meaning of "modify" in this paragraph.
  2652         -**
  2653         -*/
  2654         -SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  2655         -
  2656         -/*
  2657         -** CAPI3REF: Opening A New Database Connection
  2658         -**
  2659         -** ^These routines open an SQLite database file as specified by the 
  2660         -** filename argument. ^The filename argument is interpreted as UTF-8 for
  2661         -** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
  2662         -** order for sqlite3_open16(). ^(A [database connection] handle is usually
  2663         -** returned in *ppDb, even if an error occurs.  The only exception is that
  2664         -** if SQLite is unable to allocate memory to hold the [sqlite3] object,
  2665         -** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
  2666         -** object.)^ ^(If the database is opened (and/or created) successfully, then
  2667         -** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
  2668         -** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
  2669         -** an English language description of the error following a failure of any
  2670         -** of the sqlite3_open() routines.
  2671         -**
  2672         -** ^The default encoding will be UTF-8 for databases created using
  2673         -** sqlite3_open() or sqlite3_open_v2().  ^The default encoding for databases
  2674         -** created using sqlite3_open16() will be UTF-16 in the native byte order.
  2675         -**
  2676         -** Whether or not an error occurs when it is opened, resources
  2677         -** associated with the [database connection] handle should be released by
  2678         -** passing it to [sqlite3_close()] when it is no longer required.
  2679         -**
  2680         -** The sqlite3_open_v2() interface works like sqlite3_open()
  2681         -** except that it accepts two additional parameters for additional control
  2682         -** over the new database connection.  ^(The flags parameter to
  2683         -** sqlite3_open_v2() can take one of
  2684         -** the following three values, optionally combined with the 
  2685         -** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
  2686         -** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
  2687         -**
  2688         -** <dl>
  2689         -** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
  2690         -** <dd>The database is opened in read-only mode.  If the database does not
  2691         -** already exist, an error is returned.</dd>)^
  2692         -**
  2693         -** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
  2694         -** <dd>The database is opened for reading and writing if possible, or reading
  2695         -** only if the file is write protected by the operating system.  In either
  2696         -** case the database must already exist, otherwise an error is returned.</dd>)^
  2697         -**
  2698         -** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
  2699         -** <dd>The database is opened for reading and writing, and is created if
  2700         -** it does not already exist. This is the behavior that is always used for
  2701         -** sqlite3_open() and sqlite3_open16().</dd>)^
  2702         -** </dl>
  2703         -**
  2704         -** If the 3rd parameter to sqlite3_open_v2() is not one of the
  2705         -** combinations shown above optionally combined with other
  2706         -** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
  2707         -** then the behavior is undefined.
  2708         -**
  2709         -** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
  2710         -** opens in the multi-thread [threading mode] as long as the single-thread
  2711         -** mode has not been set at compile-time or start-time.  ^If the
  2712         -** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
  2713         -** in the serialized [threading mode] unless single-thread was
  2714         -** previously selected at compile-time or start-time.
  2715         -** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
  2716         -** eligible to use [shared cache mode], regardless of whether or not shared
  2717         -** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
  2718         -** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
  2719         -** participate in [shared cache mode] even if it is enabled.
  2720         -**
  2721         -** ^The fourth parameter to sqlite3_open_v2() is the name of the
  2722         -** [sqlite3_vfs] object that defines the operating system interface that
  2723         -** the new database connection should use.  ^If the fourth parameter is
  2724         -** a NULL pointer then the default [sqlite3_vfs] object is used.
  2725         -**
  2726         -** ^If the filename is ":memory:", then a private, temporary in-memory database
  2727         -** is created for the connection.  ^This in-memory database will vanish when
  2728         -** the database connection is closed.  Future versions of SQLite might
  2729         -** make use of additional special filenames that begin with the ":" character.
  2730         -** It is recommended that when a database filename actually does begin with
  2731         -** a ":" character you should prefix the filename with a pathname such as
  2732         -** "./" to avoid ambiguity.
  2733         -**
  2734         -** ^If the filename is an empty string, then a private, temporary
  2735         -** on-disk database will be created.  ^This private database will be
  2736         -** automatically deleted as soon as the database connection is closed.
  2737         -**
  2738         -** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
  2739         -**
  2740         -** ^If [URI filename] interpretation is enabled, and the filename argument
  2741         -** begins with "file:", then the filename is interpreted as a URI. ^URI
  2742         -** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
  2743         -** set in the fourth argument to sqlite3_open_v2(), or if it has
  2744         -** been enabled globally using the [SQLITE_CONFIG_URI] option with the
  2745         -** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
  2746         -** As of SQLite version 3.7.7, URI filename interpretation is turned off
  2747         -** by default, but future releases of SQLite might enable URI filename
  2748         -** interpretation by default.  See "[URI filenames]" for additional
  2749         -** information.
  2750         -**
  2751         -** URI filenames are parsed according to RFC 3986. ^If the URI contains an
  2752         -** authority, then it must be either an empty string or the string 
  2753         -** "localhost". ^If the authority is not an empty string or "localhost", an 
  2754         -** error is returned to the caller. ^The fragment component of a URI, if 
  2755         -** present, is ignored.
  2756         -**
  2757         -** ^SQLite uses the path component of the URI as the name of the disk file
  2758         -** which contains the database. ^If the path begins with a '/' character, 
  2759         -** then it is interpreted as an absolute path. ^If the path does not begin 
  2760         -** with a '/' (meaning that the authority section is omitted from the URI)
  2761         -** then the path is interpreted as a relative path. 
  2762         -** ^(On windows, the first component of an absolute path 
  2763         -** is a drive specification (e.g. "C:").)^
  2764         -**
  2765         -** [[core URI query parameters]]
  2766         -** The query component of a URI may contain parameters that are interpreted
  2767         -** either by SQLite itself, or by a [VFS | custom VFS implementation].
  2768         -** SQLite and its built-in [VFSes] interpret the
  2769         -** following query parameters:
  2770         -**
  2771         -** <ul>
  2772         -**   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
  2773         -**     a VFS object that provides the operating system interface that should
  2774         -**     be used to access the database file on disk. ^If this option is set to
  2775         -**     an empty string the default VFS object is used. ^Specifying an unknown
  2776         -**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
  2777         -**     present, then the VFS specified by the option takes precedence over
  2778         -**     the value passed as the fourth parameter to sqlite3_open_v2().
  2779         -**
  2780         -**   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
  2781         -**     "rwc", or "memory". Attempting to set it to any other value is
  2782         -**     an error)^. 
  2783         -**     ^If "ro" is specified, then the database is opened for read-only 
  2784         -**     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 
  2785         -**     third argument to sqlite3_open_v2(). ^If the mode option is set to 
  2786         -**     "rw", then the database is opened for read-write (but not create) 
  2787         -**     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 
  2788         -**     been set. ^Value "rwc" is equivalent to setting both 
  2789         -**     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is
  2790         -**     set to "memory" then a pure [in-memory database] that never reads
  2791         -**     or writes from disk is used. ^It is an error to specify a value for
  2792         -**     the mode parameter that is less restrictive than that specified by
  2793         -**     the flags passed in the third parameter to sqlite3_open_v2().
  2794         -**
  2795         -**   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
  2796         -**     "private". ^Setting it to "shared" is equivalent to setting the
  2797         -**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
  2798         -**     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
  2799         -**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
  2800         -**     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
  2801         -**     a URI filename, its value overrides any behavior requested by setting
  2802         -**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
  2803         -**
  2804         -**  <li> <b>psow</b>: ^The psow parameter indicates whether or not the
  2805         -**     [powersafe overwrite] property does or does not apply to the
  2806         -**     storage media on which the database file resides.
  2807         -**
  2808         -**  <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
  2809         -**     which if set disables file locking in rollback journal modes.  This
  2810         -**     is useful for accessing a database on a filesystem that does not
  2811         -**     support locking.  Caution:  Database corruption might result if two
  2812         -**     or more processes write to the same database and any one of those
  2813         -**     processes uses nolock=1.
  2814         -**
  2815         -**  <li> <b>immutable</b>: ^The immutable parameter is a boolean query
  2816         -**     parameter that indicates that the database file is stored on
  2817         -**     read-only media.  ^When immutable is set, SQLite assumes that the
  2818         -**     database file cannot be changed, even by a process with higher
  2819         -**     privilege, and so the database is opened read-only and all locking
  2820         -**     and change detection is disabled.  Caution: Setting the immutable
  2821         -**     property on a database file that does in fact change can result
  2822         -**     in incorrect query results and/or [SQLITE_CORRUPT] errors.
  2823         -**     See also: [SQLITE_IOCAP_IMMUTABLE].
  2824         -**       
  2825         -** </ul>
  2826         -**
  2827         -** ^Specifying an unknown parameter in the query component of a URI is not an
  2828         -** error.  Future versions of SQLite might understand additional query
  2829         -** parameters.  See "[query parameters with special meaning to SQLite]" for
  2830         -** additional information.
  2831         -**
  2832         -** [[URI filename examples]] <h3>URI filename examples</h3>
  2833         -**
  2834         -** <table border="1" align=center cellpadding=5>
  2835         -** <tr><th> URI filenames <th> Results
  2836         -** <tr><td> file:data.db <td> 
  2837         -**          Open the file "data.db" in the current directory.
  2838         -** <tr><td> file:/home/fred/data.db<br>
  2839         -**          file:///home/fred/data.db <br> 
  2840         -**          file://localhost/home/fred/data.db <br> <td> 
  2841         -**          Open the database file "/home/fred/data.db".
  2842         -** <tr><td> file://darkstar/home/fred/data.db <td> 
  2843         -**          An error. "darkstar" is not a recognized authority.
  2844         -** <tr><td style="white-space:nowrap"> 
  2845         -**          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
  2846         -**     <td> Windows only: Open the file "data.db" on fred's desktop on drive
  2847         -**          C:. Note that the %20 escaping in this example is not strictly 
  2848         -**          necessary - space characters can be used literally
  2849         -**          in URI filenames.
  2850         -** <tr><td> file:data.db?mode=ro&cache=private <td> 
  2851         -**          Open file "data.db" in the current directory for read-only access.
  2852         -**          Regardless of whether or not shared-cache mode is enabled by
  2853         -**          default, use a private cache.
  2854         -** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
  2855         -**          Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
  2856         -**          that uses dot-files in place of posix advisory locking.
  2857         -** <tr><td> file:data.db?mode=readonly <td> 
  2858         -**          An error. "readonly" is not a valid option for the "mode" parameter.
  2859         -** </table>
  2860         -**
  2861         -** ^URI hexadecimal escape sequences (%HH) are supported within the path and
  2862         -** query components of a URI. A hexadecimal escape sequence consists of a
  2863         -** percent sign - "%" - followed by exactly two hexadecimal digits 
  2864         -** specifying an octet value. ^Before the path or query components of a
  2865         -** URI filename are interpreted, they are encoded using UTF-8 and all 
  2866         -** hexadecimal escape sequences replaced by a single byte containing the
  2867         -** corresponding octet. If this process generates an invalid UTF-8 encoding,
  2868         -** the results are undefined.
  2869         -**
  2870         -** <b>Note to Windows users:</b>  The encoding used for the filename argument
  2871         -** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
  2872         -** codepage is currently defined.  Filenames containing international
  2873         -** characters must be converted to UTF-8 prior to passing them into
  2874         -** sqlite3_open() or sqlite3_open_v2().
  2875         -**
  2876         -** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
  2877         -** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
  2878         -** features that require the use of temporary files may fail.
  2879         -**
  2880         -** See also: [sqlite3_temp_directory]
  2881         -*/
  2882         -SQLITE_API int sqlite3_open(
  2883         -  const char *filename,   /* Database filename (UTF-8) */
  2884         -  sqlite3 **ppDb          /* OUT: SQLite db handle */
  2885         -);
  2886         -SQLITE_API int sqlite3_open16(
  2887         -  const void *filename,   /* Database filename (UTF-16) */
  2888         -  sqlite3 **ppDb          /* OUT: SQLite db handle */
  2889         -);
  2890         -SQLITE_API int sqlite3_open_v2(
  2891         -  const char *filename,   /* Database filename (UTF-8) */
  2892         -  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  2893         -  int flags,              /* Flags */
  2894         -  const char *zVfs        /* Name of VFS module to use */
  2895         -);
  2896         -
  2897         -/*
  2898         -** CAPI3REF: Obtain Values For URI Parameters
  2899         -**
  2900         -** These are utility routines, useful to VFS implementations, that check
  2901         -** to see if a database file was a URI that contained a specific query 
  2902         -** parameter, and if so obtains the value of that query parameter.
  2903         -**
  2904         -** If F is the database filename pointer passed into the xOpen() method of 
  2905         -** a VFS implementation when the flags parameter to xOpen() has one or 
  2906         -** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
  2907         -** P is the name of the query parameter, then
  2908         -** sqlite3_uri_parameter(F,P) returns the value of the P
  2909         -** parameter if it exists or a NULL pointer if P does not appear as a 
  2910         -** query parameter on F.  If P is a query parameter of F
  2911         -** has no explicit value, then sqlite3_uri_parameter(F,P) returns
  2912         -** a pointer to an empty string.
  2913         -**
  2914         -** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
  2915         -** parameter and returns true (1) or false (0) according to the value
  2916         -** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
  2917         -** value of query parameter P is one of "yes", "true", or "on" in any
  2918         -** case or if the value begins with a non-zero number.  The 
  2919         -** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
  2920         -** query parameter P is one of "no", "false", or "off" in any case or
  2921         -** if the value begins with a numeric zero.  If P is not a query
  2922         -** parameter on F or if the value of P is does not match any of the
  2923         -** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
  2924         -**
  2925         -** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
  2926         -** 64-bit signed integer and returns that integer, or D if P does not
  2927         -** exist.  If the value of P is something other than an integer, then
  2928         -** zero is returned.
  2929         -** 
  2930         -** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
  2931         -** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
  2932         -** is not a database file pathname pointer that SQLite passed into the xOpen
  2933         -** VFS method, then the behavior of this routine is undefined and probably
  2934         -** undesirable.
  2935         -*/
  2936         -SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
  2937         -SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
  2938         -SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
  2939         -
  2940         -
  2941         -/*
  2942         -** CAPI3REF: Error Codes And Messages
  2943         -**
  2944         -** ^The sqlite3_errcode() interface returns the numeric [result code] or
  2945         -** [extended result code] for the most recent failed sqlite3_* API call
  2946         -** associated with a [database connection]. If a prior API call failed
  2947         -** but the most recent API call succeeded, the return value from
  2948         -** sqlite3_errcode() is undefined.  ^The sqlite3_extended_errcode()
  2949         -** interface is the same except that it always returns the 
  2950         -** [extended result code] even when extended result codes are
  2951         -** disabled.
  2952         -**
  2953         -** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  2954         -** text that describes the error, as either UTF-8 or UTF-16 respectively.
  2955         -** ^(Memory to hold the error message string is managed internally.
  2956         -** The application does not need to worry about freeing the result.
  2957         -** However, the error string might be overwritten or deallocated by
  2958         -** subsequent calls to other SQLite interface functions.)^
  2959         -**
  2960         -** ^The sqlite3_errstr() interface returns the English-language text
  2961         -** that describes the [result code], as UTF-8.
  2962         -** ^(Memory to hold the error message string is managed internally
  2963         -** and must not be freed by the application)^.
  2964         -**
  2965         -** When the serialized [threading mode] is in use, it might be the
  2966         -** case that a second error occurs on a separate thread in between
  2967         -** the time of the first error and the call to these interfaces.
  2968         -** When that happens, the second error will be reported since these
  2969         -** interfaces always report the most recent result.  To avoid
  2970         -** this, each thread can obtain exclusive use of the [database connection] D
  2971         -** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
  2972         -** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
  2973         -** all calls to the interfaces listed here are completed.
  2974         -**
  2975         -** If an interface fails with SQLITE_MISUSE, that means the interface
  2976         -** was invoked incorrectly by the application.  In that case, the
  2977         -** error code and message may or may not be set.
  2978         -*/
  2979         -SQLITE_API int sqlite3_errcode(sqlite3 *db);
  2980         -SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
  2981         -SQLITE_API const char *sqlite3_errmsg(sqlite3*);
  2982         -SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
  2983         -SQLITE_API const char *sqlite3_errstr(int);
  2984         -
  2985         -/*
  2986         -** CAPI3REF: SQL Statement Object
  2987         -** KEYWORDS: {prepared statement} {prepared statements}
  2988         -**
  2989         -** An instance of this object represents a single SQL statement.
  2990         -** This object is variously known as a "prepared statement" or a
  2991         -** "compiled SQL statement" or simply as a "statement".
  2992         -**
  2993         -** The life of a statement object goes something like this:
  2994         -**
  2995         -** <ol>
  2996         -** <li> Create the object using [sqlite3_prepare_v2()] or a related
  2997         -**      function.
  2998         -** <li> Bind values to [host parameters] using the sqlite3_bind_*()
  2999         -**      interfaces.
  3000         -** <li> Run the SQL by calling [sqlite3_step()] one or more times.
  3001         -** <li> Reset the statement using [sqlite3_reset()] then go back
  3002         -**      to step 2.  Do this zero or more times.
  3003         -** <li> Destroy the object using [sqlite3_finalize()].
  3004         -** </ol>
  3005         -**
  3006         -** Refer to documentation on individual methods above for additional
  3007         -** information.
  3008         -*/
  3009         -typedef struct sqlite3_stmt sqlite3_stmt;
  3010         -
  3011         -/*
  3012         -** CAPI3REF: Run-time Limits
  3013         -**
  3014         -** ^(This interface allows the size of various constructs to be limited
  3015         -** on a connection by connection basis.  The first parameter is the
  3016         -** [database connection] whose limit is to be set or queried.  The
  3017         -** second parameter is one of the [limit categories] that define a
  3018         -** class of constructs to be size limited.  The third parameter is the
  3019         -** new limit for that construct.)^
  3020         -**
  3021         -** ^If the new limit is a negative number, the limit is unchanged.
  3022         -** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 
  3023         -** [limits | hard upper bound]
  3024         -** set at compile-time by a C preprocessor macro called
  3025         -** [limits | SQLITE_MAX_<i>NAME</i>].
  3026         -** (The "_LIMIT_" in the name is changed to "_MAX_".))^
  3027         -** ^Attempts to increase a limit above its hard upper bound are
  3028         -** silently truncated to the hard upper bound.
  3029         -**
  3030         -** ^Regardless of whether or not the limit was changed, the 
  3031         -** [sqlite3_limit()] interface returns the prior value of the limit.
  3032         -** ^Hence, to find the current value of a limit without changing it,
  3033         -** simply invoke this interface with the third parameter set to -1.
  3034         -**
  3035         -** Run-time limits are intended for use in applications that manage
  3036         -** both their own internal database and also databases that are controlled
  3037         -** by untrusted external sources.  An example application might be a
  3038         -** web browser that has its own databases for storing history and
  3039         -** separate databases controlled by JavaScript applications downloaded
  3040         -** off the Internet.  The internal databases can be given the
  3041         -** large, default limits.  Databases managed by external sources can
  3042         -** be given much smaller limits designed to prevent a denial of service
  3043         -** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
  3044         -** interface to further control untrusted SQL.  The size of the database
  3045         -** created by an untrusted script can be contained using the
  3046         -** [max_page_count] [PRAGMA].
  3047         -**
  3048         -** New run-time limit categories may be added in future releases.
  3049         -*/
  3050         -SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
  3051         -
  3052         -/*
  3053         -** CAPI3REF: Run-Time Limit Categories
  3054         -** KEYWORDS: {limit category} {*limit categories}
  3055         -**
  3056         -** These constants define various performance limits
  3057         -** that can be lowered at run-time using [sqlite3_limit()].
  3058         -** The synopsis of the meanings of the various limits is shown below.
  3059         -** Additional information is available at [limits | Limits in SQLite].
  3060         -**
  3061         -** <dl>
  3062         -** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
  3063         -** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
  3064         -**
  3065         -** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
  3066         -** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
  3067         -**
  3068         -** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
  3069         -** <dd>The maximum number of columns in a table definition or in the
  3070         -** result set of a [SELECT] or the maximum number of columns in an index
  3071         -** or in an ORDER BY or GROUP BY clause.</dd>)^
  3072         -**
  3073         -** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
  3074         -** <dd>The maximum depth of the parse tree on any expression.</dd>)^
  3075         -**
  3076         -** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  3077         -** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
  3078         -**
  3079         -** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
  3080         -** <dd>The maximum number of instructions in a virtual machine program
  3081         -** used to implement an SQL statement.  This limit is not currently
  3082         -** enforced, though that might be added in some future release of
  3083         -** SQLite.</dd>)^
  3084         -**
  3085         -** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  3086         -** <dd>The maximum number of arguments on a function.</dd>)^
  3087         -**
  3088         -** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
  3089         -** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
  3090         -**
  3091         -** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
  3092         -** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
  3093         -** <dd>The maximum length of the pattern argument to the [LIKE] or
  3094         -** [GLOB] operators.</dd>)^
  3095         -**
  3096         -** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
  3097         -** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
  3098         -** <dd>The maximum index number of any [parameter] in an SQL statement.)^
  3099         -**
  3100         -** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
  3101         -** <dd>The maximum depth of recursion for triggers.</dd>)^
  3102         -**
  3103         -** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
  3104         -** <dd>The maximum number of auxiliary worker threads that a single
  3105         -** [prepared statement] may start.</dd>)^
  3106         -** </dl>
  3107         -*/
  3108         -#define SQLITE_LIMIT_LENGTH                    0
  3109         -#define SQLITE_LIMIT_SQL_LENGTH                1
  3110         -#define SQLITE_LIMIT_COLUMN                    2
  3111         -#define SQLITE_LIMIT_EXPR_DEPTH                3
  3112         -#define SQLITE_LIMIT_COMPOUND_SELECT           4
  3113         -#define SQLITE_LIMIT_VDBE_OP                   5
  3114         -#define SQLITE_LIMIT_FUNCTION_ARG              6
  3115         -#define SQLITE_LIMIT_ATTACHED                  7
  3116         -#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
  3117         -#define SQLITE_LIMIT_VARIABLE_NUMBER           9
  3118         -#define SQLITE_LIMIT_TRIGGER_DEPTH            10
  3119         -#define SQLITE_LIMIT_WORKER_THREADS           11
  3120         -
  3121         -/*
  3122         -** CAPI3REF: Compiling An SQL Statement
  3123         -** KEYWORDS: {SQL statement compiler}
  3124         -**
  3125         -** To execute an SQL query, it must first be compiled into a byte-code
  3126         -** program using one of these routines.
  3127         -**
  3128         -** The first argument, "db", is a [database connection] obtained from a
  3129         -** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
  3130         -** [sqlite3_open16()].  The database connection must not have been closed.
  3131         -**
  3132         -** The second argument, "zSql", is the statement to be compiled, encoded
  3133         -** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
  3134         -** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
  3135         -** use UTF-16.
  3136         -**
  3137         -** ^If the nByte argument is less than zero, then zSql is read up to the
  3138         -** first zero terminator. ^If nByte is non-negative, then it is the maximum
  3139         -** number of  bytes read from zSql.  ^When nByte is non-negative, the
  3140         -** zSql string ends at either the first '\000' or '\u0000' character or
  3141         -** the nByte-th byte, whichever comes first. If the caller knows
  3142         -** that the supplied string is nul-terminated, then there is a small
  3143         -** performance advantage to be gained by passing an nByte parameter that
  3144         -** is equal to the number of bytes in the input string <i>including</i>
  3145         -** the nul-terminator bytes as this saves SQLite from having to
  3146         -** make a copy of the input string.
  3147         -**
  3148         -** ^If pzTail is not NULL then *pzTail is made to point to the first byte
  3149         -** past the end of the first SQL statement in zSql.  These routines only
  3150         -** compile the first statement in zSql, so *pzTail is left pointing to
  3151         -** what remains uncompiled.
  3152         -**
  3153         -** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
  3154         -** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
  3155         -** to NULL.  ^If the input text contains no SQL (if the input is an empty
  3156         -** string or a comment) then *ppStmt is set to NULL.
  3157         -** The calling procedure is responsible for deleting the compiled
  3158         -** SQL statement using [sqlite3_finalize()] after it has finished with it.
  3159         -** ppStmt may not be NULL.
  3160         -**
  3161         -** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
  3162         -** otherwise an [error code] is returned.
  3163         -**
  3164         -** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  3165         -** recommended for all new programs. The two older interfaces are retained
  3166         -** for backwards compatibility, but their use is discouraged.
  3167         -** ^In the "v2" interfaces, the prepared statement
  3168         -** that is returned (the [sqlite3_stmt] object) contains a copy of the
  3169         -** original SQL text. This causes the [sqlite3_step()] interface to
  3170         -** behave differently in three ways:
  3171         -**
  3172         -** <ol>
  3173         -** <li>
  3174         -** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  3175         -** always used to do, [sqlite3_step()] will automatically recompile the SQL
  3176         -** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
  3177         -** retries will occur before sqlite3_step() gives up and returns an error.
  3178         -** </li>
  3179         -**
  3180         -** <li>
  3181         -** ^When an error occurs, [sqlite3_step()] will return one of the detailed
  3182         -** [error codes] or [extended error codes].  ^The legacy behavior was that
  3183         -** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
  3184         -** and the application would have to make a second call to [sqlite3_reset()]
  3185         -** in order to find the underlying cause of the problem. With the "v2" prepare
  3186         -** interfaces, the underlying reason for the error is returned immediately.
  3187         -** </li>
  3188         -**
  3189         -** <li>
  3190         -** ^If the specific value bound to [parameter | host parameter] in the 
  3191         -** WHERE clause might influence the choice of query plan for a statement,
  3192         -** then the statement will be automatically recompiled, as if there had been 
  3193         -** a schema change, on the first  [sqlite3_step()] call following any change
  3194         -** to the [sqlite3_bind_text | bindings] of that [parameter]. 
  3195         -** ^The specific value of WHERE-clause [parameter] might influence the 
  3196         -** choice of query plan if the parameter is the left-hand side of a [LIKE]
  3197         -** or [GLOB] operator or if the parameter is compared to an indexed column
  3198         -** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
  3199         -** </li>
  3200         -** </ol>
  3201         -*/
  3202         -SQLITE_API int sqlite3_prepare(
  3203         -  sqlite3 *db,            /* Database handle */
  3204         -  const char *zSql,       /* SQL statement, UTF-8 encoded */
  3205         -  int nByte,              /* Maximum length of zSql in bytes. */
  3206         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3207         -  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  3208         -);
  3209         -SQLITE_API int sqlite3_prepare_v2(
  3210         -  sqlite3 *db,            /* Database handle */
  3211         -  const char *zSql,       /* SQL statement, UTF-8 encoded */
  3212         -  int nByte,              /* Maximum length of zSql in bytes. */
  3213         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3214         -  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  3215         -);
  3216         -SQLITE_API int sqlite3_prepare16(
  3217         -  sqlite3 *db,            /* Database handle */
  3218         -  const void *zSql,       /* SQL statement, UTF-16 encoded */
  3219         -  int nByte,              /* Maximum length of zSql in bytes. */
  3220         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3221         -  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  3222         -);
  3223         -SQLITE_API int sqlite3_prepare16_v2(
  3224         -  sqlite3 *db,            /* Database handle */
  3225         -  const void *zSql,       /* SQL statement, UTF-16 encoded */
  3226         -  int nByte,              /* Maximum length of zSql in bytes. */
  3227         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  3228         -  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  3229         -);
  3230         -
  3231         -/*
  3232         -** CAPI3REF: Retrieving Statement SQL
  3233         -**
  3234         -** ^This interface can be used to retrieve a saved copy of the original
  3235         -** SQL text used to create a [prepared statement] if that statement was
  3236         -** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
  3237         -*/
  3238         -SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
  3239         -
  3240         -/*
  3241         -** CAPI3REF: Determine If An SQL Statement Writes The Database
  3242         -**
  3243         -** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
  3244         -** and only if the [prepared statement] X makes no direct changes to
  3245         -** the content of the database file.
  3246         -**
  3247         -** Note that [application-defined SQL functions] or
  3248         -** [virtual tables] might change the database indirectly as a side effect.  
  3249         -** ^(For example, if an application defines a function "eval()" that 
  3250         -** calls [sqlite3_exec()], then the following SQL statement would
  3251         -** change the database file through side-effects:
  3252         -**
  3253         -** <blockquote><pre>
  3254         -**    SELECT eval('DELETE FROM t1') FROM t2;
  3255         -** </pre></blockquote>
  3256         -**
  3257         -** But because the [SELECT] statement does not change the database file
  3258         -** directly, sqlite3_stmt_readonly() would still return true.)^
  3259         -**
  3260         -** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
  3261         -** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
  3262         -** since the statements themselves do not actually modify the database but
  3263         -** rather they control the timing of when other statements modify the 
  3264         -** database.  ^The [ATTACH] and [DETACH] statements also cause
  3265         -** sqlite3_stmt_readonly() to return true since, while those statements
  3266         -** change the configuration of a database connection, they do not make 
  3267         -** changes to the content of the database files on disk.
  3268         -*/
  3269         -SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
  3270         -
  3271         -/*
  3272         -** CAPI3REF: Determine If A Prepared Statement Has Been Reset
  3273         -**
  3274         -** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
  3275         -** [prepared statement] S has been stepped at least once using 
  3276         -** [sqlite3_step(S)] but has not run to completion and/or has not 
  3277         -** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)
  3278         -** interface returns false if S is a NULL pointer.  If S is not a 
  3279         -** NULL pointer and is not a pointer to a valid [prepared statement]
  3280         -** object, then the behavior is undefined and probably undesirable.
  3281         -**
  3282         -** This interface can be used in combination [sqlite3_next_stmt()]
  3283         -** to locate all prepared statements associated with a database 
  3284         -** connection that are in need of being reset.  This can be used,
  3285         -** for example, in diagnostic routines to search for prepared 
  3286         -** statements that are holding a transaction open.
  3287         -*/
  3288         -SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
  3289         -
  3290         -/*
  3291         -** CAPI3REF: Dynamically Typed Value Object
  3292         -** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  3293         -**
  3294         -** SQLite uses the sqlite3_value object to represent all values
  3295         -** that can be stored in a database table. SQLite uses dynamic typing
  3296         -** for the values it stores.  ^Values stored in sqlite3_value objects
  3297         -** can be integers, floating point values, strings, BLOBs, or NULL.
  3298         -**
  3299         -** An sqlite3_value object may be either "protected" or "unprotected".
  3300         -** Some interfaces require a protected sqlite3_value.  Other interfaces
  3301         -** will accept either a protected or an unprotected sqlite3_value.
  3302         -** Every interface that accepts sqlite3_value arguments specifies
  3303         -** whether or not it requires a protected sqlite3_value.
  3304         -**
  3305         -** The terms "protected" and "unprotected" refer to whether or not
  3306         -** a mutex is held.  An internal mutex is held for a protected
  3307         -** sqlite3_value object but no mutex is held for an unprotected
  3308         -** sqlite3_value object.  If SQLite is compiled to be single-threaded
  3309         -** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
  3310         -** or if SQLite is run in one of reduced mutex modes 
  3311         -** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
  3312         -** then there is no distinction between protected and unprotected
  3313         -** sqlite3_value objects and they can be used interchangeably.  However,
  3314         -** for maximum code portability it is recommended that applications
  3315         -** still make the distinction between protected and unprotected
  3316         -** sqlite3_value objects even when not strictly required.
  3317         -**
  3318         -** ^The sqlite3_value objects that are passed as parameters into the
  3319         -** implementation of [application-defined SQL functions] are protected.
  3320         -** ^The sqlite3_value object returned by
  3321         -** [sqlite3_column_value()] is unprotected.
  3322         -** Unprotected sqlite3_value objects may only be used with
  3323         -** [sqlite3_result_value()] and [sqlite3_bind_value()].
  3324         -** The [sqlite3_value_blob | sqlite3_value_type()] family of
  3325         -** interfaces require protected sqlite3_value objects.
  3326         -*/
  3327         -typedef struct Mem sqlite3_value;
  3328         -
  3329         -/*
  3330         -** CAPI3REF: SQL Function Context Object
  3331         -**
  3332         -** The context in which an SQL function executes is stored in an
  3333         -** sqlite3_context object.  ^A pointer to an sqlite3_context object
  3334         -** is always first parameter to [application-defined SQL functions].
  3335         -** The application-defined SQL function implementation will pass this
  3336         -** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
  3337         -** [sqlite3_aggregate_context()], [sqlite3_user_data()],
  3338         -** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
  3339         -** and/or [sqlite3_set_auxdata()].
  3340         -*/
  3341         -typedef struct sqlite3_context sqlite3_context;
  3342         -
  3343         -/*
  3344         -** CAPI3REF: Binding Values To Prepared Statements
  3345         -** KEYWORDS: {host parameter} {host parameters} {host parameter name}
  3346         -** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
  3347         -**
  3348         -** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
  3349         -** literals may be replaced by a [parameter] that matches one of following
  3350         -** templates:
  3351         -**
  3352         -** <ul>
  3353         -** <li>  ?
  3354         -** <li>  ?NNN
  3355         -** <li>  :VVV
  3356         -** <li>  @VVV
  3357         -** <li>  $VVV
  3358         -** </ul>
  3359         -**
  3360         -** In the templates above, NNN represents an integer literal,
  3361         -** and VVV represents an alphanumeric identifier.)^  ^The values of these
  3362         -** parameters (also called "host parameter names" or "SQL parameters")
  3363         -** can be set using the sqlite3_bind_*() routines defined here.
  3364         -**
  3365         -** ^The first argument to the sqlite3_bind_*() routines is always
  3366         -** a pointer to the [sqlite3_stmt] object returned from
  3367         -** [sqlite3_prepare_v2()] or its variants.
  3368         -**
  3369         -** ^The second argument is the index of the SQL parameter to be set.
  3370         -** ^The leftmost SQL parameter has an index of 1.  ^When the same named
  3371         -** SQL parameter is used more than once, second and subsequent
  3372         -** occurrences have the same index as the first occurrence.
  3373         -** ^The index for named parameters can be looked up using the
  3374         -** [sqlite3_bind_parameter_index()] API if desired.  ^The index
  3375         -** for "?NNN" parameters is the value of NNN.
  3376         -** ^The NNN value must be between 1 and the [sqlite3_limit()]
  3377         -** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
  3378         -**
  3379         -** ^The third argument is the value to bind to the parameter.
  3380         -** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  3381         -** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
  3382         -** is ignored and the end result is the same as sqlite3_bind_null().
  3383         -**
  3384         -** ^(In those routines that have a fourth argument, its value is the
  3385         -** number of bytes in the parameter.  To be clear: the value is the
  3386         -** number of <u>bytes</u> in the value, not the number of characters.)^
  3387         -** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
  3388         -** is negative, then the length of the string is
  3389         -** the number of bytes up to the first zero terminator.
  3390         -** If the fourth parameter to sqlite3_bind_blob() is negative, then
  3391         -** the behavior is undefined.
  3392         -** If a non-negative fourth parameter is provided to sqlite3_bind_text()
  3393         -** or sqlite3_bind_text16() or sqlite3_bind_text64() then
  3394         -** that parameter must be the byte offset
  3395         -** where the NUL terminator would occur assuming the string were NUL
  3396         -** terminated.  If any NUL characters occur at byte offsets less than 
  3397         -** the value of the fourth parameter then the resulting string value will
  3398         -** contain embedded NULs.  The result of expressions involving strings
  3399         -** with embedded NULs is undefined.
  3400         -**
  3401         -** ^The fifth argument to the BLOB and string binding interfaces
  3402         -** is a destructor used to dispose of the BLOB or
  3403         -** string after SQLite has finished with it.  ^The destructor is called
  3404         -** to dispose of the BLOB or string even if the call to bind API fails.
  3405         -** ^If the fifth argument is
  3406         -** the special value [SQLITE_STATIC], then SQLite assumes that the
  3407         -** information is in static, unmanaged space and does not need to be freed.
  3408         -** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
  3409         -** SQLite makes its own private copy of the data immediately, before
  3410         -** the sqlite3_bind_*() routine returns.
  3411         -**
  3412         -** ^The sixth argument to sqlite3_bind_text64() must be one of
  3413         -** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
  3414         -** to specify the encoding of the text in the third parameter.  If
  3415         -** the sixth argument to sqlite3_bind_text64() is not one of the
  3416         -** allowed values shown above, or if the text encoding is different
  3417         -** from the encoding specified by the sixth parameter, then the behavior
  3418         -** is undefined.
  3419         -**
  3420         -** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  3421         -** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
  3422         -** (just an integer to hold its size) while it is being processed.
  3423         -** Zeroblobs are intended to serve as placeholders for BLOBs whose
  3424         -** content is later written using
  3425         -** [sqlite3_blob_open | incremental BLOB I/O] routines.
  3426         -** ^A negative value for the zeroblob results in a zero-length BLOB.
  3427         -**
  3428         -** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
  3429         -** for the [prepared statement] or with a prepared statement for which
  3430         -** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
  3431         -** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
  3432         -** routine is passed a [prepared statement] that has been finalized, the
  3433         -** result is undefined and probably harmful.
  3434         -**
  3435         -** ^Bindings are not cleared by the [sqlite3_reset()] routine.
  3436         -** ^Unbound parameters are interpreted as NULL.
  3437         -**
  3438         -** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
  3439         -** [error code] if anything goes wrong.
  3440         -** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
  3441         -** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
  3442         -** [SQLITE_MAX_LENGTH].
  3443         -** ^[SQLITE_RANGE] is returned if the parameter
  3444         -** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
  3445         -**
  3446         -** See also: [sqlite3_bind_parameter_count()],
  3447         -** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
  3448         -*/
  3449         -SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  3450         -SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
  3451         -                        void(*)(void*));
  3452         -SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
  3453         -SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
  3454         -SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  3455         -SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
  3456         -SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
  3457         -SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  3458         -SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
  3459         -                         void(*)(void*), unsigned char encoding);
  3460         -SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  3461         -SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  3462         -
  3463         -/*
  3464         -** CAPI3REF: Number Of SQL Parameters
  3465         -**
  3466         -** ^This routine can be used to find the number of [SQL parameters]
  3467         -** in a [prepared statement].  SQL parameters are tokens of the
  3468         -** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
  3469         -** placeholders for values that are [sqlite3_bind_blob | bound]
  3470         -** to the parameters at a later time.
  3471         -**
  3472         -** ^(This routine actually returns the index of the largest (rightmost)
  3473         -** parameter. For all forms except ?NNN, this will correspond to the
  3474         -** number of unique parameters.  If parameters of the ?NNN form are used,
  3475         -** there may be gaps in the list.)^
  3476         -**
  3477         -** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3478         -** [sqlite3_bind_parameter_name()], and
  3479         -** [sqlite3_bind_parameter_index()].
  3480         -*/
  3481         -SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
  3482         -
  3483         -/*
  3484         -** CAPI3REF: Name Of A Host Parameter
  3485         -**
  3486         -** ^The sqlite3_bind_parameter_name(P,N) interface returns
  3487         -** the name of the N-th [SQL parameter] in the [prepared statement] P.
  3488         -** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
  3489         -** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
  3490         -** respectively.
  3491         -** In other words, the initial ":" or "$" or "@" or "?"
  3492         -** is included as part of the name.)^
  3493         -** ^Parameters of the form "?" without a following integer have no name
  3494         -** and are referred to as "nameless" or "anonymous parameters".
  3495         -**
  3496         -** ^The first host parameter has an index of 1, not 0.
  3497         -**
  3498         -** ^If the value N is out of range or if the N-th parameter is
  3499         -** nameless, then NULL is returned.  ^The returned string is
  3500         -** always in UTF-8 encoding even if the named parameter was
  3501         -** originally specified as UTF-16 in [sqlite3_prepare16()] or
  3502         -** [sqlite3_prepare16_v2()].
  3503         -**
  3504         -** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3505         -** [sqlite3_bind_parameter_count()], and
  3506         -** [sqlite3_bind_parameter_index()].
  3507         -*/
  3508         -SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  3509         -
  3510         -/*
  3511         -** CAPI3REF: Index Of A Parameter With A Given Name
  3512         -**
  3513         -** ^Return the index of an SQL parameter given its name.  ^The
  3514         -** index value returned is suitable for use as the second
  3515         -** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
  3516         -** is returned if no matching parameter is found.  ^The parameter
  3517         -** name must be given in UTF-8 even if the original statement
  3518         -** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
  3519         -**
  3520         -** See also: [sqlite3_bind_blob|sqlite3_bind()],
  3521         -** [sqlite3_bind_parameter_count()], and
  3522         -** [sqlite3_bind_parameter_index()].
  3523         -*/
  3524         -SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  3525         -
  3526         -/*
  3527         -** CAPI3REF: Reset All Bindings On A Prepared Statement
  3528         -**
  3529         -** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
  3530         -** the [sqlite3_bind_blob | bindings] on a [prepared statement].
  3531         -** ^Use this routine to reset all host parameters to NULL.
  3532         -*/
  3533         -SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
  3534         -
  3535         -/*
  3536         -** CAPI3REF: Number Of Columns In A Result Set
  3537         -**
  3538         -** ^Return the number of columns in the result set returned by the
  3539         -** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
  3540         -** statement that does not return data (for example an [UPDATE]).
  3541         -**
  3542         -** See also: [sqlite3_data_count()]
  3543         -*/
  3544         -SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
  3545         -
  3546         -/*
  3547         -** CAPI3REF: Column Names In A Result Set
  3548         -**
  3549         -** ^These routines return the name assigned to a particular column
  3550         -** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
  3551         -** interface returns a pointer to a zero-terminated UTF-8 string
  3552         -** and sqlite3_column_name16() returns a pointer to a zero-terminated
  3553         -** UTF-16 string.  ^The first parameter is the [prepared statement]
  3554         -** that implements the [SELECT] statement. ^The second parameter is the
  3555         -** column number.  ^The leftmost column is number 0.
  3556         -**
  3557         -** ^The returned string pointer is valid until either the [prepared statement]
  3558         -** is destroyed by [sqlite3_finalize()] or until the statement is automatically
  3559         -** reprepared by the first call to [sqlite3_step()] for a particular run
  3560         -** or until the next call to
  3561         -** sqlite3_column_name() or sqlite3_column_name16() on the same column.
  3562         -**
  3563         -** ^If sqlite3_malloc() fails during the processing of either routine
  3564         -** (for example during a conversion from UTF-8 to UTF-16) then a
  3565         -** NULL pointer is returned.
  3566         -**
  3567         -** ^The name of a result column is the value of the "AS" clause for
  3568         -** that column, if there is an AS clause.  If there is no AS clause
  3569         -** then the name of the column is unspecified and may change from
  3570         -** one release of SQLite to the next.
  3571         -*/
  3572         -SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
  3573         -SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  3574         -
  3575         -/*
  3576         -** CAPI3REF: Source Of Data In A Query Result
  3577         -**
  3578         -** ^These routines provide a means to determine the database, table, and
  3579         -** table column that is the origin of a particular result column in
  3580         -** [SELECT] statement.
  3581         -** ^The name of the database or table or column can be returned as
  3582         -** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
  3583         -** the database name, the _table_ routines return the table name, and
  3584         -** the origin_ routines return the column name.
  3585         -** ^The returned string is valid until the [prepared statement] is destroyed
  3586         -** using [sqlite3_finalize()] or until the statement is automatically
  3587         -** reprepared by the first call to [sqlite3_step()] for a particular run
  3588         -** or until the same information is requested
  3589         -** again in a different encoding.
  3590         -**
  3591         -** ^The names returned are the original un-aliased names of the
  3592         -** database, table, and column.
  3593         -**
  3594         -** ^The first argument to these interfaces is a [prepared statement].
  3595         -** ^These functions return information about the Nth result column returned by
  3596         -** the statement, where N is the second function argument.
  3597         -** ^The left-most column is column 0 for these routines.
  3598         -**
  3599         -** ^If the Nth column returned by the statement is an expression or
  3600         -** subquery and is not a column value, then all of these functions return
  3601         -** NULL.  ^These routine might also return NULL if a memory allocation error
  3602         -** occurs.  ^Otherwise, they return the name of the attached database, table,
  3603         -** or column that query result column was extracted from.
  3604         -**
  3605         -** ^As with all other SQLite APIs, those whose names end with "16" return
  3606         -** UTF-16 encoded strings and the other functions return UTF-8.
  3607         -**
  3608         -** ^These APIs are only available if the library was compiled with the
  3609         -** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
  3610         -**
  3611         -** If two or more threads call one or more of these routines against the same
  3612         -** prepared statement and column at the same time then the results are
  3613         -** undefined.
  3614         -**
  3615         -** If two or more threads call one or more
  3616         -** [sqlite3_column_database_name | column metadata interfaces]
  3617         -** for the same [prepared statement] and result column
  3618         -** at the same time then the results are undefined.
  3619         -*/
  3620         -SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  3621         -SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  3622         -SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  3623         -SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  3624         -SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  3625         -SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  3626         -
  3627         -/*
  3628         -** CAPI3REF: Declared Datatype Of A Query Result
  3629         -**
  3630         -** ^(The first parameter is a [prepared statement].
  3631         -** If this statement is a [SELECT] statement and the Nth column of the
  3632         -** returned result set of that [SELECT] is a table column (not an
  3633         -** expression or subquery) then the declared type of the table
  3634         -** column is returned.)^  ^If the Nth column of the result set is an
  3635         -** expression or subquery, then a NULL pointer is returned.
  3636         -** ^The returned string is always UTF-8 encoded.
  3637         -**
  3638         -** ^(For example, given the database schema:
  3639         -**
  3640         -** CREATE TABLE t1(c1 VARIANT);
  3641         -**
  3642         -** and the following statement to be compiled:
  3643         -**
  3644         -** SELECT c1 + 1, c1 FROM t1;
  3645         -**
  3646         -** this routine would return the string "VARIANT" for the second result
  3647         -** column (i==1), and a NULL pointer for the first result column (i==0).)^
  3648         -**
  3649         -** ^SQLite uses dynamic run-time typing.  ^So just because a column
  3650         -** is declared to contain a particular type does not mean that the
  3651         -** data stored in that column is of the declared type.  SQLite is
  3652         -** strongly typed, but the typing is dynamic not static.  ^Type
  3653         -** is associated with individual values, not with the containers
  3654         -** used to hold those values.
  3655         -*/
  3656         -SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  3657         -SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  3658         -
  3659         -/*
  3660         -** CAPI3REF: Evaluate An SQL Statement
  3661         -**
  3662         -** After a [prepared statement] has been prepared using either
  3663         -** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
  3664         -** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
  3665         -** must be called one or more times to evaluate the statement.
  3666         -**
  3667         -** The details of the behavior of the sqlite3_step() interface depend
  3668         -** on whether the statement was prepared using the newer "v2" interface
  3669         -** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
  3670         -** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
  3671         -** new "v2" interface is recommended for new applications but the legacy
  3672         -** interface will continue to be supported.
  3673         -**
  3674         -** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
  3675         -** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  3676         -** ^With the "v2" interface, any of the other [result codes] or
  3677         -** [extended result codes] might be returned as well.
  3678         -**
  3679         -** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
  3680         -** database locks it needs to do its job.  ^If the statement is a [COMMIT]
  3681         -** or occurs outside of an explicit transaction, then you can retry the
  3682         -** statement.  If the statement is not a [COMMIT] and occurs within an
  3683         -** explicit transaction then you should rollback the transaction before
  3684         -** continuing.
  3685         -**
  3686         -** ^[SQLITE_DONE] means that the statement has finished executing
  3687         -** successfully.  sqlite3_step() should not be called again on this virtual
  3688         -** machine without first calling [sqlite3_reset()] to reset the virtual
  3689         -** machine back to its initial state.
  3690         -**
  3691         -** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
  3692         -** is returned each time a new row of data is ready for processing by the
  3693         -** caller. The values may be accessed using the [column access functions].
  3694         -** sqlite3_step() is called again to retrieve the next row of data.
  3695         -**
  3696         -** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
  3697         -** violation) has occurred.  sqlite3_step() should not be called again on
  3698         -** the VM. More information may be found by calling [sqlite3_errmsg()].
  3699         -** ^With the legacy interface, a more specific error code (for example,
  3700         -** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  3701         -** can be obtained by calling [sqlite3_reset()] on the
  3702         -** [prepared statement].  ^In the "v2" interface,
  3703         -** the more specific error code is returned directly by sqlite3_step().
  3704         -**
  3705         -** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  3706         -** Perhaps it was called on a [prepared statement] that has
  3707         -** already been [sqlite3_finalize | finalized] or on one that had
  3708         -** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
  3709         -** be the case that the same database connection is being used by two or
  3710         -** more threads at the same moment in time.
  3711         -**
  3712         -** For all versions of SQLite up to and including 3.6.23.1, a call to
  3713         -** [sqlite3_reset()] was required after sqlite3_step() returned anything
  3714         -** other than [SQLITE_ROW] before any subsequent invocation of
  3715         -** sqlite3_step().  Failure to reset the prepared statement using 
  3716         -** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
  3717         -** sqlite3_step().  But after version 3.6.23.1, sqlite3_step() began
  3718         -** calling [sqlite3_reset()] automatically in this circumstance rather
  3719         -** than returning [SQLITE_MISUSE].  This is not considered a compatibility
  3720         -** break because any application that ever receives an SQLITE_MISUSE error
  3721         -** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
  3722         -** can be used to restore the legacy behavior.
  3723         -**
  3724         -** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
  3725         -** API always returns a generic error code, [SQLITE_ERROR], following any
  3726         -** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
  3727         -** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
  3728         -** specific [error codes] that better describes the error.
  3729         -** We admit that this is a goofy design.  The problem has been fixed
  3730         -** with the "v2" interface.  If you prepare all of your SQL statements
  3731         -** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
  3732         -** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
  3733         -** then the more specific [error codes] are returned directly
  3734         -** by sqlite3_step().  The use of the "v2" interface is recommended.
  3735         -*/
  3736         -SQLITE_API int sqlite3_step(sqlite3_stmt*);
  3737         -
  3738         -/*
  3739         -** CAPI3REF: Number of columns in a result set
  3740         -**
  3741         -** ^The sqlite3_data_count(P) interface returns the number of columns in the
  3742         -** current row of the result set of [prepared statement] P.
  3743         -** ^If prepared statement P does not have results ready to return
  3744         -** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
  3745         -** interfaces) then sqlite3_data_count(P) returns 0.
  3746         -** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
  3747         -** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
  3748         -** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)
  3749         -** will return non-zero if previous call to [sqlite3_step](P) returned
  3750         -** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
  3751         -** where it always returns zero since each step of that multi-step
  3752         -** pragma returns 0 columns of data.
  3753         -**
  3754         -** See also: [sqlite3_column_count()]
  3755         -*/
  3756         -SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
  3757         -
  3758         -/*
  3759         -** CAPI3REF: Fundamental Datatypes
  3760         -** KEYWORDS: SQLITE_TEXT
  3761         -**
  3762         -** ^(Every value in SQLite has one of five fundamental datatypes:
  3763         -**
  3764         -** <ul>
  3765         -** <li> 64-bit signed integer
  3766         -** <li> 64-bit IEEE floating point number
  3767         -** <li> string
  3768         -** <li> BLOB
  3769         -** <li> NULL
  3770         -** </ul>)^
  3771         -**
  3772         -** These constants are codes for each of those types.
  3773         -**
  3774         -** Note that the SQLITE_TEXT constant was also used in SQLite version 2
  3775         -** for a completely different meaning.  Software that links against both
  3776         -** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
  3777         -** SQLITE_TEXT.
  3778         -*/
  3779         -#define SQLITE_INTEGER  1
  3780         -#define SQLITE_FLOAT    2
  3781         -#define SQLITE_BLOB     4
  3782         -#define SQLITE_NULL     5
  3783         -#ifdef SQLITE_TEXT
  3784         -# undef SQLITE_TEXT
  3785         -#else
  3786         -# define SQLITE_TEXT     3
  3787         -#endif
  3788         -#define SQLITE3_TEXT     3
  3789         -
  3790         -/*
  3791         -** CAPI3REF: Result Values From A Query
  3792         -** KEYWORDS: {column access functions}
  3793         -**
  3794         -** These routines form the "result set" interface.
  3795         -**
  3796         -** ^These routines return information about a single column of the current
  3797         -** result row of a query.  ^In every case the first argument is a pointer
  3798         -** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  3799         -** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  3800         -** and the second argument is the index of the column for which information
  3801         -** should be returned. ^The leftmost column of the result set has the index 0.
  3802         -** ^The number of columns in the result can be determined using
  3803         -** [sqlite3_column_count()].
  3804         -**
  3805         -** If the SQL statement does not currently point to a valid row, or if the
  3806         -** column index is out of range, the result is undefined.
  3807         -** These routines may only be called when the most recent call to
  3808         -** [sqlite3_step()] has returned [SQLITE_ROW] and neither
  3809         -** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
  3810         -** If any of these routines are called after [sqlite3_reset()] or
  3811         -** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  3812         -** something other than [SQLITE_ROW], the results are undefined.
  3813         -** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  3814         -** are called from a different thread while any of these routines
  3815         -** are pending, then the results are undefined.
  3816         -**
  3817         -** ^The sqlite3_column_type() routine returns the
  3818         -** [SQLITE_INTEGER | datatype code] for the initial data type
  3819         -** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
  3820         -** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
  3821         -** returned by sqlite3_column_type() is only meaningful if no type
  3822         -** conversions have occurred as described below.  After a type conversion,
  3823         -** the value returned by sqlite3_column_type() is undefined.  Future
  3824         -** versions of SQLite may change the behavior of sqlite3_column_type()
  3825         -** following a type conversion.
  3826         -**
  3827         -** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
  3828         -** routine returns the number of bytes in that BLOB or string.
  3829         -** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  3830         -** the string to UTF-8 and then returns the number of bytes.
  3831         -** ^If the result is a numeric value then sqlite3_column_bytes() uses
  3832         -** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  3833         -** the number of bytes in that string.
  3834         -** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
  3835         -**
  3836         -** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
  3837         -** routine returns the number of bytes in that BLOB or string.
  3838         -** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
  3839         -** the string to UTF-16 and then returns the number of bytes.
  3840         -** ^If the result is a numeric value then sqlite3_column_bytes16() uses
  3841         -** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
  3842         -** the number of bytes in that string.
  3843         -** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
  3844         -**
  3845         -** ^The values returned by [sqlite3_column_bytes()] and 
  3846         -** [sqlite3_column_bytes16()] do not include the zero terminators at the end
  3847         -** of the string.  ^For clarity: the values returned by
  3848         -** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
  3849         -** bytes in the string, not the number of characters.
  3850         -**
  3851         -** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  3852         -** even empty strings, are always zero-terminated.  ^The return
  3853         -** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
  3854         -**
  3855         -** ^The object returned by [sqlite3_column_value()] is an
  3856         -** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
  3857         -** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
  3858         -** If the [unprotected sqlite3_value] object returned by
  3859         -** [sqlite3_column_value()] is used in any other way, including calls
  3860         -** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  3861         -** or [sqlite3_value_bytes()], then the behavior is undefined.
  3862         -**
  3863         -** These routines attempt to convert the value where appropriate.  ^For
  3864         -** example, if the internal representation is FLOAT and a text result
  3865         -** is requested, [sqlite3_snprintf()] is used internally to perform the
  3866         -** conversion automatically.  ^(The following table details the conversions
  3867         -** that are applied:
  3868         -**
  3869         -** <blockquote>
  3870         -** <table border="1">
  3871         -** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
  3872         -**
  3873         -** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
  3874         -** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
  3875         -** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer
  3876         -** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer
  3877         -** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
  3878         -** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
  3879         -** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
  3880         -** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER
  3881         -** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
  3882         -** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB
  3883         -** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER
  3884         -** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL
  3885         -** <tr><td>  TEXT    <td>   BLOB    <td> No change
  3886         -** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
  3887         -** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
  3888         -** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
  3889         -** </table>
  3890         -** </blockquote>)^
  3891         -**
  3892         -** The table above makes reference to standard C library functions atoi()
  3893         -** and atof().  SQLite does not really use these functions.  It has its
  3894         -** own equivalent internal routines.  The atoi() and atof() names are
  3895         -** used in the table for brevity and because they are familiar to most
  3896         -** C programmers.
  3897         -**
  3898         -** Note that when type conversions occur, pointers returned by prior
  3899         -** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  3900         -** sqlite3_column_text16() may be invalidated.
  3901         -** Type conversions and pointer invalidations might occur
  3902         -** in the following cases:
  3903         -**
  3904         -** <ul>
  3905         -** <li> The initial content is a BLOB and sqlite3_column_text() or
  3906         -**      sqlite3_column_text16() is called.  A zero-terminator might
  3907         -**      need to be added to the string.</li>
  3908         -** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
  3909         -**      sqlite3_column_text16() is called.  The content must be converted
  3910         -**      to UTF-16.</li>
  3911         -** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
  3912         -**      sqlite3_column_text() is called.  The content must be converted
  3913         -**      to UTF-8.</li>
  3914         -** </ul>
  3915         -**
  3916         -** ^Conversions between UTF-16be and UTF-16le are always done in place and do
  3917         -** not invalidate a prior pointer, though of course the content of the buffer
  3918         -** that the prior pointer references will have been modified.  Other kinds
  3919         -** of conversion are done in place when it is possible, but sometimes they
  3920         -** are not possible and in those cases prior pointers are invalidated.
  3921         -**
  3922         -** The safest and easiest to remember policy is to invoke these routines
  3923         -** in one of the following ways:
  3924         -**
  3925         -** <ul>
  3926         -**  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  3927         -**  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  3928         -**  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  3929         -** </ul>
  3930         -**
  3931         -** In other words, you should call sqlite3_column_text(),
  3932         -** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
  3933         -** into the desired format, then invoke sqlite3_column_bytes() or
  3934         -** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
  3935         -** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  3936         -** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  3937         -** with calls to sqlite3_column_bytes().
  3938         -**
  3939         -** ^The pointers returned are valid until a type conversion occurs as
  3940         -** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  3941         -** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
  3942         -** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
  3943         -** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  3944         -** [sqlite3_free()].
  3945         -**
  3946         -** ^(If a memory allocation error occurs during the evaluation of any
  3947         -** of these routines, a default value is returned.  The default value
  3948         -** is either the integer 0, the floating point number 0.0, or a NULL
  3949         -** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  3950         -** [SQLITE_NOMEM].)^
  3951         -*/
  3952         -SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  3953         -SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  3954         -SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  3955         -SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
  3956         -SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
  3957         -SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  3958         -SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  3959         -SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  3960         -SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  3961         -SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  3962         -
  3963         -/*
  3964         -** CAPI3REF: Destroy A Prepared Statement Object
  3965         -**
  3966         -** ^The sqlite3_finalize() function is called to delete a [prepared statement].
  3967         -** ^If the most recent evaluation of the statement encountered no errors
  3968         -** or if the statement is never been evaluated, then sqlite3_finalize() returns
  3969         -** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
  3970         -** sqlite3_finalize(S) returns the appropriate [error code] or
  3971         -** [extended error code].
  3972         -**
  3973         -** ^The sqlite3_finalize(S) routine can be called at any point during
  3974         -** the life cycle of [prepared statement] S:
  3975         -** before statement S is ever evaluated, after
  3976         -** one or more calls to [sqlite3_reset()], or after any call
  3977         -** to [sqlite3_step()] regardless of whether or not the statement has
  3978         -** completed execution.
  3979         -**
  3980         -** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
  3981         -**
  3982         -** The application must finalize every [prepared statement] in order to avoid
  3983         -** resource leaks.  It is a grievous error for the application to try to use
  3984         -** a prepared statement after it has been finalized.  Any use of a prepared
  3985         -** statement after it has been finalized can result in undefined and
  3986         -** undesirable behavior such as segfaults and heap corruption.
  3987         -*/
  3988         -SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
  3989         -
  3990         -/*
  3991         -** CAPI3REF: Reset A Prepared Statement Object
  3992         -**
  3993         -** The sqlite3_reset() function is called to reset a [prepared statement]
  3994         -** object back to its initial state, ready to be re-executed.
  3995         -** ^Any SQL statement variables that had values bound to them using
  3996         -** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  3997         -** Use [sqlite3_clear_bindings()] to reset the bindings.
  3998         -**
  3999         -** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
  4000         -** back to the beginning of its program.
  4001         -**
  4002         -** ^If the most recent call to [sqlite3_step(S)] for the
  4003         -** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
  4004         -** or if [sqlite3_step(S)] has never before been called on S,
  4005         -** then [sqlite3_reset(S)] returns [SQLITE_OK].
  4006         -**
  4007         -** ^If the most recent call to [sqlite3_step(S)] for the
  4008         -** [prepared statement] S indicated an error, then
  4009         -** [sqlite3_reset(S)] returns an appropriate [error code].
  4010         -**
  4011         -** ^The [sqlite3_reset(S)] interface does not change the values
  4012         -** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
  4013         -*/
  4014         -SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
  4015         -
  4016         -/*
  4017         -** CAPI3REF: Create Or Redefine SQL Functions
  4018         -** KEYWORDS: {function creation routines}
  4019         -** KEYWORDS: {application-defined SQL function}
  4020         -** KEYWORDS: {application-defined SQL functions}
  4021         -**
  4022         -** ^These functions (collectively known as "function creation routines")
  4023         -** are used to add SQL functions or aggregates or to redefine the behavior
  4024         -** of existing SQL functions or aggregates.  The only differences between
  4025         -** these routines are the text encoding expected for
  4026         -** the second parameter (the name of the function being created)
  4027         -** and the presence or absence of a destructor callback for
  4028         -** the application data pointer.
  4029         -**
  4030         -** ^The first parameter is the [database connection] to which the SQL
  4031         -** function is to be added.  ^If an application uses more than one database
  4032         -** connection then application-defined SQL functions must be added
  4033         -** to each database connection separately.
  4034         -**
  4035         -** ^The second parameter is the name of the SQL function to be created or
  4036         -** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8
  4037         -** representation, exclusive of the zero-terminator.  ^Note that the name
  4038         -** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.  
  4039         -** ^Any attempt to create a function with a longer name
  4040         -** will result in [SQLITE_MISUSE] being returned.
  4041         -**
  4042         -** ^The third parameter (nArg)
  4043         -** is the number of arguments that the SQL function or
  4044         -** aggregate takes. ^If this parameter is -1, then the SQL function or
  4045         -** aggregate may take any number of arguments between 0 and the limit
  4046         -** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
  4047         -** parameter is less than -1 or greater than 127 then the behavior is
  4048         -** undefined.
  4049         -**
  4050         -** ^The fourth parameter, eTextRep, specifies what
  4051         -** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  4052         -** its parameters.  The application should set this parameter to
  4053         -** [SQLITE_UTF16LE] if the function implementation invokes 
  4054         -** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
  4055         -** implementation invokes [sqlite3_value_text16be()] on an input, or
  4056         -** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
  4057         -** otherwise.  ^The same SQL function may be registered multiple times using
  4058         -** different preferred text encodings, with different implementations for
  4059         -** each encoding.
  4060         -** ^When multiple implementations of the same function are available, SQLite
  4061         -** will pick the one that involves the least amount of data conversion.
  4062         -**
  4063         -** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
  4064         -** to signal that the function will always return the same result given
  4065         -** the same inputs within a single SQL statement.  Most SQL functions are
  4066         -** deterministic.  The built-in [random()] SQL function is an example of a
  4067         -** function that is not deterministic.  The SQLite query planner is able to
  4068         -** perform additional optimizations on deterministic functions, so use
  4069         -** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
  4070         -**
  4071         -** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
  4072         -** function can gain access to this pointer using [sqlite3_user_data()].)^
  4073         -**
  4074         -** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
  4075         -** pointers to C-language functions that implement the SQL function or
  4076         -** aggregate. ^A scalar SQL function requires an implementation of the xFunc
  4077         -** callback only; NULL pointers must be passed as the xStep and xFinal
  4078         -** parameters. ^An aggregate SQL function requires an implementation of xStep
  4079         -** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
  4080         -** SQL function or aggregate, pass NULL pointers for all three function
  4081         -** callbacks.
  4082         -**
  4083         -** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
  4084         -** then it is destructor for the application data pointer. 
  4085         -** The destructor is invoked when the function is deleted, either by being
  4086         -** overloaded or when the database connection closes.)^
  4087         -** ^The destructor is also invoked if the call to
  4088         -** sqlite3_create_function_v2() fails.
  4089         -** ^When the destructor callback of the tenth parameter is invoked, it
  4090         -** is passed a single argument which is a copy of the application data 
  4091         -** pointer which was the fifth parameter to sqlite3_create_function_v2().
  4092         -**
  4093         -** ^It is permitted to register multiple implementations of the same
  4094         -** functions with the same name but with either differing numbers of
  4095         -** arguments or differing preferred text encodings.  ^SQLite will use
  4096         -** the implementation that most closely matches the way in which the
  4097         -** SQL function is used.  ^A function implementation with a non-negative
  4098         -** nArg parameter is a better match than a function implementation with
  4099         -** a negative nArg.  ^A function where the preferred text encoding
  4100         -** matches the database encoding is a better
  4101         -** match than a function where the encoding is different.  
  4102         -** ^A function where the encoding difference is between UTF16le and UTF16be
  4103         -** is a closer match than a function where the encoding difference is
  4104         -** between UTF8 and UTF16.
  4105         -**
  4106         -** ^Built-in functions may be overloaded by new application-defined functions.
  4107         -**
  4108         -** ^An application-defined function is permitted to call other
  4109         -** SQLite interfaces.  However, such calls must not
  4110         -** close the database connection nor finalize or reset the prepared
  4111         -** statement in which the function is running.
  4112         -*/
  4113         -SQLITE_API int sqlite3_create_function(
  4114         -  sqlite3 *db,
  4115         -  const char *zFunctionName,
  4116         -  int nArg,
  4117         -  int eTextRep,
  4118         -  void *pApp,
  4119         -  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4120         -  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4121         -  void (*xFinal)(sqlite3_context*)
  4122         -);
  4123         -SQLITE_API int sqlite3_create_function16(
  4124         -  sqlite3 *db,
  4125         -  const void *zFunctionName,
  4126         -  int nArg,
  4127         -  int eTextRep,
  4128         -  void *pApp,
  4129         -  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4130         -  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4131         -  void (*xFinal)(sqlite3_context*)
  4132         -);
  4133         -SQLITE_API int sqlite3_create_function_v2(
  4134         -  sqlite3 *db,
  4135         -  const char *zFunctionName,
  4136         -  int nArg,
  4137         -  int eTextRep,
  4138         -  void *pApp,
  4139         -  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  4140         -  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  4141         -  void (*xFinal)(sqlite3_context*),
  4142         -  void(*xDestroy)(void*)
  4143         -);
  4144         -
  4145         -/*
  4146         -** CAPI3REF: Text Encodings
  4147         -**
  4148         -** These constant define integer codes that represent the various
  4149         -** text encodings supported by SQLite.
  4150         -*/
  4151         -#define SQLITE_UTF8           1
  4152         -#define SQLITE_UTF16LE        2
  4153         -#define SQLITE_UTF16BE        3
  4154         -#define SQLITE_UTF16          4    /* Use native byte order */
  4155         -#define SQLITE_ANY            5    /* Deprecated */
  4156         -#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
  4157         -
  4158         -/*
  4159         -** CAPI3REF: Function Flags
  4160         -**
  4161         -** These constants may be ORed together with the 
  4162         -** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
  4163         -** to [sqlite3_create_function()], [sqlite3_create_function16()], or
  4164         -** [sqlite3_create_function_v2()].
  4165         -*/
  4166         -#define SQLITE_DETERMINISTIC    0x800
  4167         -
  4168         -/*
  4169         -** CAPI3REF: Deprecated Functions
  4170         -** DEPRECATED
  4171         -**
  4172         -** These functions are [deprecated].  In order to maintain
  4173         -** backwards compatibility with older code, these functions continue 
  4174         -** to be supported.  However, new applications should avoid
  4175         -** the use of these functions.  To help encourage people to avoid
  4176         -** using these functions, we are not going to tell you what they do.
  4177         -*/
  4178         -#ifndef SQLITE_OMIT_DEPRECATED
  4179         -SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
  4180         -SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
  4181         -SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  4182         -SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
  4183         -SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
  4184         -SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
  4185         -                      void*,sqlite3_int64);
  4186         -#endif
  4187         -
  4188         -/*
  4189         -** CAPI3REF: Obtaining SQL Function Parameter Values
  4190         -**
  4191         -** The C-language implementation of SQL functions and aggregates uses
  4192         -** this set of interface routines to access the parameter values on
  4193         -** the function or aggregate.
  4194         -**
  4195         -** The xFunc (for scalar functions) or xStep (for aggregates) parameters
  4196         -** to [sqlite3_create_function()] and [sqlite3_create_function16()]
  4197         -** define callbacks that implement the SQL functions and aggregates.
  4198         -** The 3rd parameter to these callbacks is an array of pointers to
  4199         -** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
  4200         -** each parameter to the SQL function.  These routines are used to
  4201         -** extract values from the [sqlite3_value] objects.
  4202         -**
  4203         -** These routines work only with [protected sqlite3_value] objects.
  4204         -** Any attempt to use these routines on an [unprotected sqlite3_value]
  4205         -** object results in undefined behavior.
  4206         -**
  4207         -** ^These routines work just like the corresponding [column access functions]
  4208         -** except that these routines take a single [protected sqlite3_value] object
  4209         -** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
  4210         -**
  4211         -** ^The sqlite3_value_text16() interface extracts a UTF-16 string
  4212         -** in the native byte-order of the host machine.  ^The
  4213         -** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  4214         -** extract UTF-16 strings as big-endian and little-endian respectively.
  4215         -**
  4216         -** ^(The sqlite3_value_numeric_type() interface attempts to apply
  4217         -** numeric affinity to the value.  This means that an attempt is
  4218         -** made to convert the value to an integer or floating point.  If
  4219         -** such a conversion is possible without loss of information (in other
  4220         -** words, if the value is a string that looks like a number)
  4221         -** then the conversion is performed.  Otherwise no conversion occurs.
  4222         -** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
  4223         -**
  4224         -** Please pay particular attention to the fact that the pointer returned
  4225         -** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  4226         -** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  4227         -** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  4228         -** or [sqlite3_value_text16()].
  4229         -**
  4230         -** These routines must be called from the same thread as
  4231         -** the SQL function that supplied the [sqlite3_value*] parameters.
  4232         -*/
  4233         -SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
  4234         -SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
  4235         -SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  4236         -SQLITE_API double sqlite3_value_double(sqlite3_value*);
  4237         -SQLITE_API int sqlite3_value_int(sqlite3_value*);
  4238         -SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
  4239         -SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
  4240         -SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
  4241         -SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
  4242         -SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
  4243         -SQLITE_API int sqlite3_value_type(sqlite3_value*);
  4244         -SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
  4245         -
  4246         -/*
  4247         -** CAPI3REF: Obtain Aggregate Function Context
  4248         -**
  4249         -** Implementations of aggregate SQL functions use this
  4250         -** routine to allocate memory for storing their state.
  4251         -**
  4252         -** ^The first time the sqlite3_aggregate_context(C,N) routine is called 
  4253         -** for a particular aggregate function, SQLite
  4254         -** allocates N of memory, zeroes out that memory, and returns a pointer
  4255         -** to the new memory. ^On second and subsequent calls to
  4256         -** sqlite3_aggregate_context() for the same aggregate function instance,
  4257         -** the same buffer is returned.  Sqlite3_aggregate_context() is normally
  4258         -** called once for each invocation of the xStep callback and then one
  4259         -** last time when the xFinal callback is invoked.  ^(When no rows match
  4260         -** an aggregate query, the xStep() callback of the aggregate function
  4261         -** implementation is never called and xFinal() is called exactly once.
  4262         -** In those cases, sqlite3_aggregate_context() might be called for the
  4263         -** first time from within xFinal().)^
  4264         -**
  4265         -** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer 
  4266         -** when first called if N is less than or equal to zero or if a memory
  4267         -** allocate error occurs.
  4268         -**
  4269         -** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
  4270         -** determined by the N parameter on first successful call.  Changing the
  4271         -** value of N in subsequent call to sqlite3_aggregate_context() within
  4272         -** the same aggregate function instance will not resize the memory
  4273         -** allocation.)^  Within the xFinal callback, it is customary to set
  4274         -** N=0 in calls to sqlite3_aggregate_context(C,N) so that no 
  4275         -** pointless memory allocations occur.
  4276         -**
  4277         -** ^SQLite automatically frees the memory allocated by 
  4278         -** sqlite3_aggregate_context() when the aggregate query concludes.
  4279         -**
  4280         -** The first parameter must be a copy of the
  4281         -** [sqlite3_context | SQL function context] that is the first parameter
  4282         -** to the xStep or xFinal callback routine that implements the aggregate
  4283         -** function.
  4284         -**
  4285         -** This routine must be called from the same thread in which
  4286         -** the aggregate SQL function is running.
  4287         -*/
  4288         -SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
  4289         -
  4290         -/*
  4291         -** CAPI3REF: User Data For Functions
  4292         -**
  4293         -** ^The sqlite3_user_data() interface returns a copy of
  4294         -** the pointer that was the pUserData parameter (the 5th parameter)
  4295         -** of the [sqlite3_create_function()]
  4296         -** and [sqlite3_create_function16()] routines that originally
  4297         -** registered the application defined function.
  4298         -**
  4299         -** This routine must be called from the same thread in which
  4300         -** the application-defined function is running.
  4301         -*/
  4302         -SQLITE_API void *sqlite3_user_data(sqlite3_context*);
  4303         -
  4304         -/*
  4305         -** CAPI3REF: Database Connection For Functions
  4306         -**
  4307         -** ^The sqlite3_context_db_handle() interface returns a copy of
  4308         -** the pointer to the [database connection] (the 1st parameter)
  4309         -** of the [sqlite3_create_function()]
  4310         -** and [sqlite3_create_function16()] routines that originally
  4311         -** registered the application defined function.
  4312         -*/
  4313         -SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
  4314         -
  4315         -/*
  4316         -** CAPI3REF: Function Auxiliary Data
  4317         -**
  4318         -** These functions may be used by (non-aggregate) SQL functions to
  4319         -** associate metadata with argument values. If the same value is passed to
  4320         -** multiple invocations of the same SQL function during query execution, under
  4321         -** some circumstances the associated metadata may be preserved.  An example
  4322         -** of where this might be useful is in a regular-expression matching
  4323         -** function. The compiled version of the regular expression can be stored as
  4324         -** metadata associated with the pattern string.  
  4325         -** Then as long as the pattern string remains the same,
  4326         -** the compiled regular expression can be reused on multiple
  4327         -** invocations of the same function.
  4328         -**
  4329         -** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
  4330         -** associated by the sqlite3_set_auxdata() function with the Nth argument
  4331         -** value to the application-defined function. ^If there is no metadata
  4332         -** associated with the function argument, this sqlite3_get_auxdata() interface
  4333         -** returns a NULL pointer.
  4334         -**
  4335         -** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
  4336         -** argument of the application-defined function.  ^Subsequent
  4337         -** calls to sqlite3_get_auxdata(C,N) return P from the most recent
  4338         -** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
  4339         -** NULL if the metadata has been discarded.
  4340         -** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
  4341         -** SQLite will invoke the destructor function X with parameter P exactly
  4342         -** once, when the metadata is discarded.
  4343         -** SQLite is free to discard the metadata at any time, including: <ul>
  4344         -** <li> when the corresponding function parameter changes, or
  4345         -** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
  4346         -**      SQL statement, or
  4347         -** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
  4348         -** <li> during the original sqlite3_set_auxdata() call when a memory 
  4349         -**      allocation error occurs. </ul>)^
  4350         -**
  4351         -** Note the last bullet in particular.  The destructor X in 
  4352         -** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
  4353         -** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
  4354         -** should be called near the end of the function implementation and the
  4355         -** function implementation should not make any use of P after
  4356         -** sqlite3_set_auxdata() has been called.
  4357         -**
  4358         -** ^(In practice, metadata is preserved between function calls for
  4359         -** function parameters that are compile-time constants, including literal
  4360         -** values and [parameters] and expressions composed from the same.)^
  4361         -**
  4362         -** These routines must be called from the same thread in which
  4363         -** the SQL function is running.
  4364         -*/
  4365         -SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
  4366         -SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  4367         -
  4368         -
  4369         -/*
  4370         -** CAPI3REF: Constants Defining Special Destructor Behavior
  4371         -**
  4372         -** These are special values for the destructor that is passed in as the
  4373         -** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
  4374         -** argument is SQLITE_STATIC, it means that the content pointer is constant
  4375         -** and will never change.  It does not need to be destroyed.  ^The
  4376         -** SQLITE_TRANSIENT value means that the content will likely change in
  4377         -** the near future and that SQLite should make its own private copy of
  4378         -** the content before returning.
  4379         -**
  4380         -** The typedef is necessary to work around problems in certain
  4381         -** C++ compilers.
  4382         -*/
  4383         -typedef void (*sqlite3_destructor_type)(void*);
  4384         -#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
  4385         -#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
  4386         -
  4387         -/*
  4388         -** CAPI3REF: Setting The Result Of An SQL Function
  4389         -**
  4390         -** These routines are used by the xFunc or xFinal callbacks that
  4391         -** implement SQL functions and aggregates.  See
  4392         -** [sqlite3_create_function()] and [sqlite3_create_function16()]
  4393         -** for additional information.
  4394         -**
  4395         -** These functions work very much like the [parameter binding] family of
  4396         -** functions used to bind values to host parameters in prepared statements.
  4397         -** Refer to the [SQL parameter] documentation for additional information.
  4398         -**
  4399         -** ^The sqlite3_result_blob() interface sets the result from
  4400         -** an application-defined function to be the BLOB whose content is pointed
  4401         -** to by the second parameter and which is N bytes long where N is the
  4402         -** third parameter.
  4403         -**
  4404         -** ^The sqlite3_result_zeroblob() interfaces set the result of
  4405         -** the application-defined function to be a BLOB containing all zero
  4406         -** bytes and N bytes in size, where N is the value of the 2nd parameter.
  4407         -**
  4408         -** ^The sqlite3_result_double() interface sets the result from
  4409         -** an application-defined function to be a floating point value specified
  4410         -** by its 2nd argument.
  4411         -**
  4412         -** ^The sqlite3_result_error() and sqlite3_result_error16() functions
  4413         -** cause the implemented SQL function to throw an exception.
  4414         -** ^SQLite uses the string pointed to by the
  4415         -** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
  4416         -** as the text of an error message.  ^SQLite interprets the error
  4417         -** message string from sqlite3_result_error() as UTF-8. ^SQLite
  4418         -** interprets the string from sqlite3_result_error16() as UTF-16 in native
  4419         -** byte order.  ^If the third parameter to sqlite3_result_error()
  4420         -** or sqlite3_result_error16() is negative then SQLite takes as the error
  4421         -** message all text up through the first zero character.
  4422         -** ^If the third parameter to sqlite3_result_error() or
  4423         -** sqlite3_result_error16() is non-negative then SQLite takes that many
  4424         -** bytes (not characters) from the 2nd parameter as the error message.
  4425         -** ^The sqlite3_result_error() and sqlite3_result_error16()
  4426         -** routines make a private copy of the error message text before
  4427         -** they return.  Hence, the calling function can deallocate or
  4428         -** modify the text after they return without harm.
  4429         -** ^The sqlite3_result_error_code() function changes the error code
  4430         -** returned by SQLite as a result of an error in a function.  ^By default,
  4431         -** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
  4432         -** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
  4433         -**
  4434         -** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
  4435         -** error indicating that a string or BLOB is too long to represent.
  4436         -**
  4437         -** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
  4438         -** error indicating that a memory allocation failed.
  4439         -**
  4440         -** ^The sqlite3_result_int() interface sets the return value
  4441         -** of the application-defined function to be the 32-bit signed integer
  4442         -** value given in the 2nd argument.
  4443         -** ^The sqlite3_result_int64() interface sets the return value
  4444         -** of the application-defined function to be the 64-bit signed integer
  4445         -** value given in the 2nd argument.
  4446         -**
  4447         -** ^The sqlite3_result_null() interface sets the return value
  4448         -** of the application-defined function to be NULL.
  4449         -**
  4450         -** ^The sqlite3_result_text(), sqlite3_result_text16(),
  4451         -** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
  4452         -** set the return value of the application-defined function to be
  4453         -** a text string which is represented as UTF-8, UTF-16 native byte order,
  4454         -** UTF-16 little endian, or UTF-16 big endian, respectively.
  4455         -** ^The sqlite3_result_text64() interface sets the return value of an
  4456         -** application-defined function to be a text string in an encoding
  4457         -** specified by the fifth (and last) parameter, which must be one
  4458         -** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
  4459         -** ^SQLite takes the text result from the application from
  4460         -** the 2nd parameter of the sqlite3_result_text* interfaces.
  4461         -** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  4462         -** is negative, then SQLite takes result text from the 2nd parameter
  4463         -** through the first zero character.
  4464         -** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  4465         -** is non-negative, then as many bytes (not characters) of the text
  4466         -** pointed to by the 2nd parameter are taken as the application-defined
  4467         -** function result.  If the 3rd parameter is non-negative, then it
  4468         -** must be the byte offset into the string where the NUL terminator would
  4469         -** appear if the string where NUL terminated.  If any NUL characters occur
  4470         -** in the string at a byte offset that is less than the value of the 3rd
  4471         -** parameter, then the resulting string will contain embedded NULs and the
  4472         -** result of expressions operating on strings with embedded NULs is undefined.
  4473         -** ^If the 4th parameter to the sqlite3_result_text* interfaces
  4474         -** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
  4475         -** function as the destructor on the text or BLOB result when it has
  4476         -** finished using that result.
  4477         -** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
  4478         -** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
  4479         -** assumes that the text or BLOB result is in constant space and does not
  4480         -** copy the content of the parameter nor call a destructor on the content
  4481         -** when it has finished using that result.
  4482         -** ^If the 4th parameter to the sqlite3_result_text* interfaces
  4483         -** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  4484         -** then SQLite makes a copy of the result into space obtained from
  4485         -** from [sqlite3_malloc()] before it returns.
  4486         -**
  4487         -** ^The sqlite3_result_value() interface sets the result of
  4488         -** the application-defined function to be a copy the
  4489         -** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
  4490         -** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  4491         -** so that the [sqlite3_value] specified in the parameter may change or
  4492         -** be deallocated after sqlite3_result_value() returns without harm.
  4493         -** ^A [protected sqlite3_value] object may always be used where an
  4494         -** [unprotected sqlite3_value] object is required, so either
  4495         -** kind of [sqlite3_value] object can be used with this interface.
  4496         -**
  4497         -** If these routines are called from within the different thread
  4498         -** than the one containing the application-defined function that received
  4499         -** the [sqlite3_context] pointer, the results are undefined.
  4500         -*/
  4501         -SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  4502         -SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,sqlite3_uint64,void(*)(void*));
  4503         -SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
  4504         -SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
  4505         -SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
  4506         -SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
  4507         -SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
  4508         -SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
  4509         -SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
  4510         -SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
  4511         -SQLITE_API void sqlite3_result_null(sqlite3_context*);
  4512         -SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
  4513         -SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
  4514         -                           void(*)(void*), unsigned char encoding);
  4515         -SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  4516         -SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  4517         -SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  4518         -SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  4519         -SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
  4520         -
  4521         -/*
  4522         -** CAPI3REF: Define New Collating Sequences
  4523         -**
  4524         -** ^These functions add, remove, or modify a [collation] associated
  4525         -** with the [database connection] specified as the first argument.
  4526         -**
  4527         -** ^The name of the collation is a UTF-8 string
  4528         -** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  4529         -** and a UTF-16 string in native byte order for sqlite3_create_collation16().
  4530         -** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
  4531         -** considered to be the same name.
  4532         -**
  4533         -** ^(The third argument (eTextRep) must be one of the constants:
  4534         -** <ul>
  4535         -** <li> [SQLITE_UTF8],
  4536         -** <li> [SQLITE_UTF16LE],
  4537         -** <li> [SQLITE_UTF16BE],
  4538         -** <li> [SQLITE_UTF16], or
  4539         -** <li> [SQLITE_UTF16_ALIGNED].
  4540         -** </ul>)^
  4541         -** ^The eTextRep argument determines the encoding of strings passed
  4542         -** to the collating function callback, xCallback.
  4543         -** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
  4544         -** force strings to be UTF16 with native byte order.
  4545         -** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
  4546         -** on an even byte address.
  4547         -**
  4548         -** ^The fourth argument, pArg, is an application data pointer that is passed
  4549         -** through as the first argument to the collating function callback.
  4550         -**
  4551         -** ^The fifth argument, xCallback, is a pointer to the collating function.
  4552         -** ^Multiple collating functions can be registered using the same name but
  4553         -** with different eTextRep parameters and SQLite will use whichever
  4554         -** function requires the least amount of data transformation.
  4555         -** ^If the xCallback argument is NULL then the collating function is
  4556         -** deleted.  ^When all collating functions having the same name are deleted,
  4557         -** that collation is no longer usable.
  4558         -**
  4559         -** ^The collating function callback is invoked with a copy of the pArg 
  4560         -** application data pointer and with two strings in the encoding specified
  4561         -** by the eTextRep argument.  The collating function must return an
  4562         -** integer that is negative, zero, or positive
  4563         -** if the first string is less than, equal to, or greater than the second,
  4564         -** respectively.  A collating function must always return the same answer
  4565         -** given the same inputs.  If two or more collating functions are registered
  4566         -** to the same collation name (using different eTextRep values) then all
  4567         -** must give an equivalent answer when invoked with equivalent strings.
  4568         -** The collating function must obey the following properties for all
  4569         -** strings A, B, and C:
  4570         -**
  4571         -** <ol>
  4572         -** <li> If A==B then B==A.
  4573         -** <li> If A==B and B==C then A==C.
  4574         -** <li> If A&lt;B THEN B&gt;A.
  4575         -** <li> If A&lt;B and B&lt;C then A&lt;C.
  4576         -** </ol>
  4577         -**
  4578         -** If a collating function fails any of the above constraints and that
  4579         -** collating function is  registered and used, then the behavior of SQLite
  4580         -** is undefined.
  4581         -**
  4582         -** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  4583         -** with the addition that the xDestroy callback is invoked on pArg when
  4584         -** the collating function is deleted.
  4585         -** ^Collating functions are deleted when they are overridden by later
  4586         -** calls to the collation creation functions or when the
  4587         -** [database connection] is closed using [sqlite3_close()].
  4588         -**
  4589         -** ^The xDestroy callback is <u>not</u> called if the 
  4590         -** sqlite3_create_collation_v2() function fails.  Applications that invoke
  4591         -** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 
  4592         -** check the return code and dispose of the application data pointer
  4593         -** themselves rather than expecting SQLite to deal with it for them.
  4594         -** This is different from every other SQLite interface.  The inconsistency 
  4595         -** is unfortunate but cannot be changed without breaking backwards 
  4596         -** compatibility.
  4597         -**
  4598         -** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
  4599         -*/
  4600         -SQLITE_API int sqlite3_create_collation(
  4601         -  sqlite3*, 
  4602         -  const char *zName, 
  4603         -  int eTextRep, 
  4604         -  void *pArg,
  4605         -  int(*xCompare)(void*,int,const void*,int,const void*)
  4606         -);
  4607         -SQLITE_API int sqlite3_create_collation_v2(
  4608         -  sqlite3*, 
  4609         -  const char *zName, 
  4610         -  int eTextRep, 
  4611         -  void *pArg,
  4612         -  int(*xCompare)(void*,int,const void*,int,const void*),
  4613         -  void(*xDestroy)(void*)
  4614         -);
  4615         -SQLITE_API int sqlite3_create_collation16(
  4616         -  sqlite3*, 
  4617         -  const void *zName,
  4618         -  int eTextRep, 
  4619         -  void *pArg,
  4620         -  int(*xCompare)(void*,int,const void*,int,const void*)
  4621         -);
  4622         -
  4623         -/*
  4624         -** CAPI3REF: Collation Needed Callbacks
  4625         -**
  4626         -** ^To avoid having to register all collation sequences before a database
  4627         -** can be used, a single callback function may be registered with the
  4628         -** [database connection] to be invoked whenever an undefined collation
  4629         -** sequence is required.
  4630         -**
  4631         -** ^If the function is registered using the sqlite3_collation_needed() API,
  4632         -** then it is passed the names of undefined collation sequences as strings
  4633         -** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
  4634         -** the names are passed as UTF-16 in machine native byte order.
  4635         -** ^A call to either function replaces the existing collation-needed callback.
  4636         -**
  4637         -** ^(When the callback is invoked, the first argument passed is a copy
  4638         -** of the second argument to sqlite3_collation_needed() or
  4639         -** sqlite3_collation_needed16().  The second argument is the database
  4640         -** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
  4641         -** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
  4642         -** sequence function required.  The fourth parameter is the name of the
  4643         -** required collation sequence.)^
  4644         -**
  4645         -** The callback function should register the desired collation using
  4646         -** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
  4647         -** [sqlite3_create_collation_v2()].
  4648         -*/
  4649         -SQLITE_API int sqlite3_collation_needed(
  4650         -  sqlite3*, 
  4651         -  void*, 
  4652         -  void(*)(void*,sqlite3*,int eTextRep,const char*)
  4653         -);
  4654         -SQLITE_API int sqlite3_collation_needed16(
  4655         -  sqlite3*, 
  4656         -  void*,
  4657         -  void(*)(void*,sqlite3*,int eTextRep,const void*)
  4658         -);
  4659         -
  4660         -#ifdef SQLITE_HAS_CODEC
  4661         -/*
  4662         -** Specify the key for an encrypted database.  This routine should be
  4663         -** called right after sqlite3_open().
  4664         -**
  4665         -** The code to implement this API is not available in the public release
  4666         -** of SQLite.
  4667         -*/
  4668         -SQLITE_API int sqlite3_key(
  4669         -  sqlite3 *db,                   /* Database to be rekeyed */
  4670         -  const void *pKey, int nKey     /* The key */
  4671         -);
  4672         -SQLITE_API int sqlite3_key_v2(
  4673         -  sqlite3 *db,                   /* Database to be rekeyed */
  4674         -  const char *zDbName,           /* Name of the database */
  4675         -  const void *pKey, int nKey     /* The key */
  4676         -);
  4677         -
  4678         -/*
  4679         -** Change the key on an open database.  If the current database is not
  4680         -** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
  4681         -** database is decrypted.
  4682         -**
  4683         -** The code to implement this API is not available in the public release
  4684         -** of SQLite.
  4685         -*/
  4686         -SQLITE_API int sqlite3_rekey(
  4687         -  sqlite3 *db,                   /* Database to be rekeyed */
  4688         -  const void *pKey, int nKey     /* The new key */
  4689         -);
  4690         -SQLITE_API int sqlite3_rekey_v2(
  4691         -  sqlite3 *db,                   /* Database to be rekeyed */
  4692         -  const char *zDbName,           /* Name of the database */
  4693         -  const void *pKey, int nKey     /* The new key */
  4694         -);
  4695         -
  4696         -/*
  4697         -** Specify the activation key for a SEE database.  Unless 
  4698         -** activated, none of the SEE routines will work.
  4699         -*/
  4700         -SQLITE_API void sqlite3_activate_see(
  4701         -  const char *zPassPhrase        /* Activation phrase */
  4702         -);
  4703         -#endif
  4704         -
  4705         -#ifdef SQLITE_ENABLE_CEROD
  4706         -/*
  4707         -** Specify the activation key for a CEROD database.  Unless 
  4708         -** activated, none of the CEROD routines will work.
  4709         -*/
  4710         -SQLITE_API void sqlite3_activate_cerod(
  4711         -  const char *zPassPhrase        /* Activation phrase */
  4712         -);
  4713         -#endif
  4714         -
  4715         -/*
  4716         -** CAPI3REF: Suspend Execution For A Short Time
  4717         -**
  4718         -** The sqlite3_sleep() function causes the current thread to suspend execution
  4719         -** for at least a number of milliseconds specified in its parameter.
  4720         -**
  4721         -** If the operating system does not support sleep requests with
  4722         -** millisecond time resolution, then the time will be rounded up to
  4723         -** the nearest second. The number of milliseconds of sleep actually
  4724         -** requested from the operating system is returned.
  4725         -**
  4726         -** ^SQLite implements this interface by calling the xSleep()
  4727         -** method of the default [sqlite3_vfs] object.  If the xSleep() method
  4728         -** of the default VFS is not implemented correctly, or not implemented at
  4729         -** all, then the behavior of sqlite3_sleep() may deviate from the description
  4730         -** in the previous paragraphs.
  4731         -*/
  4732         -SQLITE_API int sqlite3_sleep(int);
  4733         -
  4734         -/*
  4735         -** CAPI3REF: Name Of The Folder Holding Temporary Files
  4736         -**
  4737         -** ^(If this global variable is made to point to a string which is
  4738         -** the name of a folder (a.k.a. directory), then all temporary files
  4739         -** created by SQLite when using a built-in [sqlite3_vfs | VFS]
  4740         -** will be placed in that directory.)^  ^If this variable
  4741         -** is a NULL pointer, then SQLite performs a search for an appropriate
  4742         -** temporary file directory.
  4743         -**
  4744         -** Applications are strongly discouraged from using this global variable.
  4745         -** It is required to set a temporary folder on Windows Runtime (WinRT).
  4746         -** But for all other platforms, it is highly recommended that applications
  4747         -** neither read nor write this variable.  This global variable is a relic
  4748         -** that exists for backwards compatibility of legacy applications and should
  4749         -** be avoided in new projects.
  4750         -**
  4751         -** It is not safe to read or modify this variable in more than one
  4752         -** thread at a time.  It is not safe to read or modify this variable
  4753         -** if a [database connection] is being used at the same time in a separate
  4754         -** thread.
  4755         -** It is intended that this variable be set once
  4756         -** as part of process initialization and before any SQLite interface
  4757         -** routines have been called and that this variable remain unchanged
  4758         -** thereafter.
  4759         -**
  4760         -** ^The [temp_store_directory pragma] may modify this variable and cause
  4761         -** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
  4762         -** the [temp_store_directory pragma] always assumes that any string
  4763         -** that this variable points to is held in memory obtained from 
  4764         -** [sqlite3_malloc] and the pragma may attempt to free that memory
  4765         -** using [sqlite3_free].
  4766         -** Hence, if this variable is modified directly, either it should be
  4767         -** made NULL or made to point to memory obtained from [sqlite3_malloc]
  4768         -** or else the use of the [temp_store_directory pragma] should be avoided.
  4769         -** Except when requested by the [temp_store_directory pragma], SQLite
  4770         -** does not free the memory that sqlite3_temp_directory points to.  If
  4771         -** the application wants that memory to be freed, it must do
  4772         -** so itself, taking care to only do so after all [database connection]
  4773         -** objects have been destroyed.
  4774         -**
  4775         -** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
  4776         -** prior to calling [sqlite3_open] or [sqlite3_open_v2].  Otherwise, various
  4777         -** features that require the use of temporary files may fail.  Here is an
  4778         -** example of how to do this using C++ with the Windows Runtime:
  4779         -**
  4780         -** <blockquote><pre>
  4781         -** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
  4782         -** &nbsp;     TemporaryFolder->Path->Data();
  4783         -** char zPathBuf&#91;MAX_PATH + 1&#93;;
  4784         -** memset(zPathBuf, 0, sizeof(zPathBuf));
  4785         -** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
  4786         -** &nbsp;     NULL, NULL);
  4787         -** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
  4788         -** </pre></blockquote>
  4789         -*/
  4790         -SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
  4791         -
  4792         -/*
  4793         -** CAPI3REF: Name Of The Folder Holding Database Files
  4794         -**
  4795         -** ^(If this global variable is made to point to a string which is
  4796         -** the name of a folder (a.k.a. directory), then all database files
  4797         -** specified with a relative pathname and created or accessed by
  4798         -** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
  4799         -** to be relative to that directory.)^ ^If this variable is a NULL
  4800         -** pointer, then SQLite assumes that all database files specified
  4801         -** with a relative pathname are relative to the current directory
  4802         -** for the process.  Only the windows VFS makes use of this global
  4803         -** variable; it is ignored by the unix VFS.
  4804         -**
  4805         -** Changing the value of this variable while a database connection is
  4806         -** open can result in a corrupt database.
  4807         -**
  4808         -** It is not safe to read or modify this variable in more than one
  4809         -** thread at a time.  It is not safe to read or modify this variable
  4810         -** if a [database connection] is being used at the same time in a separate
  4811         -** thread.
  4812         -** It is intended that this variable be set once
  4813         -** as part of process initialization and before any SQLite interface
  4814         -** routines have been called and that this variable remain unchanged
  4815         -** thereafter.
  4816         -**
  4817         -** ^The [data_store_directory pragma] may modify this variable and cause
  4818         -** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
  4819         -** the [data_store_directory pragma] always assumes that any string
  4820         -** that this variable points to is held in memory obtained from 
  4821         -** [sqlite3_malloc] and the pragma may attempt to free that memory
  4822         -** using [sqlite3_free].
  4823         -** Hence, if this variable is modified directly, either it should be
  4824         -** made NULL or made to point to memory obtained from [sqlite3_malloc]
  4825         -** or else the use of the [data_store_directory pragma] should be avoided.
  4826         -*/
  4827         -SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
  4828         -
  4829         -/*
  4830         -** CAPI3REF: Test For Auto-Commit Mode
  4831         -** KEYWORDS: {autocommit mode}
  4832         -**
  4833         -** ^The sqlite3_get_autocommit() interface returns non-zero or
  4834         -** zero if the given database connection is or is not in autocommit mode,
  4835         -** respectively.  ^Autocommit mode is on by default.
  4836         -** ^Autocommit mode is disabled by a [BEGIN] statement.
  4837         -** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
  4838         -**
  4839         -** If certain kinds of errors occur on a statement within a multi-statement
  4840         -** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
  4841         -** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  4842         -** transaction might be rolled back automatically.  The only way to
  4843         -** find out whether SQLite automatically rolled back the transaction after
  4844         -** an error is to use this function.
  4845         -**
  4846         -** If another thread changes the autocommit status of the database
  4847         -** connection while this routine is running, then the return value
  4848         -** is undefined.
  4849         -*/
  4850         -SQLITE_API int sqlite3_get_autocommit(sqlite3*);
  4851         -
  4852         -/*
  4853         -** CAPI3REF: Find The Database Handle Of A Prepared Statement
  4854         -**
  4855         -** ^The sqlite3_db_handle interface returns the [database connection] handle
  4856         -** to which a [prepared statement] belongs.  ^The [database connection]
  4857         -** returned by sqlite3_db_handle is the same [database connection]
  4858         -** that was the first argument
  4859         -** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
  4860         -** create the statement in the first place.
  4861         -*/
  4862         -SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  4863         -
  4864         -/*
  4865         -** CAPI3REF: Return The Filename For A Database Connection