Detailed Description

Provides access functions for generic I/O streams..

Files

file istream68.h

generic stream header..

file istream68_curl.h

cURL stream header.

file istream68_def.h

generic stream interface.

file istream68_fd.h

file descriptor stream header.

file istream68_file.h

FILE stream header.

file istream68_mem.h

Memory stream header.

file istream68_null.h

Null stream header.

file istream68_z.h

Z stream header.

Data Structures

struct _istream_t

Generic stream structure. More...

struct istream_z_option_t

gzip options. More...

Open modes

#define ISTREAM_OPEN_READ_BIT   0

Read open mode bit.

#define ISTREAM_OPEN_READ   (1<<ISTREAM_OPEN_READ_BIT)

Read open mode value.

#define ISTREAM_OPEN_WRITE_BIT   1

Write open mode bit.

#define ISTREAM_OPEN_WRITE   (1<<ISTREAM_OPEN_WRITE_BIT)

Write open mode value.

#define ISTREAM_OPEN_MASK   (ISTREAM_OPEN_READ|ISTREAM_OPEN_WRITE)

Open modes mask.

#define ISTREAM_IS_OPEN(V)   (!!((V)&(ISTREAM_OPEN_READ|ISTREAM_OPEN_WRITE)))

Test if any open flags is set (returns 0 or 1).

#define ISTREAM_IS_OPEN_READ(V)   (((V)>>ISTREAM_OPEN_READ_BIT)&1)

Test if READ open flags is set (returns 0 or 1).

#define ISTREAM_IS_OPEN_WRITE(V)   (((V)>>ISTREAM_OPEN_WRITE_BIT)&1)

Test if WRITE open flags is set (returns 0 or 1).

Stream function prototypes.

typedef const char *(* istream_name_t )(istream_t *)

typedef int(* istream_open_t )(istream_t *)

typedef int(* istream_close_t )(istream_t *)

typedef int(* istream_length_t )(istream_t *)

typedef int(* istream_tell_t )(istream_t *)

typedef int(* istream_seek_t )(istream_t *, int)

typedef int(* istream_read_t )(istream_t *, void *, int)

typedef int(* istream_write_t )(istream_t *, const void *, int)

typedef void(* istream_destroy_t )(istream_t *)

Generic access functions.

const char * istream_filename (istream_t *istream)

Get stream name.

int istream_open (istream_t *istream)

Open stream.

int istream_close (istream_t *istream)

Close stream.

int istream_read (istream_t *istream, void *data, int len)

Read data from stream.

int istream_write (istream_t *istream, const void *data, int len)

Write data into stream.

int istream_length (istream_t *istream)

Get stream length.

int istream_tell (istream_t *istream)

Get stream current position.

int istream_seek (istream_t *istream, int offset)

Set stream relative position.

int istream_seek_to (istream_t *istream, int pos)

Set stream absolute position.

void istream_destroy (istream_t *istream)

Close and destroy stream.

int istream_gets (istream_t *istream, char *buffer, int max)

Read a '\0' or '\n' terminated string.

int istream_getc (istream_t *istream)

Read next character.

int istream_puts (istream_t *istream, const char *s)

Write a '\0' terminated string.

int istream_putc (istream_t *istream, const int c)

Write a character.

cURL stream

cURL is a client-side URL transfer library.
For more informations see cURL website.

int istream_curl_init (void)

Initialize curl engine.

void istream_curl_shutdown (void)

Shutdown curl engine.

istream_t * istream_curl_create (const char *url, int mode)

Creates an URL based stream using cURL.

File descriptor stream

Implements istream_t for "unix like" file descriptor.

istream_t * istream_fd_create (const char *fname, int fd, int mode)

Creates a stream for "UNIX" file descriptor.

FILE stream

Implements istream_t for standard "C" FILE.

istream_t * istream_file_create (const char *fname, int mode)

Creates a stream for "C" FILE.

Memory stream

Implements istream_t for memory buffer.

istream_t * istream_mem_create (const void *addr, int len, int mode)

Creates a stream for memory buffer.

Null stream

Implements a null istream_t.
Null stream does nothing but checking some trivial errors (like access without opening) and dealing with a virtual stream position. The null stream length is the position the highest byte that has been either read or write. The length is resetted at open. It implies that stream length can be retrieved by the istream_length() function after istream_close() call.

istream_t * istream_null_create (const char *name)

Creates a null stream.

Typedefs

typedef _istream_t istream_t

stream type.

Function Documentation

const char* istream_filename ( istream_t * istream )

Get stream name.

Parameters:

istream stream

Returns:
stream name

Return values:

0 Failure.

int istream_open ( istream_t * istream )

Open stream.

Parameters:

