BeRTOS
Data Structures | Typedefs | Enumerations | Functions
KFile interface
BeRTOS core functionality

Virtual KFile I/O interface. More...

Data Structures

struct  ReOpenFunc_t
 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().

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)
 Move fd file seek position of offset bytes from whence.
struct KFilekfile_genericReopen (struct KFile *fd)
 Reopen file fd.
int kfile_genericClose (struct KFile *fd)
 Close file fd.

KFile access functions

Interface functions for KFile access.

size_t kfile_read (struct KFile *fd, void *buf, size_t size)
 Read size bytes from file fd into buf.
int kfile_gets (struct KFile *fd, char *buf, int size)
 Read a line long at most as size and put it in buf.
int kfile_gets_echo (struct KFile *fd, char *buf, int size, bool echo)
 Read a line long at most as size and put it in buf, with optional echo.
kfile_off_t kfile_copy (KFile *src, KFile *dst, kfile_off_t size)
 Copy size bytes from file src to dst.
size_t kfile_write (struct KFile *fd, const void *buf, size_t size)
 Write size bytes from buffer buf into KFile fd.
int kfile_printf (struct KFile *fd, const char *format,...)
 Formatted write.
int kfile_print (struct KFile *fd, const char *s)
 Write a string to kfile fd.
kfile_off_t kfile_seek (struct KFile *fd, kfile_off_t offset, KSeekMode whence)
 Seek into file (if seekable).
KFilekfile_reopen (struct KFile *fd)
 Close and reopen file fd.
int kfile_close (struct KFile *fd)
 Close file.
int kfile_flush (struct KFile *fd)
 Flush file I/O.
int kfile_error (struct KFile *fd)
 Get file error mask.
void kfile_clearerr (struct KFile *fd)
 Clear errors.
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.
void kfile_resync (KFile *fd, mtime_t delay)
 Discard input to resynchronize with remote end.
void kfile_init (struct KFile *fd)
 Base class KFile constructor.

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.

Author:
Bernie Innocenti <bernie@codewiz.org>
Francesco Sacchi <batt@develer.com>
Daniele Basile <asterix@develer.com>

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 121 of file io/kfile.h.


Function Documentation

int kfile_close ( struct KFile fd) [inline]

Close file.

Returns:
0 on success, EOF on errors.

Definition at line 307 of file io/kfile.h.

kfile_off_t kfile_copy ( KFile src,
KFile dst,
kfile_off_t  size 
)

Copy size bytes from file src to dst.

Parameters:
srcSource KFile.
dstDestionation KFile.
sizenumber of bytes to copy.
Returns:
the number of bytes copied.

Definition at line 170 of file kfile.c.

int kfile_error ( struct KFile fd) [inline]

Get file error mask.

Returns:
0 on success or file error code, device specific.

Definition at line 327 of file io/kfile.h.

int kfile_flush ( struct KFile fd) [inline]

Flush file I/O.

Returns:
0 on success, EOF on errors.

Definition at line 317 of file io/kfile.h.

int kfile_genericClose ( struct KFile fd)

Close file fd.

This is a generic implementation that only flush the file.

Definition at line 246 of file kfile.c.

struct KFile* kfile_genericReopen ( struct KFile fd) [read]

Reopen file fd.

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

Definition at line 235 of file kfile.c.

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

Move fd file seek position of offset bytes from whence.

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

Definition at line 199 of file kfile.c.

int kfile_gets ( struct KFile fd,
char *  buf,
int  size 
)

Read a line long at most as size and put it in buf.

Returns:
number of chars read or EOF in case of error.

Definition at line 126 of file kfile.c.

int kfile_gets_echo ( struct KFile fd,
char *  buf,
int  size,
bool  echo 
)

Read a line long at most as size and put it in buf, with optional echo.

Returns:
number of chars read, or EOF in case of error.

Definition at line 139 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]

Read size bytes from file fd into buf.

This function reads at most the number of requested bytes into the provided buffer. The value returned may be less than the requested bytes in case EOF is reached OR an error occurred. You need to check the error conditions using kfile_error() to understand which case happened.

Note:
This function will block if there are less than size bytes to read.
Parameters:
fdKFile context.
bufUser provided buffer.
sizeNumber of bytes to read.
Returns:
Number of bytes read.

Definition at line 240 of file io/kfile.h.

KFile* kfile_reopen ( struct KFile fd) [inline]

Close and reopen file fd.

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

Definition at line 297 of file io/kfile.h.

void kfile_resync ( KFile fd,
mtime_t  delay 
)

Discard input to resynchronize with remote end.

Discard incoming data until the kfile_getc stops receiving characters for at least delay milliseconds.

Note:
If the timeout occur, we reset the error before to quit.

Definition at line 261 of file kfile.c.

kfile_off_t kfile_seek ( struct KFile fd,
kfile_off_t  offset,
KSeekMode  whence 
) [inline]

Seek into file (if seekable).

Move fd file seek position of offset bytes from whence.

Parameters:
fdKFile context.
offsetOffset bytes to move from position whence.
whencePosition where to start the seek.
Returns:
Current postion in the file.

Definition at line 287 of file io/kfile.h.

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

Write size bytes from buffer buf into KFile fd.

Return value may be less than size.

Parameters:
fdKFile context.
bufUser provided data.
sizeNumber of bytes to write.
Returns:
Number of bytes written.

Definition at line 268 of file io/kfile.h.