diff --git a/include/cosms-core/file.h b/include/cosms-core/file.h index 52e5c0e..d91ba9e 100644 --- a/include/cosms-core/file.h +++ b/include/cosms-core/file.h @@ -45,19 +45,86 @@ struct cosms_core_file { #endif }; +/** + * @brief Opens file in specified mode. + * + * @param file Pointer to file struct (must not be NULL) + * @param path to the file to open + * @param mode to open the file in (read, write, apped, create or a combination of these) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char *path, int mode); +/** + * @brief Closes an open file. + * + * @param file Pointer to file struct that has been opened (must not be NULL) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file); +/** + * @brief Gets the size of an opened file. + * + * @param file Pointer to file struct that has been opned (must not be NULL) + * @param size Pointer to the variable to store the size in (must not be NULL) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsigned long long *size); +/** + * @brief Try's to reads specified number of bytes. + * + * @param file Pointer to file struct that has been opened in read mode (must not be NULL) + * @param buffer to store the file content in (has to be preallocated stack or heap memory) + * @param bytes_to_read from the file. + * @param bytes_read Pointer to the variable to store the amount of bytes that where actually read (can be NULL) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_read, unsigned int *bytes_read); +/** + * @brief Reads the whole file with support for reading large files. + * + * @param file Pointer to file struct that has been opened in read mode (must not be NULL) + * @param buffer Pointer to buffer to store the file content in (needs to be empty) + * @param bytes_read Pointer to the variable to store the amount of bytes that where actually read (can be NULL) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char **buffer, unsigned long long *bytes_read); +/** + * @brief Try's to write specified number of bytes. + * + * @param file Pointer to file struct that has been opened in write mode (must not be NULL) + * @param buffer that contains the bytes to write (must not be NULL) + * @param bytes_to_write to the file + * @param bytes_written Pointer to the variable to store the amount of bytes that where actually written (can be NULL) + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_write, unsigned int *bytes_written); +/** + * @brief Writes the full buffer to the file with support for writting large files. + * + * @param file Pointer to file struct that has been opened in write mode (must not be NULL) + * @param buffer that contains the bytes to write (must not be NULL) + * @param bytes_to_write to the file + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char *buffer, unsigned long long bytes_to_write); +/** + * @brief Deletes specified file from system. + * + * @param path to the file to delete + * @return COSMS_CORE_FILE_OK on success, or a negative error code + */ CosmsCoreFileError cosms_core_file_delete(const char *path); +/** + * @brief Converts error code to a string that can be used for printing/logging errors. + * + * @param error The error code to convert to a string message. + * @return The error as a string on success, or NULL + */ const char *cosms_core_file_error_string(CosmsCoreFileError error); -#endif +#endif /* COSMS_CORE_FILE */ diff --git a/src/file.c b/src/file.c index ff5b8fc..3562474 100644 --- a/src/file.c +++ b/src/file.c @@ -21,6 +21,9 @@ #include #endif +/** + * @brief Opens file in specified mode. + */ CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char *path, int mode) { file->mode = mode; @@ -111,6 +114,9 @@ CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char return COSMS_CORE_FILE_OK; } +/** + * @brief Closes an open file. + */ CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file) { #if defined(__GNUC__) int error = close(file->native_file); @@ -135,6 +141,9 @@ CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file) { return COSMS_CORE_FILE_OK; } +/** + * @brief Gets the size of an opened file. + */ CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsigned long long *size) { #if defined(__GNUC__) struct stat file_stat; @@ -164,6 +173,9 @@ CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsign return COSMS_CORE_FILE_OK; } +/** + * @brief Try's to reads specified number of bytes. + */ CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_read, unsigned int *bytes_read) { if ((file->mode & COSMS_CORE_FILE_MODE_READ) == 0) { return COSMS_CORE_FILE_INVALID_OPERATION; @@ -188,6 +200,9 @@ CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buff return COSMS_CORE_FILE_OK; } +/** + * @brief Reads the whole file with support for reading large files. + */ CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char **buffer, unsigned long long *bytes_read) { if ((file->mode & COSMS_CORE_FILE_MODE_READ) == 0) { return COSMS_CORE_FILE_INVALID_OPERATION; @@ -267,6 +282,9 @@ CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char * return COSMS_CORE_FILE_OK; } +/** + * @brief Try's to write specified number of bytes. + */ CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_write, unsigned int *bytes_written) { if ((file->mode & COSMS_CORE_FILE_MODE_WRITE) == 0) { return COSMS_CORE_FILE_INVALID_OPERATION; @@ -294,6 +312,9 @@ CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buf return COSMS_CORE_FILE_OK; } +/** + * @brief Writes the full buffer to the file with support for writting large files. + */ CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char *buffer, unsigned long long bytes_to_write) { if ((file->mode & COSMS_CORE_FILE_MODE_WRITE) == 0) { return COSMS_CORE_FILE_INVALID_OPERATION; @@ -344,6 +365,9 @@ CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char return COSMS_CORE_FILE_OK; } +/** + * @brief Deletes specified file from system. + */ CosmsCoreFileError cosms_core_file_delete(const char *path) { #if defined(__GNUC__) if (unlink(path) == -1) { @@ -384,6 +408,9 @@ CosmsCoreFileError cosms_core_file_delete(const char *path) { return COSMS_CORE_FILE_OK; } +/** + * @brief Converts error code to a string that can be used for printing/logging errors. + */ const char *cosms_core_file_error_string(CosmsCoreFileError error) { switch(error) { case COSMS_CORE_FILE_OK: diff --git a/tests/test.h b/tests/test.h index 095cfdd..427c1e4 100644 --- a/tests/test.h +++ b/tests/test.h @@ -9,15 +9,24 @@ implementation \ } +/** + * @brief Creates a list to export so it can be imported into the main test list. + */ #define COSMS_CORE_TEST_EXPORT(name, ...) static const struct cosms_core_test cosms_core_test_##name[] = { \ __VA_ARGS__, \ 0 \ } +/** + * @brief Creates a list of lists from exported tests so all tests can be easly executed. + */ #define COSMS_CORE_TEST_START static const struct cosms_core_test *cosms_core_test_tests[] = { #define COSMS_CORE_TEST_IMPORT(name) cosms_core_test_##name #define COSMS_CORE_TEST_END }; +/** + * @brief Runs all tests specified in the cosms_core_test_tests array; + */ #define COSMS_CORE_TEST_RUN() \ for (unsigned long long index = 0; index < sizeof(cosms_core_test_tests) / sizeof(cosms_core_test_tests[0]); index += 1) { \ unsigned long long test_index = 0; \ @@ -42,4 +51,4 @@ struct cosms_core_test { const char *(*function)(void); }; -#endif +#endif /* COSMS_CORE_TEST */