C-Functions for Object Data Handling: Read and Write Object Data.

These functions access the actual contents of the data-block of a certain object at a given point in time. More...

Functions
int	kogmo_rtdb_obj_initdata (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_obj_info_t *metadata_p, void *data_p)
	Initialize a new data block for an existing object.
int	kogmo_rtdb_obj_writedata (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, void *data_p)
	Write the local Data block of an Object to the Database.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the latest Data of an Object from the Database.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_older (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the Data of an Object committed before a given Timestamp.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_younger (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the Data of an Object committed after a given Timestamp.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_datatime (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the Data of an Object from the Database that was valid for the given Data Timestamp.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_dataolder (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the Data of Object that has an Data Timestamp older than a given Timestamp.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_datayounger (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_p, kogmo_rtdb_objsize_t size)
	Read the Data of Object that has an Data Timestamp younger than a given Timestamp.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_waitnext (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t old_ts, void *data_p, kogmo_rtdb_objsize_t size)
	Get the latest Data for an Object that has been committed after a given timestamp, and wait if there is no newer data.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_waitnext_ptr (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t old_ts, void *data_p, kogmo_rtdb_objsize_t size)
	kogmo_rtdb_obj_readdata_waitnext() with pointer.

---

Detailed Description

These functions access the actual contents of the data-block of a certain object at a given point in time.

Those functions will be found mostly in the main loop of applications.

Every data-block of an object begins with kogmo_rtdb_subobj_base_t, see kogmo_rtdb_objects for their definition.

---

Function Documentation

int kogmo_rtdb_obj_initdata	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_obj_info_t *	metadata_p,
		void *	data_p
	)

Initialize a new data block for an existing object.

Zeros the data structure, and fills it with defaults (e.g. the maximum size from the given kogmo_rtdb_obj_info_t).

This function is for convenience and only helps to locally initialize the passed object data structure (that always begins with kogmo_rtdb_subobj_base_t). It does not yet write the object data into the database.

Parameters:

	db_h	Database handle
	metadata_p	Pointer to the Object-Metadata structure as retrieved from the database
	data_p	Pointer to an Object data structure, that has been previously allocated by the user

Returns:

<0 on errors

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the latest Data of an Object from the Database.

This function reads the latest Data-Block of an Object from the database and writes it into a local structure of the calling process.
It finds the block with a committed_ts <= ts.

Parameters:

	db_h	Database handle
	oid	Object-ID of the desired object
	ts	Timestamp at which the Object must be "the last committed"; 0 for "now"
	data_p	Pointer to a local object data structure where the data found in the rtdb will be copied to
	size	Maximum size of the object data structure at data_p

Returns:

<0 on errors, the real size of the object data found in the rtdb on success

Return values:

	-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).
	-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)
	-KOGMO_RTDB_ERR_NOPERM	You are not allowed to read this object (see flags.read_deny)
	-KOGMO_RTDB_ERR_HISTWRAP	A history wrap-around occurred: While reading this object, the data has been overwritten. Either your reading process it too slow or the history_interval is to short.
	-KOGMO_RTDB_ERR_TOOFAST	The data it stale (too old, now_ts-committed_ts > max_cycle_time) and this check is active (flags.withhold_stale is set).

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_dataolder	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the Data of Object that has an Data Timestamp older than a given Timestamp.

This function finds the nearest data block of an object within the database with a data_ts < ts.

See also:

kogmo_rtdb_obj_readdata()

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_datatime	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the Data of an Object from the Database that was valid for the given Data Timestamp.

This function finds the nearest data block of an object within the database with a data_ts <= ts.

See also:

kogmo_rtdb_obj_readdata()

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_datayounger	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the Data of Object that has an Data Timestamp younger than a given Timestamp.

This function finds the nearest data block of an object within the database with a data_ts > ts.

See also:

kogmo_rtdb_obj_readdata()

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_older	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the Data of an Object committed before a given Timestamp.

This function finds the nearest data block of an object within the database with a committed_ts < ts.

See also:

kogmo_rtdb_obj_readdata()

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_waitnext	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	old_ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Get the latest Data for an Object that has been committed after a given timestamp, and wait if there is no newer data.

This function waits until the Data-Block of an Object has an Commit-Timestamp greater than a given Timestamp (normally the last known Timestamp).

Parameters:

	db_h	database handle
	oid	Object-ID of the desired Object
	old_ts	Timestamp to compare with the Object-Data, the commit-timestamp in the returned object will be greater than this one
	data_p	Pointer to a Object-Data-Struct where the found Data will be copied
	size	Maximum size the Object-Data-Struct at data_p can absorb

Returns:

<0 on errors, size of found Object on success

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_waitnext_ptr	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	old_ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

kogmo_rtdb_obj_readdata_waitnext() with pointer.

See also:

kogmo_rtdb_obj_readdata_waitnext() and kogmo_rtdb_obj_readdata_ptr()

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_younger	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_p,
		kogmo_rtdb_objsize_t	size
	)

Read the Data of an Object committed after a given Timestamp.

This function finds the nearest data block of an object within the database with a committed_ts > ts.

See also:

kogmo_rtdb_obj_readdata()

int kogmo_rtdb_obj_writedata	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		void *	data_p
	)

Write the local Data block of an Object to the Database.

This function writes the Data-Block of an Object to the database; this is used to update an object and is normally done at every cycle.

Parameters:

	db_h	Database handle
	oid	Object-ID of the object to write
	data_p	Pointer to an object data structure that will be copied into the database

Returns:

<0 on errors

Return values:

	-KOGMO_RTDB_ERR_NOTFOUND	There is no object with the given object-id, the specified object has no space for data blocks (size=0).
	-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)
	-KOGMO_RTDB_ERR_NOPERM	You are not allowed to write this object (see flags.write_allow)
	-KOGMO_RTDB_ERR_TOOFAST	You are committing faster than the specified min_cycle_time and flags.cycle_watch is set)

Note:

• The data_p should point to a structure, that starts with a sub-structure of kogmo_rtdb_subobj_base_t
• Set your kogmo_rtdb_subobj_base_t.size to the correct size of your whole data-struct you want to commit
• Set kogmo_rtdb_obj_subbase_t.data_ts accordingly. Do not commit data with timestamps old than in your last commit.
  (TODO: check for it, maybe refuse it)