~drizzle-trunk/drizzle/development

1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
1
/*
2
 * Drizzle Client & Protocol Library
3
 *
4
 * Copyright (C) 2008 Eric Day (eday@oddments.org)
5
 * All rights reserved.
6
 *
1971.2.1 by kalebral at gmail
update files that did not have license or had incorrect license structure
7
 * Redistribution and use in source and binary forms, with or without
8
 * modification, are permitted provided that the following conditions are
9
 * met:
10
 *
11
 *     * Redistributions of source code must retain the above copyright
12
 * notice, this list of conditions and the following disclaimer.
13
 *
14
 *     * Redistributions in binary form must reproduce the above
15
 * copyright notice, this list of conditions and the following disclaimer
16
 * in the documentation and/or other materials provided with the
17
 * distribution.
18
 *
19
 *     * The names of its contributors may not be used to endorse or
20
 * promote products derived from this software without specific prior
21
 * written permission.
22
 *
23
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
29
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34
 *
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
35
 */
36
2449.1.4 by Brian Aker
Complete update of libdrizzle
37
#pragma once
38
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
39
/**
40
 * @file
41
 * @brief Connection Declarations
42
 */
43
44
#ifdef __cplusplus
45
extern "C" {
46
#endif
47
48
/**
49
 * @addtogroup drizzle_con Connection Declarations
50
 * @ingroup drizzle_client_interface
51
 * @ingroup drizzle_server_interface
52
 * @{
53
 */
54
55
/**
56
 * Get file descriptor for connection.
57
 *
58
 * @param[in] con Connection structure previously initialized with
59
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
60
 * @return File descriptor of connection, or -1 if not active.
61
 */
62
DRIZZLE_API
63
int drizzle_con_fd(const drizzle_con_st *con);
64
65
/**
66
 * Use given file descriptor for connction.
67
 *
68
 * @param[in] con Connection structure previously initialized with
69
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
70
 * @param[in] fd File descriptor for connection.
71
 * @return Standard drizzle return value.
72
 */
73
DRIZZLE_API
74
drizzle_return_t drizzle_con_set_fd(drizzle_con_st *con, int fd);
75
76
/**
77
 * Close a connection.
78
 *
79
 * @param[in] con Connection structure previously initialized with
80
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
81
 */
82
DRIZZLE_API
83
void drizzle_con_close(drizzle_con_st *con);
84
85
/**
86
 * Set events to be watched for a connection.
87
 *
88
 * @param[in] con Connection structure previously initialized with
89
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
90
 * @param[in] events Bitfield of poll() events to watch.
91
 * @return Standard drizzle return value.
92
 */
93
DRIZZLE_API
94
drizzle_return_t drizzle_con_set_events(drizzle_con_st *con, short events);
95
96
/**
97
 * Set events that are ready for a connection. This is used with the external
98
 * event callbacks. See drizzle_set_event_watch_fn().
99
 *
100
 * @param[in] con Connection structure previously initialized with
101
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
102
 * @param[in] revents Bitfield of poll() events that were detected.
103
 * @return Standard drizzle return value.
104
 */
105
DRIZZLE_API
106
drizzle_return_t drizzle_con_set_revents(drizzle_con_st *con, short revents);
107
108
/**
109
 * Get the drizzle_st struct that the connection belongs to.
110
 *
111
 * @param[in] con Connection structure previously initialized with
112
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
113
 * @return Drizzle object that this connection is part of.
114
 */
115
DRIZZLE_API
116
drizzle_st *drizzle_con_drizzle(const drizzle_con_st *con);
117
118
/**
119
 * Return an error string for last error encountered.
120
 *
121
 * @param[in] con Connection structure previously initialized with
122
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
123
 * @return Pointer to static buffer in library that holds an error string.
124
 */
125
DRIZZLE_API
126
const char *drizzle_con_error(const drizzle_con_st *con);
127
128
/**
129
 * Value of errno in the case of a DRIZZLE_RETURN_ERRNO return value.
130
 *
131
 * @param[in] con Connection structure previously initialized with
132
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
133
 * @return An errno value as defined in your system errno.h file.
134
 */
135
DRIZZLE_API
136
int drizzle_con_errno(const drizzle_con_st *con);
137
138
/**
139
 * Get server defined error code for the last result read.
140
 *
141
 * @param[in] con Connection structure previously initialized with
142
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
143
 * @return An error code given back in the server response.
144
 */
145
DRIZZLE_API
146
uint16_t drizzle_con_error_code(const drizzle_con_st *con);
147
148
/**
149
 * Get SQL state code for the last result read.
150
 *
151
 * @param[in] con Connection structure previously initialized with
152
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
153
 * @return A SQLSTATE code given back in the server response.
154
 */
155
DRIZZLE_API
156
const char *drizzle_con_sqlstate(const drizzle_con_st *con);
157
158
/**
159
 * Get options for a connection.
160
 *
161
 * @param[in] con Connection structure previously initialized with
162
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
163
 * @return Options set for the connection structure.
164
 */
165
DRIZZLE_API
1992.6.7 by Monty Taylor
Revert -Wc++-compat change.
166
drizzle_con_options_t drizzle_con_options(const drizzle_con_st *con);
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
167
168
/**
169
 * Set options for a connection.
170
 *
171
 * @param[in] con Connection structure previously initialized with
172
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
173
 * @param[in] options Available options for connection structure to set.
174
 */
175
DRIZZLE_API
176
void drizzle_con_set_options(drizzle_con_st *con,
1992.6.7 by Monty Taylor
Revert -Wc++-compat change.
177
                             drizzle_con_options_t options);
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
178
179
/**
180
 * Add options for a connection.
181
 *
182
 * @param[in] con Connection structure previously initialized with
183
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
184
 * @param[in] options Available options for connection structure to set.
185
 */
186
DRIZZLE_API
187
void drizzle_con_add_options(drizzle_con_st *con,
1992.6.7 by Monty Taylor
Revert -Wc++-compat change.
188
                             drizzle_con_options_t options);
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
189
190
/**
191
 * Remove options for a connection.
192
 *
193
 * @param[in] con Connection structure previously initialized with
194
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
195
 * @param[in] options Available options for connection structure to remove.
196
 */
197
DRIZZLE_API
198
void drizzle_con_remove_options(drizzle_con_st *con,
1992.6.7 by Monty Taylor
Revert -Wc++-compat change.
199
                                drizzle_con_options_t options);
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
200
201
/**
202
 * Get TCP host for a connection.
203
 *
204
 * @param[in] con Connection structure previously initialized with
205
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
206
 * @return Host this connection is configured for, or NULL if not set.
207
 */
208
DRIZZLE_API
209
const char *drizzle_con_host(const drizzle_con_st *con);
210
211
/**
212
 * Get TCP port for a connection.
213
 *
214
 * @param[in] con Connection structure previously initialized with
215
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
216
 * @return Port this connection is configured for, 0 if not set.
217
 */
218
DRIZZLE_API
219
in_port_t drizzle_con_port(const drizzle_con_st *con);
220
221
/**
222
 * Set TCP host and port for a connection.
223
 *
224
 * @param[in] con Connection structure previously initialized with
225
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
226
 * @param[in] host Host to use for this connection, NULL for default value.
227
 * @param[in] port Port to use for this connection, 0 for default value.
228
 */
229
DRIZZLE_API
230
void drizzle_con_set_tcp(drizzle_con_st *con, const char *host, in_port_t port);
231
232
/**
233
 * Get unix domain socket for a connection.
234
 *
235
 * @param[in] con Connection structure previously initialized with
236
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
237
 * @return Unix domain socket set for this connection, NULL if not set.
238
 */
239
DRIZZLE_API
240
const char *drizzle_con_uds(const drizzle_con_st *con);
241
242
/**
243
 * Set unix domain socket for a connection.
244
 *
245
 * @param[in] con Connection structure previously initialized with
246
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
247
 * @param[in] uds Unix domain socket to use for this connection, NULL for
248
 *  defailt value.
249
 */
250
DRIZZLE_API
251
void drizzle_con_set_uds(drizzle_con_st *con, const char *uds);
252
253
/**
254
 * Get username for a connection.
255
 *
256
 * @param[in] con Connection structure previously initialized with
257
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
258
 * @return User associated with this connection.
259
 */
260
DRIZZLE_API
261
const char *drizzle_con_user(const drizzle_con_st *con);
262
263
/**
264
 * Get password for a connection.
265
 *
266
 * @param[in] con Connection structure previously initialized with
267
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
268
 * @return Password associated with this connection.
269
 */
270
DRIZZLE_API
271
const char *drizzle_con_password(const drizzle_con_st *con);
272
273
/**
274
 * Set username and password for a connection.
275
 *
276
 * @param[in] con Connection structure previously initialized with
277
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
278
 * @param[in] user Username to use for this connection.
279
 * @param[in] password Password to use for this connection.
280
 */
281
DRIZZLE_API
282
void drizzle_con_set_auth(drizzle_con_st *con, const char *user,
283
                          const char *password);
284
285
/**
286
 * Get database for a connection.
287
 *
288
 * @param[in] con Connection structure previously initialized with
289
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
290
 * @return Database associated with this connection.
291
 */
292
DRIZZLE_API
293
const char *drizzle_con_db(const drizzle_con_st *con);
294
295
/**
296
 * Set database for a connection.
297
 *
298
 * @param[in] con Connection structure previously initialized with
299
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
300
 * @param[in] db Database to use with this connection.
301
 */
302
DRIZZLE_API
303
void drizzle_con_set_db(drizzle_con_st *con, const char *db);
304
305
/**
306
 * Get application context pointer for a connection.
307
 *
308
 * @param[in] con Connection structure previously initialized with
309
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
310
 * @return Application context with this connection.
311
 */
312
DRIZZLE_API
313
void *drizzle_con_context(const drizzle_con_st *con);
314
315
/**
316
 * Set application context pointer for a connection.
317
 *
318
 * @param[in] con Connection structure previously initialized with
319
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
320
 * @param[in] context Application context to use with this connection.
321
 */
322
DRIZZLE_API
323
void drizzle_con_set_context(drizzle_con_st *con, void *context);
324
325
/**
326
 * Set callback function when the context pointer should be freed.
327
 *
328
 * @param[in] con Connection structure previously initialized with
329
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
330
 * @param[in] function Function to call to clean up connection context.
331
 */
332
DRIZZLE_API
333
void drizzle_con_set_context_free_fn(drizzle_con_st *con,
334
                                     drizzle_con_context_free_fn *function);
335
336
/**
337
 * Get protocol version for a connection.
338
 *
339
 * @param[in] con Connection structure previously initialized with
340
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
341
 * @return Protocol version for connection.
342
 */
343
DRIZZLE_API
344
uint8_t drizzle_con_protocol_version(const drizzle_con_st *con);
345
346
/**
347
 * Get server version string for a connection.
348
 *
349
 * @param[in] con Connection structure previously initialized with
350
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
351
 * @return Server version string for connection.
352
 */
353
DRIZZLE_API
354
const char *drizzle_con_server_version(const drizzle_con_st *con);
355
356
/**
357
 * Get server version number for a connection.
358
 *
359
 * @param[in] con Connection structure previously initialized with
360
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
361
 * @return Server version number for connection.
362
 */
363
DRIZZLE_API
364
uint32_t drizzle_con_server_version_number(const drizzle_con_st *con);
365
366
/**
367
 * Get thread ID for a connection.
368
 *
369
 * @param[in] con Connection structure previously initialized with
370
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
371
 * @return Thread ID for connection.
372
 */
373
DRIZZLE_API
374
uint32_t drizzle_con_thread_id(const drizzle_con_st *con);
375
376
/**
377
 * Get scramble buffer for a connection.
378
 *
379
 * @param[in] con Connection structure previously initialized with
380
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
381
 * @return Scramble buffer for connection.
382
 */
383
DRIZZLE_API
384
const uint8_t *drizzle_con_scramble(const drizzle_con_st *con);
385
386
/**
387
 * Get capabilities for a connection.
388
 *
389
 * @param[in] con Connection structure previously initialized with
390
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
391
 * @return Capabilities for connection.
392
 */
393
DRIZZLE_API
1992.6.7 by Monty Taylor
Revert -Wc++-compat change.
394
drizzle_capabilities_t drizzle_con_capabilities(const drizzle_con_st *con);
1712.1.1 by Monty Taylor
Merged libdrizzle directly into tree.
395
396
/**
397
 * Get character set for a connection.
398
 *
399
 * @param[in] con Connection structure previously initialized with
400
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
401
 * @return Character set for connection.
402
 */
403
DRIZZLE_API
404
drizzle_charset_t drizzle_con_charset(const drizzle_con_st *con);
405
406
/**
407
 * Get status for a connection.
408
 *
409
 * @param[in] con Connection structure previously initialized with
410
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
411
 * @return Status for connection.
412
 */
413
DRIZZLE_API
414
drizzle_con_status_t drizzle_con_status(const drizzle_con_st *con);
415
416
/**
417
 * Get max packet size for a connection.
418
 *
419
 * @param[in] con Connection structure previously initialized with
420
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
421
 * @return Max packet size for connection.
422
 */
423
DRIZZLE_API
424
uint32_t drizzle_con_max_packet_size(const drizzle_con_st *con);
425
426
/** @} */
427
428
#ifdef __cplusplus
429
}
430
#endif