From da95529c87148fa62cc2d2b3d2725aeb9fc19d64 Mon Sep 17 00:00:00 2001 From: Markus Mittendrein Date: Sun, 17 Mar 2019 01:17:22 +0100 Subject: Reorder and restructure the CC4Group_API struct and add some method descriptions --- src/cc4group.h | 93 +++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 37 deletions(-) (limited to 'src/cc4group.h') 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 -- cgit v1.2.3-54-g00ecf