istream stream

Returns:
error code

Return values:

0 Success

-1 Failure

int istream_close ( istream_t * istream )

Close stream.

Parameters:

istream stream

Returns:
error code

Return values:

0 Success

-1 Failure

int istream_read ( istream_t * istream,

void * data,

int len

)

Read data from stream.

Parameters:

istream stream

data destination buffer

len number of byte to read

Returns:
number of byte read

Return values:

-1 Failure.

int istream_write ( istream_t * istream,

const void * data,

int len

)

Write data into stream.

Parameters:

istream stream

data destination buffer

len number of byte to read

Returns:
number of byte written

Return values:

-1 Failure.

int istream_length ( istream_t * istream )

Get stream length.

Parameters:

istream stream

Returns:
number of bytes.

Return values:

-1 Failure.

int istream_tell ( istream_t * istream )

Get stream current position.

Parameters:

istream stream

Returns:
stream position

Return values:

-1 Failure.

int istream_seek ( istream_t * istream,

int offset

)

Set stream relative position.

Parameters:

istream stream

offset displacement from current position

Returns:
Absolute position after seeking

Return values:

-1 Failure.

See also:
istream_seek_to()

int istream_seek_to ( istream_t * istream,

int pos

)

Set stream absolute position.

Parameters:

istream stream

pos position to reach

Returns:
Absolute position after seeking

Return values:

-1 Failure.

See also:
istream_seek()

void istream_destroy ( istream_t * istream )

Close and destroy stream.

Parameters:

istream stream

int istream_gets ( istream_t * istream,

char * buffer,

int max

)

Read a '\0' or '\n' terminated string.

Parameters:

istream stream

buffer destination buffer

max destination buffer size

Returns:
number of char read

Return values:

-1 Failure.

int istream_getc ( istream_t * istream )

Read next character.

Parameters:

istream stream

Returns:
char value [0..255]

Return values:

-1 EOF or error.

int istream_puts ( istream_t * istream,

const char * s

)

Write a '\0' terminated string.

Parameters:

istream stream

s string

Returns:
number of char written

Return values:

-1 Failure.

int istream_putc ( istream_t * istream,

const int c

)

Write a character.

Parameters:

istream stream

c char [0..255]

Returns:
error code

Return values:

0 Success

-1 Failure

int istream_curl_init ( void )

Initialize curl engine.
The istream_curl_init() function initializes curl library. It is called by the file68_init() function and everytime a new curl stream is created with the istream_curl_create() function.

Returns:
error code

Return values:

0 success

-1 failure

istream_t* istream_fd_create ( const char * fname,

int fd,

int mode

)

Creates a stream for "UNIX" file descriptor.
If fd parameters is not -1, it is used to as file descriptor for the stream and fname is used for naming the stream. Else the file is open as a regular file with fname as path.

Parameters:

fname path of file or 0.

fd file decriptor or -1.

mode bit-0: read access, bit-1: write access.

Returns:
stream

Return values:

0 on error

Note:
filename is internally copied.
Even if fd is given the istream_open() must be call.

Warning:
When opening a stream with an already opened descriptor the mode should match the real open mode but since no tests are performed before calling r/w access, it should not failed in case of wrong access on given mode.

istream_t* istream_file_create ( const char * fname,

int mode

)

Creates a stream for "C" FILE.

Parameters:

fname path of file.

mode bit 0 : read access, bit 1 : write access.

Returns:
stream

Return values:

0 on error

Note:
filename is internally copied.

istream_t* istream_mem_create ( const void * addr,

int len,

int mode

)

Creates a stream for memory buffer.

Parameters:

addr Buffer base address.

len Buffer length.

mode Allowed open mode.

Returns:
stream

Return values:

0 on error

Note:
filename is build with memory range.

istream_t* istream_null_create ( const char * name )

Creates a null stream.

Parameters:

name Optionnal name

Returns:
stream

Return values:

0 on error

Note:
filename is prefixed by "null://".

void istream_curl_shutdown ( void )

Shutdown curl engine.
The istream_curl_shutdoen() function shutdown curl library. It is called by the file68_shutdown() function.

istream_t* istream_curl_create ( const char * url,

int mode

)

Creates an URL based stream using cURL.

Parameters:

url URL

mode bit-0: read access, bit-1: write access.

Returns:
stream

Return values:

0 on error

Note:
url is internally copied.

Todo:
Implement write mode.

I/O streams. [file68 library documentation.]

Detailed Description

Files

Data Structures

Open modes

Stream function prototypes.

Generic access functions.

cURL stream

File descriptor stream

FILE stream

Memory stream

Null stream

Typedefs

Function Documentation

I/O streams.
[file68 library documentation.]