Using these functions you can create new objects within the database and allocate space for actual data-block. You can also search for existing objects. More...
Functions | |
int | kogmo_rtdb_obj_initinfo (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_obj_info_t *metadata_p, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objsize_t size_max) |
Initialize Metadata for a new Object. | |
kogmo_rtdb_objid_t | kogmo_rtdb_obj_insert (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_obj_info_t *metadata_p) |
Insert a new Object into the Database. | |
int | kogmo_rtdb_obj_delete (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_obj_info_t *metadata_p) |
Delete an existing Object. | |
int | kogmo_rtdb_obj_readinfo (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, kogmo_rtdb_obj_info_t *metadata_p) |
Read the Metadata of an Object given by its Object-ID. | |
char * | kogmo_rtdb_obj_dumpinfo_str (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_obj_info_t *metadata_p) |
Dump the Metadata of a given Object into an ASCII-String. | |
kogmo_rtdb_objid_t | kogmo_rtdb_obj_searchinfo (kogmo_rtdb_handle_t *db_h, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objid_t parent_oid, kogmo_rtdb_objid_t proc_oid, kogmo_timestamp_t ts, kogmo_rtdb_objid_list_t idlist, int nth) |
Find Objects by their Name, Parent, creating Process and Time. | |
kogmo_rtdb_objid_t | kogmo_rtdb_obj_searchinfo_wait (kogmo_rtdb_handle_t *db_h, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objid_t parent_oid, kogmo_rtdb_objid_t proc_oid) |
Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists. | |
kogmo_rtdb_objid_t | kogmo_rtdb_obj_searchinfo_wait_until (kogmo_rtdb_handle_t *db_h, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objid_t parent_oid, kogmo_rtdb_objid_t proc_oid, kogmo_timestamp_t wakeup_ts) |
Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists, but return after a Timeout. | |
int | kogmo_rtdb_obj_searchinfo_waitnext (kogmo_rtdb_handle_t *db_h, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objid_t parent_oid, kogmo_rtdb_objid_t proc_oid, kogmo_rtdb_objid_list_t known_idlist, kogmo_rtdb_objid_list_t added_idlist, kogmo_rtdb_objid_list_t deleted_idlist) |
Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change. | |
int | kogmo_rtdb_obj_searchinfo_waitnext_until (kogmo_rtdb_handle_t *db_h, _const char *name, kogmo_rtdb_objtype_t otype, kogmo_rtdb_objid_t parent_oid, kogmo_rtdb_objid_t proc_oid, kogmo_rtdb_objid_list_t known_idlist, kogmo_rtdb_objid_list_t added_idlist, kogmo_rtdb_objid_list_t deleted_idlist, kogmo_timestamp_t wakeup_ts) |
Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change, but return after a Timeout. |
Using these functions you can create new objects within the database and allocate space for actual data-block. You can also search for existing objects.
See kogmo_rtdb_data on how to read and write object data.
Those functions will be found mostly in the initialization section of applications.
The object metadata is defined in kogmo_rtdb_obj_info_t.
int kogmo_rtdb_obj_delete | ( | kogmo_rtdb_handle_t * | db_h, | |
kogmo_rtdb_obj_info_t * | metadata_p | |||
) |
Delete an existing Object.
This removes an object, including its metadata and object data blocks.
db_h | Database handle | |
metadata_p | Pointer to its Object-Metadata (only the Object-ID will be used) |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (your metadata_p is NULL). | |
-KOGMO_RTDB_ERR_NOTFOUND | An object with the specified OID cannot be found or is already marked for deletion. | |
-KOGMO_RTDB_ERR_NOPERM | You are not allowed to delete this object. |
char* kogmo_rtdb_obj_dumpinfo_str | ( | kogmo_rtdb_handle_t * | db_h, | |
kogmo_rtdb_obj_info_t * | metadata_p | |||
) |
Dump the Metadata of a given Object into an ASCII-String.
This is useful if you want to show the Metadata to the user, e.g. for debugging.
db_h | Database handle (needed to resolve e.g. process names) | |
metadata_p | Pointer to the object metadata structure with the data to be dumped. |
Example:
char *text_p = kogmo_rtdb_obj_dumpinfo_str (&objmeta); printf ("%s", text_p); free(text_p);
int kogmo_rtdb_obj_initinfo | ( | kogmo_rtdb_handle_t * | db_h, | |
kogmo_rtdb_obj_info_t * | metadata_p, | |||
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objsize_t | size_max | |||
) |
Initialize Metadata for a new Object.
Zeros the metadata, fills it with defaults (e.g. the cycle time of the calling process) and the given parameters.
This function is for convenience and only helps to initialize the metadata structure. It does not yet create the object and does not modify the database.
db_h | Database handle | |
metadata_p | Pointer to an Object-Metadata structure, that must be previously allocated by the user | |
name | Name for the new Object; non-empty, allowed characters: a-z, A-Z, 0-9, "-", "_"; do not use "*","?" or "~" | |
otype | Type-Identifier for the new Object, see kogmo_rtdb_objtype for a list. | |
size_max | Maximum size for object data, use sizeof(your_object_t) |
See also kogmo_rtdb_obj_info_t
kogmo_rtdb_objid_t kogmo_rtdb_obj_insert | ( | kogmo_rtdb_handle_t * | db_h, | |
kogmo_rtdb_obj_info_t * | metadata_p | |||
) |
Insert a new Object into the Database.
This inserts the metadata into the database and allocates the space for the object data blocks within the database.
db_h | Database handle | |
metadata_p | Pointer to previously set up Object-Metadata |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters within your metadata_p. | |
-KOGMO_RTDB_ERR_NOTUNIQ | There is already an (unique) object, that cannot coexist with your new (unique) object. | |
-KOGMO_RTDB_ERR_NOMEMORY | Not enough memory within the database for the new object and its history, restart the manager with a larger KOGMO_RTDB_HEAPSIZE. | |
-KOGMO_RTDB_ERR_OUTOFOBJ | Out of object slots (recompile the database with a higher KOGMO_RTDB_OBJ_MAX). Be aware, that object slots are freed after their history_interval is expired. This error also occurs when the OID reaches its maximum and a restart is required (the OID is large enough that this should not happen within normal operation). |
int kogmo_rtdb_obj_readinfo | ( | kogmo_rtdb_handle_t * | db_h, | |
kogmo_rtdb_objid_t | oid, | |||
kogmo_timestamp_t | ts, | |||
kogmo_rtdb_obj_info_t * | metadata_p | |||
) |
Read the Metadata of an Object given by its Object-ID.
This function retrieves the metadata and copies it into the given metadata_p.
db_h | Database handle | |
oid | The Object-ID of the object you want to access | |
ts | Normally just 0 for "now"; with this timestamp you can specify a point in time at which the Object was alive (and therefore not yet deleted) | |
metadata_p | Pointer to a user-preallocated object metadata structure that will be filled with a copy of the Metadata of the Object |
-KOGMO_RTDB_ERR_NOTFOUND | An object with the specified OID cannot be found or is already marked for deletion at the specified ts. |
kogmo_rtdb_objid_t kogmo_rtdb_obj_searchinfo | ( | kogmo_rtdb_handle_t * | db_h, | |
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objid_t | parent_oid, | |||
kogmo_rtdb_objid_t | proc_oid, | |||
kogmo_timestamp_t | ts, | |||
kogmo_rtdb_objid_list_t | idlist, | |||
int | nth | |||
) |
Find Objects by their Name, Parent, creating Process and Time.
This function searches within the object metadata of all objects. All specified fields must match (AND), a 0 or NULL means any value.
db_h | Database handle | |
name | Look only for objects matching the given name; use NULL or "" for any name; start with ~ to specify a regular expression, e.g. "~^foobar.*$" | |
otype | If !=0, find only objects with this type | |
parent_oid | If !=0, find only objects whose parent has this object-ID | |
proc_oid | If !=0, find only objects created by this process-ID, see kogmo_rtdb_process | |
ts | Timestamp at which the Object must have been alive (and not marked deleted); 0 means "now" | |
idlist | If not NULL, the resulting list of object-IDs will be written into this user-preallocated array, terminated by an element with ID 0. The maximum size is fixed, see kogmo_rtdb_objid_list. When you want an idlist, you normally set nth=0. | |
nth | If !=0, stop the search after the n-th occurrence (starting with 1). So if you want the oid of the first hit, set idlist=NULL and nth=1. Set nth=2 for the second hit, and so on. |
-KOGMO_RTDB_ERR_NOTFOUND | There are no objects that match your search criteria. | |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (parent object does not exist (at that time), invalid regular expression). |
kogmo_rtdb_objid_t kogmo_rtdb_obj_searchinfo_wait | ( | kogmo_rtdb_handle_t * | db_h, | |
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objid_t | parent_oid, | |||
kogmo_rtdb_objid_t | proc_oid | |||
) |
Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists.
This function searches and waits if necessary until there is an object, whose metadata matches your criteria. If no object cannot be found, this functions blocks and waits until another process creates an suitable object. If there is such an object, the result is exactly the same as kogmo_rtdb_obj_searchinfo(...,idlist=NULL,nth=1).
This function searches only in the object metadata.
db_h | Database handle | |
name | Look only for objects matching the given name; use NULL or "" for any name; start with ~ to specify a regular expression, e.g. "~^foobar.*$" | |
otype | If !=0, find only objects with this type | |
parent_oid | If !=0, find only objects whose parent has this object-ID | |
proc_oid | If !=0, find only objects created by this process-ID, see kogmo_rtdb_process |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (parent object does not exist (at that time) or has been deleted (to avoid waiting forever), invalid regular expression). |
kogmo_rtdb_objid_t kogmo_rtdb_obj_searchinfo_wait_until | ( | kogmo_rtdb_handle_t * | db_h, | |
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objid_t | parent_oid, | |||
kogmo_rtdb_objid_t | proc_oid, | |||
kogmo_timestamp_t | wakeup_ts | |||
) |
Search and Wait until an Object specified by its Name, Parent, creating Process and Time exists, but return after a Timeout.
This function searches and waits if necessary until there is an object, whose metadata matches your criteria, exactly like kogmo_rtdb_obj_searchinfo_wait(). However it stops blocking and returns after a given timeout.
db_h | Database handle | |
name | Look only for objects matching the given name; use NULL or "" for any name; start with ~ to specify a regular expression, e.g. "~^foobar.*$" | |
otype | If !=0, find only objects with this type | |
parent_oid | If !=0, find only objects whose parent has this object-ID | |
proc_oid | If !=0, find only objects created by this process-ID, see kogmo_rtdb_process | |
wakeup_ts | Absolute Time at which to wake up and return if there is still no object found, 0 means infinite (like kogmo_rtdb_obj_searchinfo_wait()) |
-KOGMO_RTDB_ERR_TIMEOUT | A timeout occurred. | |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (parent object does not exist (at that time) or has been deleted (to avoid waiting forever), invalid regular expression). |
int kogmo_rtdb_obj_searchinfo_waitnext | ( | kogmo_rtdb_handle_t * | db_h, | |
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objid_t | parent_oid, | |||
kogmo_rtdb_objid_t | proc_oid, | |||
kogmo_rtdb_objid_list_t | known_idlist, | |||
kogmo_rtdb_objid_list_t | added_idlist, | |||
kogmo_rtdb_objid_list_t | deleted_idlist | |||
) |
Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change.
When you call this function the first time, it returns a list of objects, that match your search criteria (known_idlist). When you call it again, it compares this list with the current situation and waits until there is a change. Then the list (known_idlist) will be updated, and a list of the newly added or deleted objects is also returned (added_idlist and deleted_idlist).
This function searches only in the object metadata.
db_h | Database handle | |
name | Look only for objects matching the given name; use NULL or "" for any name; start with ~ to specify a regular expression, e.g. "~^foobar.*$" | |
otype | If !=0, find only objects with this type | |
parent_oid | If !=0, find only objects whose parent has this object-ID | |
proc_oid | If !=0, find only objects created by this process-ID, see kogmo_rtdb_process | |
known_idlist | The list of object-IDs already known and found in a previous call from kogmo_rtdb_obj_searchinfo(). This list will be automatically updated. You must initialize it with known_idlist[0]=0. | |
added_idlist | The list of newly created objects. | |
deleted_idlist | The list of newly deleted objects. |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (parent object does not exist (at that time) or has been deleted (to avoid waiting forever), invalid regular expression). |
int kogmo_rtdb_obj_searchinfo_waitnext_until | ( | kogmo_rtdb_handle_t * | db_h, | |
_const char * | name, | |||
kogmo_rtdb_objtype_t | otype, | |||
kogmo_rtdb_objid_t | parent_oid, | |||
kogmo_rtdb_objid_t | proc_oid, | |||
kogmo_rtdb_objid_list_t | known_idlist, | |||
kogmo_rtdb_objid_list_t | added_idlist, | |||
kogmo_rtdb_objid_list_t | deleted_idlist, | |||
kogmo_timestamp_t | wakeup_ts | |||
) |
Watch for the Creation and Deletion of Objects matching certain criteria and Wait until there is a Change, but return after a Timeout.
This function works like kogmo_rtdb_obj_searchinfo_waitnext() with the distinction that it stops blocking and returns after a given timeout.
db_h | Database handle | |
name | Look only for objects matching the given name; use NULL or "" for any name; start with ~ to specify a regular expression, e.g. "~^foobar.*$" | |
otype | If !=0, find only objects with this type | |
parent_oid | If !=0, find only objects whose parent has this object-ID | |
proc_oid | If !=0, find only objects created by this process-ID, see kogmo_rtdb_process | |
known_idlist | The list of object-IDs already known and found in a previous call from kogmo_rtdb_obj_searchinfo(). This list will be automatically updated. You must initialize it with known_idlist[0]=0 | |
added_idlist | The list of newly created objects. | |
deleted_idlist | The list of newly deleted objects. | |
wakeup_ts | Absolute Time at which to wake up and return if there is still no change, 0 means infinite (like kogmo_rtdb_obj_searchinfo_waitnext()) |
-KOGMO_RTDB_ERR_TIMEOUT | A timeout occurred. | |
-KOGMO_RTDB_ERR_INVALID | Invalid parameters (parent object does not exist (at that time) or has been deleted (to avoid waiting forever), invalid regular expression). |