00001 /*! \file kogmo_rtdb_funcs.h 00002 * \brief Functions to Access the Real-time Vehicle Database (C-Interface). 00003 * 00004 * Copyright (c) 2003-2006 Matthias Goebl <matthias.goebl*goebl.net> 00005 * Lehrstuhl fuer Realzeit-Computersysteme (RCS) 00006 * Technische Universitaet Muenchen (TUM) 00007 */ 00008 00009 #ifndef KOGMO_RTDB_FUNCS_H 00010 #define KOGMO_RTDB_FUNCS_H 00011 00012 #include <errno.h> /* error codes are based on them so far, see kogmo_rtdb_error */ 00013 #include <pthread.h> 00014 #include "kogmo_rtdb_types.h" 00015 00016 #ifdef __cplusplus 00017 namespace KogniMobil { 00018 extern "C" { 00019 #define _const const //!< constant argument for inclusion in C++ 00020 #else /* no C++ */ 00021 #define _const //!< constant argument, but irrelevant in C 00022 #endif 00023 00024 00025 /*! \defgroup kogmo_rtdb_conn C-Functions for Connection Handling 00026 */ 00027 00028 /*! \defgroup kogmo_rtdb_meta C-Functions for Object Metadata Handling: Add, Remove, Search and Wait for Objects. 00029 * 00030 * \brief Using these functions you can create new objects within the database 00031 * and allocate space for actual data-block. You can also search for existing objects. 00032 * 00033 * See kogmo_rtdb_data on how to read and write object data. 00034 * 00035 * Those functions will be found mostly in the initialization section of applications. 00036 * 00037 * The object metadata is defined in kogmo_rtdb_obj_info_t. 00038 */ 00039 /*@{*/ 00040 00041 00042 00043 /*! \brief Initialize Metadata for a new Object 00044 * 00045 * Zeros the metadata, fills it with defaults (e.g. the cycle time of the calling process) 00046 * and the given parameters. 00047 * 00048 * This function is for convenience and only helps to initialize the 00049 * metadata structure. 00050 * It does not yet create the object and does not modify the database. 00051 * 00052 * \param db_h Database handle 00053 * \param metadata_p Pointer to an Object-Metadata structure, that must be previously allocated by the user 00054 * \param name Name for the new Object; non-empty, 00055 * allowed characters: a-z, A-Z, 0-9, "-", "_"; do not use "*","?" or "~" 00056 * \param otype Type-Identifier for the new Object, see kogmo_rtdb_objtype for a list. 00057 * \param size_max Maximum size for object data, use sizeof(your_object_t) 00058 * \returns <0 on errors 00059 * 00060 * See also kogmo_rtdb_obj_info_t 00061 */ 00062 int 00063 kogmo_rtdb_obj_initinfo (kogmo_rtdb_handle_t *db_h, 00064 kogmo_rtdb_obj_info_t *metadata_p, 00065 _const char* name, kogmo_rtdb_objtype_t otype, 00066 kogmo_rtdb_objsize_t size_max); 00067 00068 00069 /*! \brief Insert a new Object into the Database 00070 * 00071 * This inserts the metadata into the database and 00072 * allocates the space for the object data blocks within the database. 00073 * 00074 * \param db_h Database handle 00075 * \param metadata_p Pointer to previously set up Object-Metadata 00076 * \returns <0 on errors, new Object-ID on success 00077 * \n(the new Object-ID will also be written into the given metadata_p). 00078 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters within your metadata_p. 00079 * \retval -KOGMO_RTDB_ERR_NOTUNIQ There is already an (unique) object, that cannot coexist with your new (unique) object. 00080 * \retval -KOGMO_RTDB_ERR_NOMEMORY Not enough memory within the database for the new object and its history, 00081 * restart the manager with a larger KOGMO_RTDB_HEAPSIZE. 00082 * \retval -KOGMO_RTDB_ERR_OUTOFOBJ Out of object slots (recompile the database with a higher KOGMO_RTDB_OBJ_MAX). 00083 * Be aware, that object slots are freed after their history_interval is expired. 00084 * This error also occurs when the OID reaches its maximum and a restart is required 00085 * (the OID is large enough that this should not happen within normal operation). 00086 */ 00087 kogmo_rtdb_objid_t 00088 kogmo_rtdb_obj_insert (kogmo_rtdb_handle_t *db_h, 00089 kogmo_rtdb_obj_info_t *metadata_p); 00090 00091 00092 /*! \brief Delete an existing Object 00093 * 00094 * This removes an object, including its metadata and object data blocks. 00095 * 00096 * \note 00097 * The object is only marked as deleted. Its history will still remain in the database for the time specified as 00098 * history_interval. After this time the database manager process will actually delete it. 00099 * - Only the metadata given at kogmo_rtdb_obj_insert() will be used! 00100 * You cannot change the history_interval later. 00101 * - If you want your objects to be removed immediately, create them with immediately_delete set. 00102 * - If the deleted object has child objects with parent_delete set, they will also be deleted. 00103 * 00104 * \param db_h Database handle 00105 * \param metadata_p Pointer to its Object-Metadata (only the Object-ID 00106 * will be used) 00107 * \returns <0 on errors 00108 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (your metadata_p is NULL). 00109 * \retval -KOGMO_RTDB_ERR_NOTFOUND An object with the specified OID cannot be found or is already marked for deletion. 00110 * \retval -KOGMO_RTDB_ERR_NOPERM You are not allowed to delete this object. 00111 */ 00112 int 00113 kogmo_rtdb_obj_delete (kogmo_rtdb_handle_t *db_h, 00114 kogmo_rtdb_obj_info_t *metadata_p); 00115 00116 00117 /*! \brief Read the Metadata of an Object given by its Object-ID. 00118 * 00119 * This function retrieves the metadata and copies it into the given metadata_p. 00120 * 00121 * \note 00122 * Because you need only the Object-ID to read the object data, 00123 * it is not necessary to retrieve the metadata first. 00124 * 00125 * \param db_h Database handle 00126 * \param oid The Object-ID of the object you want to access 00127 * \param ts Normally just 0 for "now"; with this timestamp you can specify 00128 * a point in time at which the Object was alive (and therefore not yet 00129 * deleted) 00130 * \param metadata_p Pointer to a user-preallocated object metadata structure that will be filled with a copy 00131 * of the Metadata of the Object 00132 * \returns <0 on errors 00133 * \retval -KOGMO_RTDB_ERR_NOTFOUND An object with the specified OID cannot be found or is already marked for deletion at the specified ts. 00134 */ 00135 int 00136 kogmo_rtdb_obj_readinfo (kogmo_rtdb_handle_t *db_h, 00137 kogmo_rtdb_objid_t oid, 00138 kogmo_timestamp_t ts, 00139 kogmo_rtdb_obj_info_t *metadata_p); 00140 00141 00142 /*! \brief Dump the Metadata of a given Object into an ASCII-String 00143 * 00144 * This is useful if you want to show the Metadata to the user, e.g. for debugging. 00145 * 00146 * \param db_h Database handle (needed to resolve e.g. process names) 00147 * \param metadata_p Pointer to the object metadata structure with the data to be dumped. 00148 * \returns Pointer to a string that will contain the dump in ASCII characters; 00149 * the user must FREE it by itself after usage!\n 00150 * NULL on errors 00151 * 00152 * Example: \code 00153 * char *text_p = kogmo_rtdb_obj_dumpinfo_str (&objmeta); 00154 * printf ("%s", text_p); free(text_p); \endcode 00155 */ 00156 char * 00157 kogmo_rtdb_obj_dumpinfo_str (kogmo_rtdb_handle_t *db_h, 00158 kogmo_rtdb_obj_info_t *metadata_p); 00159 00160 00161 /*! \brief Find Objects by their Name, Parent, creating Process and Time. 00162 * 00163 * This function searches within the object metadata of all objects. 00164 * All specified fields must match (AND), a 0 or NULL means any value. 00165 * 00166 * \note 00167 * Standard use case: There is at most one object, that matches your search criteria. 00168 * To find this object, set idlist=NULL and nth=1. 00169 * 00170 * \param db_h Database handle 00171 * \param name Look only for objects matching the given name; use NULL or "" for any name; 00172 * start with ~ to specify a regular expression, e.g. "~^foobar.*$" 00173 * \param otype If !=0, find only objects with this type 00174 * \param parent_oid If !=0, find only objects whose parent has this object-ID 00175 * \param proc_oid If !=0, find only objects created by this process-ID, 00176 * see kogmo_rtdb_process 00177 * \param ts Timestamp at which the Object must have been alive (and not 00178 * marked deleted); 0 means "now" 00179 * \param idlist If not NULL, the resulting list of object-IDs will be written 00180 * into this user-preallocated array, terminated by an element with ID 0. The 00181 * maximum size is fixed, see kogmo_rtdb_objid_list. 00182 * When you want an idlist, you normally set nth=0. 00183 * \param nth If !=0, stop the search after the n-th occurrence 00184 * (starting with 1). 00185 * So if you want the oid of the first hit, set idlist=NULL and nth=1. 00186 * Set nth=2 for the second hit, and so on. 00187 * \returns <0 on errors,\n 00188 * if idlist=NULL: the object-ID of the nth result,\n 00189 * if an idlist!=NULL is given, the real number of matching objects (can be 00190 * higher than the length of idlist!) 00191 * \retval -KOGMO_RTDB_ERR_NOTFOUND There are no objects that match your search criteria. 00192 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (parent object does not exist (at that time), invalid regular expression). 00193 */ 00194 kogmo_rtdb_objid_t 00195 kogmo_rtdb_obj_searchinfo (kogmo_rtdb_handle_t *db_h, 00196 _const char *name, 00197 kogmo_rtdb_objtype_t otype, 00198 kogmo_rtdb_objid_t parent_oid, 00199 kogmo_rtdb_objid_t proc_oid, 00200 kogmo_timestamp_t ts, 00201 kogmo_rtdb_objid_list_t idlist, 00202 int nth); 00203 00204 00205 /*! \brief Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists. 00206 * 00207 * This function searches and waits if necessary until there is an object, 00208 * whose metadata matches your criteria. 00209 * If no object cannot be found, this functions blocks and waits until 00210 * another process creates an suitable object. 00211 * If there is such an object, the result is exactly the same as 00212 * kogmo_rtdb_obj_searchinfo(...,idlist=NULL,nth=1). 00213 * 00214 * This function searches only in the object metadata. 00215 * 00216 * \note 00217 * You should use kogmo_rtdb_obj_searchinfo_wait() within the initialization stage 00218 * of your software. So you don't need to arrange for a certain start order, 00219 * as the needed objects are found as soon as they get created. 00220 * \n If you want to check for new objects within your main loop, 00221 * you might prefer kogmo_rtdb_obj_searchinfo() or kogmo_rtdb_obj_searchinfo_wait_until(). 00222 * 00223 * 00224 * \param db_h Database handle 00225 * \param name Look only for objects matching the given name; use NULL or "" for any name; 00226 * start with ~ to specify a regular expression, e.g. "~^foobar.*$" 00227 * \param otype If !=0, find only objects with this type 00228 * \param parent_oid If !=0, find only objects whose parent has this object-ID 00229 * \param proc_oid If !=0, find only objects created by this process-ID, 00230 * see kogmo_rtdb_process 00231 * \returns <0 on errors, otherwise the object-ID of the first matching object is returned 00232 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (parent object does not exist (at that time) 00233 * or has been deleted (to avoid waiting forever), invalid regular expression). 00234 */ 00235 kogmo_rtdb_objid_t 00236 kogmo_rtdb_obj_searchinfo_wait(kogmo_rtdb_handle_t *db_h, 00237 _const char *name, 00238 kogmo_rtdb_objtype_t otype, 00239 kogmo_rtdb_objid_t parent_oid, 00240 kogmo_rtdb_objid_t proc_oid); 00241 00242 00243 /*! \brief Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists, but return after a Timeout. 00244 * 00245 * This function searches and waits if necessary until there is an object, 00246 * whose metadata matches your criteria, exactly like kogmo_rtdb_obj_searchinfo_wait(). 00247 * However it stops blocking and returns after a given timeout. 00248 * 00249 * \param db_h Database handle 00250 * \param name Look only for objects matching the given name; use NULL or "" for any name; 00251 * start with ~ to specify a regular expression, e.g. "~^foobar.*$" 00252 * \param otype If !=0, find only objects with this type 00253 * \param parent_oid If !=0, find only objects whose parent has this object-ID 00254 * \param proc_oid If !=0, find only objects created by this process-ID, 00255 * see kogmo_rtdb_process 00256 * \param wakeup_ts Absolute Time at which to wake up and return if there is still no object found, 00257 * 0 means infinite (like kogmo_rtdb_obj_searchinfo_wait()) 00258 * \returns <0 on errors, otherwise the object-ID of the first matching object is returned 00259 * \retval -KOGMO_RTDB_ERR_TIMEOUT A timeout occurred. 00260 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (parent object does not exist (at that time) 00261 * or has been deleted (to avoid waiting forever), invalid regular expression). 00262 */ 00263 kogmo_rtdb_objid_t 00264 kogmo_rtdb_obj_searchinfo_wait_until(kogmo_rtdb_handle_t *db_h, 00265 _const char *name, 00266 kogmo_rtdb_objtype_t otype, 00267 kogmo_rtdb_objid_t parent_oid, 00268 kogmo_rtdb_objid_t proc_oid, 00269 kogmo_timestamp_t wakeup_ts); 00270 00271 00272 /*! \brief Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change. 00273 * 00274 * When you call this function the first time, it returns a list of objects, that 00275 * match your search criteria (known_idlist). When you call it again, it compares 00276 * this list with the current situation and waits until 00277 * there is a change. Then the list (known_idlist) will be updated, and a list of the newly 00278 * added or deleted objects is also returned (added_idlist and deleted_idlist). 00279 * 00280 * This function searches only in the object metadata. 00281 * 00282 * \param db_h Database handle 00283 * \param name Look only for objects matching the given name; use NULL or "" for any name; 00284 * start with ~ to specify a regular expression, e.g. "~^foobar.*$" 00285 * \param otype If !=0, find only objects with this type 00286 * \param parent_oid If !=0, find only objects whose parent has this object-ID 00287 * \param proc_oid If !=0, find only objects created by this process-ID, 00288 * see kogmo_rtdb_process 00289 * \param known_idlist The list of object-IDs already known and found in a previous call from kogmo_rtdb_obj_searchinfo(). 00290 * This list will be automatically updated. You must initialize it with known_idlist[0]=0. 00291 * \param added_idlist The list of newly created objects. 00292 * \param deleted_idlist The list of newly deleted objects. 00293 * \returns <0 on error, otherwise the sum of created plus deleted objects. 00294 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (parent object does not exist (at that time) 00295 * or has been deleted (to avoid waiting forever), invalid regular expression). 00296 */ 00297 int 00298 kogmo_rtdb_obj_searchinfo_waitnext(kogmo_rtdb_handle_t *db_h, 00299 _const char *name, 00300 kogmo_rtdb_objtype_t otype, 00301 kogmo_rtdb_objid_t parent_oid, 00302 kogmo_rtdb_objid_t proc_oid, 00303 kogmo_rtdb_objid_list_t known_idlist, 00304 kogmo_rtdb_objid_list_t added_idlist, 00305 kogmo_rtdb_objid_list_t deleted_idlist); 00306 00307 00308 /*! \brief Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change, but return after a Timeout. 00309 * 00310 * This function works like kogmo_rtdb_obj_searchinfo_waitnext() with the distinction 00311 * that it stops blocking and returns after a given timeout. 00312 * 00313 * \param db_h Database handle 00314 * \param name Look only for objects matching the given name; use NULL or "" for any name; 00315 * start with ~ to specify a regular expression, e.g. "~^foobar.*$" 00316 * \param otype If !=0, find only objects with this type 00317 * \param parent_oid If !=0, find only objects whose parent has this object-ID 00318 * \param proc_oid If !=0, find only objects created by this process-ID, 00319 * see kogmo_rtdb_process 00320 * \param known_idlist The list of object-IDs already known and found in a previous call from kogmo_rtdb_obj_searchinfo(). 00321 * This list will be automatically updated. You must initialize it with known_idlist[0]=0 00322 * \param added_idlist The list of newly created objects. 00323 * \param deleted_idlist The list of newly deleted objects. 00324 * \param wakeup_ts Absolute Time at which to wake up and return if there is still no change, 00325 * 0 means infinite (like kogmo_rtdb_obj_searchinfo_waitnext()) 00326 * \returns <0 on error, otherwise the sum of created plus deleted objects. 00327 * \retval -KOGMO_RTDB_ERR_TIMEOUT A timeout occurred. 00328 * \retval -KOGMO_RTDB_ERR_INVALID Invalid parameters (parent object does not exist (at that time) 00329 * or has been deleted (to avoid waiting forever), invalid regular expression). 00330 */ 00331 int 00332 kogmo_rtdb_obj_searchinfo_waitnext_until(kogmo_rtdb_handle_t *db_h, 00333 _const char *name, 00334 kogmo_rtdb_objtype_t otype, 00335 kogmo_rtdb_objid_t parent_oid, 00336 kogmo_rtdb_objid_t proc_oid, 00337 kogmo_rtdb_objid_list_t known_idlist, 00338 kogmo_rtdb_objid_list_t added_idlist, 00339 kogmo_rtdb_objid_list_t deleted_idlist, 00340 kogmo_timestamp_t wakeup_ts); 00341 00342 /*@}*/ 00343 00344 00345 00346 00347 00348 00349 00350 /*! \defgroup kogmo_rtdb_data C-Functions for Object Data Handling: Read and Write Object Data. 00351 * 00352 * \brief These functions access the actual contents of the data-block 00353 * of a certain object at a given point in time. 00354 * 00355 * Those functions will be found mostly in the main loop of applications. 00356 * 00357 * Every data-block of an object begins with kogmo_rtdb_subobj_base_t, 00358 * see kogmo_rtdb_objects for their definition. 00359 */ 00360 /*@{*/ 00361 00362 00363 /*! \brief Initialize a new data block for an existing object. 00364 * 00365 * Zeros the data structure, and fills it with defaults (e.g. the maximum size from the given kogmo_rtdb_obj_info_t). 00366 * 00367 * This function is for convenience and only helps to locally initialize the 00368 * passed object data structure (that always begins with kogmo_rtdb_subobj_base_t). 00369 * It does not yet write the object data into the database. 00370 * 00371 * \param db_h Database handle 00372 * \param metadata_p Pointer to the Object-Metadata structure as retrieved from the database 00373 * \param data_p Pointer to an Object data structure, that has been previously allocated by the user 00374 * \returns <0 on errors 00375 */ 00376 int 00377 kogmo_rtdb_obj_initdata (kogmo_rtdb_handle_t *db_h, 00378 kogmo_rtdb_obj_info_t *metadata_p, 00379 void *data_p); 00380 00381 00382 00383 /*! \brief Write the local Data block of an Object to the Database. 00384 * 00385 * This function writes the Data-Block of an Object to the database; 00386 * this is used to update an object and is normally done at every cycle. 00387 * 00388 * \param db_h Database handle 00389 * \param oid Object-ID of the object to write 00390 * \param data_p Pointer to an object data structure that will be copied into the database 00391 * \returns <0 on errors 00392 * \retval -KOGMO_RTDB_ERR_NOTFOUND There is no object with the given object-id, the specified object has no space for data blocks (size=0). 00393 * \retval -KOGMO_RTDB_ERR_INVALID The data size not allowed (more than size_max in kogmo_rtdb_obj_info_t or less than kogmo_rtdb_subobj_base_t) 00394 * \retval -KOGMO_RTDB_ERR_NOPERM You are not allowed to write this object (see flags.write_allow) 00395 * \retval -KOGMO_RTDB_ERR_TOOFAST You are committing faster than the specified min_cycle_time and flags.cycle_watch is set) 00396 * 00397 * \note 00398 * - The data_p should point to a structure, that starts with a sub-structure of 00399 * kogmo_rtdb_subobj_base_t 00400 * - Set your kogmo_rtdb_subobj_base_t.size to the correct size of your 00401 * whole data-struct you want to commit 00402 * - Set kogmo_rtdb_obj_subbase_t.data_ts accordingly. 00403 * Do not commit data with timestamps old than in your last commit.\n 00404 * (TODO: check for it, maybe refuse it) 00405 */ 00406 int 00407 kogmo_rtdb_obj_writedata (kogmo_rtdb_handle_t *db_h, 00408 kogmo_rtdb_objid_t oid, 00409 void *data_p); 00410 00411 00412 /*! \brief Read the latest Data of an Object from the Database 00413 * 00414 * This function reads the latest Data-Block of an Object from the database 00415 * and writes it into a local structure of the calling process.\n 00416 * It finds the block with a committed_ts <= ts. 00417 * 00418 * \param db_h Database handle 00419 * \param oid Object-ID of the desired object 00420 * \param ts Timestamp at which the Object must be "the last committed"; 00421 * 0 for "now" 00422 * \param data_p Pointer to a local object data structure where the data found in the rtdb will be copied to 00423 * \param size Maximum size of the object data structure at data_p 00424 * \returns <0 on errors, the real size of the object data found in the rtdb on success 00425 * \retval -KOGMO_RTDB_ERR_NOTFOUND There is no object with the given object-id for the specified timestamp, the specified object has no data block (not yet or size=0). 00426 * \retval -KOGMO_RTDB_ERR_INVALID The Pointer is NULL, The data size not allowed (more than size_max in kogmo_rtdb_obj_info_t or less than kogmo_rtdb_subobj_base_t) 00427 * \retval -KOGMO_RTDB_ERR_NOPERM You are not allowed to read this object (see flags.read_deny) 00428 * \retval -KOGMO_RTDB_ERR_HISTWRAP A history wrap-around occurred: While reading this object, the data has been overwritten. 00429 * Either your reading process it too slow or the history_interval is to short. 00430 * \retval -KOGMO_RTDB_ERR_TOOFAST The data it stale (too old, now_ts-committed_ts > max_cycle_time) and 00431 * this check is active (flags.withhold_stale is set). 00432 */ 00433 kogmo_rtdb_objsize_t 00434 kogmo_rtdb_obj_readdata (kogmo_rtdb_handle_t *db_h, 00435 kogmo_rtdb_objid_t oid, 00436 kogmo_timestamp_t ts, 00437 void *data_p, 00438 kogmo_rtdb_objsize_t size); 00439 00440 00441 00442 /*! \brief Read the Data of an Object committed before a given Timestamp 00443 * 00444 * This function finds the nearest data block of an object within the database with a committed_ts < ts. 00445 * \see kogmo_rtdb_obj_readdata() 00446 */ 00447 kogmo_rtdb_objsize_t 00448 kogmo_rtdb_obj_readdata_older (kogmo_rtdb_handle_t *db_h, 00449 kogmo_rtdb_objid_t oid, 00450 kogmo_timestamp_t ts, 00451 void *data_p, 00452 kogmo_rtdb_objsize_t size); 00453 00454 00455 /*! \brief Read the Data of an Object committed after a given Timestamp 00456 * 00457 * This function finds the nearest data block of an object within the database with a committed_ts > ts. 00458 * \see kogmo_rtdb_obj_readdata() 00459 */ 00460 kogmo_rtdb_objsize_t 00461 kogmo_rtdb_obj_readdata_younger (kogmo_rtdb_handle_t *db_h, 00462 kogmo_rtdb_objid_t oid, 00463 kogmo_timestamp_t ts, 00464 void *data_p, 00465 kogmo_rtdb_objsize_t size); 00466 00467 00468 /*! \brief Read the Data of an Object from the Database that was valid for the given Data Timestamp. 00469 * 00470 * This function finds the nearest data block of an object within the database with a data_ts <= ts. 00471 * \see kogmo_rtdb_obj_readdata() 00472 */ 00473 kogmo_rtdb_objsize_t 00474 kogmo_rtdb_obj_readdata_datatime (kogmo_rtdb_handle_t *db_h, 00475 kogmo_rtdb_objid_t oid, 00476 kogmo_timestamp_t ts, 00477 void *data_p, 00478 kogmo_rtdb_objsize_t size); 00479 00480 00481 /*! \brief Read the Data of Object that has an Data Timestamp older than a given Timestamp. 00482 * 00483 * This function finds the nearest data block of an object within the database with a data_ts < ts. 00484 * \see kogmo_rtdb_obj_readdata() 00485 */ 00486 kogmo_rtdb_objsize_t 00487 kogmo_rtdb_obj_readdata_dataolder (kogmo_rtdb_handle_t *db_h, 00488 kogmo_rtdb_objid_t oid, 00489 kogmo_timestamp_t ts, 00490 void *data_p, 00491 kogmo_rtdb_objsize_t size); 00492 00493 00494 /*! \brief Read the Data of Object that has an Data Timestamp younger than a given Timestamp. 00495 * 00496 * This function finds the nearest data block of an object within the database with a data_ts > ts. 00497 * \see kogmo_rtdb_obj_readdata() 00498 */ 00499 kogmo_rtdb_objsize_t 00500 kogmo_rtdb_obj_readdata_datayounger (kogmo_rtdb_handle_t *db_h, 00501 kogmo_rtdb_objid_t oid, 00502 kogmo_timestamp_t ts, 00503 void *data_p, 00504 kogmo_rtdb_objsize_t size); 00505 00506 00507 00508 /*! \brief Get the latest Data for an Object that has been committed after a given timestamp, and wait if there is no newer data 00509 * 00510 * This function waits until the Data-Block of an Object has an 00511 * Commit-Timestamp greater than a given Timestamp (normally the last 00512 * known Timestamp). 00513 * 00514 * \param db_h database handle 00515 * \param oid Object-ID of the desired Object 00516 * \param old_ts Timestamp to compare with the Object-Data, 00517 * the commit-timestamp in the returned object will be greater than this one 00518 * \param data_p Pointer to a Object-Data-Struct where the found Data will 00519 * be copied 00520 * \param size Maximum size the Object-Data-Struct at data_p can absorb 00521 * \returns <0 on errors, size of found Object on success 00522 */ 00523 kogmo_rtdb_objsize_t 00524 kogmo_rtdb_obj_readdata_waitnext (kogmo_rtdb_handle_t *db_h, 00525 kogmo_rtdb_objid_t oid, 00526 kogmo_timestamp_t old_ts, 00527 void *data_p, 00528 kogmo_rtdb_objsize_t size); 00529 00530 00531 /*! \brief kogmo_rtdb_obj_readdata_waitnext() with pointer. 00532 * 00533 * \see kogmo_rtdb_obj_readdata_waitnext() and kogmo_rtdb_obj_readdata_ptr() 00534 */ 00535 kogmo_rtdb_objsize_t 00536 kogmo_rtdb_obj_readdata_waitnext_ptr (kogmo_rtdb_handle_t *db_h, 00537 kogmo_rtdb_objid_t oid, 00538 kogmo_timestamp_t old_ts, 00539 void *data_p, 00540 kogmo_rtdb_objsize_t size); 00541 00542 00543 00544 /*@}*/ 00545 00546 00547 00548 00549 /*! \defgroup kogmo_rtdb_dataptr C-Functions for Object Data Handling with directs Database Pointers: Do not use unless you need to. 00550 * 00551 * \brief These functions access the actual contents of the data-block 00552 * of a certain object. 00553 * 00554 * The difference to kogmo_rtdb_data is, that they work with pointers, 00555 * that point directly into the internal structures of the RTDB. 00556 * By misusing the pointer you get, you can severely damage the 00557 * internals of the RTDB. 00558 * 00559 * So please do not use those functions, unless you really need to. 00560 * With direct pointer operations you can save some time for objects 00561 * significantly larger than 10000 bytes. 00562 * 00563 */ 00564 /*@{*/ 00565 00566 00567 /*! \brief Get a Pointer to the latest Data of an Object within the Database 00568 * 00569 * This function returns a pointer, that points to the last object data 00570 * within the RTDB internals.\n 00571 * It finds the block with a committed_ts <= ts. 00572 * 00573 * At the end of your calculations you SHOULD call this function again and check 00574 * that your pointer is still the same and therefore valid! 00575 * If you get another pointer or an error, the data changed while you were using 00576 * it and your results are from corrupted data. Try it again or do an appropriate 00577 * error handling. 00578 * 00579 * \param db_h Database handle 00580 * \param oid Object-ID of the desired object 00581 * \param ts Timestamp at which the Object must be "the last committed"; 00582 * 0 for "now" 00583 * \param data_pp Pointer to a pointer, that will point to the object data structure for reading afterwards 00584 * \returns <0 on errors, the real size of the object data found in the rtdb on success 00585 * 00586 * Example: \code 00587 * kogmo_rtdb_obj_c3_blaobj_t *myobj_p; 00588 * kogmo_rtdb_obj_readdata_ptr(..,&myobj_p); 00589 * access data with e.g. myobj_p->base.data_ts 00590 * \endcode 00591 */ 00592 kogmo_rtdb_objsize_t 00593 kogmo_rtdb_obj_readdata_ptr (kogmo_rtdb_handle_t *db_h, 00594 kogmo_rtdb_objid_t oid, 00595 kogmo_timestamp_t ts, 00596 void *data_pp); 00597 00598 00599 /*! \brief Start pointer-based write (fast but dangerous) 00600 * 00601 * Call this function to receive a pointer where you can 00602 * write your data. If you are done, call kogmo_rtdb_obj_writedata_ptr_commit(). 00603 * 00604 * \param db_h Database handle 00605 * \param oid Object-ID of the object to write 00606 * \param data_pp Pointer to a pointer, that will point to the object data structure for writing afterwards 00607 * \returns <0 on errors 00608 * 00609 * 00610 * \note 00611 * - The object must be created and owned by the calling process. 00612 * - The object must not be public writable. 00613 * - The maximum length is objmeta.size_max. 00614 * - You must manually set base.size before each write. 00615 * - Be cautious! You can damage the whole database. 00616 * - DO NOT TOUCH base.committed_ts !!! 00617 * - Pointer operations are only useful for objects with sizes >= 10KB size. 00618 */ 00619 kogmo_rtdb_objsize_t 00620 kogmo_rtdb_obj_writedata_ptr_begin (kogmo_rtdb_handle_t *db_h, 00621 kogmo_rtdb_objid_t oid, 00622 void *data_pp); 00623 00624 00625 /*! \brief Finish pointer-based write and publish data 00626 * 00627 * Call this function when you are done writing your data to the area, 00628 * where you received a pointer from kogmo_rtdb_obj_writedata_ptr_begin(). 00629 * DO NOT MODIFY THE DATA AFTERWARDS !!! 00630 * 00631 * \param db_h Database handle 00632 * \param oid Object-ID of the object to write 00633 * \param data_pp Pointer to a pointer the object data structure, that you got from kogmo_rtdb_obj_writedata_ptr_begin() 00634 * \returns <0 on errors 00635 * 00636 */ 00637 kogmo_rtdb_objsize_t 00638 kogmo_rtdb_obj_writedata_ptr_commit (kogmo_rtdb_handle_t *db_h, 00639 kogmo_rtdb_objid_t oid, 00640 void *data_pp); 00641 00642 00643 00644 00645 /*@}*/ 00646 00647 00648 00649 /*! \defgroup kogmo_rtdb_until C-Functions for Waiting for Data with Timeouts (Data and Metadata) 00650 * These functions contain an additional parameter wakeup_ts that 00651 * specifies an *absolute* timestamp when to wakeup from a blocking call. 00652 * They return -KOGMO_RTDB_ERR_TIMEOUT in this case. 00653 * With 0 as wakeup_ts they behave like the function that doen't have 00654 * a trailing _until in its name. \n 00655 * kogmo_rtdb_obj_readdata_waitnext_until(..,0) = kogmo_rtdb_obj_readdata_waitnext() 00656 */ 00657 /*@{*/ 00658 00659 00660 /*! \brief kogmo_rtdb_obj_readdata_waitnext() with wakeup. 00661 * see: kogmo_rtdb_obj_readdata_waitnext() 00662 * \param wakeup_ts time at which to wake up if there is no data available. 00663 * returns -KOGMO_RTDB_ERR_TIMEOUT in this case. 00664 */ 00665 kogmo_rtdb_objsize_t 00666 kogmo_rtdb_obj_readdata_waitnext_until( 00667 kogmo_rtdb_handle_t *db_h, 00668 kogmo_rtdb_objid_t oid, kogmo_timestamp_t old_ts, 00669 void *data_p, kogmo_rtdb_objsize_t size, 00670 kogmo_timestamp_t wakeup_ts); 00671 00672 /*! \brief kogmo_rtdb_obj_readdata_waitnext_ptr() with wakeup. 00673 * see: kogmo_rtdb_obj_readdata_waitnext_ptr() 00674 * \param wakeup_ts time at which to wake up if there is no data available. 00675 * returns -KOGMO_RTDB_ERR_TIMEOUT in this case. 00676 */ 00677 kogmo_rtdb_objsize_t 00678 kogmo_rtdb_obj_readdata_waitnext_until_ptr( 00679 kogmo_rtdb_handle_t *db_h, 00680 kogmo_rtdb_objid_t oid, kogmo_timestamp_t old_ts, 00681 void *data_p, kogmo_rtdb_objsize_t size, 00682 kogmo_timestamp_t wakeup_ts); 00683 /*@}*/ 00684 00685 00686 00687 /*! \defgroup kogmo_rtdb_misc C-Functions to get Timestamp, etc.. 00688 */ 00689 /*! \brief Get absolute Timestamp for current Time within the given 00690 * database (can be different to kogmo_timestamp_now() when in 00691 * simulation mode. 00692 * \param db_h database handle 00693 * \returns zero on errors 00694 */ 00695 /*@{*/ 00696 kogmo_timestamp_t 00697 kogmo_rtdb_timestamp_now (kogmo_rtdb_handle_t *db_h); 00698 00699 /*! \brief Set current Time to the given absolute Timestamp. 00700 * This has only an effect if the rtdb is in simulation mode 00701 * (kogmo_rtdb_man -s) and the clients use kogmo_rtdb_timestamp_now() 00702 * instead of kogmo_timestamp_now()). 00703 * \param db_h database handle 00704 * \param new_ts new timestamp (0: give client the real current time, kogmo_timestamp_now()) 00705 * \returns 0 for OK, -KOGMO_RTDB_ERR_NOPERM if RTDB is not in simulation mode. 00706 */ 00707 int 00708 kogmo_rtdb_timestamp_set (kogmo_rtdb_handle_t *db_h, 00709 kogmo_timestamp_t new_ts); 00710 /*@}*/ 00711 00712 00713 00714 /*! \addtogroup kogmo_rtdb_conn 00715 */ 00716 /*@{*/ 00717 00718 00719 00720 00721 00722 /*! \brief Init Info for a new Database Connection 00723 * This does not connect. It's only for convenience. 00724 * See kogmo_rtdb_connect_info_t. 00725 * 00726 * \param conninfo pointer to a Database Connection Info 00727 * \param dbhost database specifier, "" for the local default database, not more than 25 characters 00728 * \param procname choosen name, like a2_roadtracker 00729 * \param cycletime your internal cycle time in seconds (0 for system default); 00730 * you must signal your vitality every cycle with 00731 * kogmo_rtdb_cycle_done() 00732 * \returns <0 on errors 00733 */ 00734 int 00735 kogmo_rtdb_connect_initinfo (kogmo_rtdb_connect_info_t *conninfo, 00736 _const char *dbhost, 00737 _const char *procname, float cycletime); 00738 00739 00740 /*! \brief Open Connection to Real-time Vehicle Database 00741 * 00742 * \param db_h storage for the new database handle 00743 * \param conninfo connection parameters and process infos 00744 * \returns your process-ID (a positive number) on success, 00745 * <0 on errors 00746 * 00747 * Please note: 00748 * - At process termination you should call kogmo_rtdb_disconnect() 00749 * - By default there will be installed Signal-Handlers for SIG_TERM/QUIT/INT 00750 * that call kogmo_rtdb_disconnect() automatically, but please don't 00751 * rely on this 00752 */ 00753 kogmo_rtdb_objid_t 00754 kogmo_rtdb_connect (kogmo_rtdb_handle_t **db_h, 00755 kogmo_rtdb_connect_info_t *conninfo); 00756 00757 00758 /* \brief Disconnect from Real-time Vehicle Database 00759 * 00760 * \param db_h database handle 00761 * \param discinfo normally NULL (might contain special flags later) 00762 * \returns <0 on errors 00763 * 00764 * You should call this on process termination. 00765 */ 00766 int 00767 kogmo_rtdb_disconnect (kogmo_rtdb_handle_t *db_h, 00768 void *discinfo); 00769 00770 /* \brief Inform other Processes about your status and signal own Vitality to Real-time Vehicle Database 00771 * 00772 * \param db_h database handle 00773 * \param status your new status, one of kogmo_rtdb_obj_c3_process_status_t 00774 * \param msg an arbitrary status message for humans, NULL to keep the last one, 00775 * at maximum KOGMO_RTDB_PROCSTATUS_MSG_MAXLEN characters. 00776 * \param flags normally 0 00777 * \returns <0 on errors 00778 * 00779 * You should call this regularly at the end of each of your cycles. 00780 */ 00781 int 00782 kogmo_rtdb_setstatus (kogmo_rtdb_handle_t *db_h, uint32_t status, _const char* msg, uint32_t flags); 00783 // see kogmo_rtdb.hxx! 00784 #define HAVE_DEFINED_setstatus 00785 00786 /* \brief Inform other Processes that you finished your cycle and signal own Vitality to Real-time Vehicle Database. 00787 * This is equal to kogmo_rtdb_setownstatus(db_h, KOGMO_RTDB_PROCSTATUS_CYCLEDONE, "", 0) 00788 * 00789 * \param db_h database handle 00790 * \param flags normally 0 00791 * \returns <0 on errors 00792 * 00793 * You should call this (or kogmo_rtdb_setstatus()) regularly at the end of each of your cycles. 00794 */ 00795 int 00796 kogmo_rtdb_cycle_done (kogmo_rtdb_handle_t *db_h, uint32_t flags); 00797 00798 00799 00800 int 00801 kogmo_rtdb_pthread_create(kogmo_rtdb_handle_t *db_h, 00802 pthread_t *thread, 00803 pthread_attr_t *attr, 00804 void *(*start_routine)(void*), void *arg); 00805 int 00806 kogmo_rtdb_pthread_kill(kogmo_rtdb_handle_t *db_h, 00807 pthread_t thread, int sig); 00808 int 00809 kogmo_rtdb_pthread_join(kogmo_rtdb_handle_t *db_h, 00810 pthread_t thread, void **value_ptr); 00811 00812 // NOTE: kogmo_rtdb_sleep_until() in simulation mode: 00813 // => works only if simulation time runs slower than real-time! (true in most cases) 00814 int 00815 kogmo_rtdb_sleep_until(kogmo_rtdb_handle_t *db_h, 00816 _const kogmo_timestamp_t wakeup_ts); 00817 00818 /*@}*/ 00819 00820 00821 00822 00823 /*! \defgroup kogmo_rtdb_error C-Functions Return Values and Debugging 00824 * \brief These values can be returned by Calls to the Database-API. 00825 * They are returned as an integer (int) or a type kogmo_rtdb_objid_t.\n 00826 * So far, they are based on errno.h for simplicity. \n 00827 * 00828 * Please note: 00829 * - All error values returned are negative! 00830 */ 00831 /*@{*/ 00832 00833 // angelehnt an /usr/include/asm/errno.h: 00834 #define KOGMO_RTDB_ERR_NOPERM EACCES //!< 13 Permission denied 00835 #define KOGMO_RTDB_ERR_NOTFOUND ENOENT //!< 2 Object/Process not found 00836 #define KOGMO_RTDB_ERR_NOMEMORY ENOMEM //!< 12 Out of Memory 00837 #define KOGMO_RTDB_ERR_INVALID EINVAL //!< 22 Invalid Argument(s) 00838 #define KOGMO_RTDB_ERR_OUTOFOBJ EMFILE //!< 24 Out of Object/Process Slots 00839 #define KOGMO_RTDB_ERR_NOTUNIQ EEXIST //!< 17 Unique Object already exists 00840 #define KOGMO_RTDB_ERR_UNKNOWN EPERM //!< 1 General/unspecified error (-1) 00841 #define KOGMO_RTDB_ERR_CONNDENY ECONNREFUSED //!< 111 Connection refused 00842 #define KOGMO_RTDB_ERR_NOCONN ENOTCONN //!< 107 Not connected to the RTDB, can be returned by any function with a database handle, 00843 //! even if not explicitly specified as possible return value 00844 #define KOGMO_RTDB_ERR_HISTWRAP ESTALE //!< 116 History wrap-around, stale data 00845 #define KOGMO_RTDB_ERR_TOOFAST EAGAIN //!< 11 Updates too fast, try again 00846 #define KOGMO_RTDB_ERR_TIMEOUT ETIMEDOUT //!< Waiting for data timed out 00847 00848 /// current debug-level (internal) 00849 extern int kogmo_rtdb_debug; 00850 /*@}*/ 00851 00852 00853 00854 00855 00856 00857 00858 00859 00860 00861 /*! \brief Temporary solution for simulation because of thread-blocking (boost problem?) 00862 * similar to kogmo_rtdb_obj_searchinfo_waitnext() but non-blocking. 00863 */ 00864 int 00865 kogmo_rtdb_obj_searchinfo_lists_nonblocking(kogmo_rtdb_handle_t *db_h, 00866 _const char *name, 00867 kogmo_rtdb_objtype_t otype, 00868 kogmo_rtdb_objid_t parent_oid, 00869 kogmo_rtdb_objid_t proc_oid, 00870 kogmo_rtdb_objid_list_t known_idlist, 00871 kogmo_rtdb_objid_list_t added_idlist, 00872 kogmo_rtdb_objid_list_t deleted_idlist); 00873 00874 00875 /*! \brief (internal) Function to access object history slot-by-slot 00876 * mode: 0=get latest + init objslot (use this first) 00877 * 1=check old objslot + use offset for reading (use this afterwards and set offset) 00878 * -1=use offset for reading (don't check old objslot - will not detect a wrap-around) 00879 */ 00880 kogmo_rtdb_objsize_t 00881 kogmo_rtdb_obj_readdataslot_ptr (kogmo_rtdb_handle_t *db_h, 00882 int32_t mode, int32_t offset, 00883 kogmo_rtdb_obj_slot_t *objslot, 00884 void *data_pp); 00885 00886 00887 /*! \brief Comfortable Function to access object history slot-by-slot 00888 * see examples/kogmo_rtdb_slotreader.c for an example 00889 */ 00890 kogmo_rtdb_objsize_t 00891 kogmo_rtdb_obj_readdataslot_init (kogmo_rtdb_handle_t *db_h, 00892 kogmo_rtdb_obj_slot_t *objslot, 00893 kogmo_rtdb_objid_t oid); 00894 00895 /*! \brief Comfortable Function to access object history slot-by-slot 00896 * see examples/kogmo_rtdb_slotreader.c for an example 00897 */ 00898 kogmo_rtdb_objsize_t 00899 kogmo_rtdb_obj_readdataslot_relative (kogmo_rtdb_handle_t *db_h, 00900 kogmo_rtdb_obj_slot_t *objslot, 00901 int offset, 00902 void *data_p, 00903 kogmo_rtdb_objsize_t size); 00904 00905 /*! \brief Comfortable Function to access object history slot-by-slot 00906 * 00907 */ 00908 kogmo_rtdb_objsize_t 00909 kogmo_rtdb_obj_readdataslot_relative_ptr (kogmo_rtdb_handle_t *db_h, 00910 kogmo_rtdb_obj_slot_t *objslot, 00911 int offset, 00912 void *data_pp); 00913 00914 /*! \brief Comfortable Function to access object history slot-by-slot 00915 * 00916 */ 00917 kogmo_rtdb_objsize_t 00918 kogmo_rtdb_obj_readdataslot_check (kogmo_rtdb_handle_t *db_h, 00919 kogmo_rtdb_obj_slot_t *objslot); 00920 00921 00922 #ifdef __cplusplus 00923 }; /* extern "C" */ 00924 }; /* namespace KogniMobil */ 00925 #endif 00926 00927 00928 #endif /* KOGMO_RTDB_FUNCS_H */