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.

Detailed Description

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.

Function Documentation

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.

Note:

The object is only marked as deleted. Its history will still remain in the database for the time specified as history_interval. After this time the database manager process will actually delete it.

Only the metadata given at kogmo_rtdb_obj_insert() will be used! You cannot change the history_interval later.
If you want your objects to be removed immediately, create them with immediately_delete set.
If the deleted object has child objects with parent_delete set, they will also be deleted.

Parameters:

	db_h	Database handle
	metadata_p	Pointer to its Object-Metadata (only the Object-ID will be used)

Returns:: <0 on errors

Return values:

	-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.

Parameters:

	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.

Returns:: Pointer to a string that will contain the dump in ASCII characters; the user must FREE it by itself after usage!
NULL on errors

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.

Parameters:

	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)

Returns:: <0 on errors

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.

Parameters:

	db_h	Database handle
	metadata_p	Pointer to previously set up Object-Metadata

Returns:: <0 on errors, new Object-ID on success
(the new Object-ID will also be written into the given metadata_p).

Return values:

	-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.

Note:: Because you need only the Object-ID to read the object data, it is not necessary to retrieve the metadata first.

Parameters:

	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

Returns:: <0 on errors

Return values:

-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.

Note:: Standard use case: There is at most one object, that matches your search criteria. To find this object, set idlist=NULL and nth=1.

Parameters:

	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.

Returns:: <0 on errors,
if idlist=NULL: the object-ID of the nth result,
if an idlist!=NULL is given, the real number of matching objects (can be higher than the length of idlist!)

Return values:

	-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.

Note:: You should use kogmo_rtdb_obj_searchinfo_wait() within the initialization stage of your software. So you don't need to arrange for a certain start order, as the needed objects are found as soon as they get created.
If you want to check for new objects within your main loop, you might prefer kogmo_rtdb_obj_searchinfo() or kogmo_rtdb_obj_searchinfo_wait_until().

Parameters:

	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

Returns:: <0 on errors, otherwise the object-ID of the first matching object is returned

Return values:

-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.

Parameters:

	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())

Returns:: <0 on errors, otherwise the object-ID of the first matching object is returned

Return values:

	-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.

Parameters:

	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.

Returns:: <0 on error, otherwise the sum of created plus deleted objects.

Return values:

-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.

Parameters:

	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())

Returns:: <0 on error, otherwise the sum of created plus deleted objects.

Return values:

	-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).

C-Functions for Object Metadata Handling: Add, Remove, Search and Wait for Objects.

Functions

Detailed Description

Function Documentation