sparrowFile

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.  ;-)

Summary
sparrowFileSparrowFile is for file handling.
Enumerations
spFileErrorEnumeration for errors while working with files
spFileTypeEnumeration for file types
spFileSortTypeThis enumeration is needed for sorting files when searching in a folder
Types
spFilePointerSame lik SDL_RWops*, but looks better ;)
spFileListLinked list type for searching results, which contains found files.
Functions
spFileExistsTests, whether the file “filename” exists ;-)
spReadOneLineReads one line from a SDL_RWops file.
spReadUntilReads signs from the file “file” until the buffer is full (buffer_len) or the sign “end_sign” is reached.
spCreateDirectoryChainCreates a directory chain (like /home/user/.config/pinball/settings) if it not exists already.
spRemoveFileRemoves/deletes a file
spRemoveDirectoryRemoves an EMPTY directory
spRenameFileRenames a file
spRenameDirectoryRenames a directory, works exactly like spRenameFile.
spFileGetDirectorySearches 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.
spFileDeleteListDeletes a list created by spFileGetDirectory.
spFileSortListSorts the file list like you want.

Enumerations

spFileError

Enumeration for errors while working with files

SP_FILE_EVERYTHING_OKno error, everything ok
SP_FILE_ACCESS_ERRORerror while accessing the file
SP_FILE_NOT_FOUND_ERRORthe file coudln’t be found
SP_FILE_ALREADY_EXISTS_ERRORthe file already exists
SP_FILE_INVALID_PARAMETER_ERRORsome invalid parameter like a file as parameter if a path is needed
SP_FILE_UNKNOWN_ERRORunknown error

spFileType

Enumeration for file types

SP_FILE_FILEa normal file
SP_FILE_DIRECTORYa directory
SP_FILE_LINKa link to a file or a directory

spFileSortType

This enumeration is needed for sorting files when searching in a folder

SP_FILE_SORT_BY_NAMESorting by name
SP_FILE_SORT_BY_TYPESorting by type
SP_FILE_SORT_BY_TYPE_AND_NAMESort by both
SP_FILE_SORT_BACKWARDSCombine this with the above to sort backwards

Types

spFilePointer

Same lik SDL_RWops*, but looks better ;)

spFileList

Linked list type for searching results, which contains found files.

Variables

name (char*)filename
type (spFileType)filetype, see spFileType
prev (spFileList*)previous found
next (spFileList*)next found
count (int)only valid for the first element, describes the number of found files

Functions

spFileExists

PREFIX int spFileExists(const char *filename)

Tests, whether the file “filename” exists ;-)

Parameters

filenamethe filename to check

Returns

int1 if the file exists, 0 if not

spReadOneLine

PREFIX int spReadOneLine(spFilePointer file ,
char *buffer,
int buffer_len)

Reads one line from a SDL_RWops file.

Parameters

filethe file to read
bufferwhere the file content is written to
buffer_lenthe length of buffer (+ zero byte!).

Returns

intIf the end of file is reached, 1 is returned, else 0

spReadUntil

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.

Parameters

filethe file to be read
bufferthe buffer for reading signs
buffer_lenthe length of the buffer
end_signthe sign to which it will be read
ignore_windows_returnWindows 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.

Returns

intLike spReadOneLine it returns 1 if eof is reached, else 0.

spCreateDirectoryChain

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.

Parameters

directoriesthe path of the directory to create

Returns

spFileErrorSP_FILE_EVERYTHING_OK if no error, else see spFileError

spRemoveFile

PREFIX spFileError spRemoveFile(const char *filename)

Removes/deletes a file

Parameters

filenamethe name of the file

Returns

spFileErrorSP_FILE_EVERYTHING_OK if no error, else see spFileError

See Also

spRemoveDirectory

spRemoveDirectory

PREFIX spFileError spRemoveDirectory(const char *dirname)

Removes an EMPTY directory

Parameters

dirnamethe name of the directory

Returns

spFileErrorSP_FILE_EVERYTHING_OK if no error, else see spFileError

See Also

spRemoveFile

spRenameFile

PREFIX spFileError spRenameFile(const char* filename ,
const char *newname)

Renames a file

Parameters

filenamethe old filename
newnamethe new filename

Returns

spFileErrorSP_FILE_EVERYTHING_OK if no error, else see spFileError

See Also

spRenameDirectory

spRenameDirectory

Renames a directory, works exactly like spRenameFile.  In fact it is just a redefinement.

See Also

spRenameFile

spFileGetDirectory

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

Parameters

pointerpointer to an existing <spFileListPointer> (not a struct), the result will be placed in here
directorypath 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
recursiveif 0 only directory will be searched, if 1 the subdirectories, too.  Be carefull with infinite directory loops!
no_hidden_filesif 1, hidden files like .git are ignored.

Returns

spFileErrorSP_FILE_EVERYTHING_OK if no error, else see spFileError

spFileDeleteList

PREFIX void spFileDeleteList(spFileListPointer list)

Deletes a list created by spFileGetDirectory.

Parameters

listthe list to be deleted

spFileSortList

PREFIX void spFileSortList(spFileListPointer *list,
spFileSortType sortBy)

Sorts the file list like you want.

Parameters

listthe list to be sorted
sortBythe 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 int spFileExists(const char *filename)
Tests, whether the file “filename” exists ;-)
PREFIX int spReadOneLine(spFilePointer file ,
char *buffer,
int buffer_len)
Reads one line from a SDL_RWops file.
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.
PREFIX spFileError spCreateDirectoryChain(const char *directories)
Creates a directory chain (like /home/user/.config/pinball/settings) if it not exists already.
PREFIX spFileError spRemoveFile(const char *filename)
Removes/deletes a file
PREFIX spFileError spRemoveDirectory(const char *dirname)
Removes an EMPTY directory
PREFIX spFileError spRenameFile(const char* filename ,
const char *newname)
Renames a file
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.
PREFIX void spFileDeleteList(spFileListPointer list)
Deletes a list created by spFileGetDirectory.
PREFIX void spFileSortList(spFileListPointer *list,
spFileSortType sortBy)
Sorts the file list like you want.
Enumeration for file types
no error, everything ok
Enumeration for errors while working with files
Renames a directory, works exactly like spRenameFile.
Sorting by name
Sorting by type
Sort by both
Combine this with the above to sort backwards
Close