Max 5 API Reference
Max 5 API Reference
00001 /* 00002 ext_database.h 00003 Copyright 2008 - Cycling '74 00004 Timothy Place, tim@cycling74.com 00005 */ 00006 00007 #ifndef _EXT_DATABASE_H_ 00008 #define _EXT_DATABASE_H_ 00009 00010 #include "ext.h" 00011 #include "ext_obex.h" 00012 00013 #ifdef WIN_VERSION 00014 #ifndef snprintf 00015 #define snprintf _snprintf 00016 #endif 00017 #endif 00018 00019 00020 /** A database object. 00021 Use db_open() and db_close() to create and free database objects. 00022 @ingroup database */ 00023 typedef t_object t_database; 00024 00025 00026 /** A database result object. 00027 This is what the database object returns when a query is executed. 00028 @ingroup database */ 00029 typedef t_object t_db_result; 00030 00031 00032 /** A database view object. 00033 A database view wraps a query and a result for a given database, and is always updated and in-sync with the database. 00034 @ingroup database */ 00035 typedef t_object t_db_view; 00036 00037 00038 BEGIN_USING_C_LINKAGE 00039 00040 00041 /** Create an instance of a database. 00042 @ingroup database 00043 @param dbname The name of the database. 00044 @param fullpath If a database with this dbname is not already open, 00045 this will specify a full path to the location where the database is stored on disk. 00046 If NULL is passed for this argument, the database will reside in memory only. 00047 The path should be formatted as a Max style path. 00048 @param db The address of a #t_database pointer that will be set to point to the new database instance. 00049 If the pointer is not NULL, then it will be treated as a pre-existing database instance 00050 and thus will be freed. 00051 @return An error code. */ 00052 t_max_err db_open(t_symbol *dbname, const char *fullpath, t_database **db); 00053 00054 00055 /** Close an open database. 00056 @ingroup database 00057 @param db The address of the #t_database pointer for your database instance. 00058 The pointer will be freed and set NULL upon return. 00059 @return An error code. */ 00060 t_max_err db_close(t_database **db); 00061 00062 00063 /** Execute a SQL query on the database. 00064 @ingroup database 00065 @param db The #t_database pointer for your database instance. 00066 @param dbresult The address of a #t_db_result pointer. 00067 If the pointer is passed-in set to NULL then a new dbresult will be created. 00068 If the pointer is not NULL then it is assumed to be a valid dbresult, which will be filled in with the query results. 00069 When you are done with the dbresult you should free it with object_free(). 00070 @param sql A C-string containing a valid SQL query, possibly with sprintf() formatting codes. 00071 @param ... If an sprintf() formatting codes are used in the sql string, these values will be interpolated into the sql string. 00072 @return An error code. */ 00073 t_max_err db_query(t_database *db, t_db_result **dbresult, const char *sql, ...); 00074 00075 00076 /** Execute a SQL query on the database, temporarily overriding the database's error logging attribute. 00077 @ingroup database 00078 @param db The #t_database pointer for your database instance. 00079 @param dbresult The address of a #t_db_result pointer. 00080 If the pointer is passed-in set to NULL then a new dbresult will be created. 00081 If the pointer is not NULL then it is assumed to be a valid dbresult, which will be filled in with the query results. 00082 When you are done with the dbresult you should free it with object_free(). 00083 @param sql A C-string containing a valid SQL query, possibly with sprintf() formatting codes. 00084 @param ... If an sprintf() formatting codes are used in the sql string, these values will be interpolated into the sql string. 00085 @return An error code. */ 00086 t_max_err db_query_silent(t_database *db, t_db_result **dbresult, const char *sql, ...); 00087 00088 00089 /** Determine the id (key) number for the most recent INSERT query executed on the database. 00090 @ingroup database 00091 @param db The #t_database pointer for your database instance. 00092 @param id The address of a variable to hold the result on return. 00093 @return An error code. */ 00094 t_max_err db_query_getlastinsertid(t_database *db, long *id); 00095 00096 00097 /** Create a new table in a database. 00098 @ingroup database 00099 @param db The #t_database pointer for your database instance. 00100 @param tablename The name to use for the new table. 00101 The new table will be created with one column, which holds the primary key for the table, 00102 and is named according the form {tablename}_id. 00103 @return An error code. */ 00104 t_max_err db_query_table_new(t_database *db, const char *tablename); 00105 00106 00107 /** Add a new column to an existing table in a database. 00108 @ingroup database 00109 @param db The #t_database pointer for your database instance. 00110 @param tablename The name of the table to which the column should be added. 00111 @param columnname The name to use for the new column. 00112 @param columntype The SQL type for the data that will be stored in the column. 00113 For example: "INTEGER" or "VARCHAR" 00114 @param flags If you wish to specify any additional information for the column, then pass that here. 00115 Otherwise pass NULL. 00116 @return An error code. */ 00117 t_max_err db_query_table_addcolumn(t_database *db, const char *tablename, const char *columnname, const char *columntype, const char *flags); 00118 00119 00120 /** Begin a database transaction. 00121 When you are working with a file-based database, then the database will not be flushed to disk until db_transacation_end() is called. 00122 This means that you can _much_ more efficiently execute a sequence of queries in one transaction rather than independently. 00123 00124 That database object reference counts transactions, so it is possible nest calls to db_transacation_start() and db_transacation_end(). 00125 It is important to balance all calls with db_transacation_end() or the database contents will never be flushed to disk. 00126 00127 @ingroup database 00128 @param db The #t_database pointer for your database instance. 00129 @return An error code. */ 00130 t_max_err db_transaction_start(t_database *db); 00131 00132 00133 /** Finalize a database transaction. 00134 @ingroup database 00135 @param db The #t_database pointer for your database instance. 00136 @return An error code. */ 00137 t_max_err db_transaction_end(t_database *db); 00138 00139 00140 /** Force any open transactions to close. 00141 @ingroup database 00142 @param db The #t_database pointer for your database instance. 00143 @return An error code. */ 00144 t_max_err db_transaction_flush(t_database *db); 00145 00146 00147 // DB VIEWS 00148 00149 /** A database view is a way of looking at a particular set of records in the database. 00150 This particular set of records is defined with a standard SQL query, 00151 and the view maintains a copy of the results of the query internally. 00152 Any time the database is modified the internal result set is updated, 00153 and any objects listening to the view are notified via object_notify(). 00154 00155 @ingroup database 00156 @param db The #t_database pointer for your database instance. 00157 @param sql A SQL query that defines the set of results provided by the view. 00158 @param dbview The address of a NULL #t_db_view pointer which will be set with the new view upon return. 00159 @return An error code. */ 00160 t_max_err db_view_create(t_database *db, const char *sql, t_db_view **dbview); 00161 00162 00163 /** Remove a database view created using db_view_create(). 00164 @ingroup database 00165 @param db The #t_database pointer for your database instance for which this view was created. 00166 @param dbview The address of the #t_db_view pointer for the view. 00167 This pointer will be freed and set NULL upon return. 00168 @return An error code. */ 00169 t_max_err db_view_remove(t_database *db, t_db_view **dbview); 00170 00171 00172 /** Fetch the pointer for a #t_db_view's query result. 00173 @ingroup database 00174 @param dbview The #t_db_view pointer for your database view instance. 00175 @param result The address of a pointer to a #t_db_result object. 00176 This pointer will be overwritten with the view's result pointer upon return. 00177 @return An error code. */ 00178 t_max_err db_view_getresult(t_db_view *dbview, t_db_result **result); 00179 00180 00181 /** Set the query used by the view. 00182 @ingroup database 00183 @param dbview The #t_db_view pointer for your database view instance. 00184 @param newquery The SQL string to define a new query for the view, replacing the old query. 00185 @return An error code. */ 00186 t_max_err db_view_setquery(t_db_view *dbview, char *newquery); 00187 00188 00189 // DB RESULTS 00190 00191 /** Return the next record from a set of results that you are walking. 00192 When you are returned a result from a query of the database, 00193 the result is prepared for walking the results from the beginning. 00194 You can also reset the result manually to the beginning of the record list 00195 by calling db_result_reset(). 00196 00197 @ingroup database 00198 @param result The #t_db_result pointer for your query results. 00199 @return An array of C-Strings with the values for every requested column (field) of a database record. 00200 To find out how many columns are represented in the array, use db_result_numfields(). */ 00201 char** db_result_nextrecord(t_db_result *result); 00202 00203 00204 /** Reset the interface for walking a result's record list to the first record. 00205 @ingroup database 00206 @param result The #t_db_result pointer for your query results. */ 00207 void db_result_reset(t_db_result *result); 00208 00209 00210 /** Zero-out a database result. 00211 @ingroup database 00212 @param result The #t_db_result pointer for your query results. */ 00213 void db_result_clear(t_db_result *result); 00214 00215 00216 /** Return a count of all records in the query result. 00217 @ingroup database 00218 @param result The #t_db_result pointer for your query results. 00219 @return The count of records in the query result. */ 00220 long db_result_numrecords(t_db_result *result); 00221 00222 00223 /** Return a count of all fields (columns) in the query result. 00224 @ingroup database 00225 @param result The #t_db_result pointer for your query results. 00226 @return The count of fields in the query result. */ 00227 long db_result_numfields(t_db_result *result); 00228 00229 00230 /** Return the name of a field specified by its index number. 00231 @ingroup database 00232 @param result The #t_db_result pointer for your query results. 00233 @param fieldindex The zero-based index number of the field (column) in the result. 00234 @return A C-String with the name of the field. */ 00235 char* db_result_fieldname(t_db_result *result, long fieldindex); 00236 00237 00238 /** Return a single value from a result according to its index and field coordinates. 00239 @ingroup database 00240 @param result The #t_db_result pointer for your query results. 00241 @param recordindex The zero-based index number of the record (row) in the result. 00242 @param fieldindex The zero-based index number of the field (column) in the result. 00243 @return A C-String with the content of the specified cell in the result. */ 00244 char* db_result_string(t_db_result *result, long recordindex, long fieldindex); 00245 00246 /** Return a single value from a result according to its index and field coordinates. 00247 @ingroup database 00248 @param result The #t_db_result pointer for your query results. 00249 @param recordindex The zero-based index number of the record (row) in the result. 00250 @param fieldindex The zero-based index number of the field (column) in the result. 00251 @return The content of the specified cell from the result scanned out to a long int. */ 00252 long db_result_long(t_db_result *result, long recordindex, long fieldindex); 00253 00254 /** Return a single value from a result according to its index and field coordinates. 00255 @ingroup database 00256 @param result The #t_db_result pointer for your query results. 00257 @param recordindex The zero-based index number of the record (row) in the result. 00258 @param fieldindex The zero-based index number of the field (column) in the result. 00259 @return The content of the specified cell from the result scanned out to a float. */ 00260 float db_result_float(t_db_result *result, long recordindex, long fieldindex); 00261 00262 /** Return a single value from a result according to its index and field coordinates. 00263 The value will be coerced from an expected datetime field into seconds. 00264 @ingroup database 00265 @param result The #t_db_result pointer for your query results. 00266 @param recordindex The zero-based index number of the record (row) in the result. 00267 @param fieldindex The zero-based index number of the field (column) in the result. 00268 @return The datetime represented in seconds. */ 00269 unsigned long db_result_datetimeinseconds(t_db_result *result, long recordindex, long fieldindex); 00270 00271 00272 // UTILITIES 00273 00274 /** A utility to convert from a sql datetime string into seconds. 00275 @ingroup database 00276 @param string A C-string containing a date and time in SQL format. 00277 @param date The datetime represented in seconds upon return. */ 00278 void db_util_stringtodate(const char *string, unsigned long *date); 00279 00280 00281 /** A utility to convert from seconds into a sql-ready datetime string. 00282 @ingroup database 00283 @param date The datetime represented in seconds. 00284 @param string The address of a valid C-string 00285 whose contents will be set to a SQL-ready string format upon return. */ 00286 void db_util_datetostring(const unsigned long date, char *string); 00287 00288 00289 END_USING_C_LINKAGE 00290 00291 00292 #endif // _EXT_DATABASE_H_
Copyright © 2008, Cycling '74