Virtual Files

Topics
	I/O routines
	Virtual file sources
	RAM virtual files

Data Structures
struct	VIRTUAL_FILE
	Virtual File type. More...
struct	VIRTUAL_FILE_SOURCE
	Structure representing a Virtual File Source. More...
struct	OSL_VIRTUALFILENAME
	Virtual file list item. More...

Macros
#define	VF_MAX_SOURCES   16
	Maximum number of virtual file sources.
#define	VirtualFileGetSource(vf)
	Gets a pointer to the virtual file source associated with a given virtual file.

Enumerations
enum	VF_OPEN_MODES { VF_O_READ , VF_O_READWRITE , VF_O_WRITE }
	Enumeration of the available file open modes. More...

Functions
void	VirtualFileInit ()
	Initializes the virtual filesystem.
VIRTUAL_FILE *	VirtualFileOpen (void *param1, int param2, int type, int mode)
	Opens a new virtual file.
int	VirtualFileClose (VIRTUAL_FILE *f)
	Closes an open virtual file.
int	VirtualFileRegisterSource (VIRTUAL_FILE_SOURCE *vfs)
	Registers a new virtual file source.
OSL_VIRTUALFILENAME *	oslFindFileInVirtualFilenameList (const char *fname, int type)
	Finds a file in the virtual filename list.
void *	oslReadEntireFileToMemory (VIRTUAL_FILE *f, int *size)
	Reads an entire file into memory.

Variables
VIRTUAL_FILE_SOURCE *	VirtualFileSources [VF_MAX_SOURCES]
	List of virtual file sources.
int	VirtualFileSourcesNb
	Number of registered virtual file sources.
OSL_VIRTUALFILENAME *	osl_virtualFileList
	List of virtual filenames used for RAM-based virtual files.
int	osl_virtualFileListNumber
	Number of entries in the virtual file list.
int	osl_defaultVirtualFileSource
	Default virtual file source type.
const char *	osl_tempFileName
	Name of the temporary virtual file.

Detailed Description

Virtual File support for OSLib. This API is meant to provide a universal interface for manipulating file sources, allowing users to define their own.

Macro Definition Documentation

VirtualFileGetSource

#define VirtualFileGetSource

(

vf

)

Value:

(VirtualFileSources[(vf)->type])

Gets a pointer to the virtual file source associated with a given virtual file.

Parameters

vf	Pointer to the virtual file.

Returns

A pointer to the associated VIRTUAL_FILE_SOURCE.

Enumeration Type Documentation

VF_OPEN_MODES

enum VF_OPEN_MODES

Enumeration of the available file open modes.

Note that some sources do not support some modes like READWRITE or WRITE. In such cases, opening a file in one of these modes will fail, and VirtualFileOpen will return NULL.

Enumerator
VF_O_READ	Read only.
VF_O_READWRITE	Read & Write.
VF_O_WRITE	Write only.

Function Documentation

VirtualFileInit()

void VirtualFileInit

(

)

Initializes the virtual filesystem.

This function is called automatically by OSLib, so there is no need to call it manually.

VirtualFileOpen()

VIRTUAL_FILE * VirtualFileOpen	(	void *	param1,
		int	param2,
		int	type,
		int	mode )

Opens a new virtual file.

Parameters

param1	Pointer to a string representing the file name.
param2	Should always be 0.
type	File type. By default, can be VF_MEMORY or VF_FILE.
mode	One of VF_OPEN_MODES.

Returns

A pointer to the opened virtual file, or NULL if the operation failed.

VirtualFileClose()

int VirtualFileClose

(

VIRTUAL_FILE *

f

)

Closes an open virtual file.

Parameters

f	Pointer to the virtual file to close.

Returns

1 if successful, 0 otherwise.

VirtualFileRegisterSource()

int VirtualFileRegisterSource

(

VIRTUAL_FILE_SOURCE *

vfs

)

Registers a new virtual file source.

Parameters

vfs	Pointer to a valid VIRTUAL_FILE_SOURCE interface containing the functions for handling the file source.

Returns

The identifier of the source, or -1 if the operation failed.

oslFindFileInVirtualFilenameList()

OSL_VIRTUALFILENAME * oslFindFileInVirtualFilenameList	(	const char *	fname,
		int	type )

Finds a file in the virtual filename list.

This function is used in the virtual file source OPEN handler if it's a RAM-based device and param2 is 0.

Parameters

fname	The name of the file.
type	The file type.

Returns

A pointer to the OSL_VIRTUALFILENAME structure, or NULL if the file is not found.

oslReadEntireFileToMemory()

void * oslReadEntireFileToMemory ( VIRTUAL_FILE * f, int * size )

extern

Reads an entire file into memory.

The memory block is allocated in steps of 4kB, so even a 1kB file will occupy 16kB. This function is not recommended for opening a lot of small files.

Parameters

f	Pointer to the virtual file.
size	Pointer to an integer that will store the number of bytes read.

Returns

A pointer to the memory block containing the file data.