Appendix G: C API
|
|
The C API comes with MySQL distributions and is included in the mysqlclient library. Many of the MySQL clients are written in C, and most of the APIs from other languages use the C API (take a look at the similarity between the C and PHP functions, for example). You can also use the C API for C++ development; for an object-oriented approach, you can use MySQL++, available from the MySQL website (www.mysql.com).
C API Data Types
The C data types represent the data you'll be dealing with when interacting with the database server. They are of different types, some being structures and others being simple Booleans, for example. You'll need to become familiar with these types, and which functions return them or use them as arguments, to master the C API.
my_ulonglong
A numeric type from –1 to 1.84e19, used for return values from functions such as mysql_ affected_rows(), mysql_num_rows(), and mysql_insert_id().
MYSQL
A database handle (a connection to the database server). The variable is initialized with the mysql_init() function and used by most of the API functions.
MYSQL_FIELD
Field data, returned from the mysql_fetch_field() function, including the fieldname, type, and size. The actual field values are stored in the MYSQL_ROW structure. You can find the following members in the structure:
char * name The fieldname as a null-terminated string.
char * table The table containing the field or an empty string if there is none (such as a calculated field).
char * def The field's default value as a null-terminated string. This is only available if the mysql_list_fields() function was used to return MYSQL_RES.
enum enum_field_types type The field type. The value here corresponds to the MySQL field type as shown in Table G.1.
| Value | MySQL Type |
|---|---|
| FIELD_TYPE_TINY | TINYINT |
| FIELD_TYPE_SHORT | SMALLINT |
| FIELD_TYPE_LONG | INTEGER |
| FIELD_TYPE_INT24 | MEDIUMINT |
| FIELD_TYPE_LONGLONG | BIGINT |
| FIELD_TYPE_DECIMAL | DECIMAL or NUMERIC |
| FIELD_TYPE_FLOAT | FLOAT |
| FIELD_TYPE_DOUBLE | DOUBLE or REAL |
| FIELD_TYPE_TIMESTAMP | TIMESTAMP |
| FIELD_TYPE_DATE | DATE |
| FIELD_TYPE_TIME | TIME |
| FIELD_TYPE_DATETIME | DATETIME |
| FIELD_TYPE_YEAR | YEAR |
| FIELD_TYPE_STRING | CHAR or VARCHAR |
| FIELD_TYPE_BLOB | BLOB or TEXT |
| FIELD_TYPE_SET | SET |
| FIELD_TYPE_ENUM | ENUM |
| FIELD_TYPE_NULL | NULL-type |
| FIELD_TYPE_CHAR | Deprecated, replaced by FIELD_TYPE_TINY |
unsigned int length The maximum width of the field, determined by the table definition.
unsigned int max_length The largest width of a field in the result set. Often confused with the length member, but max_length will usually be smaller. This will contain zero if it was the mysql_use_result() function that returned MYSQL_RES.
unsigned int flags Any of the flags shown in Table G.2 can be set; they provide extra information about the field.
| Flag | Description |
|---|---|
| NOT_NULL_FLAG | Defined as NOT NULL |
| PRI_KEY_FLAG | Part of the primary key |
| UNIQUE_KEY_FLAG | Part of a unique key |
| MULTIPLE_KEY_FLAG | Part of a nonunique key |
| UNSIGNED_FLAG | Defined as UNSIGNED |
| ZEROFILL_FLAG | Defined with ZEROFILL |
| BINARY_FLAG | Defined as BINARY |
| AUTO_INCREMENT_FLAG | Defined as an AUTO_INCREMENT field |
| ENUM_FLAG | Defined as an ENUM (deprecated, use FIELD_TYPE_ENUM) |
| SET_FLAG | Defined as a SET (deprecated, use FIELD_TYPE_SET) |
| BLOB_FLAG | Defined as a BLOB or TEXT (deprecated, use FIELD_TYPE_BLOB) |
| TIMESTAMP_FLAG | Defined as a TIMESTAMP (deprecated, use FIELD_TYPE_TIMESTAMP) |
The following is an example of using one of these options:
if (field->flags & MULTIPLE_KEY_FLAG) { /* do something with the fact that the field is a multiple key */ } The macros shown in Table G.3 ease the testing of some of the flag values.
| Macro | Description |
|---|---|
| IS_NOT_NULL(flags) | True if the field is defined as NOT NULL |
| IS_PRI_KEY(flags) | True if the field is, or is part of, a primary key |
| IS_BLOB(flags) | True if the field is a BLOB or TEXT (deprecated, use FIELD_TYPE_BLOB instead) |
| IS_NUM(flags) | True if the field is numeric |
unsigned int decimals The number of decimal places used by a numeric.
MYSQL_FIELD_OFFSET
Represents the position of the field pointer within a field list, beginning at 0 for the first field. It is used by the mysql_field_seek() function.
MYSQL_RES
A structure containing the results of a query that returns data (such as SELECT, DESCRIBE, SHOW, or EXPLAIN).
MYSQL_ROW
A single row of data, obtained from the mysql_fetch_row() function. All data is represented as an array of strings that may contain null bytes if any of the data is binary.
|
|
