~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to libdrizzle-2.0/libdrizzle/conn.h

  • Committer: Monty Taylor
  • Date: 2011-03-22 18:39:54 UTC
  • mto: (2246.1.1 build)
  • mto: This revision was merged to the branch mainline in revision 2247.
  • Revision ID: mordred@inaugust.com-20110322183954-fz8ciuywjz2llbyo
Split libdrizzle into 1.0 and 2.0. Applied the C++ changes to 2.0 branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
/*
 
2
 * Drizzle Client & Protocol Library
 
3
 *
 
4
 * Copyright (C) 2008 Eric Day (eday@oddments.org)
 
5
 * All rights reserved.
 
6
 *
 
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
 *
 
35
 */
 
36
 
 
37
/**
 
38
 * @file
 
39
 * @brief Connection Declarations
 
40
 */
 
41
 
 
42
#ifndef __DRIZZLE_CONN_H
 
43
#define __DRIZZLE_CONN_H
 
44
 
 
45
#ifdef __cplusplus
 
46
extern "C" {
 
47
#endif
 
48
 
 
49
/**
 
50
 * @addtogroup drizzle_con Connection Declarations
 
51
 * @ingroup drizzle_client_interface
 
52
 * @ingroup drizzle_server_interface
 
53
 * @{
 
54
 */
 
55
 
 
56
/**
 
57
 * Get file descriptor for connection.
 
58
 *
 
59
 * @param[in] con Connection structure previously initialized with
 
60
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
61
 * @return File descriptor of connection, or -1 if not active.
 
62
 */
 
63
DRIZZLE_API
 
64
int drizzle_con_fd(const drizzle_con_st *con);
 
65
 
 
66
/**
 
67
 * Use given file descriptor for connction.
 
68
 *
 
69
 * @param[in] con Connection structure previously initialized with
 
70
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
71
 * @param[in] fd File descriptor for connection.
 
72
 * @return Standard drizzle return value.
 
73
 */
 
74
DRIZZLE_API
 
75
drizzle_return_t drizzle_con_set_fd(drizzle_con_st *con, int fd);
 
76
 
 
77
/**
 
78
 * Close a connection.
 
79
 *
 
80
 * @param[in] con Connection structure previously initialized with
 
81
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
82
 */
 
83
DRIZZLE_API
 
84
void drizzle_con_close(drizzle_con_st *con);
 
85
 
 
86
/**
 
87
 * Set events to be watched for a connection.
 
88
 *
 
89
 * @param[in] con Connection structure previously initialized with
 
90
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
91
 * @param[in] events Bitfield of poll() events to watch.
 
92
 * @return Standard drizzle return value.
 
93
 */
 
94
DRIZZLE_API
 
95
drizzle_return_t drizzle_con_set_events(drizzle_con_st *con, short events);
 
96
 
 
97
/**
 
98
 * Set events that are ready for a connection. This is used with the external
 
99
 * event callbacks. See drizzle_set_event_watch_fn().
 
100
 *
 
101
 * @param[in] con Connection structure previously initialized with
 
102
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
103
 * @param[in] revents Bitfield of poll() events that were detected.
 
104
 * @return Standard drizzle return value.
 
105
 */
 
106
DRIZZLE_API
 
107
drizzle_return_t drizzle_con_set_revents(drizzle_con_st *con, short revents);
 
108
 
 
109
/**
 
110
 * Get the drizzle_st struct that the connection belongs to.
 
111
 *
 
112
 * @param[in] con Connection structure previously initialized with
 
113
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
114
 * @return Drizzle object that this connection is part of.
 
115
 */
 
116
DRIZZLE_API
 
117
drizzle_st *drizzle_con_drizzle(const drizzle_con_st *con);
 
118
 
 
119
/**
 
120
 * Return an error string for last error encountered.
 
121
 *
 
122
 * @param[in] con Connection structure previously initialized with
 
123
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
124
 * @return Pointer to static buffer in library that holds an error string.
 
125
 */
 
126
DRIZZLE_API
 
127
const char *drizzle_con_error(const drizzle_con_st *con);
 
128
 
 
129
/**
 
130
 * Value of errno in the case of a DRIZZLE_RETURN_ERRNO return value.
 
131
 *
 
132
 * @param[in] con Connection structure previously initialized with
 
133
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
134
 * @return An errno value as defined in your system errno.h file.
 
135
 */
 
136
DRIZZLE_API
 
137
int drizzle_con_errno(const drizzle_con_st *con);
 
138
 
 
139
/**
 
140
 * Get server defined error code for the last result read.
 
141
 *
 
142
 * @param[in] con Connection structure previously initialized with
 
143
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
144
 * @return An error code given back in the server response.
 
145
 */
 
146
DRIZZLE_API
 
147
uint16_t drizzle_con_error_code(const drizzle_con_st *con);
 
148
 
 
149
/**
 
150
 * Get SQL state code for the last result read.
 
151
 *
 
152
 * @param[in] con Connection structure previously initialized with
 
153
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
154
 * @return A SQLSTATE code given back in the server response.
 
155
 */
 
156
DRIZZLE_API
 
157
const char *drizzle_con_sqlstate(const drizzle_con_st *con);
 
158
 
 
159
/**
 
160
 * Get options for a connection.
 
161
 *
 
162
 * @param[in] con Connection structure previously initialized with
 
163
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
164
 * @return Options set for the connection structure.
 
165
 */
 
166
DRIZZLE_API
 
167
int drizzle_con_options(const drizzle_con_st *con);
 
168
 
 
169
/**
 
170
 * Set options for a connection.
 
171
 *
 
172
 * @param[in] con Connection structure previously initialized with
 
173
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
174
 * @param[in] options Available options for connection structure to set.
 
175
 */
 
176
DRIZZLE_API
 
177
void drizzle_con_set_options(drizzle_con_st *con,
 
178
                             int options);
 
179
 
 
180
/**
 
181
 * Add options for a connection.
 
182
 *
 
183
 * @param[in] con Connection structure previously initialized with
 
184
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
185
 * @param[in] options Available options for connection structure to set.
 
186
 */
 
187
DRIZZLE_API
 
188
void drizzle_con_add_options(drizzle_con_st *con,
 
189
                             int options);
 
190
 
 
191
/**
 
192
 * Remove options for a connection.
 
193
 *
 
194
 * @param[in] con Connection structure previously initialized with
 
195
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
196
 * @param[in] options Available options for connection structure to remove.
 
197
 */
 
198
DRIZZLE_API
 
199
void drizzle_con_remove_options(drizzle_con_st *con,
 
200
                                int options);
 
201
 
 
202
/**
 
203
 * Get TCP host for a connection.
 
204
 *
 
205
 * @param[in] con Connection structure previously initialized with
 
206
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
207
 * @return Host this connection is configured for, or NULL if not set.
 
208
 */
 
209
DRIZZLE_API
 
210
const char *drizzle_con_host(const drizzle_con_st *con);
 
211
 
 
212
/**
 
213
 * Get TCP port for a connection.
 
214
 *
 
215
 * @param[in] con Connection structure previously initialized with
 
216
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
217
 * @return Port this connection is configured for, 0 if not set.
 
218
 */
 
219
DRIZZLE_API
 
220
in_port_t drizzle_con_port(const drizzle_con_st *con);
 
221
 
 
222
/**
 
223
 * Set TCP host and port for a connection.
 
224
 *
 
225
 * @param[in] con Connection structure previously initialized with
 
226
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
227
 * @param[in] host Host to use for this connection, NULL for default value.
 
228
 * @param[in] port Port to use for this connection, 0 for default value.
 
229
 */
 
230
DRIZZLE_API
 
231
void drizzle_con_set_tcp(drizzle_con_st *con, const char *host, in_port_t port);
 
232
 
 
233
/**
 
234
 * Get unix domain socket for a connection.
 
235
 *
 
236
 * @param[in] con Connection structure previously initialized with
 
237
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
238
 * @return Unix domain socket set for this connection, NULL if not set.
 
239
 */
 
240
DRIZZLE_API
 
241
const char *drizzle_con_uds(const drizzle_con_st *con);
 
242
 
 
243
/**
 
244
 * Set unix domain socket for a connection.
 
245
 *
 
246
 * @param[in] con Connection structure previously initialized with
 
247
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
248
 * @param[in] uds Unix domain socket to use for this connection, NULL for
 
249
 *  defailt value.
 
250
 */
 
251
DRIZZLE_API
 
252
void drizzle_con_set_uds(drizzle_con_st *con, const char *uds);
 
253
 
 
254
/**
 
255
 * Get username for a connection.
 
256
 *
 
257
 * @param[in] con Connection structure previously initialized with
 
258
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
259
 * @return User associated with this connection.
 
260
 */
 
261
DRIZZLE_API
 
262
const char *drizzle_con_user(const drizzle_con_st *con);
 
263
 
 
264
/**
 
265
 * Get password for a connection.
 
266
 *
 
267
 * @param[in] con Connection structure previously initialized with
 
268
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
269
 * @return Password associated with this connection.
 
270
 */
 
271
DRIZZLE_API
 
272
const char *drizzle_con_password(const drizzle_con_st *con);
 
273
 
 
274
/**
 
275
 * Set username and password for a connection.
 
276
 *
 
277
 * @param[in] con Connection structure previously initialized with
 
278
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
279
 * @param[in] user Username to use for this connection.
 
280
 * @param[in] password Password to use for this connection.
 
281
 */
 
282
DRIZZLE_API
 
283
void drizzle_con_set_auth(drizzle_con_st *con, const char *user,
 
284
                          const char *password);
 
285
 
 
286
/**
 
287
 * Get database for a connection.
 
288
 *
 
289
 * @param[in] con Connection structure previously initialized with
 
290
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
291
 * @return Database associated with this connection.
 
292
 */
 
293
DRIZZLE_API
 
294
const char *drizzle_con_db(const drizzle_con_st *con);
 
295
 
 
296
/**
 
297
 * Set database for a connection.
 
298
 *
 
299
 * @param[in] con Connection structure previously initialized with
 
300
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
301
 * @param[in] db Database to use with this connection.
 
302
 */
 
303
DRIZZLE_API
 
304
void drizzle_con_set_db(drizzle_con_st *con, const char *db);
 
305
 
 
306
/**
 
307
 * Get application context pointer for a connection.
 
308
 *
 
309
 * @param[in] con Connection structure previously initialized with
 
310
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
311
 * @return Application context with this connection.
 
312
 */
 
313
DRIZZLE_API
 
314
void *drizzle_con_context(const drizzle_con_st *con);
 
315
 
 
316
/**
 
317
 * Set application context pointer for a connection.
 
318
 *
 
319
 * @param[in] con Connection structure previously initialized with
 
320
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
321
 * @param[in] context Application context to use with this connection.
 
322
 */
 
323
DRIZZLE_API
 
324
void drizzle_con_set_context(drizzle_con_st *con, void *context);
 
325
 
 
326
/**
 
327
 * Set callback function when the context pointer should be freed.
 
328
 *
 
329
 * @param[in] con Connection structure previously initialized with
 
330
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
331
 * @param[in] function Function to call to clean up connection context.
 
332
 */
 
333
DRIZZLE_API
 
334
void drizzle_con_set_context_free_fn(drizzle_con_st *con,
 
335
                                     drizzle_con_context_free_fn *function);
 
336
 
 
337
/**
 
338
 * Get protocol version for a connection.
 
339
 *
 
340
 * @param[in] con Connection structure previously initialized with
 
341
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
342
 * @return Protocol version for connection.
 
343
 */
 
344
DRIZZLE_API
 
345
uint8_t drizzle_con_protocol_version(const drizzle_con_st *con);
 
346
 
 
347
/**
 
348
 * Get server version string for a connection.
 
349
 *
 
350
 * @param[in] con Connection structure previously initialized with
 
351
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
352
 * @return Server version string for connection.
 
353
 */
 
354
DRIZZLE_API
 
355
const char *drizzle_con_server_version(const drizzle_con_st *con);
 
356
 
 
357
/**
 
358
 * Get server version number for a connection.
 
359
 *
 
360
 * @param[in] con Connection structure previously initialized with
 
361
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
362
 * @return Server version number for connection.
 
363
 */
 
364
DRIZZLE_API
 
365
uint32_t drizzle_con_server_version_number(const drizzle_con_st *con);
 
366
 
 
367
/**
 
368
 * Get thread ID for a connection.
 
369
 *
 
370
 * @param[in] con Connection structure previously initialized with
 
371
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
372
 * @return Thread ID for connection.
 
373
 */
 
374
DRIZZLE_API
 
375
uint32_t drizzle_con_thread_id(const drizzle_con_st *con);
 
376
 
 
377
/**
 
378
 * Get scramble buffer for a connection.
 
379
 *
 
380
 * @param[in] con Connection structure previously initialized with
 
381
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
382
 * @return Scramble buffer for connection.
 
383
 */
 
384
DRIZZLE_API
 
385
const uint8_t *drizzle_con_scramble(const drizzle_con_st *con);
 
386
 
 
387
/**
 
388
 * Get capabilities for a connection.
 
389
 *
 
390
 * @param[in] con Connection structure previously initialized with
 
391
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
392
 * @return Capabilities for connection.
 
393
 */
 
394
DRIZZLE_API
 
395
int drizzle_con_capabilities(const drizzle_con_st *con);
 
396
 
 
397
/**
 
398
 * Get character set for a connection.
 
399
 *
 
400
 * @param[in] con Connection structure previously initialized with
 
401
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
402
 * @return Character set for connection.
 
403
 */
 
404
DRIZZLE_API
 
405
drizzle_charset_t drizzle_con_charset(const drizzle_con_st *con);
 
406
 
 
407
/**
 
408
 * Get status for a connection.
 
409
 *
 
410
 * @param[in] con Connection structure previously initialized with
 
411
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
412
 * @return Status for connection.
 
413
 */
 
414
DRIZZLE_API
 
415
drizzle_con_status_t drizzle_con_status(const drizzle_con_st *con);
 
416
 
 
417
/**
 
418
 * Get max packet size for a connection.
 
419
 *
 
420
 * @param[in] con Connection structure previously initialized with
 
421
 *  drizzle_con_create(), drizzle_con_clone(), or related functions.
 
422
 * @return Max packet size for connection.
 
423
 */
 
424
DRIZZLE_API
 
425
uint32_t drizzle_con_max_packet_size(const drizzle_con_st *con);
 
426
 
 
427
/** @} */
 
428
 
 
429
#ifdef __cplusplus
 
430
}
 
431
#endif
 
432
 
 
433
#endif /* __DRIZZLE_CONN_H */