C-Functions for Object Data Handling with directs Database Pointers: Do not use unless you need to.

These functions access the actual contents of the data-block of a certain object. More...

Functions
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_readdata_ptr (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, kogmo_timestamp_t ts, void *data_pp)
	Get a Pointer to the latest Data of an Object within the Database.
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_writedata_ptr_begin (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, void *data_pp)
	Start pointer-based write (fast but dangerous).
kogmo_rtdb_objsize_t	kogmo_rtdb_obj_writedata_ptr_commit (kogmo_rtdb_handle_t *db_h, kogmo_rtdb_objid_t oid, void *data_pp)
	Finish pointer-based write and publish data.

---

Detailed Description

These functions access the actual contents of the data-block of a certain object.

The difference to kogmo_rtdb_data is, that they work with pointers, that point directly into the internal structures of the RTDB. By misusing the pointer you get, you can severely damage the internals of the RTDB.

So please do not use those functions, unless you really need to. With direct pointer operations you can save some time for objects significantly larger than 10000 bytes.

---

Function Documentation

kogmo_rtdb_objsize_t kogmo_rtdb_obj_readdata_ptr	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		kogmo_timestamp_t	ts,
		void *	data_pp
	)

Get a Pointer to the latest Data of an Object within the Database.

This function returns a pointer, that points to the last object data within the RTDB internals.
It finds the block with a committed_ts <= ts.

At the end of your calculations you SHOULD call this function again and check that your pointer is still the same and therefore valid! If you get another pointer or an error, the data changed while you were using it and your results are from corrupted data. Try it again or do an appropriate error handling.

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_pp	Pointer to a pointer, that will point to the object data structure for reading afterwards

Returns:

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

Example:

                kogmo_rtdb_obj_c3_blaobj_t *myobj_p;
                kogmo_rtdb_obj_readdata_ptr(..,&myobj_p); 
                access data with e.g. myobj_p->base.data_ts

kogmo_rtdb_objsize_t kogmo_rtdb_obj_writedata_ptr_begin	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		void *	data_pp
	)

Start pointer-based write (fast but dangerous).

Call this function to receive a pointer where you can write your data. If you are done, call kogmo_rtdb_obj_writedata_ptr_commit().

Parameters:

	db_h	Database handle
	oid	Object-ID of the object to write
	data_pp	Pointer to a pointer, that will point to the object data structure for writing afterwards

Returns:

<0 on errors

Note:

• The object must be created and owned by the calling process.
• The object must not be public writable.
• The maximum length is objmeta.size_max.
• You must manually set base.size before each write.
• Be cautious! You can damage the whole database.
• DO NOT TOUCH base.committed_ts !!!
• Pointer operations are only useful for objects with sizes >= 10KB size.

kogmo_rtdb_objsize_t kogmo_rtdb_obj_writedata_ptr_commit	(	kogmo_rtdb_handle_t *	db_h,
		kogmo_rtdb_objid_t	oid,
		void *	data_pp
	)

Finish pointer-based write and publish data.

Call this function when you are done writing your data to the area, where you received a pointer from kogmo_rtdb_obj_writedata_ptr_begin(). DO NOT MODIFY THE DATA AFTERWARDS !!!

Parameters:

	db_h	Database handle
	oid	Object-ID of the object to write
	data_pp	Pointer to a pointer the object data structure, that you got from kogmo_rtdb_obj_writedata_ptr_begin()

Returns:

<0 on errors