Reorder and restructure the CC4Group_API struct and add some method descriptions

1 files changed, 56 insertions, 37 deletions

diff --git a/src/cc4group.h b/src/cc4group.h
index c8aeea0..d15f135 100644
--- a/src/cc4group.h
+++ b/src/cc4group.h
@@ -42,16 +42,36 @@ typedef bool (*CC4Group_ReadCallback)(const void** const data, size_t* const siz
 typedef bool (*CC4Group_ReadSetupCallback)(void* const arg);
 
 typedef struct {
+	struct {
+		int Take; // cc4group will free the data when its not needed anymore; e.g. in the destructor or when setting the file's data again
+		int Copy; // cc4group will copy the data to use it; the original data is untouched and needs to be freed by the caller whenever desired
+		int Reference; // cc4group will use the data as is (i.e. store the pointer and use it); the caller must guarantee it's validity throughout the groups lifetime (or until the file's data is set to a new pointer) and needs to take care of freeing it afterwards
+	} const MemoryManagement;
+
+
+	struct {
+		CC4Group_TmpMemoryStrategy Memory;
+		CC4Group_TmpMemoryStrategy File;
+		CC4Group_TmpMemoryStrategy Auto;
+	} const TmpMemoryStrategies;
+
+	void (*setTmpMemoryStrategy)(const CC4Group_TmpMemoryStrategy strategy);
+
+
+	// allocates and initializes a new group object, like the operator new
 	CC4Group* (*new)(void);
-	bool (*create)(CC4Group* const this);
+	// destructs the group object and frees all memory used by group, like the operator delete
 	void (*delete)(CC4Group* const this);
 
-	// opens a group on the filesystem; path may point to a directory inside a group
-	// only open an existing group on a frehsly created group object
+
+	// after creating a group with new, exactly one of create, openExisting, openMemory, openFd, openFilePointer or openWithReadCallback must be called before any other action on the group object may be executed (except delete)
+	// initializes the group to be a fresh, empty group
+	bool (*create)(CC4Group* const this);
+
+	// opens a group on the filesystem; path may point to a directory inside a group; path "-" can be used to read the group from stdin
 	bool (*openExisting)(CC4Group* const this, const char* const path);
 
 	// opens a group that is stored entirely in memory
-	// only open an in-memory group on a frehsly created group object
 	// see the description of MemoryManagement to know if and when data has to be freed by the caller
 	// if the lazy mode is not used, the data can be freed immediately after this function returns
 	bool (*openMemory)(CC4Group* const this, const void* const groupData, size_t const size, int const memoryManagement);
@@ -67,44 +87,31 @@ typedef struct {
 	// opens a group and calls the callback to get the group data; initCallback is called before readCallback is called and deinitCallback is called after all read operations are done; initCallback and deinitCallback may be NULL if they should not be used
 	bool (*openWithReadCallback)(CC4Group* const this, CC4Group_ReadCallback const readCallback, void* const callbackArg, int const memoryManagement, CC4Group_ReadSetupCallback const initCallback, CC4Group_ReadSetupCallback const deinitCallback);
 
+
+	// saves the current in-memory state of the group as a compressed c4group to disk
+	// fails if the given path already exists
 	bool (*save)(CC4Group* const this, const char* const path);
+
+	// same as save, except that an already existing group will be overwritten
+	// be careful, any existing file will be overwritten in-place. if any error occurs after opening the target file (e.g. out of memory, a program or system crash), the previous contents will be lost
 	bool (*saveOverwrite)(CC4Group* const this, const char* const path);
 
+
 	// extraction to disk
 	bool (*extractAll)(CC4Group* const this, const char* const targetPath);
 	bool (*extractSingle)(CC4Group* const this, const char* const entryPath, const char* const targetPath);
 
-	// the group owns the data pointed to. the pointer is valid until the group destructor is called
-	bool (*getEntryData)(CC4Group* const this, const char* const entryPath, const void** const data, size_t* const size);
-
-	// all error information is only meaningfully defined after any error ocurred (indicated by any method returning false) and always describes the last error that ocurred
-	// returns a human readable error message, including the "error causer", an interpretation of the error code, the internal method in which the error occured ("error method") and possibly also the error code
-	// the returned error message pointer is valid until the next call to getErrorMessage is issued or the group is destructed
-	// this method may return NULL if memory allocation for the formatted message fails; so NULL should be considered as out of memory
-	const char* (*getErrorMessage)(CC4Group* const this);
-
-	// returns the error code of the last error; interpretation of this code depends on the internally used function that caused the error
-	int32_t (*getErrorCode)(const CC4Group* const this);
 
-	// returns the internal method name in which the error ocurred
-	const char* (*getErrorMethod)(const CC4Group* const this);
+	bool (*getEntryInfo)(CC4Group* const this, const char* const path, CC4Group_EntryInfo* const info);
+	bool (*getEntryInfos)(CC4Group* const this, const char* const path, CC4Group_EntryInfo** const infos, size_t* const size);
 
-	// returns human readable information during which operation the error occured
-	const char* (*getErrorCauser)(const CC4Group* const this);
 
-	struct {
-		CC4Group_TmpMemoryStrategy Memory;
-		CC4Group_TmpMemoryStrategy File;
-		CC4Group_TmpMemoryStrategy Auto;
-	} const TmpMemoryStrategies;
+	// the group owns the data pointed to. the pointer is valid until the group destructor is called
+	bool (*getEntryData)(CC4Group* const this, const char* const entryPath, const void** const data, size_t* const size);
 
-	struct {
-		int Take; // cc4group will free the data when its not needed anymore; e.g. in the destructor or when setting the file's data again
-		int Copy; // cc4group will copy the data to use it; the original data is untouched and needs to be freed by the caller whenever desired
-		int Reference; // cc4group will use the data as is (i.e. store the pointer and use it); the caller must guarantee it's validity throughout the groups lifetime (or until the file's data is set to a new pointer) and needs to take care of freeing it afterwards
-	} const MemoryManagement;
+	// see the description of MemoryManagement to know if and when data has to be freed by the caller
+	bool (*setEntryData)(CC4Group* const this, const char* const entryPath, const void* const data, size_t const size, int const memoryManagementMode);
 
-	void (*setTmpMemoryStrategy)(const CC4Group_TmpMemoryStrategy strategy);
 
 	// group metadata handling
 	bool (*setMaker)(CC4Group* const this, const char* const maker, const char* const path, bool const recursive);
@@ -112,18 +119,30 @@ typedef struct {
 	bool (*setOfficial)(CC4Group* const this, bool const official, const char* const path, bool const recursive);
 	bool (*setExecutable)(CC4Group* const this, bool const executable, const char* const path);
 
-	bool (*getEntryInfo)(CC4Group* const this, const char* const path, CC4Group_EntryInfo* const info);
-	bool (*getEntryInfos)(CC4Group* const this, const char* const path, CC4Group_EntryInfo** const infos, size_t* const size);
 
 	// modifying the group
-	bool (*deleteEntry)(CC4Group* const this, const char* const path, bool const recursive);
-	bool (*renameEntry)(CC4Group* const this, const char* const oldPath, const char* const newPath);
 	bool (*createDirectory)(CC4Group* const this, const char* const path);
-
 	bool (*createFile)(CC4Group* const this, const char* const path);
+	bool (*renameEntry)(CC4Group* const this, const char* const oldPath, const char* const newPath);
+	bool (*deleteEntry)(CC4Group* const this, const char* const path, bool const recursive);
 
-	// see the description of MemoryManagement to know if and when data has to be freed by the caller
-	bool (*setEntryData)(CC4Group* const this, const char* const entryPath, const void* const data, size_t const size, int const memoryManagementMode);
+
+	// error information
+	// all error information is only meaningfully defined after any error ocurred (indicated by any method returning false) and always describes the last error that ocurred
+
+	// returns a human readable error message, including the "error causer", an interpretation of the error code, the internal method in which the error occured ("error method") and possibly also the error code
+	// the returned error message pointer is valid until the next call to getErrorMessage is issued or the group is destructed
+	// this method may return NULL if memory allocation for the formatted message fails; so NULL should be considered as out of memory
+	const char* (*getErrorMessage)(CC4Group* const this);
+
+	// returns the error code of the last error; interpretation of this code depends on the internally used function that caused the error
+	int32_t (*getErrorCode)(const CC4Group* const this);
+
+	// returns the internal method name in which the error ocurred
+	const char* (*getErrorMethod)(const CC4Group* const this);
+
+	// returns human readable information during which operation the error occured
+	const char* (*getErrorCauser)(const CC4Group* const this);
 } const CC4Group_API;
 
 #ifndef CC4GROUP_DYNAMIC_LOAD