diff --git a/TODO.md b/TODO.md index d9b244f..440e41a 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,8 @@ # TODO in libg1m +## Things +- Implement the 'in case of error, finish reading the file so that the + provided stream is usable' behaviour? + ## Find out what these formats are/how to parse them - G3M (like G1M?); - G1K/G3K (keys?). diff --git a/doc/g1m_error.3.txt b/doc/g1m_error.3.txt index b40bd1e..fc0694b 100644 --- a/doc/g1m_error.3.txt +++ b/doc/g1m_error.3.txt @@ -32,6 +32,8 @@ the code of the error that happened. The error codes are the following: Provided or generated stream was *NULL*. *g1m_error_noread*:: Stream was not readable. +*g1m_error_wrong_type*:: + The found type was not the expected type. *g1m_error_magic*:: File might be corrupted. *g1m_error_eof*:: diff --git a/doc/g1m_open.3.txt b/doc/g1m_open.3.txt index 50860de..89524cb 100644 --- a/doc/g1m_open.3.txt +++ b/doc/g1m_open.3.txt @@ -15,17 +15,27 @@ SYNOPSIS ---- #include -int g1m_open(g1m_t **handle, const char *path); -int g1m_fopen(g1m_t **handle, FILE *stream); +int g1m_open(g1m_t **handle, const char *path, + g1m_type_t expected_types); +int g1m_fopen(g1m_t **handle, FILE *stream, + g1m_type_t expected_types); ---- DESCRIPTION ----------- Open and decode a file. If everything goes well, the handle is stored at -**handle*. +**handle*. If you are expecting one or more types in particular, set +*expected_types* to the OR'd types (e.g. _g1m_type_mcs | g1m_type_storage_), +then, if the wrong type is found, the file will not be decoded to the end, +only to the point where it can be identified. If you aren't expecting any +type in particular, set *expected_types* to zero. -For *g1m_fopen*, the stream only requires reading (writing and seeking -capabilities are not required). +*g1m_open* will open the file at the given path, decode it, and close it, +whereas *g1m_fopen* will take an opened stream (with libc) and will not +close it. Only reading is required (writing and seeking capabilities are +not). In case of a decoding error (magic problem, memory allocation error, +...), the stream is unusable as the number of read bytes by libg1m is not +known. RETURN VALUE ------------