<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libsq3: sq3.hpp Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
</ul>
</div>
<h1>sq3.hpp</h1><div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="preprocessor">#ifndef s11n_net_SQ3_HPP_INCLUDED</span>
<a name="l00002"></a>00002 <span class="preprocessor"></span><span class="preprocessor">#define s11n_net_SQ3_HPP_INCLUDED 1</span>
<a name="l00003"></a>00003 <span class="preprocessor"></span>
<a name="l00004"></a>00004 <span class="preprocessor">#include <string></span>
<a name="l00005"></a>00005 <span class="preprocessor">#include <map></span>
<a name="l00006"></a>00006 <span class="preprocessor">#include <sqlite3.h></span>
<a name="l00007"></a>00007
<a name="l00008"></a>00008 <span class="preprocessor">#ifndef SQ3_USE_WCHAR</span>
<a name="l00009"></a>00009 <span class="preprocessor"></span><span class="preprocessor"># define SQ3_USE_WCHAR 0</span>
<a name="l00010"></a>00010 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
<a name="l00011"></a>00011 <span class="preprocessor"></span>
<a name="l00012"></a>00012 <span class="comment">// Enable WCHAR support when it's there. Thanks to Artem Gr <artem@bizlink.ru></span>
<a name="l00013"></a>00013 <span class="comment">// for this. However, sqlite3's wchar code requires that a wchar is 16-bit, which</span>
<a name="l00014"></a>00014 <span class="comment">// is not the case on gcc/linux (32-bit).</span>
<a name="l00015"></a>00015 <span class="preprocessor">#ifndef SQ3_USE_WCHAR</span>
<a name="l00016"></a>00016 <span class="preprocessor"></span><span class="preprocessor"># ifdef _GLIBCXX_USE_WCHAR_T</span>
<a name="l00017"></a>00017 <span class="preprocessor"></span><span class="preprocessor"># define SQ3_USE_WCHAR 1</span>
<a name="l00018"></a>00018 <span class="preprocessor"></span><span class="preprocessor"># elif defined(UNICODE) // Windows uses this</span>
<a name="l00019"></a>00019 <span class="preprocessor"></span><span class="preprocessor"># define SQ3_USE_WCHAR 1</span>
<a name="l00020"></a>00020 <span class="preprocessor"></span><span class="preprocessor"># else</span>
<a name="l00021"></a>00021 <span class="preprocessor"></span><span class="preprocessor"># define SQ3_USE_WCHAR 0 // default</span>
<a name="l00022"></a>00022 <span class="preprocessor"></span><span class="preprocessor"># endif</span>
<a name="l00023"></a>00023 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
<a name="l00024"></a>00024 <span class="preprocessor"></span>
<a name="l00025"></a>00025 <span class="preprocessor">#if SQ3_USE_WCHAR</span>
<a name="l00026"></a>00026 <span class="preprocessor"></span><span class="preprocessor"># warning SQ3_USE_WCHAR: INCOMPLETE/BROKEN code is enabled!</span>
<a name="l00027"></a>00027 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
<a name="l00028"></a>00028 <span class="preprocessor"></span>
<a name="l00029"></a>00029
<a name="l00030"></a>00030 <span class="comment">// #ifndef COUT</span>
<a name="l00031"></a>00031 <span class="comment">// #include <iostream></span>
<a name="l00032"></a>00032 <span class="comment">// #define COUT std::cerr << "SQ3:"<<__FILE__ << ":" << std::dec<<__LINE__ << ": "</span>
<a name="l00033"></a>00033 <span class="comment">// #endif</span>
<a name="l00034"></a>00034
<a name="l00035"></a>00035 <span class="preprocessor">#include "refcount.hpp"</span>
<a name="l00036"></a>00036
<a name="l00037"></a>00037 <span class="comment"></span>
<a name="l00038"></a>00038 <span class="comment">/**</span>
<a name="l00039"></a>00039 <span class="comment"> The sq3 namespace encapsulates an OO sqlite3 API very similar to</span>
<a name="l00040"></a>00040 <span class="comment"> the sqlite3x API, but this one uses no exception handling (i.e., it</span>
<a name="l00041"></a><a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba">00041</a> <span class="comment"> doesn't throw on errors). It is intended to be an alternative for</span>
<a name="l00042"></a>00042 <span class="comment"> platforms/projects where exceptions are not desired or not</span>
<a name="l00043"></a>00043 <span class="comment"> available.</span>
<a name="l00044"></a>00044 <span class="comment"></span>
<a name="l00045"></a><a class="code" href="namespacesq3.html#aa38b960af8f064739ca9c6a0ec71cd73">00045</a> <span class="comment"> Wide-char support does not currently work. (On my platform</span>
<a name="l00046"></a>00046 <span class="comment"> (gcc/linux) wchar_t is 4 bytes and sqlite3 wants 2-bytes wide chars</span>
<a name="l00047"></a>00047 <span class="comment"> for UTF16 text.)</span>
<a name="l00048"></a>00048 <span class="comment"></span>
<a name="l00049"></a>00049 <span class="comment"> This code was written by stephan beal (stephan@s11n.net) and is</span>
<a name="l00050"></a>00050 <span class="comment"> released into the Public Domain. It was modelled heavily after code</span>
<a name="l00051"></a>00051 <span class="comment"> written by Cory Nelson, but was reimplemented from scratch for use</span>
<a name="l00052"></a>00052 <span class="comment"> on a PocketPC platform where throwing exceptions wasn't allowed.</span>
<a name="l00053"></a>00053 <span class="comment"></span>
<a name="l00054"></a>00054 <span class="comment"> This code's home page is:</span>
<a name="l00055"></a>00055 <span class="comment"></span>
<a name="l00056"></a>00056 <span class="comment"> http://s11n.net/sqlite/</span>
<a name="l00057"></a>00057 <span class="comment"></span>
<a name="l00058"></a>00058 <span class="comment"> Change history (only "significant" changes documented here):</span>
<a name="l00059"></a>00059 <span class="comment"></span>
<a name="l00060"></a>00060 <span class="comment"> - 2007.02.26: integrated isnull() patch from </span>
<a name="l00061"></a>00061 <span class="comment"> Xosé Antón Otero Ferreira <xoseotero at gmail com></span>
<a name="l00062"></a>00062 <span class="comment"></span>
<a name="l00063"></a>00063 <span class="comment"> - 2007.01.22: sq3::reader class renamed to sq3::cursor.</span>
<a name="l00064"></a>00064 <span class="comment"> Renamed cursor::read() to cursor::step().</span>
<a name="l00065"></a>00065 <span class="comment"></span>
<a name="l00066"></a>00066 <span class="comment"> - 2007.01.27: Added the cursor::get(std::string const&,...)</span>
<a name="l00067"></a>00067 <span class="comment"> family of functions to enable get-by-string-index. Added</span>
<a name="l00068"></a>00068 <span class="comment"> database::clear().</span>
<a name="l00069"></a>00069 <span class="comment"></span>
<a name="l00070"></a>00070 <span class="comment"> - 2007.01.28: rcptr<> shared pointer class introduced to enable</span>
<a name="l00071"></a>00071 <span class="comment"> reasonable copy semantics for the major underlying data structures.</span>
<a name="l00072"></a>00072 <span class="comment"> sq3::database and sq3::statement can now be shallowly copied.</span>
<a name="l00073"></a>00073 <span class="comment"></span>
<a name="l00074"></a>00074 <span class="comment"> - 2007.02.14: added statement::bind(char const *,...) functions.</span>
<a name="l00075"></a>00075 <span class="comment"></span>
<a name="l00076"></a>00076 <span class="comment">*/</span>
<a name="l00077"></a><a class="code" href="namespacesq3.html">00077</a> <span class="keyword">namespace </span>sq3 {
<a name="l00078"></a>00078 <span class="comment"></span>
<a name="l00079"></a>00079 <span class="comment"> /**</span>
<a name="l00080"></a>00080 <span class="comment"> The type used for signed 64-bit integer operations.</span>
<a name="l00081"></a>00081 <span class="comment"> */</span>
<a name="l00082"></a>00082 <span class="keyword">typedef</span> sqlite_int64 <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a>;<span class="comment"></span>
<a name="l00083"></a>00083 <span class="comment"> /**</span>
<a name="l00084"></a>00084 <span class="comment"> The type used for unsigned 64-bit integer operations.</span>
<a name="l00085"></a>00085 <span class="comment"> */</span>
<a name="l00086"></a><a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f">00086</a> <span class="keyword">typedef</span> sqlite_uint64 <a class="code" href="namespacesq3.html#aa38b960af8f064739ca9c6a0ec71cd73" title="The type used for unsigned 64-bit integer operations.">uint64_t</a>;
<a name="l00087"></a>00087
<a name="l00088"></a>00088 <span class="comment">// /**</span>
<a name="l00089"></a>00089 <span class="comment">// The published result codes from the sqlite3 API.</span>
<a name="l00090"></a>00090 <span class="comment">// */</span>
<a name="l00091"></a>00091 <span class="comment">// enum Sqlite3ResultCodes {</span>
<a name="l00092"></a>00092 <span class="comment">// ResultOK = SQLITE_OK,</span>
<a name="l00093"></a>00093 <span class="comment">// ResultERROR = SQLITE_ERROR,</span>
<a name="l00094"></a>00094 <span class="comment">// ResultINTERNAL = SQLITE_INTERNAL,</span>
<a name="l00095"></a><a class="code" href="structsq3_1_1sqlite3__finalizer.html">00095</a> <span class="comment">// ResultPERM = SQLITE_PERM,</span>
<a name="l00096"></a>00096 <span class="comment">// ResultABORT = SQLITE_ABORT,</span>
<a name="l00097"></a>00097 <span class="comment">// ResultBUSY = SQLITE_BUSY,</span>
<a name="l00098"></a>00098 <span class="comment">// ResultLOCKED = SQLITE_LOCKED,</span>
<a name="l00099"></a>00099 <span class="comment">// ResultNOMEM = SQLITE_NOMEM,</span>
<a name="l00100"></a>00100 <span class="comment">// ResultREADONLY = SQLITE_READONLY,</span>
<a name="l00101"></a>00101 <span class="comment">// ResultINTERRUPT = SQLITE_INTERRUPT,</span>
<a name="l00102"></a>00102 <span class="comment">// ResultIOERR = SQLITE_IOERR,</span>
<a name="l00103"></a>00103 <span class="comment">// ResultCORRUPT = SQLITE_CORRUPT,</span>
<a name="l00104"></a>00104 <span class="comment">// ResultNOTFOUND = SQLITE_NOTFOUND,</span>
<a name="l00105"></a>00105 <span class="comment">// ResultFULL = SQLITE_FULL,</span>
<a name="l00106"></a>00106 <span class="comment">// ResultCANTOPEN = SQLITE_CANTOPEN,</span>
<a name="l00107"></a>00107 <span class="comment">// ResultPROTOCOL = SQLITE_PROTOCOL,</span>
<a name="l00108"></a><a class="code" href="structsq3_1_1statement__reset__finalizer.html">00108</a> <span class="comment">// ResultEMPTY = SQLITE_EMPTY,</span>
<a name="l00109"></a>00109 <span class="comment">// ResultSCHEMA = SQLITE_SCHEMA,</span>
<a name="l00110"></a>00110 <span class="comment">// ResultTOOBIG = SQLITE_TOOBIG,</span>
<a name="l00111"></a>00111 <span class="comment">// ResultCONSTRAINT = SQLITE_CONSTRAINT,</span>
<a name="l00112"></a>00112 <span class="comment">// ResultMISMATCH = SQLITE_MISMATCH,</span>
<a name="l00113"></a>00113 <span class="comment">// ResultMISUSE = SQLITE_MISUSE,</span>
<a name="l00114"></a>00114 <span class="comment">// ResultNOLFS = SQLITE_NOLFS,</span>
<a name="l00115"></a>00115 <span class="comment">// ResultAUTH = SQLITE_AUTH,</span>
<a name="l00116"></a>00116 <span class="comment">// ResultROW = SQLITE_ROW,</span>
<a name="l00117"></a>00117 <span class="comment">// ResultDONE = SQLITE_DONE</span>
<a name="l00118"></a>00118 <span class="comment">// };</span>
<a name="l00119"></a>00119 <span class="comment"></span>
<a name="l00120"></a>00120 <span class="comment"> /**</span>
<a name="l00121"></a><a class="code" href="structsq3_1_1sqlite3__stmt__reset__finalizer.html">00121</a> <span class="comment"> A char type used by some of the sqlite3 API to represent</span>
<a name="l00122"></a>00122 <span class="comment"> text data. This is really annoying, but sqlite3's API</span>
<a name="l00123"></a>00123 <span class="comment"> explicitely uses UNSIGNED char arrays for a couple of</span>
<a name="l00124"></a>00124 <span class="comment"> strings, while using signed char arrays for almost</span>
<a name="l00125"></a>00125 <span class="comment"> everything else.</span>
<a name="l00126"></a>00126 <span class="comment"> */</span>
<a name="l00127"></a>00127 <span class="keyword">typedef</span> <span class="keywordtype">char</span> <span class="keywordtype">unsigned</span> <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a>;
<a name="l00128"></a>00128
<a name="l00129"></a>00129
<a name="l00130"></a>00130 <span class="keyword">class </span><a class="code" href="classsq3_1_1statement.html" title="This class represents a prepared database statement.">statement</a>; <span class="comment">// unfortunate fwd decl</span>
<a name="l00131"></a>00131 <span class="comment"></span>
<a name="l00132"></a>00132 <span class="comment"> /**</span>
<a name="l00133"></a>00133 <span class="comment"> A specialized dtor to close sqlite3 handles, for use</span>
<a name="l00134"></a>00134 <span class="comment"> with refcount::rcptr<sqlite3,sqlite3_finalizer >.</span>
<a name="l00135"></a><a class="code" href="structsq3_1_1sqlite3__stmt__finalizer.html">00135</a> <span class="comment"> */</span>
<a name="l00136"></a>00136 <span class="keyword">struct </span><a class="code" href="structsq3_1_1sqlite3__finalizer.html" title="A specialized dtor to close sqlite3 handles, for use with refcount::rcptr&lt;sqlite3...">sqlite3_finalizer</a>
<a name="l00137"></a>00137 {<span class="comment"></span>
<a name="l00138"></a>00138 <span class="comment"> /**</span>
<a name="l00139"></a>00139 <span class="comment"> Calls sqlite3_close(t) and assigns t to 0.</span>
<a name="l00140"></a>00140 <span class="comment"> */</span>
<a name="l00141"></a>00141 <span class="keywordtype">void</span> <a class="code" href="structsq3_1_1sqlite3__finalizer.html#a4fab246707b5af35712b24c4a22fa0f5" title="Calls sqlite3_close(t) and assigns t to 0.">operator()</a>( sqlite3 * & t );
<a name="l00142"></a>00142 };
<a name="l00143"></a>00143 <span class="comment"></span>
<a name="l00144"></a>00144 <span class="comment"> /**</span>
<a name="l00145"></a>00145 <span class="comment"> A specialized dtor to reset (not close)</span>
<a name="l00146"></a>00146 <span class="comment"> sq3::statement objects, for use with</span>
<a name="l00147"></a>00147 <span class="comment"> refcount::rcptr<sqlite3,statement_reset_finalizer>.</span>
<a name="l00148"></a>00148 <span class="comment"> */</span>
<a name="l00149"></a>00149 <span class="keyword">struct </span><a class="code" href="structsq3_1_1statement__reset__finalizer.html" title="A specialized dtor to reset (not close) sq3::statement objects, for use with refcount::rcptr&lt;sqli...">statement_reset_finalizer</a>
<a name="l00150"></a>00150 {<span class="comment"></span>
<a name="l00151"></a>00151 <span class="comment"> /**</span>
<a name="l00152"></a>00152 <span class="comment"> Calls t->reset() and assigns t to 0.</span>
<a name="l00153"></a>00153 <span class="comment"> */</span>
<a name="l00154"></a>00154 <span class="keywordtype">void</span> <a class="code" href="structsq3_1_1statement__reset__finalizer.html#a971093f32adc41f731a01407f281b85f" title="Calls t-&gt;reset() and assigns t to 0.">operator()</a>( ::<a class="code" href="classsq3_1_1statement.html" title="This class represents a prepared database statement.">sq3::statement</a> * & t );
<a name="l00155"></a>00155 };
<a name="l00156"></a>00156 <span class="comment"></span>
<a name="l00157"></a>00157 <span class="comment"> /**</span>
<a name="l00158"></a>00158 <span class="comment"> A specialized dtor to call reset sqlite3_stmt</span>
<a name="l00159"></a>00159 <span class="comment"> handles(), for use with</span>
<a name="l00160"></a>00160 <span class="comment"> refcount::rcptr<sqlite3,sqlite3_stmt_reset_finalizer>.</span>
<a name="l00161"></a>00161 <span class="comment"> */</span>
<a name="l00162"></a>00162 <span class="keyword">struct </span>sqlite3_stmt_reset_finalizer
<a name="l00163"></a>00163 {<span class="comment"></span>
<a name="l00164"></a>00164 <span class="comment"> /**</span>
<a name="l00165"></a>00165 <span class="comment"> Calls sqlite3_reset(t) and assigns t to 0.</span>
<a name="l00166"></a>00166 <span class="comment"> */</span>
<a name="l00167"></a>00167 <span class="keywordtype">void</span> <a class="code" href="structsq3_1_1sqlite3__stmt__reset__finalizer.html#a65ff29a33d7b8c1166f09b3226d6a25e" title="Calls sqlite3_reset(t) and assigns t to 0.">operator()</a>( sqlite3_stmt * & t );
<a name="l00168"></a>00168 };
<a name="l00169"></a>00169
<a name="l00170"></a>00170 <span class="comment"></span>
<a name="l00171"></a>00171 <span class="comment"> /**</span>
<a name="l00172"></a>00172 <span class="comment"> A specialized dtor to finalize sqlite3_stmt</span>
<a name="l00173"></a>00173 <span class="comment"> handles, for use with</span>
<a name="l00174"></a>00174 <span class="comment"> refcount::rcptr<sqlite3,sqlite3_stmt_finalizer>.</span>
<a name="l00175"></a>00175 <span class="comment"> */</span>
<a name="l00176"></a>00176 <span class="keyword">struct </span>sqlite3_stmt_finalizer
<a name="l00177"></a>00177 {<span class="comment"></span>
<a name="l00178"></a>00178 <span class="comment"> /**</span>
<a name="l00179"></a>00179 <span class="comment"> Calls sqlite3_finalize(t) and assigns t to 0.</span>
<a name="l00180"></a>00180 <span class="comment"> */</span>
<a name="l00181"></a>00181 <span class="keywordtype">void</span> <a class="code" href="structsq3_1_1sqlite3__stmt__finalizer.html#a394e4ae2be74ff6cba9dbe8b2ec6016b" title="Calls sqlite3_finalize(t) and assigns t to 0.">operator()</a>( sqlite3_stmt * & t );
<a name="l00182"></a>00182 };
<a name="l00183"></a>00183 <span class="comment"></span>
<a name="l00184"></a>00184 <span class="comment"> /**</span>
<a name="l00185"></a>00185 <span class="comment"> rc_is_okay() is an easy way to check if rc is one of</span>
<a name="l00186"></a>00186 <span class="comment"> SQLITE_OK, SQLITE_ROW, or SQLITE_DONE. This function</span>
<a name="l00187"></a>00187 <span class="comment"> returns true if rc is one of those values, else false.</span>
<a name="l00188"></a>00188 <span class="comment"> (Code which accepts arbitrary SQL from a user often has to</span>
<a name="l00189"></a>00189 <span class="comment"> accept any of those three result codes as success.)</span>
<a name="l00190"></a>00190 <span class="comment"> */</span>
<a name="l00191"></a><a class="code" href="classsq3_1_1database.html">00191</a> <span class="keywordtype">bool</span> <a class="code" href="namespacesq3.html#a080ee04ba6c41a38c4d3efbb1ccb741d" title="rc_is_okay() is an easy way to check if rc is one of SQLITE_OK, SQLITE_ROW, or SQLITE_DONE...">rc_is_okay</a>( <span class="keywordtype">int</span> rc );
<a name="l00192"></a>00192
<a name="l00193"></a>00193 <span class="comment"></span>
<a name="l00194"></a>00194 <span class="comment"> /**</span>
<a name="l00195"></a>00195 <span class="comment"> Encapsulates a connection to an sqlite database.</span>
<a name="l00196"></a>00196 <span class="comment"></span>
<a name="l00197"></a>00197 <span class="comment"> This type is virtual/subclassable so that clients can add</span>
<a name="l00198"></a>00198 <span class="comment"> initialization routines to all of their databases, such as</span>
<a name="l00199"></a>00199 <span class="comment"> adding sqlite-builtin functions and collating sequences.</span>
<a name="l00200"></a>00200 <span class="comment"> Simply do such initializations in your subclass ctors.</span>
<a name="l00201"></a>00201 <span class="comment"></span>
<a name="l00202"></a>00202 <span class="comment"> A note on the lack of proper constness for much of this</span>
<a name="l00203"></a>00203 <span class="comment"> API... Potentially, in the face of triggers, multiple</span>
<a name="l00204"></a>00204 <span class="comment"> threads, and whatnot, it is not generically possible to</span>
<a name="l00205"></a>00205 <span class="comment"> 100% ensure that any given SQL statement does *not* modify</span>
<a name="l00206"></a>00206 <span class="comment"> the database in at least *some* way. To reflect this</span>
<a name="l00207"></a>00207 <span class="comment"> underlying state of flux, "it was decided" (it really was)</span>
<a name="l00208"></a>00208 <span class="comment"> that very little, if any, of the members of this class</span>
<a name="l00209"></a>00209 <span class="comment"> would be const. Only those which could 100% guaranty proper</span>
<a name="l00210"></a>00210 <span class="comment"> constness.</span>
<a name="l00211"></a>00211 <span class="comment"></span>
<a name="l00212"></a>00212 <span class="comment"> Notes about copying:</span>
<a name="l00213"></a>00213 <span class="comment"></span>
<a name="l00214"></a>00214 <span class="comment"> Copying a db object is actually shallow copying. All copies</span>
<a name="l00215"></a>00215 <span class="comment"> of this type will refer to the same underlying (sqlite3*)</span>
<a name="l00216"></a>00216 <span class="comment"> db handle until/unless:</span>
<a name="l00217"></a>00217 <span class="comment"></span>
<a name="l00218"></a>00218 <span class="comment"> - When open() is called, the object on which it was</span>
<a name="l00219"></a>00219 <span class="comment"> called may separate itself from the rcptr relationship with</span>
<a name="l00220"></a>00220 <span class="comment"> the older db handle and start a new one.</span>
<a name="l00221"></a>00221 <span class="comment"></span>
<a name="l00222"></a>00222 <span class="comment"> - close(false) affects only the calling db. When the</span>
<a name="l00223"></a>00223 <span class="comment"> reference count for the (sqlite3*) handle drops to zero,</span>
<a name="l00224"></a>00224 <span class="comment"> then sqlite3_close() will be called. close(true) closes the</span>
<a name="l00225"></a>00225 <span class="comment"> db handle immediately, affecting all copies of this object.</span>
<a name="l00226"></a>00226 <span class="comment"></span>
<a name="l00227"></a>00227 <span class="comment"> - When take_handle() is</span>
<a name="l00228"></a>00228 <span class="comment"> called then ownership of the underlying db handle is removed from ALL</span>
<a name="l00229"></a>00229 <span class="comment"> copies of this object. They will still refer to the handle, but using it</span>
<a name="l00230"></a>00230 <span class="comment"> is not legal.</span>
<a name="l00231"></a>00231 <span class="comment"> */</span>
<a name="l00232"></a>00232 <span class="keyword">class </span><a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a>
<a name="l00233"></a>00233 {
<a name="l00234"></a>00234 <span class="keyword">private</span>:
<a name="l00235"></a>00235 <span class="keyword">friend</span> <span class="keyword">class </span><a class="code" href="classsq3_1_1statement.html" title="This class represents a prepared database statement.">statement</a>;
<a name="l00236"></a>00236 <span class="keyword">mutable</span> <a class="code" href="classrefcount_1_1rcptr.html">refcount::rcptr<sqlite3,sqlite3_finalizer></a> m_dbh;
<a name="l00237"></a>00237 std::string m_name;
<a name="l00238"></a>00238 <span class="keyword">public</span>:
<a name="l00239"></a>00239 <span class="comment"></span>
<a name="l00240"></a>00240 <span class="comment"> /**</span>
<a name="l00241"></a>00241 <span class="comment"> The low-level handle to the sqlite db.</span>
<a name="l00242"></a>00242 <span class="comment"> NEVER close this handle. It is permissible</span>
<a name="l00243"></a>00243 <span class="comment"> to use it to run queries, add functions</span>
<a name="l00244"></a>00244 <span class="comment"> to the db, etc.</span>
<a name="l00245"></a>00245 <span class="comment"></span>
<a name="l00246"></a>00246 <span class="comment"> This object retains ownership of the returned</span>
<a name="l00247"></a>00247 <span class="comment"> handle.</span>
<a name="l00248"></a>00248 <span class="comment"> */</span>
<a name="l00249"></a>00249 sqlite3 * <a class="code" href="classsq3_1_1database.html#a674d66007f7cf0fe2f68233593526ecb" title="The low-level handle to the sqlite db.">handle</a>() <span class="keyword">const</span>;<span class="comment"></span>
<a name="l00250"></a>00250 <span class="comment"> /**</span>
<a name="l00251"></a>00251 <span class="comment"> Creates an unopened database. Use open()</span>
<a name="l00252"></a>00252 <span class="comment"> to open a file or take_handle() to transfer</span>
<a name="l00253"></a>00253 <span class="comment"> an existing db handle to this object.</span>
<a name="l00254"></a>00254 <span class="comment"> */</span>
<a name="l00255"></a>00255 <a class="code" href="classsq3_1_1database.html#a031f52c894718d806d3d09696901dcca" title="Creates an unopened database.">database</a>();
<a name="l00256"></a>00256 <span class="comment"></span>
<a name="l00257"></a>00257 <span class="comment"> /**</span>
<a name="l00258"></a>00258 <span class="comment"> dbh is assumed to be an opened, valid db handle.</span>
<a name="l00259"></a>00259 <span class="comment"> This function transfers ownership of dbh to this</span>
<a name="l00260"></a>00260 <span class="comment"> object. Specifically, dbh will be closed when the</span>
<a name="l00261"></a>00261 <span class="comment"> last database with the same db handle goes out of</span>
<a name="l00262"></a>00262 <span class="comment"> scope or is closed. The name is simply informative,</span>
<a name="l00263"></a>00263 <span class="comment"> and may or may not be the same actually used for</span>
<a name="l00264"></a>00264 <span class="comment"> opening dbh.</span>
<a name="l00265"></a>00265 <span class="comment"></span>
<a name="l00266"></a>00266 <span class="comment"> Note that this function does not call the protected</span>
<a name="l00267"></a>00267 <span class="comment"> this->on_open() because, quite frankly, i'm not yet</span>
<a name="l00268"></a>00268 <span class="comment"> sure if it really makes sense to do so.</span>
<a name="l00269"></a>00269 <span class="comment"> */</span>
<a name="l00270"></a>00270 <span class="keywordtype">void</span> <a class="code" href="classsq3_1_1database.html#a96e7f35f86397c1f82325ec902d66600" title="Transfers ownership of this-&gt;handle() to the caller.">take_handle</a>( sqlite3 * dbh, std::string <span class="keyword">const</span> & <a class="code" href="classsq3_1_1database.html#a70b7775e8ec6b930cd1df88c1d691d6a" title="Returns the name of the db file.">name</a> = <span class="stringliteral">""</span> );
<a name="l00271"></a>00271 <span class="comment"></span>
<a name="l00272"></a>00272 <span class="comment"> /**</span>
<a name="l00273"></a>00273 <span class="comment"> Transfers ownership of this->handle() to the</span>
<a name="l00274"></a>00274 <span class="comment"> caller. ALL copies of this object which point to</span>
<a name="l00275"></a>00275 <span class="comment"> the handle, except for this copy, still have a</span>
<a name="l00276"></a>00276 <span class="comment"> pointer to that handle but will not call the handle</span>
<a name="l00277"></a>00277 <span class="comment"> dtor when they go out of scope or are closed.</span>
<a name="l00278"></a>00278 <span class="comment"> */</span>
<a name="l00279"></a>00279 sqlite3 * <a class="code" href="classsq3_1_1database.html#a96e7f35f86397c1f82325ec902d66600" title="Transfers ownership of this-&gt;handle() to the caller.">take_handle</a>();
<a name="l00280"></a>00280 <span class="comment"></span>
<a name="l00281"></a>00281 <span class="comment"> /**</span>
<a name="l00282"></a>00282 <span class="comment"> Opens/creates the given db file. Use is_open() to</span>
<a name="l00283"></a>00283 <span class="comment"> see if the opening worked.</span>
<a name="l00284"></a>00284 <span class="comment"></span>
<a name="l00285"></a>00285 <span class="comment"> Subclasses should not call this from a ctor</span>
<a name="l00286"></a>00286 <span class="comment"> initialization list because this function may</span>
<a name="l00287"></a>00287 <span class="comment"> eventually call on_open(), which is virtual, but</span>
<a name="l00288"></a>00288 <span class="comment"> the subclass part of the class may not be in place</span>
<a name="l00289"></a>00289 <span class="comment"> to catch that virtual call. So subclasses should</span>
<a name="l00290"></a>00290 <span class="comment"> initialize with the no-arg parent class ctor</span>
<a name="l00291"></a>00291 <span class="comment"> and should then call open(filename) themselves.</span>
<a name="l00292"></a>00292 <span class="comment"> */</span>
<a name="l00293"></a>00293 <span class="keyword">explicit</span> <a class="code" href="classsq3_1_1database.html#a031f52c894718d806d3d09696901dcca" title="Creates an unopened database.">database</a>( std::string <span class="keyword">const</span> & filename );
<a name="l00294"></a>00294 <span class="comment"></span>
<a name="l00295"></a>00295 <span class="comment"> /**</span>
<a name="l00296"></a>00296 <span class="comment"> Closes this db.</span>
<a name="l00297"></a>00297 <span class="comment"> */</span>
<a name="l00298"></a>00298 <span class="keyword">virtual</span> <a class="code" href="classsq3_1_1database.html#a23fa7ca868f48e4de39c0f0f55cd2c9c" title="Closes this db.">~database</a>();
<a name="l00299"></a>00299 <span class="comment"></span>
<a name="l00300"></a>00300 <span class="comment"> /**</span>
<a name="l00301"></a>00301 <span class="comment"> Returns true if this db is opened.</span>
<a name="l00302"></a>00302 <span class="comment"> Does not detect errors such as opening</span>
<a name="l00303"></a>00303 <span class="comment"> a non-db file.</span>
<a name="l00304"></a>00304 <span class="comment"> */</span>
<a name="l00305"></a>00305 <span class="keywordtype">bool</span> <a class="code" href="classsq3_1_1database.html#af3b6b07c453a2ce5eaf9072e9cbe1f84" title="Returns true if this db is opened.">is_open</a>() <span class="keyword">const</span>;
<a name="l00306"></a>00306 <span class="comment"></span>
<a name="l00307"></a>00307 <span class="comment"> /**</span>
<a name="l00308"></a>00308 <span class="comment"> Returns the name of the db file.</span>
<a name="l00309"></a>00309 <span class="comment"> */</span>
<a name="l00310"></a>00310 std::string <a class="code" href="classsq3_1_1database.html#a70b7775e8ec6b930cd1df88c1d691d6a" title="Returns the name of the db file.">name</a>() <span class="keyword">const</span>;
<a name="l00311"></a>00311 <span class="comment"></span>
<a name="l00312"></a>00312 <span class="comment"> /**</span>
<a name="l00313"></a>00313 <span class="comment"> Returns the last error message from</span>
<a name="l00314"></a>00314 <span class="comment"> sqlite, or an empty string if this object</span>
<a name="l00315"></a>00315 <span class="comment"> is not opened. Unfortunately, sqlite3</span>
<a name="l00316"></a>00316 <span class="comment"> returns the literal string "not an error"</span>
<a name="l00317"></a>00317 <span class="comment"> on non-errors, instead of returning an empty</span>
<a name="l00318"></a>00318 <span class="comment"> string.</span>
<a name="l00319"></a>00319 <span class="comment"> */</span>
<a name="l00320"></a>00320 std::string <a class="code" href="classsq3_1_1database.html#ad108bff8ea5c80026f5ab45d19ec313c" title="Returns the last error message from sqlite, or an empty string if this object is...">errormsg</a>() <span class="keyword">const</span>;
<a name="l00321"></a>00321 <span class="comment"></span>
<a name="l00322"></a>00322 <span class="comment"> /**</span>
<a name="l00323"></a>00323 <span class="comment"> Creates/opens the given db file.</span>
<a name="l00324"></a>00324 <span class="comment"></span>
<a name="l00325"></a>00325 <span class="comment"> The flags parameter is only used if this code is</span>
<a name="l00326"></a>00326 <span class="comment"> compiled against sqlite3 >= 3.5.1, and can</span>
<a name="l00327"></a>00327 <span class="comment"> theoretically take any values defined in the</span>
<a name="l00328"></a>00328 <span class="comment"> SQLITE_OPEN_xxx family of macros. The sqlite3</span>
<a name="l00329"></a>00329 <span class="comment"> documentation only describes the use of</span>
<a name="l00330"></a>00330 <span class="comment"> SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, and</span>
<a name="l00331"></a>00331 <span class="comment"> SQLITE_OPEN_CREATE, thus other values may nor may</span>
<a name="l00332"></a>00332 <span class="comment"> not work. If (0==flags) then</span>
<a name="l00333"></a>00333 <span class="comment"> (SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE) is</span>
<a name="l00334"></a>00334 <span class="comment"> assumed. See sqlite3_open_v2() for the exact</span>
<a name="l00335"></a>00335 <span class="comment"> semantics.</span>
<a name="l00336"></a>00336 <span class="comment"></span>
<a name="l00337"></a>00337 <span class="comment"> On success it returns SQLITE_OK, or some other</span>
<a name="l00338"></a>00338 <span class="comment"> value on error.</span>
<a name="l00339"></a>00339 <span class="comment"></span>
<a name="l00340"></a>00340 <span class="comment"> Calling open() will implicitly call close() on any</span>
<a name="l00341"></a>00341 <span class="comment"> existing connection. If that close() fails then</span>
<a name="l00342"></a>00342 <span class="comment"> this open() will also fail. If the open() succeeds,</span>
<a name="l00343"></a>00343 <span class="comment"> it does NOT affect other (shallow) copies of this</span>
<a name="l00344"></a>00344 <span class="comment"> object: they will still refer to the older db</span>
<a name="l00345"></a>00345 <span class="comment"> handle.</span>
<a name="l00346"></a>00346 <span class="comment"> </span>
<a name="l00347"></a>00347 <span class="comment"> Note that sqlite3 supports the special db name</span>
<a name="l00348"></a>00348 <span class="comment"> ":memory:" to represent an in-memory database. Such</span>
<a name="l00349"></a>00349 <span class="comment"> databases cannot be saved directly to disk and are</span>
<a name="l00350"></a>00350 <span class="comment"> lost when this object closes the db.</span>
<a name="l00351"></a>00351 <span class="comment"></span>
<a name="l00352"></a>00352 <span class="comment"> Windows users beware: according to the sqlite3</span>
<a name="l00353"></a>00353 <span class="comment"> documentation, the db name MUST be in UTF8 format,</span>
<a name="l00354"></a>00354 <span class="comment"> regardless of the current codepage used by Windows,</span>
<a name="l00355"></a>00355 <span class="comment"> and it is the caller's responsibility to perform</span>
<a name="l00356"></a>00356 <span class="comment"> any conversion, if needed.</span>
<a name="l00357"></a>00357 <span class="comment"></span>
<a name="l00358"></a>00358 <span class="comment"> Internal notes:</span>
<a name="l00359"></a>00359 <span class="comment"></span>
<a name="l00360"></a>00360 <span class="comment"> If the underlying sqlite3_open() succeeds, the</span>
<a name="l00361"></a>00361 <span class="comment"> protected member on_open() in called. If it returns</span>
<a name="l00362"></a>00362 <span class="comment"> a value other than SQLITE_OK then this->close() is</span>
<a name="l00363"></a>00363 <span class="comment"> called and the value returned from on_open() is</span>
<a name="l00364"></a>00364 <span class="comment"> returned from this function.</span>
<a name="l00365"></a>00365 <span class="comment"></span>
<a name="l00366"></a>00366 <span class="comment"> Subclasses which override this function and do not</span>
<a name="l00367"></a>00367 <span class="comment"> want to call the base implementation should call</span>
<a name="l00368"></a>00368 <span class="comment"> on_open() when done to allow subclasses to</span>
<a name="l00369"></a>00369 <span class="comment"> initialize the database if they like. If on_open()</span>
<a name="l00370"></a>00370 <span class="comment"> fails then this->close() should be called to free</span>
<a name="l00371"></a>00371 <span class="comment"> up the resources and mark this object as unopened.</span>
<a name="l00372"></a>00372 <span class="comment"></span>
<a name="l00373"></a>00373 <span class="comment"> The flags argument was added 20071018, suggested by</span>
<a name="l00374"></a>00374 <span class="comment"> Joaquim Campos Salles (Joaquim.Salles at</span>
<a name="l00375"></a>00375 <span class="comment"> br.unisys.com).</span>
<a name="l00376"></a>00376 <span class="comment"></span>
<a name="l00377"></a>00377 <span class="comment"> */</span>
<a name="l00378"></a>00378 <span class="keyword">virtual</span> <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> *, <span class="keywordtype">long</span> flags = 0 );
<a name="l00379"></a>00379 <span class="comment"></span>
<a name="l00380"></a>00380 <span class="comment"> /**</span>
<a name="l00381"></a>00381 <span class="comment"> Functionally identical to open(char const*,long).</span>
<a name="l00382"></a>00382 <span class="comment"> This function calls that one, so subclasses wishing</span>
<a name="l00383"></a>00383 <span class="comment"> to change open()'s behaviour need only reimplement</span>
<a name="l00384"></a>00384 <span class="comment"> that one.</span>
<a name="l00385"></a>00385 <span class="comment"> */</span>
<a name="l00386"></a>00386 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open</a>( std::string <span class="keyword">const</span> &, <span class="keywordtype">long</span> flags = 0 );
<a name="l00387"></a>00387 <span class="comment"></span>
<a name="l00388"></a>00388 <span class="comment"> /**</span>
<a name="l00389"></a>00389 <span class="comment"> "Closes" this db. That actually means that</span>
<a name="l00390"></a>00390 <span class="comment"> it queues it to be closed when the last</span>
<a name="l00391"></a>00391 <span class="comment"> database object which is using that db handle</span>
<a name="l00392"></a>00392 <span class="comment"> closes or goes out of scope.</span>
<a name="l00393"></a>00393 <span class="comment"></span>
<a name="l00394"></a>00394 <span class="comment"> The force parameter changes the handling of those</span>
<a name="l00395"></a>00395 <span class="comment"> sqlite3_close():</span>
<a name="l00396"></a>00396 <span class="comment"></span>
<a name="l00397"></a>00397 <span class="comment"> If force is false, this function always returns</span>
<a name="l00398"></a>00398 <span class="comment"> SQLITE_OK unless this object is already closed, in</span>
<a name="l00399"></a>00399 <span class="comment"> which case SQLITE_ERROR is returned but can almost</span>
<a name="l00400"></a>00400 <span class="comment"> certainly be safely ignored. Unfortunately, due to</span>
<a name="l00401"></a>00401 <span class="comment"> the asynchronous nature of this operation, we can't</span>
<a name="l00402"></a>00402 <span class="comment"> return the value from the actual sqlite3_close()</span>
<a name="l00403"></a>00403 <span class="comment"> call (if any) when force is set to false.</span>
<a name="l00404"></a>00404 <span class="comment"></span>
<a name="l00405"></a>00405 <span class="comment"> If force is true then the internal reference</span>
<a name="l00406"></a>00406 <span class="comment"> counting is anulled and the db handle is closed</span>
<a name="l00407"></a>00407 <span class="comment"> immediately. This affects all copies of this</span>
<a name="l00408"></a>00408 <span class="comment"> object, so use with care (but use if you must). In</span>
<a name="l00409"></a>00409 <span class="comment"> this case, the value of sqlite3_close() is</span>
<a name="l00410"></a>00410 <span class="comment"> returned, but the the exact state of the underlying</span>
<a name="l00411"></a>00411 <span class="comment"> database handle is ambiguously defined in the</span>
<a name="l00412"></a>00412 <span class="comment"> sqlite3 docs. So... if that happens then the</span>
<a name="l00413"></a>00413 <span class="comment"> underlying db handle is assumed to be invalid, since</span>
<a name="l00414"></a>00414 <span class="comment"> the "test*.c" files which come with sqlite3 seem</span>
<a name="l00415"></a>00415 <span class="comment"> to treat it as such.</span>
<a name="l00416"></a>00416 <span class="comment"> */</span>
<a name="l00417"></a>00417 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title="&quot;Closes&quot; this db.">close</a>( <span class="keywordtype">bool</span> force = <span class="keyword">false</span> );
<a name="l00418"></a>00418
<a name="l00419"></a>00419
<a name="l00420"></a>00420 <span class="comment"></span>
<a name="l00421"></a>00421 <span class="comment"> /**</span>
<a name="l00422"></a>00422 <span class="comment"> Returns the rowid of the most recently inserted row</span>
<a name="l00423"></a>00423 <span class="comment"> on this db.</span>
<a name="l00424"></a>00424 <span class="comment"> */</span>
<a name="l00425"></a>00425 <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> <a class="code" href="classsq3_1_1database.html#aefe363278ea935699a1c9f3d0b0c6e90" title="Returns the rowid of the most recently inserted row on this db.">insertid</a>();
<a name="l00426"></a>00426 <span class="comment"></span>
<a name="l00427"></a>00427 <span class="comment"> /**</span>
<a name="l00428"></a>00428 <span class="comment"> Returns the number of database rows that were</span>
<a name="l00429"></a>00429 <span class="comment"> changed (or inserted or deleted) by the most recently</span>
<a name="l00430"></a>00430 <span class="comment"> completed INSERT, UPDATE, or DELETE statement.</span>
<a name="l00431"></a>00431 <span class="comment"></span>
<a name="l00432"></a>00432 <span class="comment"> SQLite implements the command "DELETE FROM table"</span>
<a name="l00433"></a>00433 <span class="comment"> without a WHERE clause by dropping and recreating</span>
<a name="l00434"></a>00434 <span class="comment"> the table. To get an accurate count of the number</span>
<a name="l00435"></a>00435 <span class="comment"> of rows deleted, use "DELETE FROM table WHERE 1"</span>
<a name="l00436"></a>00436 <span class="comment"> instead.</span>
<a name="l00437"></a>00437 <span class="comment"> */</span>
<a name="l00438"></a>00438 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a722715171d91b3713e07485fc89f5fda" title="Returns the number of database rows that were changed (or inserted or deleted) by...">changes</a>();
<a name="l00439"></a>00439 <span class="comment"></span>
<a name="l00440"></a>00440 <span class="comment"> /**</span>
<a name="l00441"></a>00441 <span class="comment"> See sqlite3_busy_timeout().</span>
<a name="l00442"></a>00442 <span class="comment"> */</span>
<a name="l00443"></a>00443 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a0baa615d200aad7e121f8e11aad12d33" title="See sqlite3_busy_timeout().">setbusytimeout</a>( <span class="keywordtype">int</span> ms );
<a name="l00444"></a>00444 <span class="comment"></span>
<a name="l00445"></a>00445 <span class="comment"> /**</span>
<a name="l00446"></a>00446 <span class="comment"> Functionally identical to execute(char const *).</span>
<a name="l00447"></a>00447 <span class="comment"> */</span>
<a name="l00448"></a>00448 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keyword">const</span> std::string &sql);
<a name="l00449"></a>00449 <span class="comment"></span>
<a name="l00450"></a>00450 <span class="comment"> /**</span>
<a name="l00451"></a>00451 <span class="comment"> Executes a statement which is assumed to have</span>
<a name="l00452"></a>00452 <span class="comment"> a single step and a void result. Returned result</span>
<a name="l00453"></a>00453 <span class="comment"> is that of an underlying call to sqlite3_step(),</span>
<a name="l00454"></a>00454 <span class="comment"> which means that SQLITE_DONE or SQLITE_ROW evaluate</span>
<a name="l00455"></a>00455 <span class="comment"> to success.</span>
<a name="l00456"></a>00456 <span class="comment"> */</span>
<a name="l00457"></a>00457 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql);
<a name="l00458"></a>00458 <span class="comment"></span>
<a name="l00459"></a>00459 <span class="comment"> /**</span>
<a name="l00460"></a>00460 <span class="comment"> Executes a statement which is assumed to have</span>
<a name="l00461"></a>00461 <span class="comment"> a single result step and an integer result.</span>
<a name="l00462"></a>00462 <span class="comment"> On success, tgt will be set to the query's</span>
<a name="l00463"></a>00463 <span class="comment"> value. Typically one of SQLITE_ROW or SQLITE_DONE</span>
<a name="l00464"></a>00464 <span class="comment"> are returned on success.</span>
<a name="l00465"></a>00465 <span class="comment"> */</span>
<a name="l00466"></a>00466 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, <span class="keywordtype">int</span> & tgt);
<a name="l00467"></a>00467 <span class="comment"></span>
<a name="l00468"></a>00468 <span class="comment"> /**</span>
<a name="l00469"></a>00469 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00470"></a>00470 <span class="comment"> */</span>
<a name="l00471"></a>00471 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <span class="keywordtype">int</span> & tgt);
<a name="l00472"></a>00472 <span class="comment"></span>
<a name="l00473"></a>00473 <span class="comment"> /**</span>
<a name="l00474"></a>00474 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00475"></a>00475 <span class="comment"> */</span>
<a name="l00476"></a>00476 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> & tgt);
<a name="l00477"></a>00477 <span class="comment"></span>
<a name="l00478"></a>00478 <span class="comment"> /**</span>
<a name="l00479"></a>00479 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00480"></a>00480 <span class="comment"> */</span>
<a name="l00481"></a>00481 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> & tgt);
<a name="l00482"></a>00482 <span class="comment"></span>
<a name="l00483"></a>00483 <span class="comment"> /**</span>
<a name="l00484"></a>00484 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00485"></a>00485 <span class="comment"> */</span>
<a name="l00486"></a>00486 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <span class="keywordtype">double</span> & tgt);<span class="comment"></span>
<a name="l00487"></a>00487 <span class="comment"> /**</span>
<a name="l00488"></a>00488 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00489"></a>00489 <span class="comment"> */</span>
<a name="l00490"></a>00490 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, <span class="keywordtype">double</span> & tgt);
<a name="l00491"></a>00491 <span class="comment"></span>
<a name="l00492"></a>00492 <span class="comment"> /**</span>
<a name="l00493"></a>00493 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00494"></a>00494 <span class="comment"> */</span>
<a name="l00495"></a>00495 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, std::string & tgt);<span class="comment"></span>
<a name="l00496"></a>00496 <span class="comment"> /**</span>
<a name="l00497"></a>00497 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00498"></a>00498 <span class="comment"> */</span>
<a name="l00499"></a>00499 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, std::string & tgt);
<a name="l00500"></a>00500 <span class="comment"></span>
<a name="l00501"></a>00501 <span class="comment"> /**</span>
<a name="l00502"></a>00502 <span class="comment"> See execute( std::string, int & );</span>
<a name="l00503"></a>00503 <span class="comment"></span>
<a name="l00504"></a>00504 <span class="comment"> sql is executed and the string result is written to</span>
<a name="l00505"></a>00505 <span class="comment"> tgt and the length of the result string (in bytes)</span>
<a name="l00506"></a>00506 <span class="comment"> is written to len. The text bytes are owned by</span>
<a name="l00507"></a>00507 <span class="comment"> sqlite and will likely become invalid on the next</span>
<a name="l00508"></a>00508 <span class="comment"> db cursor operation, so copy them if you need them.</span>
<a name="l00509"></a>00509 <span class="comment"></span>
<a name="l00510"></a>00510 <span class="comment"> Returns the result of stepping through a result</span>
<a name="l00511"></a>00511 <span class="comment"> set, which is typically one of SQLITE_ROW or</span>
<a name="l00512"></a>00512 <span class="comment"> SQLITE_DONE.</span>
<a name="l00513"></a>00513 <span class="comment"> */</span>
<a name="l00514"></a>00514 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & len );<span class="comment"></span>
<a name="l00515"></a>00515 <span class="comment"> /**</span>
<a name="l00516"></a>00516 <span class="comment"> See execute( char const *, sqlite3_text_char_t const **, int & ).</span>
<a name="l00517"></a>00517 <span class="comment"> This function is identical.</span>
<a name="l00518"></a>00518 <span class="comment"> */</span>
<a name="l00519"></a>00519 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & len );
<a name="l00520"></a>00520
<a name="l00521"></a>00521 <span class="comment"></span>
<a name="l00522"></a>00522 <span class="comment"> /**</span>
<a name="l00523"></a>00523 <span class="comment"> See execute( char const *, sqlite3_text_char_t **, int & ).</span>
<a name="l00524"></a>00524 <span class="comment"> This function is identical except that tgt is a</span>
<a name="l00525"></a>00525 <span class="comment"> void pointer.</span>
<a name="l00526"></a>00526 <span class="comment"> */</span>
<a name="l00527"></a>00527 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(std::string <span class="keyword">const</span> & sql, <span class="keywordtype">void</span> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );<span class="comment"></span>
<a name="l00528"></a>00528 <span class="comment"> /**</span>
<a name="l00529"></a>00529 <span class="comment"> See execute( char const *, sqlite3_text_char_t **, int & ).</span>
<a name="l00530"></a>00530 <span class="comment"> This function is identical except that tgt is a</span>
<a name="l00531"></a>00531 <span class="comment"> void pointer.</span>
<a name="l00532"></a>00532 <span class="comment"> */</span>
<a name="l00533"></a>00533 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>(<span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <span class="keywordtype">void</span> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );
<a name="l00534"></a>00534
<a name="l00535"></a>00535 <span class="comment"></span>
<a name="l00536"></a>00536 <span class="comment"> /**</span>
<a name="l00537"></a>00537 <span class="comment"> Executes the given query, calling the given callback function for each</span>
<a name="l00538"></a>00538 <span class="comment"> row of the result set. The data pointer is passed on as-is to the callback.</span>
<a name="l00539"></a>00539 <span class="comment"> Any error string is written to errmsg.</span>
<a name="l00540"></a>00540 <span class="comment"></span>
<a name="l00541"></a>00541 <span class="comment"> Return value is that of an underlying sqlite3_exec() call.</span>
<a name="l00542"></a>00542 <span class="comment"> */</span>
<a name="l00543"></a>00543 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>( std::string <span class="keyword">const</span> & sql, sqlite3_callback callback, <span class="keywordtype">void</span> * data, std::string & errmsg );<span class="comment"></span>
<a name="l00544"></a>00544 <span class="comment"> /**</span>
<a name="l00545"></a>00545 <span class="comment"> Identical to the execute(std::string,sqlite3_callback,void*,std::string&).</span>
<a name="l00546"></a>00546 <span class="comment"> */</span>
<a name="l00547"></a>00547 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * sql, sqlite3_callback callback, <span class="keywordtype">void</span> * data, std::string & errmsg );
<a name="l00548"></a>00548 <span class="comment"></span>
<a name="l00549"></a>00549 <span class="comment"> /**</span>
<a name="l00550"></a>00550 <span class="comment"> Convenience overload which has a default data value</span>
<a name="l00551"></a>00551 <span class="comment"> of 0 and ignores any error string passed back by</span>
<a name="l00552"></a>00552 <span class="comment"> sqlite3_exec().</span>
<a name="l00553"></a>00553 <span class="comment"> */</span>
<a name="l00554"></a>00554 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>( std::string <span class="keyword">const</span> & sql, sqlite3_callback callback, <span class="keywordtype">void</span> * data = 0 );<span class="comment"></span>
<a name="l00555"></a>00555 <span class="comment"> /**</span>
<a name="l00556"></a>00556 <span class="comment"> Convenience overload which has a default data value</span>
<a name="l00557"></a>00557 <span class="comment"> of 0 and ignores any error string passed back by</span>
<a name="l00558"></a>00558 <span class="comment"> sqlite3_exec().</span>
<a name="l00559"></a>00559 <span class="comment"> */</span>
<a name="l00560"></a>00560 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * sql, sqlite3_callback callback, <span class="keywordtype">void</span> * data = 0 );
<a name="l00561"></a>00561 <span class="comment"></span>
<a name="l00562"></a>00562 <span class="comment"> /**</span>
<a name="l00563"></a>00563 <span class="comment"> This is a convenience wrapper for execute( "pragma ..." ).</span>
<a name="l00564"></a>00564 <span class="comment"> Return value is that of the underlying execute() call.</span>
<a name="l00565"></a>00565 <span class="comment"></span>
<a name="l00566"></a>00566 <span class="comment"> code should be a pragma key or key/value string, such as</span>
<a name="l00567"></a>00567 <span class="comment"> "temp_store=MEMORY" or "synchronous=OFF"</span>
<a name="l00568"></a>00568 <span class="comment"> */</span>
<a name="l00569"></a>00569 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#ac9fda7f2a5e13df8a1e7cce2ecb13279" title="This is a convenience wrapper for execute( &quot;pragma ...&quot; ).">pragma</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * code );
<a name="l00570"></a>00570 <span class="comment"></span>
<a name="l00571"></a>00571 <span class="comment"> /**</span>
<a name="l00572"></a>00572 <span class="comment"> Convenience wrapper around execute("vacuum"). The</span>
<a name="l00573"></a>00573 <span class="comment"> vacuum operation attempts to free up any unused</span>
<a name="l00574"></a>00574 <span class="comment"> disk space in the database.</span>
<a name="l00575"></a>00575 <span class="comment"> */</span>
<a name="l00576"></a>00576 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#a1cd1358658597f872f849691dafc12ed" title="Convenience wrapper around execute(&quot;vacuum&quot;).">vacuum</a>();
<a name="l00577"></a>00577
<a name="l00578"></a>00578 <span class="preprocessor">#if SQ3_USE_WCHAR</span>
<a name="l00579"></a>00579 <span class="preprocessor"></span> <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open</a>( <span class="keywordtype">wchar_t</span> <span class="keyword">const</span> * dbname );
<a name="l00580"></a>00580 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open</a>( std::wstring <span class="keyword">const</span> & dbname );
<a name="l00581"></a>00581 <span class="comment">// int execute(char const * sql, std::wstring & tgt);</span>
<a name="l00582"></a>00582 <span class="comment">// int execute(std::string const & sql, std::wstring & tgt);</span>
<a name="l00583"></a><a class="code" href="classsq3_1_1transaction.html">00583</a> <span class="preprocessor">#endif // SQ3_USE_WCHAR</span>
<a name="l00584"></a>00584 <span class="preprocessor"></span><span class="comment"></span>
<a name="l00585"></a>00585 <span class="comment"> /**</span>
<a name="l00586"></a>00586 <span class="comment"> Looks through sqlite_master for a list of views,</span>
<a name="l00587"></a>00587 <span class="comment"> triggers, and tables, and drops them all (in that</span>
<a name="l00588"></a>00588 <span class="comment"> order). Subclasses are welcomed to reimplement it</span>
<a name="l00589"></a>00589 <span class="comment"> to do less destructive cleansing, such as just</span>
<a name="l00590"></a>00590 <span class="comment"> dropping data from a certain table.</span>
<a name="l00591"></a>00591 <span class="comment"></span>
<a name="l00592"></a>00592 <span class="comment"> Returns SQLITE_OK on success.</span>
<a name="l00593"></a>00593 <span class="comment"></span>
<a name="l00594"></a>00594 <span class="comment"> If you need to free up the newly-freed space, be</span>
<a name="l00595"></a>00595 <span class="comment"> sure to call vacuum(), or else the file size may</span>
<a name="l00596"></a>00596 <span class="comment"> not actually shrink.</span>
<a name="l00597"></a>00597 <span class="comment"></span>
<a name="l00598"></a>00598 <span class="comment"> Also remember that any code which is expecting data</span>
<a name="l00599"></a>00599 <span class="comment"> to be in this database will not work after this function</span>
<a name="l00600"></a>00600 <span class="comment"> is done!</span>
<a name="l00601"></a>00601 <span class="comment"> */</span>
<a name="l00602"></a>00602 <span class="keyword">virtual</span> <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#abd2da1a48439fe0bcb4d2f1f1985c9c6" title="Looks through sqlite_master for a list of views, triggers, and tables, and drops...">clear</a>();
<a name="l00603"></a>00603
<a name="l00604"></a>00604 <span class="keyword">protected</span>:<span class="comment"></span>
<a name="l00605"></a>00605 <span class="comment"> /**</span>
<a name="l00606"></a>00606 <span class="comment"> This function is called when open() succeeds. The</span>
<a name="l00607"></a>00607 <span class="comment"> default implementation does nothing and always</span>
<a name="l00608"></a>00608 <span class="comment"> returns SQLITE_OK, but subclasses may wish to do</span>
<a name="l00609"></a>00609 <span class="comment"> something here. If this function returns any value</span>
<a name="l00610"></a>00610 <span class="comment"> other than SQLITE_OK then this->close() is called</span>
<a name="l00611"></a>00611 <span class="comment"> before open() returns.</span>
<a name="l00612"></a>00612 <span class="comment"></span>
<a name="l00613"></a>00613 <span class="comment"> */</span>
<a name="l00614"></a>00614 <span class="keyword">virtual</span> <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open</a>();
<a name="l00615"></a>00615
<a name="l00616"></a>00616
<a name="l00617"></a>00617 };
<a name="l00618"></a>00618 <span class="comment"></span>
<a name="l00619"></a>00619 <span class="comment"> /**</span>
<a name="l00620"></a>00620 <span class="comment"> This type represents a transaction block in an SQL</span>
<a name="l00621"></a>00621 <span class="comment"> session. Note that as of this writing, sqlite3 does</span>
<a name="l00622"></a>00622 <span class="comment"> not support nested transactions.</span>
<a name="l00623"></a>00623 <span class="comment"> */</span>
<a name="l00624"></a>00624 <span class="keyword">class </span><a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a>
<a name="l00625"></a>00625 {
<a name="l00626"></a>00626 <span class="keyword">private</span>:
<a name="l00627"></a>00627 <a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a> & operator=( <a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a> <span class="keyword">const</span> & ); <span class="comment">// unimplemented</span>
<a name="l00628"></a>00628 <a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a>( <a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a> <span class="keyword">const</span> & ); <span class="comment">// unimplemented</span>
<a name="l00629"></a>00629 <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & m_db;
<a name="l00630"></a>00630 <span class="keywordtype">bool</span> m_intrans;
<a name="l00631"></a>00631 <span class="keyword">public</span>:<span class="comment"></span>
<a name="l00632"></a>00632 <span class="comment"> /**</span>
<a name="l00633"></a>00633 <span class="comment"> Creates a transaction for the given db. If start</span>
<a name="l00634"></a>00634 <span class="comment"> is true (the default) then this->begin() is called.</span>
<a name="l00635"></a>00635 <span class="comment"> */</span>
<a name="l00636"></a>00636 <a class="code" href="classsq3_1_1transaction.html" title="This type represents a transaction block in an SQL session.">transaction</a>( <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & db, <span class="keywordtype">bool</span> start = <span class="keyword">true</span> );<span class="comment"></span>
<a name="l00637"></a>00637 <span class="comment"> /**</span>
<a name="l00638"></a>00638 <span class="comment"> Calls this->rollback()</span>
<a name="l00639"></a>00639 <span class="comment"> */</span>
<a name="l00640"></a>00640 <a class="code" href="classsq3_1_1transaction.html#aba444c389b8f7758edac498d194b1aeb" title="Calls this-&gt;rollback().">~transaction</a>();<span class="comment"></span>
<a name="l00641"></a>00641 <span class="comment"> /**</span>
<a name="l00642"></a>00642 <span class="comment"> Starts the transaction. Return value is the result</span>
<a name="l00643"></a><a class="code" href="classsq3_1_1cursor.html">00643</a> <span class="comment"> of calling sqlite3_exec(db,"begin;"). If SQLITE_OK</span>
<a name="l00644"></a>00644 <span class="comment"> is returned then this object considers itself to be</span>
<a name="l00645"></a>00645 <span class="comment"> active, such that calling commit() and rollback()</span>
<a name="l00646"></a>00646 <span class="comment"> should be able to succeed.</span>
<a name="l00647"></a>00647 <span class="comment"> */</span>
<a name="l00648"></a>00648 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1transaction.html#a7c2086d6e48f39b27f006a2c1cb5fae0" title="Starts the transaction.">begin</a>();<span class="comment"></span>
<a name="l00649"></a>00649 <span class="comment"> /**</span>
<a name="l00650"></a>00650 <span class="comment"> Commits the active transaction. Returns SQLITE_OK</span>
<a name="l00651"></a>00651 <span class="comment"> on success and any other value on error. Return</span>
<a name="l00652"></a>00652 <span class="comment"> value is that of the underlying sqlite3_exec()</span>
<a name="l00653"></a>00653 <span class="comment"> call.</span>
<a name="l00654"></a>00654 <span class="comment"></span>
<a name="l00655"></a>00655 <span class="comment"> After calling this function, this object is considered to</span>
<a name="l00656"></a>00656 <span class="comment"> NOT be in a transaction unless SQLITE_BUSY is returned.</span>
<a name="l00657"></a>00657 <span class="comment"> If that happens, the transaction is still open and commit()</span>
<a name="l00658"></a>00658 <span class="comment"> should be called later to close the transaction.</span>
<a name="l00659"></a>00659 <span class="comment"> */</span>
<a name="l00660"></a>00660 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1transaction.html#a7508951fb31172fc90e5d5170a640332" title="Commits the active transaction.">commit</a>();<span class="comment"></span>
<a name="l00661"></a>00661 <span class="comment"> /**</span>
<a name="l00662"></a>00662 <span class="comment"> Initiates a rollback and returns the result of</span>
<a name="l00663"></a>00663 <span class="comment"> executing a rollback command. If this object is not</span>
<a name="l00664"></a>00664 <span class="comment"> active (begin() has not been called) then this</span>
<a name="l00665"></a>00665 <span class="comment"> function returns SQLITE_ERROR and has no</span>
<a name="l00666"></a>00666 <span class="comment"> side-effects. Return value is that of the</span>
<a name="l00667"></a>00667 <span class="comment"> underlying sqlite3_exec() call.</span>
<a name="l00668"></a>00668 <span class="comment"> */</span>
<a name="l00669"></a>00669 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1transaction.html#aef819599c00a3a780ea565671155747d" title="Initiates a rollback and returns the result of executing a rollback command.">rollback</a>();
<a name="l00670"></a>00670 };
<a name="l00671"></a>00671 <span class="comment"></span>
<a name="l00672"></a>00672 <span class="comment"> /**</span>
<a name="l00673"></a>00673 <span class="comment"> This type is for stepping through a db query result.</span>
<a name="l00674"></a>00674 <span class="comment"> Clients do not normally create cursors directly, but</span>
<a name="l00675"></a>00675 <span class="comment"> through the statement::get_cursor()</span>
<a name="l00676"></a>00676 <span class="comment"> function.</span>
<a name="l00677"></a>00677 <span class="comment"></span>
<a name="l00678"></a>00678 <span class="comment"> cursor objects are copied shallowly - each copy points</span>
<a name="l00679"></a>00679 <span class="comment"> back to a single original statement object. That statement</span>
<a name="l00680"></a>00680 <span class="comment"> is reset when the last of these copies goes out of scope</span>
<a name="l00681"></a>00681 <span class="comment"> or is finalized.</span>
<a name="l00682"></a>00682 <span class="comment"></span>
<a name="l00683"></a>00683 <span class="comment"> */</span>
<a name="l00684"></a>00684 <span class="keyword">class </span><a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a>
<a name="l00685"></a>00685 {
<a name="l00686"></a>00686 <span class="keyword">private</span>:
<a name="l00687"></a>00687 <span class="comment">//friend class statement;</span>
<a name="l00688"></a>00688 <a class="code" href="classrefcount_1_1rcptr.html">refcount::rcptr<statement,statement_reset_finalizer></a> m_stmt;<span class="comment"></span>
<a name="l00689"></a>00689 <span class="comment"> /**</span>
<a name="l00690"></a>00690 <span class="comment"> And internal helper type for fetching data sets by</span>
<a name="l00691"></a>00691 <span class="comment"> string lookups instead of integer indexes.</span>
<a name="l00692"></a>00692 <span class="comment"> */</span>
<a name="l00693"></a>00693 <span class="keyword">typedef</span> std::map<std::string,int> NameToIndexMap;
<a name="l00694"></a>00694 NameToIndexMap * m_cn; <span class="comment">// maps column names to column indexes for use with get().</span>
<a name="l00695"></a>00695
<a name="l00696"></a>00696 <span class="comment"></span>
<a name="l00697"></a>00697 <span class="comment"> /**</span>
<a name="l00698"></a>00698 <span class="comment"> If rhs is this object, this function does nothing,</span>
<a name="l00699"></a>00699 <span class="comment"> otherwise it copies rhs.</span>
<a name="l00700"></a>00700 <span class="comment"> */</span>
<a name="l00701"></a>00701 <span class="keywordtype">void</span> copy( <a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a> <span class="keyword">const</span> & rhs );<span class="comment"></span>
<a name="l00702"></a>00702 <span class="comment"> /**</span>
<a name="l00703"></a>00703 <span class="comment"> Hashes the colname-to-index mapping.</span>
<a name="l00704"></a>00704 <span class="comment"> Returns:</span>
<a name="l00705"></a>00705 <span class="comment"></span>
<a name="l00706"></a>00706 <span class="comment"> -1: result was cached before and will stay cached until</span>
<a name="l00707"></a>00707 <span class="comment"> this object expires.</span>
<a name="l00708"></a>00708 <span class="comment"></span>
<a name="l00709"></a>00709 <span class="comment"> 0: this result set has no columns. This is likely an error.</span>
<a name="l00710"></a>00710 <span class="comment"></span>
<a name="l00711"></a>00711 <span class="comment"> 1 or higher: the number of column indexes.</span>
<a name="l00712"></a>00712 <span class="comment"></span>
<a name="l00713"></a>00713 <span class="comment"> As a side-effect, this function initializes this->m_cn</span>
<a name="l00714"></a>00714 <span class="comment"> if that object has not already been created.</span>
<a name="l00715"></a>00715 <span class="comment"></span>
<a name="l00716"></a>00716 <span class="comment"> If the return value is anything other than this->colcount()</span>
<a name="l00717"></a>00717 <span class="comment"> then an error occurred during the collection of the</span>
<a name="l00718"></a>00718 <span class="comment"> column names. This is exceedingly unlikely to happen.</span>
<a name="l00719"></a>00719 <span class="comment"> */</span>
<a name="l00720"></a>00720 <span class="keywordtype">int</span> index_colnames();
<a name="l00721"></a>00721
<a name="l00722"></a>00722 <span class="keyword">public</span>:<span class="comment"></span>
<a name="l00723"></a>00723 <span class="comment"> /**</span>
<a name="l00724"></a>00724 <span class="comment"> Creates an empty cursor, whose only valid use is to</span>
<a name="l00725"></a>00725 <span class="comment"> assign it from another cursor.</span>
<a name="l00726"></a>00726 <span class="comment"> */</span>
<a name="l00727"></a>00727 <a class="code" href="classsq3_1_1cursor.html#a9101adc9b33c4bcc4b9c30ae3306aa62" title="Creates an empty cursor, whose only valid use is to assign it from another cursor...">cursor</a>();<span class="comment"></span>
<a name="l00728"></a>00728 <span class="comment"> /**</span>
<a name="l00729"></a>00729 <span class="comment"> Copies rhs. This object and rhs now point to the</span>
<a name="l00730"></a>00730 <span class="comment"> same underlying sqlite3 structures, and modifying</span>
<a name="l00731"></a>00731 <span class="comment"> one of these objects modifies the other, in effect.</span>
<a name="l00732"></a>00732 <span class="comment"> */</span>
<a name="l00733"></a>00733 <a class="code" href="classsq3_1_1cursor.html#a9101adc9b33c4bcc4b9c30ae3306aa62" title="Creates an empty cursor, whose only valid use is to assign it from another cursor...">cursor</a>( <a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a> <span class="keyword">const</span> & rhs );<span class="comment"></span>
<a name="l00734"></a>00734 <span class="comment"> /**</span>
<a name="l00735"></a>00735 <span class="comment"> See the copy ctor.</span>
<a name="l00736"></a>00736 <span class="comment"> */</span>
<a name="l00737"></a>00737 <a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a> & <a class="code" href="classsq3_1_1cursor.html#ad219d06e0b9c31b7a62bfa5cb21879ef" title="See the copy ctor.">operator=</a>( <a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a> <span class="keyword">const</span> & );
<a name="l00738"></a>00738 <span class="comment"></span>
<a name="l00739"></a>00739 <span class="comment"> /**</span>
<a name="l00740"></a>00740 <span class="comment"> Identical to calling st.get_cursor().</span>
<a name="l00741"></a>00741 <span class="comment"> */</span>
<a name="l00742"></a>00742 <a class="code" href="classsq3_1_1cursor.html#a9101adc9b33c4bcc4b9c30ae3306aa62" title="Creates an empty cursor, whose only valid use is to assign it from another cursor...">cursor</a>( <a class="code" href="classsq3_1_1statement.html" title="This class represents a prepared database statement.">statement</a> & st );
<a name="l00743"></a>00743 <span class="comment"></span>
<a name="l00744"></a>00744 <span class="comment"> /**</span>
<a name="l00745"></a>00745 <span class="comment"> A curious side-effect which one needs to be</span>
<a name="l00746"></a>00746 <span class="comment"> aware of but very rarely is an issue:</span>
<a name="l00747"></a>00747 <span class="comment"></span>
<a name="l00748"></a>00748 <span class="comment"> When cursors are created they *always* have an</span>
<a name="l00749"></a>00749 <span class="comment"> associated prepared statement. When the last cursor</span>
<a name="l00750"></a>00750 <span class="comment"> with a reference to that same statement goes out of</span>
<a name="l00751"></a>00751 <span class="comment"> scope or is close()ed then the underlying statement</span>
<a name="l00752"></a>00752 <span class="comment"> object is reset(). That sounds curious, but is</span>
<a name="l00753"></a>00753 <span class="comment"> indeed the desired behaviour for this class, and</span>
<a name="l00754"></a>00754 <span class="comment"> breaks some common client code constructs when the</span>
<a name="l00755"></a>00755 <span class="comment"> underlying statement is not automatically reset.</span>
<a name="l00756"></a>00756 <span class="comment"> Without this "feature", client code could not run,</span>
<a name="l00757"></a>00757 <span class="comment"> for exaple, myStatement.execute( myInt ), two times</span>
<a name="l00758"></a>00758 <span class="comment"> in a row because the second time around the</span>
<a name="l00759"></a>00759 <span class="comment"> statement would be at its end point and need to be</span>
<a name="l00760"></a>00760 <span class="comment"> manually reset. Thus client code should never mix</span>
<a name="l00761"></a>00761 <span class="comment"> the use of a cursor object and the non-cursor</span>
<a name="l00762"></a>00762 <span class="comment"> statement API on the same statement.</span>
<a name="l00763"></a>00763 <span class="comment"></span>
<a name="l00764"></a>00764 <span class="comment"> See statement::close() for more details.</span>
<a name="l00765"></a>00765 <span class="comment"> */</span>
<a name="l00766"></a>00766 <a class="code" href="classsq3_1_1cursor.html#a90597816ef97b8b500740c896808e5a4" title="A curious side-effect which one needs to be aware of but very rarely is an issue:...">~cursor</a>();
<a name="l00767"></a>00767 <span class="comment"></span>
<a name="l00768"></a>00768 <span class="comment"> /**</span>
<a name="l00769"></a>00769 <span class="comment"> Uses sqlite3_step() to step through this object's</span>
<a name="l00770"></a>00770 <span class="comment"> data set by one step. Returns the result of</span>
<a name="l00771"></a>00771 <span class="comment"> sqlite3_step(), which means: SQLITE_ROW if it</span>
<a name="l00772"></a>00772 <span class="comment"> read, SQLITE_DONE at the end of a data set,</span>
<a name="l00773"></a>00773 <span class="comment"> and any other value on error.</span>
<a name="l00774"></a>00774 <span class="comment"> */</span>
<a name="l00775"></a>00775 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#a7253c675929242bbbef16ec6e3ba6ad0" title="Uses sqlite3_step() to step through this object&#39;s data set by one step.">step</a>();<span class="comment"></span>
<a name="l00776"></a>00776 <span class="comment"> /**</span>
<a name="l00777"></a>00777 <span class="comment"> This is functionally the same as calling reset on</span>
<a name="l00778"></a>00778 <span class="comment"> the underlying prepared statement object to which</span>
<a name="l00779"></a>00779 <span class="comment"> this cursor is tied. Use with care, as it affects</span>
<a name="l00780"></a>00780 <span class="comment"> all cursors which point to the same statement</span>
<a name="l00781"></a>00781 <span class="comment"> object.</span>
<a name="l00782"></a>00782 <span class="comment"></span>
<a name="l00783"></a>00783 <span class="comment"> returns SQLITE_OK on success, else another sqlite3</span>
<a name="l00784"></a>00784 <span class="comment"> error code.</span>
<a name="l00785"></a>00785 <span class="comment"> */</span>
<a name="l00786"></a>00786 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#a44cfae0c25e1be91325c00a415541aa7" title="This is functionally the same as calling reset on the underlying prepared statement...">reset</a>();
<a name="l00787"></a>00787 <span class="comment"></span>
<a name="l00788"></a>00788 <span class="comment"> /**</span>
<a name="l00789"></a>00789 <span class="comment"> "Disconnects" this object from the underlying</span>
<a name="l00790"></a>00790 <span class="comment"> result set, making this object useless for anything</span>
<a name="l00791"></a>00791 <span class="comment"> but as the target of an assignment.</span>
<a name="l00792"></a>00792 <span class="comment"></span>
<a name="l00793"></a>00793 <span class="comment"> It is normally not necessary to call this function,</span>
<a name="l00794"></a>00794 <span class="comment"> but it may be in some special cases.</span>
<a name="l00795"></a>00795 <span class="comment"> */</span>
<a name="l00796"></a>00796 <span class="keywordtype">void</span> <a class="code" href="classsq3_1_1cursor.html#a6b41bb7f1aebca20d69da0822fffbc57" title="&quot;Disconnects&quot; this object from the underlying result set, making this object...">close</a>();
<a name="l00797"></a>00797 <span class="comment"></span>
<a name="l00798"></a>00798 <span class="comment"> /**</span>
<a name="l00799"></a>00799 <span class="comment"> Returns the column count of the underlying</span>
<a name="l00800"></a>00800 <span class="comment"> prepared statement. May return 0 for queries which</span>
<a name="l00801"></a>00801 <span class="comment"> has no return value (e.g. UPDATE). Returns -1</span>
<a name="l00802"></a>00802 <span class="comment"> on error.</span>
<a name="l00803"></a>00803 <span class="comment"> */</span>
<a name="l00804"></a>00804 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#ab43f9599d49c13195e78e49943d6157f" title="Returns the column count of the underlying prepared statement.">colcount</a>();
<a name="l00805"></a>00805 <span class="comment"></span>
<a name="l00806"></a>00806 <span class="comment"> /**</span>
<a name="l00807"></a>00807 <span class="comment"> If column index (0-based) is in bounds then this</span>
<a name="l00808"></a>00808 <span class="comment"> function check if the value of the given column index</span>
<a name="l00809"></a>00809 <span class="comment"> is NULL and assigns tgt to the result of this</span>
<a name="l00810"></a>00810 <span class="comment"> comprobation. On success, SQLITE_OK is returned.</span>
<a name="l00811"></a>00811 <span class="comment"> On any other return value, tgt is not modifed.</span>
<a name="l00812"></a>00812 <span class="comment"> */</span>
<a name="l00813"></a>00813 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#a067706590778ef5147676499a7cfb808" title="If column index (0-based) is in bounds then this function check if the value of the...">isnull</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">bool</span> & tgt );
<a name="l00814"></a>00814 <span class="comment"></span>
<a name="l00815"></a>00815 <span class="comment"> /**</span>
<a name="l00816"></a>00816 <span class="comment"> If column index (0-based) is in bounds then this</span>
<a name="l00817"></a>00817 <span class="comment"> function assigns tgt to the value of the given</span>
<a name="l00818"></a>00818 <span class="comment"> column index. On success, SQLITE_OK is returned.</span>
<a name="l00819"></a>00819 <span class="comment"> On any other return value, tgt is not modifed.</span>
<a name="l00820"></a>00820 <span class="comment"> */</span>
<a name="l00821"></a>00821 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, <span class="keywordtype">int</span> & tgt );<span class="comment"></span>
<a name="l00822"></a>00822 <span class="comment"> /**</span>
<a name="l00823"></a>00823 <span class="comment"> See get(int,int&).</span>
<a name="l00824"></a>00824 <span class="comment"> */</span>
<a name="l00825"></a>00825 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> & tgt );<span class="comment"></span>
<a name="l00826"></a>00826 <span class="comment"> /**</span>
<a name="l00827"></a>00827 <span class="comment"> See get(int,int&).</span>
<a name="l00828"></a>00828 <span class="comment"> */</span>
<a name="l00829"></a>00829 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, <span class="keywordtype">double</span> & tgt );<span class="comment"></span>
<a name="l00830"></a>00830 <span class="comment"> /**</span>
<a name="l00831"></a>00831 <span class="comment"> See get(int,int&).</span>
<a name="l00832"></a>00832 <span class="comment"> */</span>
<a name="l00833"></a>00833 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, std::string & tgt );<span class="comment"></span>
<a name="l00834"></a>00834 <span class="comment"> /**</span>
<a name="l00835"></a>00835 <span class="comment"> If index (0-based) is in bounds, this function</span>
<a name="l00836"></a>00836 <span class="comment"> gets the (char unsigned const *) data at that</span>
<a name="l00837"></a>00837 <span class="comment"> column index and assigns tgt to that value</span>
<a name="l00838"></a>00838 <span class="comment"> and sz to the size of the data.</span>
<a name="l00839"></a>00839 <span class="comment"></span>
<a name="l00840"></a>00840 <span class="comment"> tgt is written to by this func but ownership</span>
<a name="l00841"></a>00841 <span class="comment"> of the underlying data remains with sqlite.</span>
<a name="l00842"></a>00842 <span class="comment"> That is, the caller does not need to free</span>
<a name="l00843"></a>00843 <span class="comment"> the memory pointed to by tgt, but may need to</span>
<a name="l00844"></a>00844 <span class="comment"> copy it if he wants to use it later.</span>
<a name="l00845"></a>00845 <span class="comment"> */</span>
<a name="l00846"></a>00846 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );<span class="comment"></span>
<a name="l00847"></a>00847 <span class="comment"> /**</span>
<a name="l00848"></a>00848 <span class="comment"> See get(int,char const **, int&). Only the tgt</span>
<a name="l00849"></a>00849 <span class="comment"> type is different.</span>
<a name="l00850"></a>00850 <span class="comment"> */</span>
<a name="l00851"></a>00851 <span class="keywordtype">int</span> <span class="keyword">get</span>( <span class="keywordtype">int</span> index, <span class="keywordtype">void</span> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );
<a name="l00852"></a>00852
<a name="l00853"></a>00853 <span class="comment"></span>
<a name="l00854"></a>00854 <span class="comment"> /**</span>
<a name="l00855"></a>00855 <span class="comment"> This is fundamentally identical to get(int,int &)</span>
<a name="l00856"></a>00856 <span class="comment"> except that the key type is a string, which must</span>
<a name="l00857"></a>00857 <span class="comment"> exactly (case-sensitively) match a column name from</span>
<a name="l00858"></a>00858 <span class="comment"> this result set. On success, SQLITE_OK is returned</span>
<a name="l00859"></a>00859 <span class="comment"> and tgt is modified. On error, some other code is</span>
<a name="l00860"></a>00860 <span class="comment"> returned and tgt is not modified.</span>
<a name="l00861"></a>00861 <span class="comment"></span>
<a name="l00862"></a>00862 <span class="comment"> Note that fetching by string index is much less</span>
<a name="l00863"></a>00863 <span class="comment"> efficient than looking up by integer index, but of</span>
<a name="l00864"></a>00864 <span class="comment"> course also a lot more convenient. If you're</span>
<a name="l00865"></a>00865 <span class="comment"> looking for the most speed, go with</span>
<a name="l00866"></a>00866 <span class="comment"> get(int,...). If you're looking for flexibility and</span>
<a name="l00867"></a>00867 <span class="comment"> convenience, at the cost of a few extra cyles and a</span>
<a name="l00868"></a>00868 <span class="comment"> tiny bit of extra memory usage per cursor, then use</span>
<a name="l00869"></a>00869 <span class="comment"> string-based keys.</span>
<a name="l00870"></a>00870 <span class="comment"> */</span>
<a name="l00871"></a>00871 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, <span class="keywordtype">int</span> & tgt );<span class="comment"></span>
<a name="l00872"></a>00872 <span class="comment"> /**</span>
<a name="l00873"></a>00873 <span class="comment"> See get(std::string const &,int&).</span>
<a name="l00874"></a>00874 <span class="comment"> */</span>
<a name="l00875"></a>00875 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> & tgt );<span class="comment"></span>
<a name="l00876"></a>00876 <span class="comment"> /**</span>
<a name="l00877"></a>00877 <span class="comment"> See get(std::string const &,int&).</span>
<a name="l00878"></a>00878 <span class="comment"> */</span>
<a name="l00879"></a>00879 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, <span class="keywordtype">double</span> & tgt );<span class="comment"></span>
<a name="l00880"></a>00880 <span class="comment"> /**</span>
<a name="l00881"></a>00881 <span class="comment"> See get(std::string const &,int&).</span>
<a name="l00882"></a>00882 <span class="comment"> */</span>
<a name="l00883"></a>00883 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, std::string & tgt );<span class="comment"></span>
<a name="l00884"></a>00884 <span class="comment"> /**</span>
<a name="l00885"></a>00885 <span class="comment"> If indexis in bounds, this function gets the (char</span>
<a name="l00886"></a>00886 <span class="comment"> unsigned const *) data at that column index and</span>
<a name="l00887"></a>00887 <span class="comment"> assigns tgt to that value and sz to the size of the</span>
<a name="l00888"></a>00888 <span class="comment"> data.</span>
<a name="l00889"></a>00889 <span class="comment"></span>
<a name="l00890"></a>00890 <span class="comment"> tgt is written to by this func but ownership</span>
<a name="l00891"></a>00891 <span class="comment"> of the underlying data remains with sqlite.</span>
<a name="l00892"></a>00892 <span class="comment"> That is, the caller does not need to free</span>
<a name="l00893"></a>00893 <span class="comment"> the memory pointed to by tgt, but may need to</span>
<a name="l00894"></a>00894 <span class="comment"> copy it if he wants to use it later.</span>
<a name="l00895"></a>00895 <span class="comment"> */</span>
<a name="l00896"></a>00896 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );<span class="comment"></span>
<a name="l00897"></a>00897 <span class="comment"> /**</span>
<a name="l00898"></a>00898 <span class="comment"> See get(std::string const &,char const **, int&). Only the tgt</span>
<a name="l00899"></a>00899 <span class="comment"> type is different.</span>
<a name="l00900"></a>00900 <span class="comment"> */</span>
<a name="l00901"></a>00901 <span class="keywordtype">int</span> <span class="keyword">get</span>( std::string <span class="keyword">const</span> & key, <span class="keywordtype">void</span> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & sz );
<a name="l00902"></a>00902
<a name="l00903"></a>00903 <span class="comment"></span>
<a name="l00904"></a>00904 <span class="comment"> /**</span>
<a name="l00905"></a>00905 <span class="comment"> Sets str to the column name as the given index</span>
<a name="l00906"></a>00906 <span class="comment"> (0-based). Returns SQLITE_OK on success, else</span>
<a name="l00907"></a>00907 <span class="comment"> SQLITE_ERROR and str is not modified.</span>
<a name="l00908"></a>00908 <span class="comment"> */</span>
<a name="l00909"></a>00909 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#afb920de1da87ee657a29fa7165ba4859" title="Sets str to the column name as the given index (0-based).">colname</a>( <span class="keywordtype">int</span> index, std::string & str );<span class="comment"></span>
<a name="l00910"></a>00910 <span class="comment"> /**</span>
<a name="l00911"></a>00911 <span class="comment"> Points str to the nul-terminated column name at the</span>
<a name="l00912"></a>00912 <span class="comment"> given index (0-based), or 0 on error. This</span>
<a name="l00913"></a>00913 <span class="comment"> overload avoids an extra copy of the column name,</span>
<a name="l00914"></a>00914 <span class="comment"> but sqlite owns the string and clients will need to</span>
<a name="l00915"></a>00915 <span class="comment"> make a copy of it if they want to continue to use</span>
<a name="l00916"></a>00916 <span class="comment"> it beyond the lifetime of this object's underlying</span>
<a name="l00917"></a>00917 <span class="comment"> prepared statement.</span>
<a name="l00918"></a>00918 <span class="comment"></span>
<a name="l00919"></a>00919 <span class="comment"> Returns SQLITE_OK if str is set, otherwise</span>
<a name="l00920"></a>00920 <span class="comment"> SQLITE_ERROR.</span>
<a name="l00921"></a>00921 <span class="comment"> */</span>
<a name="l00922"></a>00922 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1cursor.html#afb920de1da87ee657a29fa7165ba4859" title="Sets str to the column name as the given index (0-based).">colname</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">char</span> <span class="keyword">const</span> ** str );
<a name="l00923"></a>00923 <span class="comment">//int colname( int index, std::wstring & );</span>
<a name="l00924"></a>00924 };
<a name="l00925"></a>00925
<a name="l00926"></a>00926 <span class="comment"></span>
<a name="l00927"></a>00927 <span class="comment"> /**</span>
<a name="l00928"></a>00928 <span class="comment"> This class represents a prepared database statement.</span>
<a name="l00929"></a>00929 <span class="comment"></span>
<a name="l00930"></a>00930 <span class="comment"> statement objects are copied shallowly - each copy points</span>
<a name="l00931"></a>00931 <span class="comment"> back to a single original sqlite3_stmt object. That sqlite3_stmt</span>
<a name="l00932"></a><a class="code" href="classsq3_1_1statement.html">00932</a> <span class="comment"> is finalized with the last of these copies goes out of scope</span>
<a name="l00933"></a>00933 <span class="comment"> or is finalized.</span>
<a name="l00934"></a>00934 <span class="comment"></span>
<a name="l00935"></a>00935 <span class="comment"> Sample usage:</span>
<a name="l00936"></a>00936 <span class="comment">\code</span>
<a name="l00937"></a>00937 <span class="comment"> // Reading data:</span>
<a name="l00938"></a>00938 <span class="comment"> statement st(mydb, "select * from sqlite_master");</span>
<a name="l00939"></a>00939 <span class="comment"> if( ! st.is_prepared() )</span>
<a name="l00940"></a>00940 <span class="comment"> {</span>
<a name="l00941"></a>00941 <span class="comment"> ... error ...</span>
<a name="l00942"></a>00942 <span class="comment"> }</span>
<a name="l00943"></a>00943 <span class="comment"> cursor cur( st.get_cursor() );</span>
<a name="l00944"></a>00944 <span class="comment"> while( SQLITE_ROW == cur.step() )</span>
<a name="l00945"></a>00945 <span class="comment"> {</span>
<a name="l00946"></a>00946 <span class="comment"> ... do something with each row ...</span>
<a name="l00947"></a>00947 <span class="comment"> }</span>
<a name="l00948"></a>00948 <span class="comment"></span>
<a name="l00949"></a>00949 <span class="comment"></span>
<a name="l00950"></a>00950 <span class="comment"> // Or:</span>
<a name="l00951"></a>00951 <span class="comment"> statement st(mydb, "select count(*) from mytable" );</span>
<a name="l00952"></a>00952 <span class="comment"> int val = 0;</span>
<a name="l00953"></a>00953 <span class="comment"> int rc = st.execute( val );</span>
<a name="l00954"></a>00954 <span class="comment"> if( ! rc_is_okay( rc ) ) { ... error ... }</span>
<a name="l00955"></a>00955 <span class="comment"> std::cout << "count(*) == " << val << '\n';</span>
<a name="l00956"></a>00956 <span class="comment"></span>
<a name="l00957"></a>00957 <span class="comment"> // Writing data:</span>
<a name="l00958"></a>00958 <span class="comment"> statement st( mydb, "insert into mytable values(?,?)" );</span>
<a name="l00959"></a>00959 <span class="comment"> st.bind( 1, "a value" );</span>
<a name="l00960"></a>00960 <span class="comment"> st.bind( 2, someIntValue );</span>
<a name="l00961"></a>00961 <span class="comment"> int rc = st.execute();</span>
<a name="l00962"></a>00962 <span class="comment"> if( ! rc_is_okay( rc ) ) { ... error ... }</span>
<a name="l00963"></a>00963 <span class="comment"></span>
<a name="l00964"></a>00964 <span class="comment">\endcode</span>
<a name="l00965"></a>00965 <span class="comment"></span>
<a name="l00966"></a>00966 <span class="comment"></span>
<a name="l00967"></a>00967 <span class="comment"> Note about copying: copying a statement object produces a</span>
<a name="l00968"></a>00968 <span class="comment"> shallow copy. All copies of this type will refer to the</span>
<a name="l00969"></a>00969 <span class="comment"> same underlying (sqlite3_stmt*) handle. The handle will be</span>
<a name="l00970"></a>00970 <span class="comment"> closed when the last instance of this class which points to</span>
<a name="l00971"></a>00971 <span class="comment"> that statement goes out of scope or is finalized.</span>
<a name="l00972"></a>00972 <span class="comment"> */</span>
<a name="l00973"></a>00973 <span class="keyword">class </span><a class="code" href="classsq3_1_1statement.html" title="This class represents a prepared database statement.">statement</a>
<a name="l00974"></a>00974 {
<a name="l00975"></a>00975 <span class="keyword">private</span>:
<a name="l00976"></a>00976 <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & m_db;
<a name="l00977"></a>00977 <a class="code" href="classrefcount_1_1rcptr.html">refcount::rcptr<sqlite3_stmt,sqlite3_stmt_finalizer></a> m_stmt;
<a name="l00978"></a>00978 <span class="keywordtype">int</span> m_argc;
<a name="l00979"></a>00979 <span class="keyword">friend</span> <span class="keyword">class </span><a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a>;
<a name="l00980"></a>00980 <span class="keyword">public</span>:<span class="comment"></span>
<a name="l00981"></a>00981 <span class="comment"> /**</span>
<a name="l00982"></a>00982 <span class="comment"> Initializes a prepared statement without a</span>
<a name="l00983"></a>00983 <span class="comment"> query. Use prepare() to prepare the statement.</span>
<a name="l00984"></a>00984 <span class="comment"> */</span>
<a name="l00985"></a>00985 <a class="code" href="classsq3_1_1statement.html#ad0d64808c79092f3973663cf64285a90" title="Initializes a prepared statement without a query.">statement</a>( <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & db );
<a name="l00986"></a>00986 <span class="comment"></span>
<a name="l00987"></a>00987 <span class="comment"> /**</span>
<a name="l00988"></a>00988 <span class="comment"> Initializes a statement with the given sql.</span>
<a name="l00989"></a>00989 <span class="comment"> Use is_prepared() to determine if the sql compiled</span>
<a name="l00990"></a>00990 <span class="comment"> successfully.</span>
<a name="l00991"></a>00991 <span class="comment"> */</span>
<a name="l00992"></a>00992 <a class="code" href="classsq3_1_1statement.html#ad0d64808c79092f3973663cf64285a90" title="Initializes a prepared statement without a query.">statement</a>( <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & db, std::string <span class="keyword">const</span> & sql );<span class="comment"></span>
<a name="l00993"></a>00993 <span class="comment"> /**</span>
<a name="l00994"></a>00994 <span class="comment"> Initializes a statement with the given sql.</span>
<a name="l00995"></a>00995 <span class="comment"> Use is_prepared() to determine if the sql compiled</span>
<a name="l00996"></a>00996 <span class="comment"> successfully. byteCount is the length of sql, in bytes.</span>
<a name="l00997"></a>00997 <span class="comment"> If set to -1 then strlen() is used to determine the size</span>
<a name="l00998"></a>00998 <span class="comment"> of sql.</span>
<a name="l00999"></a>00999 <span class="comment"> */</span>
<a name="l01000"></a>01000 <a class="code" href="classsq3_1_1statement.html#ad0d64808c79092f3973663cf64285a90" title="Initializes a prepared statement without a query.">statement</a>( <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & db, <span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <span class="keywordtype">int</span> byteCount = -1 );
<a name="l01001"></a>01001 <span class="comment"></span>
<a name="l01002"></a>01002 <span class="comment"> /**</span>
<a name="l01003"></a>01003 <span class="comment"> Calls this->finalize()</span>
<a name="l01004"></a>01004 <span class="comment"> */</span>
<a name="l01005"></a>01005 <a class="code" href="classsq3_1_1statement.html#a4707efaac820b250b2bb3bf38c008c32" title="Calls this-&gt;finalize().">~statement</a>();
<a name="l01006"></a>01006 <span class="comment"></span>
<a name="l01007"></a>01007 <span class="comment"> /**</span>
<a name="l01008"></a>01008 <span class="comment"> (Re-)prepares an SQL statement. Return code is that</span>
<a name="l01009"></a>01009 <span class="comment"> of sqlite3_prepare(). If any value other than</span>
<a name="l01010"></a>01010 <span class="comment"> SQLITE_OK is returned then preparation failed and</span>
<a name="l01011"></a>01011 <span class="comment"> this object is not ready to be used.</span>
<a name="l01012"></a>01012 <span class="comment"> */</span>
<a name="l01013"></a>01013 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a5926de0822117564de1efc0bf9dbfe15" title="(Re-)prepares an SQL statement.">prepare</a>( std::string <span class="keyword">const</span> & sql );<span class="comment"></span>
<a name="l01014"></a>01014 <span class="comment"> /**</span>
<a name="l01015"></a>01015 <span class="comment"> Same as prepare(std::string) but the len parameter</span>
<a name="l01016"></a>01016 <span class="comment"> specifies the length of sql. If byteCount is -1 then</span>
<a name="l01017"></a>01017 <span class="comment"> strlen(sql) is used to find the length.</span>
<a name="l01018"></a>01018 <span class="comment"> */</span>
<a name="l01019"></a>01019 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a5926de0822117564de1efc0bf9dbfe15" title="(Re-)prepares an SQL statement.">prepare</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * sql, <span class="keywordtype">int</span> byteCount = -1 );
<a name="l01020"></a>01020
<a name="l01021"></a>01021 <span class="preprocessor">#if SQ3_USE_WCHAR</span>
<a name="l01022"></a>01022 <span class="preprocessor"></span> <span class="comment">//statement( database & db, std::wstring const & sql );</span>
<a name="l01023"></a>01023 <a class="code" href="classsq3_1_1statement.html#ad0d64808c79092f3973663cf64285a90" title="Initializes a prepared statement without a query.">statement</a>( <a class="code" href="classsq3_1_1database.html" title="Encapsulates a connection to an sqlite database.">database</a> & db, <span class="keywordtype">wchar_t</span> <span class="keyword">const</span> * sql, <span class="keywordtype">int</span> byteCount = -1 );<span class="comment"></span>
<a name="l01024"></a>01024 <span class="comment"> /**</span>
<a name="l01025"></a>01025 <span class="comment"> */</span>
<a name="l01026"></a>01026 <span class="comment">//int prepare( std::wstring const & sql );</span><span class="comment"></span>
<a name="l01027"></a>01027 <span class="comment"> /**</span>
<a name="l01028"></a>01028 <span class="comment"> */</span>
<a name="l01029"></a>01029 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a5926de0822117564de1efc0bf9dbfe15" title="(Re-)prepares an SQL statement.">prepare</a>( sqlite3_wstring_t <span class="keyword">const</span> sql, <span class="keywordtype">int</span> byteCount = -1 );
<a name="l01030"></a>01030 <span class="comment">//int execute( wchar_t * tgt, int & len );</span>
<a name="l01031"></a>01031 <span class="comment">//int execute( std::wchar & tgt );</span>
<a name="l01032"></a>01032 <span class="comment">//int bind( int index, wchar_t const * data, int len );</span>
<a name="l01033"></a>01033 <span class="comment">//int bind( int index, std::wstring const & data );</span>
<a name="l01034"></a>01034 <span class="preprocessor">#endif // SQ3_USE_WCHAR</span>
<a name="l01035"></a>01035 <span class="preprocessor"></span><span class="comment"></span>
<a name="l01036"></a>01036 <span class="comment"> /**</span>
<a name="l01037"></a>01037 <span class="comment"> Binds NULL to the given placeholder index (1-based,</span>
<a name="l01038"></a>01038 <span class="comment"> not 0-based!).</span>
<a name="l01039"></a>01039 <span class="comment"></span>
<a name="l01040"></a>01040 <span class="comment"> Placeholders are added to SQL code with question</span>
<a name="l01041"></a>01041 <span class="comment"> marks, like this:</span>
<a name="l01042"></a>01042 <span class="comment"></span>
<a name="l01043"></a>01043 <span class="comment"> \code</span>
<a name="l01044"></a>01044 <span class="comment"> INSERT INTO MyTable(a,b) VALUES(?,?);</span>
<a name="l01045"></a>01045 <span class="comment"> \endcode</span>
<a name="l01046"></a>01046 <span class="comment"></span>
<a name="l01047"></a>01047 <span class="comment"> In this case we have two placeholders at indexes 1</span>
<a name="l01048"></a>01048 <span class="comment"> and 2.</span>
<a name="l01049"></a>01049 <span class="comment"></span>
<a name="l01050"></a>01050 <span class="comment"> Note that all bind()-related indexes are 1-based,</span>
<a name="l01051"></a>01051 <span class="comment"> but cursor::get() uses 0-based indexes. This</span>
<a name="l01052"></a>01052 <span class="comment"> inconsistency is an artefact of the sqlite3 API</span>
<a name="l01053"></a>01053 <span class="comment"> (and may even have a longer history).</span>
<a name="l01054"></a>01054 <span class="comment"> */</span>
<a name="l01055"></a>01055 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index );<span class="comment"></span>
<a name="l01056"></a>01056 <span class="comment"> /**</span>
<a name="l01057"></a>01057 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01058"></a>01058 <span class="comment"> not 0-based!).</span>
<a name="l01059"></a>01059 <span class="comment"> */</span>
<a name="l01060"></a>01060 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">int</span> data );<span class="comment"></span>
<a name="l01061"></a>01061 <span class="comment"> /**</span>
<a name="l01062"></a>01062 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01063"></a>01063 <span class="comment"> not 0-based!).</span>
<a name="l01064"></a>01064 <span class="comment"> */</span>
<a name="l01065"></a>01065 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> data );<span class="comment"></span>
<a name="l01066"></a>01066 <span class="comment"> /**</span>
<a name="l01067"></a>01067 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01068"></a>01068 <span class="comment"> not 0-based!).</span>
<a name="l01069"></a>01069 <span class="comment"> */</span>
<a name="l01070"></a>01070 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">double</span> data );<span class="comment"></span>
<a name="l01071"></a>01071 <span class="comment"> /**</span>
<a name="l01072"></a>01072 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01073"></a>01073 <span class="comment"> not 0-based!). len must be the length of data, in bytes.</span>
<a name="l01074"></a>01074 <span class="comment"> */</span>
<a name="l01075"></a>01075 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">char</span> <span class="keyword">const</span> * data, <span class="keywordtype">int</span> len );<span class="comment"></span>
<a name="l01076"></a>01076 <span class="comment"> /**</span>
<a name="l01077"></a>01077 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01078"></a>01078 <span class="comment"> not 0-based!). len must be the length of data, in bytes.</span>
<a name="l01079"></a>01079 <span class="comment"> */</span>
<a name="l01080"></a>01080 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">void</span> <span class="keyword">const</span> * data, <span class="keywordtype">int</span> len );
<a name="l01081"></a>01081 <span class="comment"></span>
<a name="l01082"></a>01082 <span class="comment"> /**</span>
<a name="l01083"></a>01083 <span class="comment"> Binds data to the given placeholder index (1-based,</span>
<a name="l01084"></a>01084 <span class="comment"> not 0-based!).</span>
<a name="l01085"></a>01085 <span class="comment"> */</span>
<a name="l01086"></a>01086 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">int</span> index, std::string <span class="keyword">const</span> & data );
<a name="l01087"></a>01087 <span class="comment"></span>
<a name="l01088"></a>01088 <span class="comment"> /**</span>
<a name="l01089"></a>01089 <span class="comment"> Binds NULL to the given placeholder index. Note</span>
<a name="l01090"></a>01090 <span class="comment"> that binding by string index is notably less</span>
<a name="l01091"></a>01091 <span class="comment"> efficient than binding by integer index.</span>
<a name="l01092"></a>01092 <span class="comment"></span>
<a name="l01093"></a>01093 <span class="comment"> Named placeholders are embedded in SQL similar</span>
<a name="l01094"></a>01094 <span class="comment"> to:</span>
<a name="l01095"></a>01095 <span class="comment"></span>
<a name="l01096"></a>01096 <span class="comment"> \code</span>
<a name="l01097"></a>01097 <span class="comment"> INSERT INTO MyTable (a,b) VALUES(:A,:B);</span>
<a name="l01098"></a>01098 <span class="comment"> \endcode</span>
<a name="l01099"></a>01099 <span class="comment"></span>
<a name="l01100"></a>01100 <span class="comment"> In that string we have two named bound arguments:</span>
<a name="l01101"></a>01101 <span class="comment"> ":A" and ":B", at indexes 1 and 2, respectively.</span>
<a name="l01102"></a>01102 <span class="comment"> Note that the leading colon is considered to be part</span>
<a name="l01103"></a>01103 <span class="comment"> of the name.</span>
<a name="l01104"></a>01104 <span class="comment"> */</span>
<a name="l01105"></a>01105 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index );<span class="comment"></span>
<a name="l01106"></a>01106 <span class="comment"> /**</span>
<a name="l01107"></a>01107 <span class="comment"> Binds data to the given placeholder index. See</span>
<a name="l01108"></a>01108 <span class="comment"> bind(char const *) for more info.</span>
<a name="l01109"></a>01109 <span class="comment"> */</span>
<a name="l01110"></a>01110 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, <span class="keywordtype">int</span> data );<span class="comment"></span>
<a name="l01111"></a>01111 <span class="comment"> /**</span>
<a name="l01112"></a>01112 <span class="comment"> Binds data to the given placeholder index. See</span>
<a name="l01113"></a>01113 <span class="comment"> bind(char const *) for more info.</span>
<a name="l01114"></a>01114 <span class="comment"> */</span>
<a name="l01115"></a>01115 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> data );<span class="comment"></span>
<a name="l01116"></a>01116 <span class="comment"> /**</span>
<a name="l01117"></a>01117 <span class="comment"> Binds data to the given placeholder index. See</span>
<a name="l01118"></a>01118 <span class="comment"> bind(char const *) for more info.</span>
<a name="l01119"></a>01119 <span class="comment"> */</span>
<a name="l01120"></a>01120 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, <span class="keywordtype">double</span> data );<span class="comment"></span>
<a name="l01121"></a>01121 <span class="comment"> /**</span>
<a name="l01122"></a>01122 <span class="comment"> Binds data to the given placeholder index. len must</span>
<a name="l01123"></a>01123 <span class="comment"> be the length of data, in bytes. See</span>
<a name="l01124"></a>01124 <span class="comment"> bind(char const *) for more info.</span>
<a name="l01125"></a>01125 <span class="comment"> */</span>
<a name="l01126"></a>01126 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, <span class="keywordtype">char</span> <span class="keyword">const</span> * data, <span class="keywordtype">int</span> len );<span class="comment"></span>
<a name="l01127"></a>01127 <span class="comment"> /**</span>
<a name="l01128"></a>01128 <span class="comment"> Binds data to the given placeholder index. len must</span>
<a name="l01129"></a>01129 <span class="comment"> be the length of data, in bytes. See bind(char</span>
<a name="l01130"></a>01130 <span class="comment"> const *) for more info.</span>
<a name="l01131"></a>01131 <span class="comment"> */</span>
<a name="l01132"></a>01132 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, <span class="keywordtype">void</span> <span class="keyword">const</span> * data, <span class="keywordtype">int</span> len );
<a name="l01133"></a>01133 <span class="comment"></span>
<a name="l01134"></a>01134 <span class="comment"> /**</span>
<a name="l01135"></a>01135 <span class="comment"> Binds data to the given placeholder index. See</span>
<a name="l01136"></a>01136 <span class="comment"> bind(char const *) for more info.</span>
<a name="l01137"></a>01137 <span class="comment"> */</span>
<a name="l01138"></a>01138 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a46f848c8167a24d86e79f8c76ab26e52" title="Binds NULL to the given placeholder index (1-based, not 0-based!).">bind</a>( <span class="keywordtype">char</span> <span class="keyword">const</span> * index, std::string <span class="keyword">const</span> & data );
<a name="l01139"></a>01139 <span class="comment"></span>
<a name="l01140"></a>01140 <span class="comment"> /**</span>
<a name="l01141"></a>01141 <span class="comment"> Returns a cursor object ready to step over</span>
<a name="l01142"></a>01142 <span class="comment"> the result set from this object.</span>
<a name="l01143"></a>01143 <span class="comment"></span>
<a name="l01144"></a>01144 <span class="comment"> Note that due to low-level design details, it is</span>
<a name="l01145"></a>01145 <span class="comment"> unwise to mix the execute() functions and</span>
<a name="l01146"></a>01146 <span class="comment"> get_cursor() on the same statement. All cursors</span>
<a name="l01147"></a>01147 <span class="comment"> created from this statement (and all copies of</span>
<a name="l01148"></a>01148 <span class="comment"> those cursors) relate back to *this* statement</span>
<a name="l01149"></a>01149 <span class="comment"> object and when the last cursor goes out of scope</span>
<a name="l01150"></a>01150 <span class="comment"> the underlying prepared statement is</span>
<a name="l01151"></a>01151 <span class="comment"> reset. Additionally, the execute() family of</span>
<a name="l01152"></a>01152 <span class="comment"> functions are all actually implemented in terms of</span>
<a name="l01153"></a>01153 <span class="comment"> get_cursor(). Mis-interactions between a mixture of</span>
<a name="l01154"></a>01154 <span class="comment"> get_cursor() and execute() on the same client-side</span>
<a name="l01155"></a>01155 <span class="comment"> statement object cannot be ruled out.</span>
<a name="l01156"></a>01156 <span class="comment"></span>
<a name="l01157"></a>01157 <span class="comment"> See the ~cursor destructor for more details.</span>
<a name="l01158"></a>01158 <span class="comment"> */</span>
<a name="l01159"></a>01159 <a class="code" href="classsq3_1_1cursor.html" title="This type is for stepping through a db query result.">cursor</a> <a class="code" href="classsq3_1_1statement.html#a0fddc7388f7713d15d4bfe8451ca5971" title="Returns a cursor object ready to step over the result set from this object.">get_cursor</a>();
<a name="l01160"></a>01160 <span class="comment"></span>
<a name="l01161"></a>01161 <span class="comment"> /**</span>
<a name="l01162"></a>01162 <span class="comment"> Assumes this object's SQL statement is a single</span>
<a name="l01163"></a>01163 <span class="comment"> statement. Executes that statement and returns the</span>
<a name="l01164"></a>01164 <span class="comment"> value from an underlying sqlite3_step() call. Thus</span>
<a name="l01165"></a>01165 <span class="comment"> SQLITE_ROW or SQLITE_DONE will be returned on</span>
<a name="l01166"></a>01166 <span class="comment"> success, depending on the underlying query.</span>
<a name="l01167"></a>01167 <span class="comment"> */</span>
<a name="l01168"></a>01168 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>();
<a name="l01169"></a>01169 <span class="comment"></span>
<a name="l01170"></a>01170 <span class="comment"> /**</span>
<a name="l01171"></a>01171 <span class="comment"> Executes this statement and saves the return value</span>
<a name="l01172"></a>01172 <span class="comment"> of that statement in tgt. If this function returns</span>
<a name="l01173"></a>01173 <span class="comment"> any other value than SQLITE_OK then tgt is not</span>
<a name="l01174"></a>01174 <span class="comment"> modified. Note that the value of this object's</span>
<a name="l01175"></a>01175 <span class="comment"> first field must be lexically convertible to tgt's</span>
<a name="l01176"></a>01176 <span class="comment"> type or else tgt will be set to some unspecified</span>
<a name="l01177"></a>01177 <span class="comment"> value.</span>
<a name="l01178"></a>01178 <span class="comment"> */</span>
<a name="l01179"></a>01179 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( <span class="keywordtype">int</span> & tgt );
<a name="l01180"></a>01180 <span class="comment"></span>
<a name="l01181"></a>01181 <span class="comment"> /** See execute(int&). */</span>
<a name="l01182"></a>01182 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( <a class="code" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba" title="The type used for signed 64-bit integer operations.">int64_t</a> & tgt );
<a name="l01183"></a>01183 <span class="comment"></span>
<a name="l01184"></a>01184 <span class="comment"> /** See execute(int&). */</span>
<a name="l01185"></a>01185 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( <span class="keywordtype">double</span> & tgt );
<a name="l01186"></a>01186 <span class="comment"></span>
<a name="l01187"></a>01187 <span class="comment"> /** See execute(int&). */</span>
<a name="l01188"></a>01188 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( std::string & tgt );
<a name="l01189"></a>01189 <span class="comment"></span>
<a name="l01190"></a>01190 <span class="comment"> /**</span>
<a name="l01191"></a>01191 <span class="comment"> See execute(int&). The length of the "returned"</span>
<a name="l01192"></a>01192 <span class="comment"> string is saved in len (in bytes). Ownership of the</span>
<a name="l01193"></a>01193 <span class="comment"> string remains with sqlite3, and the client should</span>
<a name="l01194"></a>01194 <span class="comment"> copy it if he wants to ensure that he has it for</span>
<a name="l01195"></a>01195 <span class="comment"> later. The string's exact lifetime is unspecified</span>
<a name="l01196"></a>01196 <span class="comment"> in the sqlite3 documentation, but in theory it is</span>
<a name="l01197"></a>01197 <span class="comment"> valid until this statement object is finalized or</span>
<a name="l01198"></a>01198 <span class="comment"> a cursor object steps through the result set of this</span>
<a name="l01199"></a>01199 <span class="comment"> statement.</span>
<a name="l01200"></a>01200 <span class="comment"> */</span>
<a name="l01201"></a>01201 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( <a class="code" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f" title="The published result codes from the sqlite3 API.">sqlite3_text_char_t</a> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & len );
<a name="l01202"></a>01202 <span class="comment"></span>
<a name="l01203"></a>01203 <span class="comment"> /**</span>
<a name="l01204"></a>01204 <span class="comment"> See execute(sqlite3_text_char_t const</span>
<a name="l01205"></a>01205 <span class="comment"> **,int&). This is similar but is used to fetch blob</span>
<a name="l01206"></a>01206 <span class="comment"> data. The blob is "returned" by passinging tgt to</span>
<a name="l01207"></a>01207 <span class="comment"> it. The length of the blob (in bytes) is saved in</span>
<a name="l01208"></a>01208 <span class="comment"> len. Ownership of the blob data remains with</span>
<a name="l01209"></a>01209 <span class="comment"> sqlite3, and the client should copy it if he wants</span>
<a name="l01210"></a>01210 <span class="comment"> to ensure that he has it for later. The blob's</span>
<a name="l01211"></a>01211 <span class="comment"> exact lifetime is unspecified in the sqlite3</span>
<a name="l01212"></a>01212 <span class="comment"> documentation, but in theory it is</span>
<a name="l01213"></a>01213 <span class="comment"> valid until this statement object is finalized or</span>
<a name="l01214"></a>01214 <span class="comment"> a cursor object steps through the result set of this</span>
<a name="l01215"></a>01215 <span class="comment"> statement.</span>
<a name="l01216"></a>01216 <span class="comment"> */</span>
<a name="l01217"></a>01217 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab3bc7d1e366f0743720dd67d6d953ed0" title="Assumes this object&#39;s SQL statement is a single statement.">execute</a>( <span class="keywordtype">void</span> <span class="keyword">const</span> ** tgt, <span class="keywordtype">int</span> & len );
<a name="l01218"></a>01218 <span class="comment"></span>
<a name="l01219"></a>01219 <span class="comment"> /**</span>
<a name="l01220"></a>01220 <span class="comment"> Finizalizes the underlying prepared statement,</span>
<a name="l01221"></a>01221 <span class="comment"> freeing its resources. Any cursor objects created</span>
<a name="l01222"></a>01222 <span class="comment"> through this->get_cursor() now points to stale</span>
<a name="l01223"></a>01223 <span class="comment"> data and must not be used.</span>
<a name="l01224"></a>01224 <span class="comment"></span>
<a name="l01225"></a>01225 <span class="comment"> Return value is the result of calling sqlite3_finalize(),</span>
<a name="l01226"></a>01226 <span class="comment"> or SQLITE_ERROR if finalization cannot take place (e.g.</span>
<a name="l01227"></a>01227 <span class="comment"> finalize() was already called).</span>
<a name="l01228"></a>01228 <span class="comment"> */</span>
<a name="l01229"></a>01229 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ab5c77d11b7f3c7cc5bd73cf8a8a1842e" title="Finizalizes the underlying prepared statement, freeing its resources.">finalize</a>();
<a name="l01230"></a>01230 <span class="comment"></span>
<a name="l01231"></a>01231 <span class="comment"> /**</span>
<a name="l01232"></a>01232 <span class="comment"> Use after construction to ensure that a statement</span>
<a name="l01233"></a>01233 <span class="comment"> was compiled. Returns true if the statement was</span>
<a name="l01234"></a>01234 <span class="comment"> compiled, else false. Returning false typically</span>
<a name="l01235"></a>01235 <span class="comment"> means that the supplied SQL has a syntax error,</span>
<a name="l01236"></a>01236 <span class="comment"> refers to non-existing fields, etc.</span>
<a name="l01237"></a>01237 <span class="comment"> */</span>
<a name="l01238"></a>01238 <span class="keywordtype">bool</span> <a class="code" href="classsq3_1_1statement.html#abce97e649b635a8cd8b6bebee657f3be" title="Use after construction to ensure that a statement was compiled.">is_prepared</a>() <span class="keyword">const</span>;
<a name="l01239"></a>01239 <span class="comment"></span>
<a name="l01240"></a>01240 <span class="comment"> /**</span>
<a name="l01241"></a>01241 <span class="comment"> Calls sqlite3_reset() on the underlying statement</span>
<a name="l01242"></a>01242 <span class="comment"> handle and returns the result.</span>
<a name="l01243"></a>01243 <span class="comment"> */</span>
<a name="l01244"></a>01244 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#ae0270423dc9bf151b5a57bfd42da2efb" title="Calls sqlite3_reset() on the underlying statement handle and returns the result.">reset</a>();
<a name="l01245"></a>01245 <span class="comment"></span>
<a name="l01246"></a>01246 <span class="comment"> /** Returns the column count of this prepared</span>
<a name="l01247"></a>01247 <span class="comment"> statement, or -1 on error. May return 0 for</span>
<a name="l01248"></a>01248 <span class="comment"> queries which has no return value (e.g. UPDATE).</span>
<a name="l01249"></a>01249 <span class="comment"> */</span>
<a name="l01250"></a>01250 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a2f917c5d299bc269db65dbf66137f140" title="Returns the column count of this prepared statement, or -1 on error.">colcount</a>();
<a name="l01251"></a>01251 <span class="comment"></span>
<a name="l01252"></a>01252 <span class="comment"> /**</span>
<a name="l01253"></a>01253 <span class="comment"> On success, it returns the null-terminated column</span>
<a name="l01254"></a>01254 <span class="comment"> name of the given column. On error it returns</span>
<a name="l01255"></a>01255 <span class="comment"> 0. The returned string is owned by sqlite3 and is</span>
<a name="l01256"></a>01256 <span class="comment"> not guaranteed to be valid longer than the lifetime</span>
<a name="l01257"></a>01257 <span class="comment"> of this statement, so copy it if you need it.</span>
<a name="l01258"></a>01258 <span class="comment"> */</span>
<a name="l01259"></a>01259 <span class="keywordtype">char</span> <span class="keyword">const</span> * <a class="code" href="classsq3_1_1statement.html#a9afbafab262574f41b71dd1fa7988713" title="On success, it returns the null-terminated column name of the given column.">colname</a>( <span class="keywordtype">int</span> index );
<a name="l01260"></a>01260 <span class="comment"></span>
<a name="l01261"></a>01261 <span class="comment"> /**</span>
<a name="l01262"></a>01262 <span class="comment"> On success, assigns cn to the null-terminated column</span>
<a name="l01263"></a>01263 <span class="comment"> name at the given index and returns SQLITE_OK. On</span>
<a name="l01264"></a>01264 <span class="comment"> failure cn is not modified and some other value is</span>
<a name="l01265"></a>01265 <span class="comment"> returned. The column name string is not guaranteed</span>
<a name="l01266"></a>01266 <span class="comment"> to be valid longer than this preparation of this</span>
<a name="l01267"></a>01267 <span class="comment"> statement object, so copy it immediately if you will</span>
<a name="l01268"></a>01268 <span class="comment"> need it later.</span>
<a name="l01269"></a>01269 <span class="comment"> */</span>
<a name="l01270"></a>01270 <span class="keywordtype">int</span> <a class="code" href="classsq3_1_1statement.html#a9afbafab262574f41b71dd1fa7988713" title="On success, it returns the null-terminated column name of the given column.">colname</a>( <span class="keywordtype">int</span> index, <span class="keywordtype">char</span> <span class="keyword">const</span> ** cn );
<a name="l01271"></a>01271
<a name="l01272"></a>01272 };
<a name="l01273"></a>01273
<a name="l01274"></a>01274 } <span class="comment">// namespace sq3</span>
<a name="l01275"></a>01275
<a name="l01276"></a>01276
<a name="l01277"></a>01277 <span class="preprocessor">#endif // s11n_net_SQ3_HPP_INCLUDED</span>
</pre></div></div>
<hr class="footer"/><address style="text-align: right;"><small>Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2-20100208 </small></address>
</body>
</html>
