Debian Codegraph @

www/c3ref/get_clientdata.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>Database Connection Client Data</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_get_clientdata sqlite3_set_clientdata -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Database Connection Client Data</h2>
122 </div>
123 <blockquote><pre>
124 void *sqlite3_get_clientdata(sqlite3*,const char*);
125 int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));
126 </pre></blockquote>
127 <p>
128 These functions are used to associate one or more named pointers
129 with a <a href="../c3ref/sqlite3.html">database connection</a>.
130 A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P
131 to be attached to <a href="../c3ref/sqlite3.html">database connection</a> D using name N. Subsequent
132 calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P
133 or a NULL pointer if there were no prior calls to
134 sqlite3_set_clientdata() with the same values of D and N.
135 Names are compared using strcmp() and are thus case sensitive.
136 It returns 0 on success and SQLITE_NOMEM on allocation failure.</p>
137
138 <p>If P and X are both non-NULL, then the destructor X is invoked with
139 argument P on the first of the following occurrences:
140 <ul>
141 <li> An out-of-memory error occurs during the call to
142 sqlite3_set_clientdata() which attempts to register pointer P.
143 <li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made
144 with the same D and N parameters.
145 <li> The database connection closes. SQLite does not make any guarantees
146 about the order in which destructors are called, only that all
147 destructors will be called exactly once at some point during the
148 database connection closing process.
149 </ul></p>
150
151 <p>SQLite does not do anything with client data other than invoke
152 destructors on the client data at the appropriate time. The intended
153 use for client data is to provide a mechanism for wrapper libraries
154 to store additional information about an SQLite database connection.</p>
155
156 <p>There is no limit (other than available memory) on the number of different
157 client data pointers (with different names) that can be attached to a
158 single database connection. However, the current implementation stores
159 the content on a linked list. Insert and retrieval performance will
160 be proportional to the number of entries. The design use case, and
161 the use case for which the implementation is optimized, is
162 that an application will store only small number of client data names,
163 typically just one or two. This interface is not intended to be a
164 generalized key/value store for thousands or millions of keys. It
165 will work for that, but performance might be disappointing.</p>
166
167 <p>There is no way to enumerate the client data pointers
168 associated with a database connection. The N parameter can be thought
169 of as a secret key such that only code that knows the secret key is able
170 to access the associated data.</p>
171
172 <p>Security Warning: These interfaces should not be exposed in scripting
173 languages or in other circumstances where it might be possible for an
174 attacker to invoke them. Any agent that can invoke these interfaces
175 can probably also take control of the process.</p>
176
177 <p>Database connection client data is only available for SQLite
178 version 3.44.0 (2023-11-01) and later.</p>
179
180 <p>See also: <a href="../c3ref/get_auxdata.html">sqlite3_set_auxdata()</a> and <a href="../c3ref/get_auxdata.html">sqlite3_get_auxdata()</a>.
181 </p><p>See also lists of
182 <a href="../c3ref/objlist.html">Objects</a>,
183 <a href="../c3ref/constlist.html">Constants</a>, and
184 <a href="../c3ref/funclist.html">Functions</a>.</p>
185