| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| 2 |
<HTML |
| 3 |
><HEAD |
| 4 |
><TITLE |
| 5 |
>DBD Helper Functions</TITLE |
| 6 |
><META |
| 7 |
NAME="GENERATOR" |
| 8 |
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK |
| 9 |
REL="HOME" |
| 10 |
TITLE="Database Independent Abstraction Layer for C" |
| 11 |
HREF="index.html"><LINK |
| 12 |
REL="UP" |
| 13 |
TITLE="Driver Functions" |
| 14 |
HREF="driverfuncs.html"><LINK |
| 15 |
REL="PREVIOUS" |
| 16 |
TITLE="Public Database Query Functions" |
| 17 |
HREF="driverfuncs-publicdbquery.html"><LINK |
| 18 |
REL="NEXT" |
| 19 |
TITLE="GNU Free Documentation License" |
| 20 |
HREF="copying-fdl.html"></HEAD |
| 21 |
><BODY |
| 22 |
CLASS="SECTION" |
| 23 |
BGCOLOR="#FFFFFF" |
| 24 |
TEXT="#000000" |
| 25 |
LINK="#0000FF" |
| 26 |
VLINK="#840084" |
| 27 |
ALINK="#0000FF" |
| 28 |
><DIV |
| 29 |
CLASS="NAVHEADER" |
| 30 |
><TABLE |
| 31 |
SUMMARY="Header navigation table" |
| 32 |
WIDTH="100%" |
| 33 |
BORDER="0" |
| 34 |
CELLPADDING="0" |
| 35 |
CELLSPACING="0" |
| 36 |
><TR |
| 37 |
><TH |
| 38 |
COLSPAN="3" |
| 39 |
ALIGN="center" |
| 40 |
>Database Independent Abstraction Layer for C: libdbi Driver Author's Guide</TH |
| 41 |
></TR |
| 42 |
><TR |
| 43 |
><TD |
| 44 |
WIDTH="10%" |
| 45 |
ALIGN="left" |
| 46 |
VALIGN="bottom" |
| 47 |
><A |
| 48 |
HREF="driverfuncs-publicdbquery.html" |
| 49 |
ACCESSKEY="P" |
| 50 |
>Prev</A |
| 51 |
></TD |
| 52 |
><TD |
| 53 |
WIDTH="80%" |
| 54 |
ALIGN="center" |
| 55 |
VALIGN="bottom" |
| 56 |
>Chapter 3. Driver Functions</TD |
| 57 |
><TD |
| 58 |
WIDTH="10%" |
| 59 |
ALIGN="right" |
| 60 |
VALIGN="bottom" |
| 61 |
><A |
| 62 |
HREF="copying-fdl.html" |
| 63 |
ACCESSKEY="N" |
| 64 |
>Next</A |
| 65 |
></TD |
| 66 |
></TR |
| 67 |
></TABLE |
| 68 |
><HR |
| 69 |
ALIGN="LEFT" |
| 70 |
WIDTH="100%"></DIV |
| 71 |
><DIV |
| 72 |
CLASS="SECTION" |
| 73 |
><H1 |
| 74 |
CLASS="SECTION" |
| 75 |
><A |
| 76 |
NAME="HELPERFUNCS" |
| 77 |
>3.4. DBD Helper Functions</A |
| 78 |
></H1 |
| 79 |
><P |
| 80 |
>libdbi implements a couple of functions which come in handy when implementing database engine drivers. Call them from your driver code if appropriate.</P |
| 81 |
><DIV |
| 82 |
CLASS="SECTION" |
| 83 |
><H2 |
| 84 |
CLASS="SECTION" |
| 85 |
><A |
| 86 |
NAME="INTERNAL-DBD-RESULT-CREATE" |
| 87 |
>3.4.1. _dbd_result_create</A |
| 88 |
></H2 |
| 89 |
><DIV |
| 90 |
CLASS="FUNCSYNOPSIS" |
| 91 |
><P |
| 92 |
></P |
| 93 |
><A |
| 94 |
NAME="AEN729" |
| 95 |
></A |
| 96 |
><P |
| 97 |
><CODE |
| 98 |
><CODE |
| 99 |
CLASS="FUNCDEF" |
| 100 |
>dbi_result_t *<B |
| 101 |
CLASS="FSFUNC" |
| 102 |
>_dbd_result_create</B |
| 103 |
></CODE |
| 104 |
>(dbi_conn_t *<VAR |
| 105 |
CLASS="PDPARAM" |
| 106 |
>conn</VAR |
| 107 |
>, void *<VAR |
| 108 |
CLASS="PDPARAM" |
| 109 |
>handle</VAR |
| 110 |
>, unsigned long long <VAR |
| 111 |
CLASS="PDPARAM" |
| 112 |
>numrows_matched</VAR |
| 113 |
>, unsigned long long <VAR |
| 114 |
CLASS="PDPARAM" |
| 115 |
>numrows_affected</VAR |
| 116 |
>);</CODE |
| 117 |
></P |
| 118 |
><P |
| 119 |
></P |
| 120 |
></DIV |
| 121 |
><P |
| 122 |
>Allocates a new dbi_result_t, filling the number of rows matched and affected, storing the database-specific result handle, and allocating room for rows to be stored.</P |
| 123 |
><P |
| 124 |
></P |
| 125 |
><DIV |
| 126 |
CLASS="VARIABLELIST" |
| 127 |
><DL |
| 128 |
><DT |
| 129 |
>Arguments</DT |
| 130 |
><DD |
| 131 |
><P |
| 132 |
><TT |
| 133 |
CLASS="LITERAL" |
| 134 |
>conn</TT |
| 135 |
>: The target connection.</P |
| 136 |
><P |
| 137 |
><TT |
| 138 |
CLASS="LITERAL" |
| 139 |
>handle</TT |
| 140 |
>: The database-specific result handle used internally by the driver.</P |
| 141 |
><P |
| 142 |
><TT |
| 143 |
CLASS="LITERAL" |
| 144 |
>numrows_matched</TT |
| 145 |
>: The number of rows matched by the query.</P |
| 146 |
><P |
| 147 |
><TT |
| 148 |
CLASS="LITERAL" |
| 149 |
>numrows_affected</TT |
| 150 |
>: The number of rows affected by the query.</P |
| 151 |
></DD |
| 152 |
><DT |
| 153 |
>Returns</DT |
| 154 |
><DD |
| 155 |
><P |
| 156 |
>A new DBI result object.</P |
| 157 |
></DD |
| 158 |
></DL |
| 159 |
></DIV |
| 160 |
></DIV |
| 161 |
><DIV |
| 162 |
CLASS="SECTION" |
| 163 |
><H2 |
| 164 |
CLASS="SECTION" |
| 165 |
><A |
| 166 |
NAME="INTERNAL-DBD-RESULT-SET-NUMFIELDS" |
| 167 |
>3.4.2. _dbd_result_set_numfields</A |
| 168 |
></H2 |
| 169 |
><DIV |
| 170 |
CLASS="FUNCSYNOPSIS" |
| 171 |
><P |
| 172 |
></P |
| 173 |
><A |
| 174 |
NAME="AEN760" |
| 175 |
></A |
| 176 |
><P |
| 177 |
><CODE |
| 178 |
><CODE |
| 179 |
CLASS="FUNCDEF" |
| 180 |
>void <B |
| 181 |
CLASS="FSFUNC" |
| 182 |
>_dbd_result_set_numfields</B |
| 183 |
></CODE |
| 184 |
>(dbi_result_t *<VAR |
| 185 |
CLASS="PDPARAM" |
| 186 |
>result</VAR |
| 187 |
>, unsigned int <VAR |
| 188 |
CLASS="PDPARAM" |
| 189 |
>numfields</VAR |
| 190 |
>);</CODE |
| 191 |
></P |
| 192 |
><P |
| 193 |
></P |
| 194 |
></DIV |
| 195 |
><P |
| 196 |
>Sets a result's number of fields and allocates memory for field information to be stored.</P |
| 197 |
><P |
| 198 |
></P |
| 199 |
><DIV |
| 200 |
CLASS="VARIABLELIST" |
| 201 |
><DL |
| 202 |
><DT |
| 203 |
>Arguments</DT |
| 204 |
><DD |
| 205 |
><P |
| 206 |
><TT |
| 207 |
CLASS="LITERAL" |
| 208 |
>result</TT |
| 209 |
>: The target result.</P |
| 210 |
><P |
| 211 |
><TT |
| 212 |
CLASS="LITERAL" |
| 213 |
>numfields</TT |
| 214 |
>: The number of fields in the result set.</P |
| 215 |
></DD |
| 216 |
></DL |
| 217 |
></DIV |
| 218 |
></DIV |
| 219 |
><DIV |
| 220 |
CLASS="SECTION" |
| 221 |
><H2 |
| 222 |
CLASS="SECTION" |
| 223 |
><A |
| 224 |
NAME="INTERNAL-DBD-RESULT-ADD-FIELD" |
| 225 |
>3.4.3. _dbd_result_add_field</A |
| 226 |
></H2 |
| 227 |
><DIV |
| 228 |
CLASS="FUNCSYNOPSIS" |
| 229 |
><P |
| 230 |
></P |
| 231 |
><A |
| 232 |
NAME="AEN779" |
| 233 |
></A |
| 234 |
><P |
| 235 |
><CODE |
| 236 |
><CODE |
| 237 |
CLASS="FUNCDEF" |
| 238 |
>void <B |
| 239 |
CLASS="FSFUNC" |
| 240 |
>_dbd_result_add_field</B |
| 241 |
></CODE |
| 242 |
>(dbi_result_t *<VAR |
| 243 |
CLASS="PDPARAM" |
| 244 |
>result</VAR |
| 245 |
>, unsigned int <VAR |
| 246 |
CLASS="PDPARAM" |
| 247 |
>idx</VAR |
| 248 |
>, char *<VAR |
| 249 |
CLASS="PDPARAM" |
| 250 |
>name</VAR |
| 251 |
>, unsigned short <VAR |
| 252 |
CLASS="PDPARAM" |
| 253 |
>type</VAR |
| 254 |
>, unsigned int <VAR |
| 255 |
CLASS="PDPARAM" |
| 256 |
>attribs</VAR |
| 257 |
>);</CODE |
| 258 |
></P |
| 259 |
><P |
| 260 |
></P |
| 261 |
></DIV |
| 262 |
><P |
| 263 |
>Stores information about the target field into the result set.</P |
| 264 |
><P |
| 265 |
></P |
| 266 |
><DIV |
| 267 |
CLASS="VARIABLELIST" |
| 268 |
><DL |
| 269 |
><DT |
| 270 |
>Arguments</DT |
| 271 |
><DD |
| 272 |
><P |
| 273 |
><TT |
| 274 |
CLASS="LITERAL" |
| 275 |
>result</TT |
| 276 |
>: The target result.</P |
| 277 |
><P |
| 278 |
><TT |
| 279 |
CLASS="LITERAL" |
| 280 |
>idx</TT |
| 281 |
>: The numeric field index.</P |
| 282 |
><P |
| 283 |
><TT |
| 284 |
CLASS="LITERAL" |
| 285 |
>name</TT |
| 286 |
>: The name of the field.</P |
| 287 |
><P |
| 288 |
><TT |
| 289 |
CLASS="LITERAL" |
| 290 |
>type</TT |
| 291 |
>: The datatype of the field.</P |
| 292 |
><P |
| 293 |
><TT |
| 294 |
CLASS="LITERAL" |
| 295 |
>attribs</TT |
| 296 |
>: The attributes of the field.</P |
| 297 |
></DD |
| 298 |
></DL |
| 299 |
></DIV |
| 300 |
></DIV |
| 301 |
><DIV |
| 302 |
CLASS="SECTION" |
| 303 |
><H2 |
| 304 |
CLASS="SECTION" |
| 305 |
><A |
| 306 |
NAME="INTERNAL-DBD-ROW-ALLOCATE" |
| 307 |
>3.4.4. _dbd_row_allocate</A |
| 308 |
></H2 |
| 309 |
><DIV |
| 310 |
CLASS="FUNCSYNOPSIS" |
| 311 |
><P |
| 312 |
></P |
| 313 |
><A |
| 314 |
NAME="AEN810" |
| 315 |
></A |
| 316 |
><P |
| 317 |
><CODE |
| 318 |
><CODE |
| 319 |
CLASS="FUNCDEF" |
| 320 |
>dbi_row_t *<B |
| 321 |
CLASS="FSFUNC" |
| 322 |
>_dbd_row_allocate</B |
| 323 |
></CODE |
| 324 |
>(unsigned int <VAR |
| 325 |
CLASS="PDPARAM" |
| 326 |
>numfields</VAR |
| 327 |
>);</CODE |
| 328 |
></P |
| 329 |
><P |
| 330 |
></P |
| 331 |
></DIV |
| 332 |
><P |
| 333 |
>Allocates a new row, ready to be filled with data.</P |
| 334 |
><P |
| 335 |
></P |
| 336 |
><DIV |
| 337 |
CLASS="VARIABLELIST" |
| 338 |
><DL |
| 339 |
><DT |
| 340 |
>Arguments</DT |
| 341 |
><DD |
| 342 |
><P |
| 343 |
><TT |
| 344 |
CLASS="LITERAL" |
| 345 |
>numfields</TT |
| 346 |
>: The number of fields in the result set.</P |
| 347 |
></DD |
| 348 |
><DT |
| 349 |
>Returns</DT |
| 350 |
><DD |
| 351 |
><P |
| 352 |
>A new DBI row, or NULL on error.</P |
| 353 |
></DD |
| 354 |
></DL |
| 355 |
></DIV |
| 356 |
></DIV |
| 357 |
><DIV |
| 358 |
CLASS="SECTION" |
| 359 |
><H2 |
| 360 |
CLASS="SECTION" |
| 361 |
><A |
| 362 |
NAME="INTERNAL-DBD-ROW-FINALIZE" |
| 363 |
>3.4.5. _dbd_row_finalize</A |
| 364 |
></H2 |
| 365 |
><DIV |
| 366 |
CLASS="FUNCSYNOPSIS" |
| 367 |
><P |
| 368 |
></P |
| 369 |
><A |
| 370 |
NAME="AEN829" |
| 371 |
></A |
| 372 |
><P |
| 373 |
><CODE |
| 374 |
><CODE |
| 375 |
CLASS="FUNCDEF" |
| 376 |
>void <B |
| 377 |
CLASS="FSFUNC" |
| 378 |
>_dbd_row_finalize</B |
| 379 |
></CODE |
| 380 |
>(dbi_result_t *<VAR |
| 381 |
CLASS="PDPARAM" |
| 382 |
>result</VAR |
| 383 |
>, dbi_row_t *<VAR |
| 384 |
CLASS="PDPARAM" |
| 385 |
>row</VAR |
| 386 |
>, unsigned long long <VAR |
| 387 |
CLASS="PDPARAM" |
| 388 |
>rowidx</VAR |
| 389 |
>);</CODE |
| 390 |
></P |
| 391 |
><P |
| 392 |
></P |
| 393 |
></DIV |
| 394 |
><P |
| 395 |
>Associates and stores the row with the result set, once the row's data has been filled.</P |
| 396 |
><P |
| 397 |
></P |
| 398 |
><DIV |
| 399 |
CLASS="VARIABLELIST" |
| 400 |
><DL |
| 401 |
><DT |
| 402 |
>Arguments</DT |
| 403 |
><DD |
| 404 |
><P |
| 405 |
><TT |
| 406 |
CLASS="LITERAL" |
| 407 |
>result</TT |
| 408 |
>: The target result set.</P |
| 409 |
><P |
| 410 |
><TT |
| 411 |
CLASS="LITERAL" |
| 412 |
>row</TT |
| 413 |
>: The target row object.</P |
| 414 |
><P |
| 415 |
><TT |
| 416 |
CLASS="LITERAL" |
| 417 |
>rowidx</TT |
| 418 |
>: The index of the row.</P |
| 419 |
></DD |
| 420 |
></DL |
| 421 |
></DIV |
| 422 |
></DIV |
| 423 |
><DIV |
| 424 |
CLASS="SECTION" |
| 425 |
><H2 |
| 426 |
CLASS="SECTION" |
| 427 |
><A |
| 428 |
NAME="INTERNAL-DBD-INTERNAL-ERROR-HANDLER" |
| 429 |
>3.4.6. _dbd_internal_error_handler</A |
| 430 |
></H2 |
| 431 |
><DIV |
| 432 |
CLASS="FUNCSYNOPSIS" |
| 433 |
><P |
| 434 |
></P |
| 435 |
><A |
| 436 |
NAME="AEN852" |
| 437 |
></A |
| 438 |
><P |
| 439 |
><CODE |
| 440 |
><CODE |
| 441 |
CLASS="FUNCDEF" |
| 442 |
>void <B |
| 443 |
CLASS="FSFUNC" |
| 444 |
>_dbd_internal_error_handler</B |
| 445 |
></CODE |
| 446 |
>(dbi_conn_t *<VAR |
| 447 |
CLASS="PDPARAM" |
| 448 |
>conn</VAR |
| 449 |
>, const char *<VAR |
| 450 |
CLASS="PDPARAM" |
| 451 |
>errmsg</VAR |
| 452 |
>, const int <VAR |
| 453 |
CLASS="PDPARAM" |
| 454 |
>errno</VAR |
| 455 |
>);</CODE |
| 456 |
></P |
| 457 |
><P |
| 458 |
></P |
| 459 |
></DIV |
| 460 |
><P |
| 461 |
>Saves error message information. libdbi makes this information available to the software to check the error status after each call to a libdbi API function. If an old error message string exists, it will be freed.</P |
| 462 |
><P |
| 463 |
></P |
| 464 |
><DIV |
| 465 |
CLASS="VARIABLELIST" |
| 466 |
><DL |
| 467 |
><DT |
| 468 |
>Arguments</DT |
| 469 |
><DD |
| 470 |
><P |
| 471 |
><TT |
| 472 |
CLASS="LITERAL" |
| 473 |
>conn</TT |
| 474 |
>: The target connection.</P |
| 475 |
><P |
| 476 |
><TT |
| 477 |
CLASS="LITERAL" |
| 478 |
>errmsg</TT |
| 479 |
>: The error message to store. This will be stdup'd by libdbi so it has its own copy. If NULL, libdbi will attempt to provide an appropriate message string.</P |
| 480 |
><P |
| 481 |
><TT |
| 482 |
CLASS="LITERAL" |
| 483 |
>errno</TT |
| 484 |
>: The error number to store. Use only the predefined (in <TT |
| 485 |
CLASS="FILENAME" |
| 486 |
>include/dbi/dbi.h</TT |
| 487 |
>) constants DBI_ERROR_*. If the error number is DBI_ERROR_DBD, libdbi will replace the error number and message by calling the driver function <CODE |
| 488 |
CLASS="FUNCTION" |
| 489 |
>dbd_geterror</CODE |
| 490 |
> which retrieves the error code and message from the database client library. If errmsg is NULL and errno is any other of the predefined constants, libdbi will provide its own message string.</P |
| 491 |
></DD |
| 492 |
></DL |
| 493 |
></DIV |
| 494 |
></DIV |
| 495 |
><DIV |
| 496 |
CLASS="SECTION" |
| 497 |
><H2 |
| 498 |
CLASS="SECTION" |
| 499 |
><A |
| 500 |
NAME="INTERNAL-DBD-RESULT-CREATE-FROM-STRINGARRAY" |
| 501 |
>3.4.7. _dbd_result_create_from_stringarray</A |
| 502 |
></H2 |
| 503 |
><DIV |
| 504 |
CLASS="FUNCSYNOPSIS" |
| 505 |
><P |
| 506 |
></P |
| 507 |
><A |
| 508 |
NAME="AEN877" |
| 509 |
></A |
| 510 |
><P |
| 511 |
><CODE |
| 512 |
><CODE |
| 513 |
CLASS="FUNCDEF" |
| 514 |
>dbi_result_t *<B |
| 515 |
CLASS="FSFUNC" |
| 516 |
>_dbd_result_create_from_stringarray</B |
| 517 |
></CODE |
| 518 |
>(dbi_conn_t *<VAR |
| 519 |
CLASS="PDPARAM" |
| 520 |
>conn</VAR |
| 521 |
>, unsigned long long <VAR |
| 522 |
CLASS="PDPARAM" |
| 523 |
>numrows_matched</VAR |
| 524 |
>, const char **<VAR |
| 525 |
CLASS="PDPARAM" |
| 526 |
>stringarray</VAR |
| 527 |
>);</CODE |
| 528 |
></P |
| 529 |
><P |
| 530 |
></P |
| 531 |
></DIV |
| 532 |
><P |
| 533 |
>Creates a result object from an array of strings which contains the data of a single field for each row.</P |
| 534 |
><P |
| 535 |
></P |
| 536 |
><DIV |
| 537 |
CLASS="VARIABLELIST" |
| 538 |
><DL |
| 539 |
><DT |
| 540 |
>Arguments</DT |
| 541 |
><DD |
| 542 |
><P |
| 543 |
><TT |
| 544 |
CLASS="LITERAL" |
| 545 |
>conn</TT |
| 546 |
>: The target connection.</P |
| 547 |
><P |
| 548 |
><TT |
| 549 |
CLASS="LITERAL" |
| 550 |
>numrows_matched</TT |
| 551 |
>: The number of rows contained in the <CODE |
| 552 |
CLASS="PARAMETER" |
| 553 |
>stringarray</CODE |
| 554 |
>.</P |
| 555 |
><P |
| 556 |
><TT |
| 557 |
CLASS="LITERAL" |
| 558 |
>stringarray</TT |
| 559 |
>: A pointer to an array of strings with <CODE |
| 560 |
CLASS="PARAMETER" |
| 561 |
>numrows_matched</CODE |
| 562 |
> members.</P |
| 563 |
></DD |
| 564 |
><DT |
| 565 |
><EM |
| 566 |
>Returns</EM |
| 567 |
></DT |
| 568 |
><DD |
| 569 |
><P |
| 570 |
>A result object, or NULL if there is an error.</P |
| 571 |
></DD |
| 572 |
></DL |
| 573 |
></DIV |
| 574 |
></DIV |
| 575 |
><DIV |
| 576 |
CLASS="SECTION" |
| 577 |
><H2 |
| 578 |
CLASS="SECTION" |
| 579 |
><A |
| 580 |
NAME="INTERNAL-DBD-REGISTER-DRIVER-CAP" |
| 581 |
>3.4.8. _dbd_register_driver_cap</A |
| 582 |
></H2 |
| 583 |
><DIV |
| 584 |
CLASS="FUNCSYNOPSIS" |
| 585 |
><P |
| 586 |
></P |
| 587 |
><A |
| 588 |
NAME="AEN907" |
| 589 |
></A |
| 590 |
><P |
| 591 |
><CODE |
| 592 |
><CODE |
| 593 |
CLASS="FUNCDEF" |
| 594 |
>void <B |
| 595 |
CLASS="FSFUNC" |
| 596 |
>_dbd_register_driver_cap</B |
| 597 |
></CODE |
| 598 |
>(dbi_driver_t *<VAR |
| 599 |
CLASS="PDPARAM" |
| 600 |
>driver</VAR |
| 601 |
>, const char *<VAR |
| 602 |
CLASS="PDPARAM" |
| 603 |
>capname</VAR |
| 604 |
>, int <VAR |
| 605 |
CLASS="PDPARAM" |
| 606 |
>value</VAR |
| 607 |
>);</CODE |
| 608 |
></P |
| 609 |
><P |
| 610 |
></P |
| 611 |
></DIV |
| 612 |
><P |
| 613 |
>Adds a key-value pair to the list of driver capabilities.</P |
| 614 |
><P |
| 615 |
></P |
| 616 |
><DIV |
| 617 |
CLASS="VARIABLELIST" |
| 618 |
><DL |
| 619 |
><DT |
| 620 |
>Arguments</DT |
| 621 |
><DD |
| 622 |
><P |
| 623 |
><TT |
| 624 |
CLASS="LITERAL" |
| 625 |
>driver</TT |
| 626 |
>: The target driver.</P |
| 627 |
><P |
| 628 |
><TT |
| 629 |
CLASS="LITERAL" |
| 630 |
>capname</TT |
| 631 |
>: The key.</P |
| 632 |
><P |
| 633 |
><TT |
| 634 |
CLASS="LITERAL" |
| 635 |
>value</TT |
| 636 |
>: The value.</P |
| 637 |
></DD |
| 638 |
></DL |
| 639 |
></DIV |
| 640 |
></DIV |
| 641 |
><DIV |
| 642 |
CLASS="SECTION" |
| 643 |
><H2 |
| 644 |
CLASS="SECTION" |
| 645 |
><A |
| 646 |
NAME="INTERNAL-DBD-REGISTER-CONN-CAP" |
| 647 |
>3.4.9. _dbd_register_conn_cap</A |
| 648 |
></H2 |
| 649 |
><DIV |
| 650 |
CLASS="FUNCSYNOPSIS" |
| 651 |
><P |
| 652 |
></P |
| 653 |
><A |
| 654 |
NAME="AEN930" |
| 655 |
></A |
| 656 |
><P |
| 657 |
><CODE |
| 658 |
><CODE |
| 659 |
CLASS="FUNCDEF" |
| 660 |
>void <B |
| 661 |
CLASS="FSFUNC" |
| 662 |
>_dbd_register_conn_cap</B |
| 663 |
></CODE |
| 664 |
>(dbi_conn_t *<VAR |
| 665 |
CLASS="PDPARAM" |
| 666 |
>conn</VAR |
| 667 |
>, const char *<VAR |
| 668 |
CLASS="PDPARAM" |
| 669 |
>capname</VAR |
| 670 |
>, int <VAR |
| 671 |
CLASS="PDPARAM" |
| 672 |
>value</VAR |
| 673 |
>);</CODE |
| 674 |
></P |
| 675 |
><P |
| 676 |
></P |
| 677 |
></DIV |
| 678 |
><P |
| 679 |
>Adds a key-value pair to the list of connection capabilities.</P |
| 680 |
><P |
| 681 |
></P |
| 682 |
><DIV |
| 683 |
CLASS="VARIABLELIST" |
| 684 |
><DL |
| 685 |
><DT |
| 686 |
>Arguments</DT |
| 687 |
><DD |
| 688 |
><P |
| 689 |
><TT |
| 690 |
CLASS="LITERAL" |
| 691 |
>conn</TT |
| 692 |
>: The target connection.</P |
| 693 |
><P |
| 694 |
><TT |
| 695 |
CLASS="LITERAL" |
| 696 |
>capname</TT |
| 697 |
>: The key.</P |
| 698 |
><P |
| 699 |
><TT |
| 700 |
CLASS="LITERAL" |
| 701 |
>value</TT |
| 702 |
>: The value.</P |
| 703 |
></DD |
| 704 |
></DL |
| 705 |
></DIV |
| 706 |
></DIV |
| 707 |
><DIV |
| 708 |
CLASS="SECTION" |
| 709 |
><H2 |
| 710 |
CLASS="SECTION" |
| 711 |
><A |
| 712 |
NAME="INTERNAL-DBD-PARSE-DATETIME" |
| 713 |
>3.4.10. _dbd_parse_datetime</A |
| 714 |
></H2 |
| 715 |
><DIV |
| 716 |
CLASS="FUNCSYNOPSIS" |
| 717 |
><P |
| 718 |
></P |
| 719 |
><A |
| 720 |
NAME="AEN953" |
| 721 |
></A |
| 722 |
><P |
| 723 |
><CODE |
| 724 |
><CODE |
| 725 |
CLASS="FUNCDEF" |
| 726 |
>time_t <B |
| 727 |
CLASS="FSFUNC" |
| 728 |
>_dbd_parse_datetime</B |
| 729 |
></CODE |
| 730 |
>(const char *<VAR |
| 731 |
CLASS="PDPARAM" |
| 732 |
>raw</VAR |
| 733 |
>, unsigned int <VAR |
| 734 |
CLASS="PDPARAM" |
| 735 |
>attribs</VAR |
| 736 |
>);</CODE |
| 737 |
></P |
| 738 |
><P |
| 739 |
></P |
| 740 |
></DIV |
| 741 |
><P |
| 742 |
>Parses the input time, date, or datetime string and converts the value into a time_t value.</P |
| 743 |
><P |
| 744 |
></P |
| 745 |
><DIV |
| 746 |
CLASS="VARIABLELIST" |
| 747 |
><DL |
| 748 |
><DT |
| 749 |
>Arguments</DT |
| 750 |
><DD |
| 751 |
><P |
| 752 |
><TT |
| 753 |
CLASS="LITERAL" |
| 754 |
>raw</TT |
| 755 |
>: A zero-terminated string containing a time, date, or datetime value. Accepted formats are YYYY-MM-DD for date values, HH:MM:SS for time values, and YYYY-MM-DD HH:MM:SS for datetime values. The separators must be present, but can be any character.</P |
| 756 |
><P |
| 757 |
><TT |
| 758 |
CLASS="LITERAL" |
| 759 |
>attribs</TT |
| 760 |
>: The field attributes of raw.</P |
| 761 |
></DD |
| 762 |
><DT |
| 763 |
><EM |
| 764 |
>Returns</EM |
| 765 |
></DT |
| 766 |
><DD |
| 767 |
><P |
| 768 |
>The numeric equivalent of the input based on UTC. In case of an error, this function returns the start of the Unix epoch.</P |
| 769 |
></DD |
| 770 |
></DL |
| 771 |
></DIV |
| 772 |
></DIV |
| 773 |
><DIV |
| 774 |
CLASS="SECTION" |
| 775 |
><H2 |
| 776 |
CLASS="SECTION" |
| 777 |
><A |
| 778 |
NAME="INTERNAL-DBD-ESCAPE-CHARS" |
| 779 |
>3.4.11. _dbd_escape_chars</A |
| 780 |
></H2 |
| 781 |
><DIV |
| 782 |
CLASS="FUNCSYNOPSIS" |
| 783 |
><P |
| 784 |
></P |
| 785 |
><A |
| 786 |
NAME="AEN977" |
| 787 |
></A |
| 788 |
><P |
| 789 |
><CODE |
| 790 |
><CODE |
| 791 |
CLASS="FUNCDEF" |
| 792 |
>size_t <B |
| 793 |
CLASS="FSFUNC" |
| 794 |
>_dbd_escape_chars</B |
| 795 |
></CODE |
| 796 |
>(char *<VAR |
| 797 |
CLASS="PDPARAM" |
| 798 |
>dest</VAR |
| 799 |
>, const char *<VAR |
| 800 |
CLASS="PDPARAM" |
| 801 |
>orig</VAR |
| 802 |
>, size_t <VAR |
| 803 |
CLASS="PDPARAM" |
| 804 |
>orig_size</VAR |
| 805 |
>, const char *<VAR |
| 806 |
CLASS="PDPARAM" |
| 807 |
>toescape</VAR |
| 808 |
>);</CODE |
| 809 |
></P |
| 810 |
><P |
| 811 |
></P |
| 812 |
></DIV |
| 813 |
><P |
| 814 |
>Escapes the characters contained in <CODE |
| 815 |
CLASS="PARAMETER" |
| 816 |
>toescape</CODE |
| 817 |
> in the string <CODE |
| 818 |
CLASS="PARAMETER" |
| 819 |
>orig</CODE |
| 820 |
> and puts the result into the allocated memory pointed to by <CODE |
| 821 |
CLASS="PARAMETER" |
| 822 |
>dest</CODE |
| 823 |
>. The size of <CODE |
| 824 |
CLASS="PARAMETER" |
| 825 |
>dest</CODE |
| 826 |
> must be at least (<CODE |
| 827 |
CLASS="PARAMETER" |
| 828 |
>orig_size</CODE |
| 829 |
>*2)+5. The characters are escaped by preceding them with a backslash.</P |
| 830 |
><P |
| 831 |
></P |
| 832 |
><DIV |
| 833 |
CLASS="VARIABLELIST" |
| 834 |
><DL |
| 835 |
><DT |
| 836 |
>Arguments</DT |
| 837 |
><DD |
| 838 |
><P |
| 839 |
><TT |
| 840 |
CLASS="LITERAL" |
| 841 |
>dest</TT |
| 842 |
>: Pointer to allocated memory which will receive the escaped string.</P |
| 843 |
><P |
| 844 |
><TT |
| 845 |
CLASS="LITERAL" |
| 846 |
>orig</TT |
| 847 |
>: The string to escape.</P |
| 848 |
><P |
| 849 |
><TT |
| 850 |
CLASS="LITERAL" |
| 851 |
>orig_size</TT |
| 852 |
>: The length of the string to escape.</P |
| 853 |
><P |
| 854 |
><TT |
| 855 |
CLASS="LITERAL" |
| 856 |
>toescape</TT |
| 857 |
>: A string containing all characters that need escaping.</P |
| 858 |
></DD |
| 859 |
><DT |
| 860 |
><EM |
| 861 |
>Returns</EM |
| 862 |
></DT |
| 863 |
><DD |
| 864 |
><P |
| 865 |
>The length, in bytes, of the escaped string.</P |
| 866 |
></DD |
| 867 |
></DL |
| 868 |
></DIV |
| 869 |
></DIV |
| 870 |
><DIV |
| 871 |
CLASS="SECTION" |
| 872 |
><H2 |
| 873 |
CLASS="SECTION" |
| 874 |
><A |
| 875 |
NAME="INTERNAL-DBD-ENCODE-BINARY" |
| 876 |
>3.4.12. _dbd_encode_binary</A |
| 877 |
></H2 |
| 878 |
><DIV |
| 879 |
CLASS="FUNCSYNOPSIS" |
| 880 |
><P |
| 881 |
></P |
| 882 |
><A |
| 883 |
NAME="AEN1014" |
| 884 |
></A |
| 885 |
><P |
| 886 |
><CODE |
| 887 |
><CODE |
| 888 |
CLASS="FUNCDEF" |
| 889 |
>size_t <B |
| 890 |
CLASS="FSFUNC" |
| 891 |
>_dbd_encode_binary</B |
| 892 |
></CODE |
| 893 |
>(const unsigned char *<VAR |
| 894 |
CLASS="PDPARAM" |
| 895 |
>in</VAR |
| 896 |
>, size_t <VAR |
| 897 |
CLASS="PDPARAM" |
| 898 |
>n</VAR |
| 899 |
>, unsigned char *<VAR |
| 900 |
CLASS="PDPARAM" |
| 901 |
>out</VAR |
| 902 |
>);</CODE |
| 903 |
></P |
| 904 |
><P |
| 905 |
></P |
| 906 |
></DIV |
| 907 |
><P |
| 908 |
>Encodes a binary string as a zero-terminated string which can be safely included in a SQL query. Use <A |
| 909 |
HREF="helperfuncs.html#INTERNAL-DBD-DECODE-BINARY" |
| 910 |
>_dbd_decode_binary</A |
| 911 |
> to decode the string again.</P |
| 912 |
><P |
| 913 |
></P |
| 914 |
><DIV |
| 915 |
CLASS="VARIABLELIST" |
| 916 |
><DL |
| 917 |
><DT |
| 918 |
>Arguments</DT |
| 919 |
><DD |
| 920 |
><P |
| 921 |
><TT |
| 922 |
CLASS="LITERAL" |
| 923 |
>in</TT |
| 924 |
>: Pointer to the binary string.</P |
| 925 |
><P |
| 926 |
><TT |
| 927 |
CLASS="LITERAL" |
| 928 |
>n</TT |
| 929 |
>: Length, in bytes, of the binary string <CODE |
| 930 |
CLASS="PARAMETER" |
| 931 |
>in</CODE |
| 932 |
>.</P |
| 933 |
><P |
| 934 |
><TT |
| 935 |
CLASS="LITERAL" |
| 936 |
>out</TT |
| 937 |
>: Pointer to allocated memory which will receive the escaped string. The size must be at least 2 +(257*<CODE |
| 938 |
CLASS="PARAMETER" |
| 939 |
>n</CODE |
| 940 |
>)/254 bytes.</P |
| 941 |
></DD |
| 942 |
><DT |
| 943 |
><EM |
| 944 |
>Returns</EM |
| 945 |
></DT |
| 946 |
><DD |
| 947 |
><P |
| 948 |
>The length, in bytes, of the escaped string.</P |
| 949 |
></DD |
| 950 |
></DL |
| 951 |
></DIV |
| 952 |
></DIV |
| 953 |
><DIV |
| 954 |
CLASS="SECTION" |
| 955 |
><H2 |
| 956 |
CLASS="SECTION" |
| 957 |
><A |
| 958 |
NAME="INTERNAL-DBD-DECODE-BINARY" |
| 959 |
>3.4.13. _dbd_decode_binary</A |
| 960 |
></H2 |
| 961 |
><DIV |
| 962 |
CLASS="FUNCSYNOPSIS" |
| 963 |
><P |
| 964 |
></P |
| 965 |
><A |
| 966 |
NAME="AEN1045" |
| 967 |
></A |
| 968 |
><P |
| 969 |
><CODE |
| 970 |
><CODE |
| 971 |
CLASS="FUNCDEF" |
| 972 |
>size_t <B |
| 973 |
CLASS="FSFUNC" |
| 974 |
>_dbd_decode_binary</B |
| 975 |
></CODE |
| 976 |
>(const unsigned char *<VAR |
| 977 |
CLASS="PDPARAM" |
| 978 |
>in</VAR |
| 979 |
>, unsigned char *<VAR |
| 980 |
CLASS="PDPARAM" |
| 981 |
>out</VAR |
| 982 |
>);</CODE |
| 983 |
></P |
| 984 |
><P |
| 985 |
></P |
| 986 |
></DIV |
| 987 |
><P |
| 988 |
>Decodes a zero-terminated string with escaped characters as created by <A |
| 989 |
HREF="helperfuncs.html#INTERNAL-DBD-ENCODE-BINARY" |
| 990 |
>_dbd_encode_binary</A |
| 991 |
>.</P |
| 992 |
><P |
| 993 |
></P |
| 994 |
><DIV |
| 995 |
CLASS="VARIABLELIST" |
| 996 |
><DL |
| 997 |
><DT |
| 998 |
>Arguments</DT |
| 999 |
><DD |
| 1000 |
><P |
| 1001 |
><TT |
| 1002 |
CLASS="LITERAL" |
| 1003 |
>in</TT |
| 1004 |
>: Pointer to the input string.</P |
| 1005 |
><P |
| 1006 |
><TT |
| 1007 |
CLASS="LITERAL" |
| 1008 |
>out</TT |
| 1009 |
>: Pointer to allocated memory which will receive the unescaped string. The output string is always shorter than the input string, i.e. if the size of <CODE |
| 1010 |
CLASS="PARAMETER" |
| 1011 |
>out</CODE |
| 1012 |
> is the same as the size of <CODE |
| 1013 |
CLASS="PARAMETER" |
| 1014 |
>in</CODE |
| 1015 |
>, you're on the safe side. The implementation allows to decode the string in place, i.e. <CODE |
| 1016 |
CLASS="PARAMETER" |
| 1017 |
>out</CODE |
| 1018 |
> may be the same as <CODE |
| 1019 |
CLASS="PARAMETER" |
| 1020 |
>in</CODE |
| 1021 |
>.</P |
| 1022 |
></DD |
| 1023 |
><DT |
| 1024 |
><EM |
| 1025 |
>Returns</EM |
| 1026 |
></DT |
| 1027 |
><DD |
| 1028 |
><P |
| 1029 |
>The length, in bytes, of the unescaped binary string.</P |
| 1030 |
></DD |
| 1031 |
></DL |
| 1032 |
></DIV |
| 1033 |
></DIV |
| 1034 |
></DIV |
| 1035 |
><DIV |
| 1036 |
CLASS="NAVFOOTER" |
| 1037 |
><HR |
| 1038 |
ALIGN="LEFT" |
| 1039 |
WIDTH="100%"><TABLE |
| 1040 |
SUMMARY="Footer navigation table" |
| 1041 |
WIDTH="100%" |
| 1042 |
BORDER="0" |
| 1043 |
CELLPADDING="0" |
| 1044 |
CELLSPACING="0" |
| 1045 |
><TR |
| 1046 |
><TD |
| 1047 |
WIDTH="33%" |
| 1048 |
ALIGN="left" |
| 1049 |
VALIGN="top" |
| 1050 |
><A |
| 1051 |
HREF="driverfuncs-publicdbquery.html" |
| 1052 |
ACCESSKEY="P" |
| 1053 |
>Prev</A |
| 1054 |
></TD |
| 1055 |
><TD |
| 1056 |
WIDTH="34%" |
| 1057 |
ALIGN="center" |
| 1058 |
VALIGN="top" |
| 1059 |
><A |
| 1060 |
HREF="index.html" |
| 1061 |
ACCESSKEY="H" |
| 1062 |
>Home</A |
| 1063 |
></TD |
| 1064 |
><TD |
| 1065 |
WIDTH="33%" |
| 1066 |
ALIGN="right" |
| 1067 |
VALIGN="top" |
| 1068 |
><A |
| 1069 |
HREF="copying-fdl.html" |
| 1070 |
ACCESSKEY="N" |
| 1071 |
>Next</A |
| 1072 |
></TD |
| 1073 |
></TR |
| 1074 |
><TR |
| 1075 |
><TD |
| 1076 |
WIDTH="33%" |
| 1077 |
ALIGN="left" |
| 1078 |
VALIGN="top" |
| 1079 |
>Public Database Query Functions</TD |
| 1080 |
><TD |
| 1081 |
WIDTH="34%" |
| 1082 |
ALIGN="center" |
| 1083 |
VALIGN="top" |
| 1084 |
><A |
| 1085 |
HREF="driverfuncs.html" |
| 1086 |
ACCESSKEY="U" |
| 1087 |
>Up</A |
| 1088 |
></TD |
| 1089 |
><TD |
| 1090 |
WIDTH="33%" |
| 1091 |
ALIGN="right" |
| 1092 |
VALIGN="top" |
| 1093 |
>GNU Free Documentation License</TD |
| 1094 |
></TR |
| 1095 |
></TABLE |
| 1096 |
></DIV |
| 1097 |
></BODY |
| 1098 |
></HTML |
| 1099 |
> |