SparrowFile is for file handling. Most basic tasks (opening, reading a amount of bytes, closing) are already done by SDL. sparrowFile extends this to checking whether a file exists, reading until specific signs, searching files, creating folders, etc. Use only /! not \ ... For more information about file functions see http://www.libsdl.org/cgi/docwiki.cgi/SDL_API and scroll down to “Files (RWops)”. Keep in mind: spFilePointer and SDL_RWops* are EXACTLY the same. ;-)
| sparrowFile | SparrowFile is for file handling. |
| Enumerations | |
| spFileError | Enumeration for errors while working with files |
| spFileType | Enumeration for file types |
| spFileSortType | This enumeration is needed for sorting files when searching in a folder |
| Types | |
| spFilePointer | Same lik SDL_RWops*, but looks better ;) |
| spFileList | Linked list type for searching results, which contains found files. |
| Functions | |
| spFileExists | Tests, whether the file “filename” exists ;-) |
| spReadOneLine | Reads one line from a SDL_RWops file. |
| spWriteOneLine | Writes one line from a SDL_RWops file. |
| spReadUntil | Reads signs from the file “file” until the buffer is full (buffer_len) or the sign “end_sign” is reached. |
| spCreateDirectoryChain | Creates a directory chain (like /home/user/.config/pinball/settings) if it not exists already. |
| spRemoveFile | Removes/deletes a file |
| spRemoveDirectory | Removes an EMPTY directory |
| spRenameFile | Renames a file |
| spRenameDirectory | Renames a directory, works exactly like spRenameFile. |
| spFileGetDirectory | Searches for files Puts a double linked list of found files in directory to pointer, found files are directly extracted from the system and may very well not be ordered. |
| spFileDeleteList | Deletes a list created by spFileGetDirectory. |
| spFileSortList | Sorts the file list like you want. |
| spConfigGetPath | Returns the path to config files, which may be everywhere on different targets, e.g. |
| Types | |
| spConfigEntry | List type for config entries. |
| spConfig | Config type |
| Functions | |
| spConfigRead | Reads a config and saves it to a spConfig struct |
| spConfigWrite | Writes the config to the file. |
| spConfigFree | Frees the struct if you don’t need it anymore |
| spConfigGetString | Returns the string value to a specific key. |
| spConfigGetStringWithComment | Returns the string value to a specific key. |
| spConfigGetBool | Returns the bool value to a specific key. |
| spConfigGetBoolWithComment | Returns the bool value to a specific key. |
| spConfigSetBool | Sets the bool value to a specific key. |
| spConfigSetBoolWithComment | Sets the bool value to a specific key. |
| spConfigGetInt | Returns the int value to a specific key. |
| spConfigGetIntWithComment | Returns the int value to a specific key. |
| spConfigSetInt | Sets the int value to a specific key. |
| spConfigSetIntWithComment | Sets the int value to a specific key. |
| spConfigGetFloat | Returns the float value to a specific key. |
| spConfigGetFloatWithComment | Returns the float value to a specific key. |
| spConfigSetFloat | Sets the float value to a specific key. |
| spConfigSetFloatWithComment | Sets the float value to a specific key. |
Enumeration for errors while working with files
Linked list type for searching results, which contains found files.
| name (char*) | filename |
| type (spFileType) | filetype, see spFileType |
| last_mod | time of the last modification in seconds since 1.1.1970 00:00:00 |
| last_acc | time of the last access in seconds since 1.1.1970 00:00:00 |
| prev (spFileList*) | previous found |
| next (spFileList*) | next found |
| count (int) | only valid for the first element, describes the number of found files |
PREFIX int spReadOneLine( spFilePointer file , char * buffer, int buffer_len )
Reads one line from a SDL_RWops file.
| file | the file to read |
| buffer | where the file content is written to |
| buffer_len | the length of buffer (+ zero byte!). |
| int | If the end of file is reached, 1 is returned, else 0 |
PREFIX int spReadUntil( spFilePointer file , char * buffer, int buffer_len, char end_sign, char ignore_windows_return )
Reads signs from the file “file” until the buffer is full (buffer_len) or the sign “end_sign” is reached. The sign before “end_sign” is the last sign of the string! If you read more signs from the file, the sign AFTER “end_sign” is the next you will read. It is useful for parsing simple XML files.
| file | the file to be read |
| buffer | the buffer for reading signs |
| buffer_len | the length of the buffer |
| end_sign | the sign to which it will be read |
| ignore_windows_return | Windows uses 2 signs for line breaks (VERY smart...), so if you set ignore_windows_return to 1, \r will be ignored. Necessary for Windows text files, but for binary files it doesn’t make sense at all. |
| int | Like spReadOneLine it returns 1 if eof is reached, else 0. |
PREFIX spFileError spCreateDirectoryChain( const char * directories )
Creates a directory chain (like /home/user/.config/pinball/settings) if it not exists already. That means if you create e.g. rainbow/dash, the folder rainbow will be created if it doesn’t exist.
| directories | the path of the directory to create |
| spFileError | SP_FILE_EVERYTHING_OK if no error, else see spFileError |
PREFIX spFileError spRemoveFile( const char * filename )
Removes/deletes a file
| filename | the name of the file |
| spFileError | SP_FILE_EVERYTHING_OK if no error, else see spFileError |
PREFIX spFileError spRemoveDirectory( const char * dirname )
Removes an EMPTY directory
| dirname | the name of the directory |
| spFileError | SP_FILE_EVERYTHING_OK if no error, else see spFileError |
PREFIX spFileError spRenameFile( const char* filename , const char * newname )
Renames a file
| filename | the old filename |
| newname | the new filename |
| spFileError | SP_FILE_EVERYTHING_OK if no error, else see spFileError |
PREFIX spFileError spFileGetDirectory( spFileListPointer * pointer, char * directory, int recursive, int no_hidden_files )
Searches for files Puts a double linked list of found files in directory to pointer, found files are directly extracted from the system and may very well not be ordered. Call spFileSortList on the list afterwards. Finally call spFileDeleteList to dispose the list. Returned filepaths include the passed directory string
| pointer | pointer to an existing <spFileListPointer> (not a struct), the result will be placed in here |
| directory | path of the directory to be searched. Use forward slashes (even on Windows). Use “.” for working directory, “..” for parent dir. DON’T include a trailing slash |
| recursive | if 0 only directory will be searched, if 1 the subdirectories, too. Be carefull with infinite directory loops! |
| no_hidden_files | if 1, hidden files like .git are ignored. |
| spFileError | SP_FILE_EVERYTHING_OK if no error, else see spFileError |
PREFIX void spFileSortList( spFileListPointer * list, spFileSortType sortBy )
Sorts the file list like you want.
| list | the list to be sorted |
| sortBy | the sorting pattern. The possible sort pattern are (self-explanatory): SP_FILE_SORT_BY_NAME, SP_FILE_SORT_BY_TYPE, SP_FILE_SORT_BY_TYPE_AND_NAME. Add SP_FILE_SORT_BACKWARDS to sort backwards |
PREFIX char* spConfigGetPath( char * buffer, char * subfolder, char * file )
Returns the path to config files, which may be everywhere on different targets, e.g. in appdata for the pandora, home-folder for the gcw, etc.
| buffer | buffer to fill with the path |
| subfolder | name of the program used to create subfolders e.g. in ~/.config. Not used by every target. In fact only by x86 linux and gcw. |
| file | name of the config file to give the path to |
| char* | filled pointer to buffer |
PREFIX spConfigPointer spConfigRead( char * filename, char * subfolder )
Reads a config and saves it to a spConfig struct
| filename | filename of the config. It will be saved to a specific folder on every target |
| subfolder | needed to “calculate” this specific folder. Should just be your program name |
| spConfigPointer | Pointer to a spConfig Struct |
PREFIX char* spConfigGetString( spConfigPointer config, char * key, char * default_value )
Returns the string value to a specific key. If the key is not found, it will be added with the default_value. There is no Setter function, because you can edit the returned pointer directly.
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| char* | the value |
PREFIX char* spConfigGetStringWithComment( spConfigPointer config, char * key, char * default_value, char * comment )
Returns the string value to a specific key. If the key is not found, it will be added with the default_value. There is no Setter function, because you can edit the returned pointer directly. If the key is not available in the config yet, the comment will be added before the setting
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
| char* | the value |
PREFIX int spConfigGetBool( spConfigPointer config, char * key, int default_value )
Returns the bool value to a specific key. If the key is not found, it will be added with the default_value.
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| int | the value. 1 means true, 0 false |
PREFIX int spConfigGetBoolWithComment( spConfigPointer config, char * key, int default_value, char * comment )
Returns the bool value to a specific key. If the key is not found, it will be added with the default_value. If the key is not available in the config yet, the comment will be added before the setting
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
| int | the value. 1 means true, 0 false |
PREFIX void spConfigSetBoolWithComment( spConfigPointer config, char * key, int value, char * comment )
Sets the bool value to a specific key. If the key is not found, it will be added. If the key is not available in the config yet, the comment will be added before the setting
| config | config to write to |
| key | key of the item |
| value | value to set |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
PREFIX int spConfigGetInt( spConfigPointer config, char * key, int default_value )
Returns the int value to a specific key. If the key is not found, it will be added with the default_value.
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| int | the value |
PREFIX int spConfigGetIntWithComment( spConfigPointer config, char * key, int default_value, char * comment )
Returns the int value to a specific key. If the key is not found, it will be added with the default_value. If the key is not available in the config yet, the comment will be added before the setting
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
| int | the value |
PREFIX void spConfigSetIntWithComment( spConfigPointer config, char * key, int value, char * comment )
Sets the int value to a specific key. If the key is not found, it will be added. If the key is not available in the config yet, the comment will be added before the setting
| config | config to write to |
| key | key of the item |
| value | value to set |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
PREFIX float spConfigGetFloat( spConfigPointer config, char * key, float default_value )
Returns the float value to a specific key. If the key is not found, it will be added with the default_value.
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| float | the value |
PREFIX float spConfigGetFloatWithComment( spConfigPointer config, char * key, float default_value, char * comment )
Returns the float value to a specific key. If the key is not found, it will be added with the default_value. If the key is not available in the config yet, the comment will be added before the setting
| config | config to read from |
| key | key of the item |
| default_value | value to add/return if the key is not available yet |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
| float | the value |
PREFIX void spConfigSetFloatWithComment( spConfigPointer config, char * key, float value, char * comment )
Sets the float value to a specific key. If the key is not found, it will be added. If the key is not available in the config yet, the comment will be added before the setting
| config | config to write to |
| key | key of the item |
| value | value to set |
| comment | a comment, which will be set before the key-value-pair in the config if it doesn’t exist yet |
Tests, whether the file “filename” exists ;-)
PREFIX int spFileExists( const char * filename )
Reads one line from a SDL_RWops file.
PREFIX int spReadOneLine( spFilePointer file , char * buffer, int buffer_len )
Writes one line from a SDL_RWops file.
PREFIX int spWriteOneLine( spFilePointer file , char * buffer )
Reads signs from the file “file” until the buffer is full (buffer_len) or the sign “end_sign” is reached.
PREFIX int spReadUntil( spFilePointer file , char * buffer, int buffer_len, char end_sign, char ignore_windows_return )
Creates a directory chain (like /home/user/.config/pinball/settings) if it not exists already.
PREFIX spFileError spCreateDirectoryChain( const char * directories )
Removes/deletes a file
PREFIX spFileError spRemoveFile( const char * filename )
Removes an EMPTY directory
PREFIX spFileError spRemoveDirectory( const char * dirname )
Renames a file
PREFIX spFileError spRenameFile( const char* filename , const char * newname )
Searches for files Puts a double linked list of found files in directory to pointer, found files are directly extracted from the system and may very well not be ordered.
PREFIX spFileError spFileGetDirectory( spFileListPointer * pointer, char * directory, int recursive, int no_hidden_files )
Deletes a list created by spFileGetDirectory.
PREFIX void spFileDeleteList( spFileListPointer list )
Sorts the file list like you want.
PREFIX void spFileSortList( spFileListPointer * list, spFileSortType sortBy )
Returns the path to config files, which may be everywhere on different targets, e.g.
PREFIX char* spConfigGetPath( char * buffer, char * subfolder, char * file )
Reads a config and saves it to a spConfig struct
PREFIX spConfigPointer spConfigRead( char * filename, char * subfolder )
Writes the config to the file.
PREFIX void spConfigWrite( spConfigPointer config )
Frees the struct if you don’t need it anymore
PREFIX void spConfigFree( spConfigPointer config )
Returns the string value to a specific key.
PREFIX char* spConfigGetString( spConfigPointer config, char * key, char * default_value )
Returns the string value to a specific key.
PREFIX char* spConfigGetStringWithComment( spConfigPointer config, char * key, char * default_value, char * comment )
Returns the bool value to a specific key.
PREFIX int spConfigGetBool( spConfigPointer config, char * key, int default_value )
Returns the bool value to a specific key.
PREFIX int spConfigGetBoolWithComment( spConfigPointer config, char * key, int default_value, char * comment )
Sets the bool value to a specific key.
PREFIX void spConfigSetBool( spConfigPointer config, char * key, int value )
Sets the bool value to a specific key.
PREFIX void spConfigSetBoolWithComment( spConfigPointer config, char * key, int value, char * comment )
Returns the int value to a specific key.
PREFIX int spConfigGetInt( spConfigPointer config, char * key, int default_value )
Returns the int value to a specific key.
PREFIX int spConfigGetIntWithComment( spConfigPointer config, char * key, int default_value, char * comment )
Sets the int value to a specific key.
PREFIX void spConfigSetInt( spConfigPointer config, char * key, int value )
Sets the int value to a specific key.
PREFIX void spConfigSetIntWithComment( spConfigPointer config, char * key, int value, char * comment )
Returns the float value to a specific key.
PREFIX float spConfigGetFloat( spConfigPointer config, char * key, float default_value )
Returns the float value to a specific key.
PREFIX float spConfigGetFloatWithComment( spConfigPointer config, char * key, float default_value, char * comment )
Sets the float value to a specific key.
PREFIX void spConfigSetFloat( spConfigPointer config, char * key, float value )
Sets the float value to a specific key.
PREFIX void spConfigSetFloatWithComment( spConfigPointer config, char * key, float value, char * comment )