Add openAsChild, currently without writing support

1 files changed, 13 insertions, 1 deletions

diff --git a/src/cc4group.h b/src/cc4group.h
index 8b86d9c..207ef15 100644
--- a/src/cc4group.h
+++ b/src/cc4group.h
@@ -29,7 +29,7 @@
 //    the directory separator used for all entry paths in cc4group is "/" _regardless of the platform_. yes, you better watch out Windows users!
 //    in contrast to paths names are only the the name of the entry itself, not the whole path
 //  - to free all resources used by the group when it is not needed anymore, call cc4group.delete with the group pointer and discard it afterwards (i.e. don't use it anymore)
-//  - all functions, except cc4group.new, cc4group.delete and cc4group.setTmpMemoryStrategy (where the latter can't fail) follow the same scheme
+//  - all functions, except cc4group.new, cc4group.openAsChild, cc4group.delete and cc4group.setTmpMemoryStrategy (where the latter two can't fail) follow the same scheme
 //    all of them can fail, either caused by wrong arguments or by things outside of the applications control
 //    they all return _true_ if everything went well and _false_ if any error occured
 //    information about the error (incredibly useful for debugging or asking for help with problems) can be obtained by using one the cc4group.getError* functions
@@ -188,6 +188,8 @@ typedef struct {
 	CC4Group* (*new)(void);
 
 	// destructs the group object and frees all memory used by group, like the operator delete
+	// the group object may be freed at a later time if cc4group.openAsChild was used on it and the child is not deleted yet
+	// child relations are tracked through reference counting, thus the group will be really destructed when all referencing child groups are gone
 	void (*delete)(CC4Group* const this);
 
 
@@ -316,6 +318,16 @@ typedef struct {
 
 	// returns human readable information during which operation the error occured
 	const char* (*getErrorCauser)(const CC4Group* const this);
+
+
+	// returns a new CC4Group object that represents a subgroup denoted by path
+	// path must point to a directory
+	// in any error case NULL will be returned
+	// the returned group will share most resources with its parent (the one passed as this)
+	// the parent may be deleted anytime, but it will stay in memory until the child is deleted as well (using reference counting)
+	// because both share most of their data, modifications of the child will affect the parent and the opposite direction is also possible if the modifications involve the subgroup
+	// saving through child groups is not implemented yet, it will result in an error
+	CC4Group* (*openAsChild)(CC4Group* const this, const char* const path);
 } const CC4Group_API;