kfile.h File Reference

Virtual KFile I/O interface. More...

#include <cfg/compiler.h>
#include <cfg/debug.h>
#include <cfg/macros.h>

Go to the source code of this file.

Data Structures
struct	KFile
	Context data for callback functions which operate on pseudo files. More...
Typedefs
typedef int32_t	kfile_off_t
	KFile offset type, used by kfile_seek().
typedef size_t(*	ReadFunc_t )(struct KFile *fd, void *buf, size_t size)
	Prototypes for KFile access functions.
typedef size_t(*	WriteFunc_t )(struct KFile *fd, const void *buf, size_t size)
	Write to file.
typedef kfile_off_t(*	SeekFunc_t )(struct KFile *fd, kfile_off_t offset, KSeekMode whence)
	Seek into file (if seekable).
typedef struct KFile *(*	ReOpenFunc_t )(struct KFile *fd)
	Close and reopen file fd.
typedef int(*	CloseFunc_t )(struct KFile *fd)
	Close file.
typedef int(*	FlushFunc_t )(struct KFile *fd)
	Flush file I/O.
typedef int(*	ErrorFunc_t )(struct KFile *fd)
	Get file error mask.
typedef void(*	ClearErrFunc_t )(struct KFile *fd)
	Clear errors.
Enumerations
enum	KSeekMode { KSM_SEEK_SET, KSM_SEEK_CUR, KSM_SEEK_END }
	Costants for repositioning read/write file offset. More...
Functions
kfile_off_t	kfile_genericSeek (struct KFile *fd, kfile_off_t offset, KSeekMode whence)
	Generic implementation of kfile_seek.
struct KFile *	kfile_genericReopen (struct KFile *fd)
	Generic implementation of kfile_reopen.
int	kfile_putc (int c, struct KFile *fd)
	Generic putc implementation using kfile_write.
int	kfile_getc (struct KFile *fd)
	Generic getc implementation using kfile_read.
int	kfile_print (struct KFile *fd, const char *s)
	Write a string to kfile fd.
int	kfile_testSetUp (void)
	Kfile test function.
size_t	kfile_read (struct KFile *fd, void *buf, size_t size)
	Interface functions for KFile access.

---

Detailed Description

Virtual KFile I/O interface.

KFile is a simple, generic interface for file I/O. It uses an object-oriented model to supply a device-neutral interface to communicate with drivers.

This module contains only definitions, the instance structure and the common API. Each KFile subclass can override one or more methods of the interface, and can extend the base KFile structure with its own private data. For instance, a serial driver might implement the KFile interface by declaring a context structure like this:

 typedef struct Serial
 {
      // base class instance
      KFile fd;

      // private instance data
      FIFOBuffer txfifo, rxfifo;
 } Serial;

You should also supply a macro for casting KFile to Serial:

 INLINE Serial * SERIAL_CAST(KFile *fd)
 {
        ASSERT(fd->_type == KFT_SERIAL);
        return (Serial *)fd;
 }

Then you can implement as many interface functions as needed and leave the rest to NULL.

Example implementation of the close KFile method for Serial:

 static int ser_kfile_close(struct KFile *fd)
 {
        Serial *fds = SERIAL_CAST(fd);
      // [driver specific code here]
        return 0;
 }

The SERIAL_CAST() macro helps ensure that the passed object is really of type Serial.

The KFile interface does not supply an open function: this is deliberate, because in embedded systems each device has its own init parameters. For the same reason, specific device settings like, for example, the baudrate, are not part of interface and should be handled by the driver-specific API.

Version:

Id

kfile.h 1798 2008-09-05 17:31:32Z batt

Author:

Bernie Innocenti <bernie@codewiz.org>

Francesco Sacchi <batt@develer.com>

Daniele Basile <asterix@develer.com>

Definition in file kfile.h.

---

Typedef Documentation

typedef int(* CloseFunc_t)(struct KFile *fd)

Close file.

Returns:

0 on success, EOF on errors.

Definition at line 157 of file kfile.h.

typedef int(* ErrorFunc_t)(struct KFile *fd)

Get file error mask.

Returns:

0 on success or file error code, device specific.

Definition at line 169 of file kfile.h.

typedef int(* FlushFunc_t)(struct KFile *fd)

Flush file I/O.

Returns:

0 on success, EOF on errors.

Definition at line 163 of file kfile.h.

typedef size_t(* ReadFunc_t)(struct KFile *fd, void *buf, size_t size)

Prototypes for KFile access functions.

I/O file functions must be ANSI compliant.

Note:

A KFile user can choose which function subset to implement, but has to set to NULL unimplemented features. Read from file.

Returns:

the number of bytes read.

Definition at line 133 of file kfile.h.

typedef struct KFile*(* ReOpenFunc_t)(struct KFile *fd)

Close and reopen file fd.

The reopening is done with the former file parameters and access modes.

Definition at line 151 of file kfile.h.

typedef kfile_off_t(* SeekFunc_t)(struct KFile *fd, kfile_off_t offset, KSeekMode whence)

Seek into file (if seekable).

Returns:

the new file offset or EOF on errors.

Definition at line 145 of file kfile.h.

typedef size_t(* WriteFunc_t)(struct KFile *fd, const void *buf, size_t size)

Write to file.

Returns:

the number of bytes written.

Definition at line 139 of file kfile.h.

---

Enumeration Type Documentation

enum KSeekMode

Costants for repositioning read/write file offset.

These are needed because on some embedded platforms ANSI I/O library may not be present.

Enumerator:

KSM_SEEK_SET	Seek from file beginning.
KSM_SEEK_CUR	Seek from file current position.
KSM_SEEK_END	Seek from file end.

Definition at line 114 of file kfile.h.

---

Function Documentation

struct KFile* kfile_genericReopen

(

struct KFile *

fd

)

[read]

Generic implementation of kfile_reopen.

Generic implementation of kfile_reopen.

This is a generic implementation that only flush file and reset seek_pos to 0.

Definition at line 214 of file kfile.c.

kfile_off_t kfile_genericSeek	(	struct KFile *	fd,
		kfile_off_t	offset,
		KSeekMode	whence
	)

Generic implementation of kfile_seek.

Generic implementation of kfile_seek.

This is a generic implementation of seek function, you can redefine it in your local module if needed.

Definition at line 176 of file kfile.c.

int kfile_print	(	struct KFile *	fd,
		const char *	s
	)

Write a string to kfile fd.

Returns:

0 if OK, EOF in case of error.

Definition at line 109 of file kfile.c.

size_t kfile_read	(	struct KFile *	fd,
		void *	buf,
		size_t	size
	)			[inline]

Interface functions for KFile access.

Note:

Remember to change following functions if KFile interface changes.

Definition at line 225 of file kfile.h.