Browse code

- obsolete documentation removed

Jan Janak authored on 19/07/2006 17:17:29
Showing 2 changed files
1 1
deleted file mode 100644
... ...
@@ -1,6 +0,0 @@
1
-$Id$
2
-
3
-How to write a support for a new database
4
-
5
-TBD
6
-
7 0
deleted file mode 100644
... ...
@@ -1,593 +0,0 @@
1
-# $Id$
2
-# 
3
-# History:
4
-# --------
5
-#  2004-06-06  updated (bind_dbmod and obsoleted db_* macros)  (andrei)
6
-
7
-Generic Database Interface
8
-
9
-This is a generic database interface for modules that need to utilize a 
10
-database. The interface should be used by all modules that access database.
11
-The interface will be independent of the underlying database server.
12
-
13
-Notes:
14
-
15
-If possible, use predefined macros if you need to access any structure 
16
-attributes.  
17
-
18
-For additional description, see comments in sources of mysql module.
19
-
20
-If you want to see more complicated examples of how the API could be used, 
21
-see sources of dbexample, usrloc or auth modules.
22
-
23
-
24
-1 Data types
25
-
26
-There are several new data types. All of them are defined in header file db.h,
27
-a client must include the header file to be able to use them.
28
-
29
-1.1 Type db_con_t
30
-
31
-1.1.1 Description
32
-
33
-This type represents a database connection, all database functions (described 
34
-below) use a variable of this type as one argument. In other words, variable 
35
-of db_con_t type serves as a handle for a particular database connection.
36
-
37
-1.1.2 Definition
38
-
39
-   typedef struct db_con {
40
-        char* table;     /* Default table to use */
41
-        void* con;       /* Database connection */
42
-        void* res;       /* Result of previous operation */
43
-        void* row;       /* Internal, not for public use */
44
-        int connected;   /* 1 if connection is established */
45
-   } db_con_t;
46
-
47
-1.1.3 Macros
48
-
49
-There are no macros for db_con_t type.
50
-
51
-
52
-1.2 Type db_key_t
53
-
54
-1.2.1 Description
55
-
56
-This type represents a database key. Every time you need to specify a key 
57
-value, this type should be used. In fact, this type is identical to const 
58
-char*.
59
-
60
-1.2.2 Definition
61
-   
62
-   typedef const char* db_key_t;
63
-
64
-1.2.3 Macros
65
-
66
-There are no macros (It is not needed).
67
-
68
-
69
-1.3 Type db_type_t
70
-
71
-1.3.1 Description
72
-
73
-Each cell in a database table can be of a different type. To distinguish
74
-among these types, the db_type_t enumeration is used. Every value of the
75
-enumeration represents one datatype that is recognized by the database
76
-API. This enumeration is used in conjunction with db_type_t. For more
77
-information, see the next section.
78
-
79
-1.3.2 Definition
80
-
81
-   typedef enum {
82
-       DB_INT,       /* Integer number */
83
-       DB_DOUBLE,    /* Decimal number */
84
-       DB_STRING,    /* String */
85
-       DB_STR,       /* str structure */
86
-       DB_DATETIME   /* Date and time */
87
-       DB_BLOB       /* Binary large object */
88
-       DB_BITMAP     /* Bitmap, one-dimensional array of flags */
89
-   } db_type_t;
90
-
91
-1.3.3 Macros
92
-
93
-There are no macros.
94
-
95
-
96
-1.4 Type db_val_t
97
-
98
-1.4.1 Description
99
-
100
-This structure represents a value in the database. Several datatypes are
101
-recognized and converted by the database API:
102
-
103
-DB_INT      - Value in the database represents an integer number
104
-DB_DOUBLE   - Value in the database represents a decimal number
105
-DB_STRING   - Value in the database represents a string
106
-DB_STR      - Value in the database represents a string
107
-DB_DATETIME - Value in the database represents date and time
108
-DB_BLOB     - Value in the database represents binary large object
109
-DB_BITMAP   - Value in the database represents an array of flags
110
-
111
-These datatypes are automaticaly recognized, converted from internal database
112
-representation and stored in the variable of corresponding type.
113
-
114
-1.4.2 Definition
115
-
116
-    typedef struct db_val {
117
-         db_type_t type;              /* Type of the value */
118
-         int nul;                     /* NULL flag */
119
-         union {                      
120
-             int int_val;             /* Integer value */
121
-             double double_val;       /* Double value */
122
-             time_t time_val;         /* Unix time_t value */
123
-             const char* string_val;  /* Zero terminated string */
124
-	     str str_val;             /* str structure */
125
-             str blob_val;            /* Structure describing blob */
126
-             unsigned int bitmap_val; /* Array of flags */
127
-         } val;
128
-    } db_val_t;
129
-
130
-1.4.3 Macros
131
-
132
-Note: All macros expect reference to db_val_t variable as the parameter.
133
-
134
-1.4.3.1 VAL_TYPE(value) Macro
135
-
136
-Use this macro if you need to set/get the type of the value
137
-
138
-Example: VAL_TYPE(val) = DB_INT;
139
-         if (VAL_TYPE(val) == DB_FLOAT) ...
140
-
141
-1.4.3.2 VAL_NULL(value) Macro
142
-
143
-Use this macro if you need to set/get the null flag. Non-zero flag means that 
144
-the corresponding cell in the database contained no data (NULL value in MySQL
145
-terminology).
146
-
147
-Example: if (VAL_NULL(val) == 1) {
148
-             printf("The cell is NULL");
149
-         }
150
-
151
-1.4.3.3 VAL_INT(value) Macro
152
-
153
-Use this macro if you need to access integer value in the db_val_t structure.
154
-
155
-Example: if (VAL_TYPE(val) == DB_INT) {
156
-             printf("%d", VAL_INT(val));
157
-         }
158
-
159
-1.4.3.4 VAL_DOUBLE(value) Macro 
160
-
161
-Use this macro if you need to access double value in the db_val_t structure.
162
-
163
-Example: if (VAL_TYPE(val) == DB_DOUBLE) {
164
-             printf("%f", VAL_DOUBLE(val));
165
-         }
166
-
167
-1.4.3.5 VAL_TIME(value) Macro 
168
-
169
-Use this macro if you need to access time_t value in the db_val_t structure.
170
-
171
-Example: time_t tim;
172
-         if (VAL_TYPE(val) == DB_DATETIME) {
173
-             tim = VAL_TIME(val);
174
-         }
175
-
176
-1.4.3.6 VAL_STRING(value) Macro 
177
-
178
-Use this macro if you need to access string value in the db_val_t structure.
179
-
180
-Example: if (VAL_TYPE(val) == DB_STRING) {
181
-             printf("%s", VAL_STRING(val));
182
-         }
183
-
184
-1.4.3.7 VAL_STR(value) Macro
185
-
186
-Use this macro if you need to access str structure in the db_val_t structure.
187
-
188
-Example: if (VAL_TYPE(val) == DB_STR) {
189
-             printf("%.*s", VAL_STR(val).len, VAL_STR(val).s);
190
-         }
191
-
192
-1.4.3.8 VAL_BLOB(value) Macro
193
-
194
-Use this macro if you need to access blob value in the db_val_t structure.
195
-
196
-Example: if (VAL_TYPE(val) == DB_BLOB) {
197
-	     printf("%.*s", VAL_BLOB(val).len, VAL_BLOB(val).s);
198
-         }
199
-
200
-1.4.3.9 VAL_BITMAP(value) Macro
201
-
202
-Use this macro if you need to access bitmap value in the db_val_t structure.
203
-
204
-Example: if (VAL_TYPE(val) == DB_BITMAP) {
205
-	    printf("%d", VAL_BITMAP(val));
206
-	 }
207
-
208
-1.5 Type db_row_t
209
-
210
-1.5.1 Description
211
-
212
-This type represents one row in a database table. In other words, the row is an
213
-array of db_val_t variables, where each db_val_t variable represents exactly 
214
-one cell in the table.
215
-
216
-1.5.2 Definition
217
-
218
-   typedef struct db_row {
219
-       db_val_t* values;    /* Array of values in the row */
220
-       int n;               /* Number of values in the row */
221
-   } db_val_t;
222
-
223
-1.5.3 Macros
224
-
225
-1.5.3.1 ROW_VALUES(row) Macro 
226
-
227
-Use this macro to get pointer to the array of db_val_t structures.
228
-
229
-Example: db_val_t* v = ROW_VALUES(row);
230
-         if (VAL_TYPE(v) == DB_INT) ....
231
-
232
-1.5.3.2 ROW_N(row) Macro 
233
-
234
-Use this macro to get number of cells in the row.
235
-
236
-Example: db_val_t* val = ROW_VALUES(row);
237
-         for(i = 0; i < ROW_N(row); i++) {
238
-             switch(VAL_TYPE(val + i)) {
239
-             case DB_INT: ...; break;
240
-             case DB_DOUBLE: ...; break;
241
-             ...
242
-             }
243
-         }
244
-
245
-
246
-1.6 Type db_res_t
247
-
248
-1.6.1 Description
249
-
250
-This type represents a result returned by db_query function (see below). The 
251
-result can consist of zero or more rows (see db_row_t description).
252
-
253
-Note: A variable of type db_res_t returned by db_query function uses dynamicaly
254
-      allocated memory, don't forget to call db_free_result if you don't need 
255
-      the variable anymore. You will encounter memory leaks if you fail to do 
256
-      this !
257
-
258
-In addition to zero or more rows, each db_res_t object contains also an array 
259
-of db_key_t objects. The objects represent keys (names of columns).
260
-
261
-1.6.2 Definition
262
-
263
-   typedef struct db_res {
264
-       struct {
265
-           db_key_t* keys;    /* Array of column names */
266
-           db_type_t* types;  /* Array of column types */
267
-           int n;             /* Number of columns */
268
-       } col;
269
-       struct db_row* rows;   /* Array of rows */
270
-       int n;                 /* Number of rows */
271
-   } db_res_t;
272
-
273
-1.6.3 Macros
274
-
275
-1.6.3.1 RES_NAMES(res) Macro 
276
-
277
-Use this macro if you want to obtain pointer to the array of cell names.
278
-
279
-Example: db_key_t* column_names = ROW_NAMES(row);
280
-
281
-1.6.3.2 RES_COL_N(res) Macro 
282
-
283
-Use this macro if you want to get the number of columns in the result.
284
-
285
-Example: int ncol = RES_COL_N(res)
286
-         for(i = 0; i < ncol; i++) {
287
-             /* do something with the column */
288
-         }
289
-
290
-1.6.3.3 RES_ROWS(res) Macro 
291
-
292
-Use this macro if you need to obtain pointer to array of rows.
293
-
294
-Example: db_row_t* rows = RES_ROWS(res);
295
- 
296
-1.6.3.4 RES_ROW_N(res) Macro 
297
-
298
-Use this macro if you need to obtain the number of rows in the result
299
-
300
-Example: int n = RES_ROW_N(res);
301
-
302
-
303
-1.7 Type db_op_t
304
-
305
-1.7.1 Description
306
-
307
-This type represents an expression operator. In fact, this type is 
308
-identical to const char*.
309
-
310
-1.7.2 Definition
311
-   
312
-   typedef const char* db_op_t;
313
-
314
-1.7.3 Macros
315
-
316
-There are no macros (It is not needed).
317
-
318
-
319
-2 Functions
320
-
321
-There are several functions that implement the database API logic. All function
322
-names start with db_ prefix, except bind_dbmod. bind_dbmod function is 
323
-implemented in db.c file, all other functions are implemented in a standalone 
324
-database module. You will need to compile and link db.c in your module to be 
325
-able to use the bind_dbmod function. Detailed function description follows.
326
-
327
-
328
-2.1 Function bind_dbmod
329
-
330
-2.1.1 Description
331
-
332
-This function is special, it's only purpose is to call find_export function in
333
-the ser core and find addresses of all other functions (starting with db_
334
-prefix). This function MUST be called __FIRST__ !
335
-
336
-2.1.2 Prototype
337
-
338
-   int bind_dbmod(char* db_url, db_func_t* dbf);
339
-
340
-2.1.3 Parameters
341
-
342
-The function takes two parameters, the first parameter must contain a database 
343
-connection URL or a database module name. The db_url is of the form 
344
-"mysql://username:password@host:port/database" or
345
-"mysql" (database module name).
346
-In the case of a database connection URL, this function looks only at the first
347
-token (the database protocol). In the example above that would be "mysql":
348
-The second parameter will be filled by this function with the corresponding
349
- database module callbacks (see the db_func_t structure definition in
350
-  db.h and the callbacks definitions below).
351
-
352
-
353
-2.1.4 Return Value
354
-
355
-The function returns 0 if it was able to find the addresses of all the 
356
-corresponding module database functions and a value < 0 otherwise.
357
-
358
-
359
-2.2 Callback dbf.init
360
-
361
-2.2.1 Description
362
-
363
-Use this function to initialize the database API and open a new database 
364
-connection. This function must be called after bind_dbmod but before any other 
365
-function is called.
366
-
367
-2.2.2 Prototype
368
-
369
-   db_con_t* (*db_init_f)(const char* _sql_url);
370
-
371
-2.2.3 Parameters
372
-
373
-The function takes one parameter, the parameter must contain database 
374
-connection URL. The URL is of the form 
375
-mysql://username:password@host:port/database where:
376
-
377
-username: Username to use when logging into database (optional).
378
-password: password if it was set (optional)
379
-host:     Hosname or IP address of the host where database server lives 
380
-          (mandatory)
381
-port:     Port number of the server if the port differs from default value 
382
-          (optional)
383
-database: If the database server supports multiple databases, you must specify 
384
-          name of the database (optional).
385
-
386
-
387
-2.2.4 Return Value
388
-
389
-The function returns pointer to db_con_t* representing the connection if it was
390
-successful, otherwise 0 is returned.
391
-
392
-
393
-2.3 Callback dbf.close
394
-
395
-2.3.1 Description
396
-
397
-The function closes previously open connection and frees all previously 
398
-allocated memory. The function db_close must be the very last function called.
399
-
400
-
401
-2.3.2 Prototype
402
-
403
-   void (*db_close_f)(db_con_t* _h);
404
-
405
-2.3.3 Parameters
406
-
407
-The function takes one parameter, this parameter is a pointer to db_con_t
408
-structure representing database connection that should be closed.
409
-
410
-2.3.4 Return Value
411
-
412
-Function doesn't return anything.
413
-
414
-
415
-2.4 Callback dbf.query
416
-
417
-2.4.1 Description
418
-
419
-This function implements SELECT SQL directive.
420
-
421
-2.4.2 Prototype
422
-
423
-   int (*db_query_f)(db_con_t* _h, db_key_t* _k, db_op_t* _op,
424
-                db_val_t* _v, db_key_t* _c, 
425
-	        int _n, int _nc, db_key_t _o, db_res_t** _r);
426
-
427
-2.4.3 Parameters
428
-
429
-The function takes 7 parameters:
430
-_h:  Database connection handle
431
-_k:  Array of column names that will be compared and their values must match
432
-_op: Array of operators to be used with key-value pairs
433
-_v:  Array of values, columns specified in _k parameter must match these values
434
-_c:  Array of column names that you are interested in
435
-_n:  Number of key-value pairs to match in _k and _v parameters
436
-_nc: Number of columns in _c parameter
437
-_o:  Order by
438
-_r:  Address of variable where pointer to the result will be stored
439
-
440
-If _k and _v parameters are NULL and _n is zero, you will get the whole table.
441
-if _c is NULL and _nc is zero, you will get all table columns in the result
442
-
443
-_r will point to a dynamically allocated structure, it is neccessary to call
444
-db_free_result function once you are finished with the result.
445
-
446
-If _op is 0, equal (=) will be used for all key-value pairs.
447
-
448
-Strings in the result are not duplicated, they will be discarded if you call
449
-db_free_result, make a copy yourself if you need to keep it after db_free_result.
450
-
451
-You must call db_free_result _BEFORE_ you can call db_query again !
452
-
453
-2.4.4 Return Value
454
-
455
-The function returns 0 if everything is OK, otherwise value < 0 is returned.
456
-
457
-
458
-2.5 Callback dbf.free_result
459
-
460
-2.5.1 Description
461
-
462
-This function frees all memory allocated previously in db_query, it is
463
-neccessary to call this function on a db_res_t structure if you don't need the
464
-structure anymore. You must call this function _BEFORE_ you call db_query
465
-again !
466
-
467
-2.5.2 Prototype
468
-
469
-   int (*db_free_result_f)(db_con_t* _h, db_res_t* _r);
470
-
471
-2.5.3 Parameters
472
-
473
-The function takes 2 parameters:
474
-_h: Database connection handle
475
-_r: Pointer to db_res_t structure to destroy
476
-
477
-2.5.4 Return Value
478
-
479
-The function returns 0 if everything is OK, otherwise the function returns
480
-value < 0.
481
-
482
-
483
-2.6 Callback dbf.insert
484
-
485
-2.6.1 Description
486
-
487
-This function implements INSERT SQL directive, you can insert one or more
488
-rows in a table using this function.
489
-
490
-2.6.2 Prototype
491
-
492
-   int (*db_insert_f)(db_con_t* _h, db_key_t* _k, db_val_t* _v, int _n);
493
-
494
-2.6.3 Parameters
495
-
496
-The function takes 4 parameters:
497
-_h: Database connection handle
498
-_k: Array of keys (column names) 
499
-_v: Array of values for keys specified in _k parameter
500
-_n: Number of keys-value pairs int _k and _v parameters
501
-
502
-2.6.4 Return Value
503
-
504
-The function returns 0 if everything is OK, otherwise the function returns
505
-value < 0.
506
-
507
-
508
-2.7 Callback dbf.delete
509
-
510
-2.7.1 Description
511
-
512
-This function implements DELETE SQL directive, it is possible to delete one or
513
-more rows from a table.
514
-
515
-2.7.2 Prototype
516
-
517
-   int (*db_delete_f)(db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _v,
518
-                       int _n);
519
-
520
-2.7.3 Parameters
521
-
522
-The function takes 4 parameters:
523
-_h: Database connection handle
524
-_k: Array of keys (column names) that will be matched
525
-_o: Array of operators to be used with key-value pairs
526
-_v: Array of values that the row must match to be deleted
527
-_n: Number of keys-value parameters in _k and _v parameters
528
-
529
-If _k is NULL and _v is NULL and _n is zero, all rows are deleted (table will
530
-be empty).
531
-
532
-If _o is NULL, equal operator (=) will be used everywhere.
533
-
534
-2.7.4 Return Value
535
-
536
-The function returns 0 if everything is OK, otherwise the function returns
537
-value < 0.
538
-
539
-
540
-2.8 Callback dbf.update
541
-
542
-2.8.1 Description
543
-
544
-The function implements UPDATE SQL directive. It is possible to modify one
545
-or more rows in a table using this function.
546
-
547
-2.8.2 Prototype
548
-
549
-   int (*db_update_f)(db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _v,
550
-	         db_key_t* _uk, db_val_t* _uv, int _n, int _un);
551
-
552
-2.8.3 Parameters
553
-
554
-The function takes 7 parameters:
555
-_h: Database connection handle
556
-_k: Array of keys (column names) that will be matched
557
-_o: Array of operators to be used with key-value pairs
558
-_v: Array of values that the row must match to be modified
559
-_uk: Array of keys (column names) that will be modified
560
-_uv: New values for keys specified in _k parameter
561
-_n: Number of key-value pairs in _k and _v parameters
562
-_un: Number of key-value pairs in _uk and _uv parameters 
563
-
564
-2.8.4 Return Value
565
-
566
-The function returns 0 if everything is OK, otherwise the function returns
567
-value < 0.
568
-
569
-
570
-2.9 Callback dbf.use_table
571
-
572
-2.9.1 Description
573
-
574
-The function db_use_table takes a table name and stores it db_con_t structure.
575
-All subsequent operations (insert, delete, update, query) are performed on
576
-that table.
577
-
578
-2.9.2 Prototype
579
-
580
-   int (*db_use_table_f)(db_con_t* _h, const char* _t);
581
-
582
-2.9.3 Parameters
583
-
584
-The function takes 2 parameters:
585
-_h: Database connection handle
586
-_t: Table name
587
-
588
-2.9.4 Return Value
589
-
590
-The function returns 0 if everything is OK, otherwise the function returns
591
-value < 0.
592
-