Debian Codegraph @

www/c3ref/preupdate_blobwrite.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>The pre-update hook.</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_preupdate_blobwrite sqlite3_preupdate_count sqlite3_preupdate_depth sqlite3_preupdate_hook sqlite3_preupdate_new sqlite3_preupdate_old -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>The pre-update hook.</h2>
122 </div>
123 <blockquote><pre>
124 #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
125 void *sqlite3_preupdate_hook(
126 sqlite3 *db,
127 void(*xPreUpdate)(
128 void *pCtx, /* Copy of third arg to preupdate_hook() */
129 sqlite3 *db, /* Database handle */
130 int op, /* SQLITE_UPDATE, DELETE or INSERT */
131 char const *zDb, /* Database name */
132 char const *zName, /* Table name */
133 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
134 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
135 ),
136 void*
137 );
138 int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
139 int sqlite3_preupdate_count(sqlite3 *);
140 int sqlite3_preupdate_depth(sqlite3 *);
141 int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
142 int sqlite3_preupdate_blobwrite(sqlite3 *);
143 #endif
144 </pre></blockquote>
145 <p>
146 These interfaces are only available if SQLite is compiled using the
147 <a href="../compile.html#enable_preupdate_hook">SQLITE_ENABLE_PREUPDATE_HOOK</a> compile-time option.</p>
148
149 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_hook()</a> interface registers a callback function
150 that is invoked prior to each <a href="../lang_insert.html">INSERT</a>, <a href="../lang_update.html">UPDATE</a>, and <a href="../lang_delete.html">DELETE</a> operation
151 on a database table.
152 At most one preupdate hook may be registered at a time on a single
153 <a href="../c3ref/sqlite3.html">database connection</a>; each call to <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_hook()</a> overrides
154 the previous setting.
155 The preupdate hook is disabled by invoking <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_hook()</a>
156 with a NULL pointer as the second parameter.
157 The third parameter to <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_hook()</a> is passed through as
158 the first parameter to callbacks.</p>
159
160 <p>The preupdate hook only fires for changes to real database tables; the
161 preupdate hook is not invoked for changes to <a href="../vtab.html">virtual tables</a> or to
162 system tables like sqlite_sequence or sqlite_stat1.</p>
163
164 <p>The second parameter to the preupdate callback is a pointer to
165 the <a href="../c3ref/sqlite3.html">database connection</a> that registered the preupdate hook.
166 The third parameter to the preupdate callback is one of the constants
167 <a href="../c3ref/c_alter_table.html">SQLITE_INSERT</a>, <a href="../c3ref/c_alter_table.html">SQLITE_DELETE</a>, or <a href="../c3ref/c_alter_table.html">SQLITE_UPDATE</a> to identify the
168 kind of update operation that is about to occur.
169 The fourth parameter to the preupdate callback is the name of the
170 database within the database connection that is being modified. This
171 will be "main" for the main database or "temp" for TEMP tables or
172 the name given after the AS keyword in the <a href="../lang_attach.html">ATTACH</a> statement for attached
173 databases.
174 The fifth parameter to the preupdate callback is the name of the
175 table that is being modified.</p>
176
177 <p>For an UPDATE or DELETE operation on a <a href="../rowidtable.html">rowid table</a>, the sixth
178 parameter passed to the preupdate callback is the initial <a href="../lang_createtable.html#rowid">rowid</a> of the
179 row being modified or deleted. For an INSERT operation on a rowid table,
180 or any operation on a WITHOUT ROWID table, the value of the sixth
181 parameter is undefined. For an INSERT or UPDATE on a rowid table the
182 seventh parameter is the final rowid value of the row being inserted
183 or updated. The value of the seventh parameter passed to the callback
184 function is not defined for operations on WITHOUT ROWID tables, or for
185 DELETE operations on rowid tables.</p>
186
187 <p>The sqlite3_preupdate_hook(D,C,P) function returns the P argument from
188 the previous call on the same <a href="../c3ref/sqlite3.html">database connection</a> D, or NULL for
189 the first call on D.</p>
190
191 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_old()</a>, <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_new()</a>,
192 <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_count()</a>, and <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_depth()</a> interfaces
193 provide additional information about a preupdate event. These routines
194 may only be called from within a preupdate callback. Invoking any of
195 these routines from outside of a preupdate callback or with a
196 <a href="../c3ref/sqlite3.html">database connection</a> pointer that is different from the one supplied
197 to the preupdate callback results in undefined and probably undesirable
198 behavior.</p>
199
200 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_count(D)</a> interface returns the number of columns
201 in the row that is being inserted, updated, or deleted.</p>
202
203 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_old(D,N,P)</a> interface writes into P a pointer to
204 a <a href="../c3ref/value.html">protected sqlite3_value</a> that contains the value of the Nth column of
205 the table row before it is updated. The N parameter must be between 0
206 and one less than the number of columns or the behavior will be
207 undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
208 preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
209 behavior is undefined. The <a href="../c3ref/value.html">sqlite3_value</a> that P points to
210 will be destroyed when the preupdate callback returns.</p>
211
212 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_new(D,N,P)</a> interface writes into P a pointer to
213 a <a href="../c3ref/value.html">protected sqlite3_value</a> that contains the value of the Nth column of
214 the table row after it is updated. The N parameter must be between 0
215 and one less than the number of columns or the behavior will be
216 undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
217 preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
218 behavior is undefined. The <a href="../c3ref/value.html">sqlite3_value</a> that P points to
219 will be destroyed when the preupdate callback returns.</p>
220
221 <p>The <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_depth(D)</a> interface returns 0 if the preupdate
222 callback was invoked as a result of a direct insert, update, or delete
223 operation; or 1 for inserts, updates, or deletes invoked by top-level
224 triggers; or 2 for changes resulting from triggers called by top-level
225 triggers; and so forth.</p>
226
227 <p>When the <a href="../c3ref/blob_write.html">sqlite3_blob_write()</a> API is used to update a blob column,
228 the pre-update hook is invoked with SQLITE_DELETE, because
229 the new values are not yet available. In this case, when a
230 callback made with op==SQLITE_DELETE is actually a write using the
231 sqlite3_blob_write() API, the <a href="../c3ref/preupdate_blobwrite.html">sqlite3_preupdate_blobwrite()</a> returns
232 the index of the column being written. In other cases, where the
233 pre-update hook is being invoked for some other reason, including a
234 regular DELETE, sqlite3_preupdate_blobwrite() returns -1.</p>
235
236 <p>See also: <a href="../c3ref/update_hook.html">sqlite3_update_hook()</a>
237 </p><p>See also lists of
238 <a href="../c3ref/objlist.html">Objects</a>,
239 <a href="../c3ref/constlist.html">Constants</a>, and
240 <a href="../c3ref/funclist.html">Functions</a>.</p>
241