dkstream.h File Reference

Generic I/O API. More...

#include <dk.h>
#include <dktypes.h>
#include <zlib.h>
#include <bzlib.h>

Go to the source code of this file.

Defines

#define DK_STREAM_CMD_TEST   1
 Low-level API commands: Test support for command.
#define DK_STREAM_CMD_RDBUF   2
 Low-level API commands: Read bytes into buffer.
#define DK_STREAM_CMD_WRBUF   3
 Low-level API commands: Write bytes from buffer.
#define DK_STREAM_CMD_FINAL   4
 Low-level API commands: Flush after final write operation.
#define DK_STREAM_CMD_FINISH   5
 Low-level API commands: Stream is closed now.
#define DK_STREAM_CMD_REWIND   6
 Low-level API commands: Rewind to start of stream data.
#define DK_STREAM_CMD_FLUSH   7
 Low-level API commands: Flush.
#define DK_STREAM_CMD_AT_END   8
 Low-level API commands: Check whether end of input is reached.
#define DK_STREAM_CMD_GETS   9
 Low-level API commands: Get string.
#define DK_STREAM_CMD_PUTS   10
 Low-level API commands: Put string.
#define DK_STREAM_OPT_DOUBLE_NO_EXPONENT   1
 Do not use exponent notation for double values.

Functions

dk_stream_tdkstream_new (void *data, dk_stream_fct_t *fct)
 Create a new dk_stream_t dynamically.
void dkstream_delete (dk_stream_t *st)
 Release a dk_stream_t structure obtained from dkstream_new().
dk_stream_tdkstream_openfile (char *n, char *m, int i, int *r)
 Open stream for plain file.
dk_stream_tdkstream_opengz (char *n, char *m, int i, int *r)
 Open stream for gzip compressed file.
dk_stream_tdkstream_openbz2 (char *n, char *m, int i, int *r)
 Open stream for bzip2 compressed file.
dk_stream_tdkstream_for_file (FILE *f)
 Open stream for already opened file.
dk_stream_tdkstream_for_gz (gzFile gzf)
 Open stream for already gzFile.
dk_stream_tdkstream_for_bz2 (BZFILE *bzf)
 Open stream for already opened BZFILE.
void dkstream_close (dk_stream_t *st)
 Releases dk_stream_t structures obtained from dkstream_openfile(), dkstream_opengz(), dkstream_openbz2(), dkstream_for_file(), dkstream_for_gz() and dkstream_for_bz2().
size_t dkstream_write (dk_stream_t *s, char *b, size_t l)
 Write binary data to stream.
size_t dkstream_read (dk_stream_t *s, char *b, size_t l)
 Read binary data from stream.
int dkstream_wb_word (dk_stream_t *s, dk_word w)
 Write a word (2 bytes) to stream binary.
int dkstream_wb_uword (dk_stream_t *s, dk_uword w)
 Write an unsigned word (2 bytes) to stream binary.
int dkstream_wb_dword (dk_stream_t *s, dk_dword w)
 Write a double-word (4 bytes) to stream binary.
int dkstream_wb_udword (dk_stream_t *s, dk_udword w)
 Write an unsigned double-word (4 bytes) to stream binary.
int dkstream_wb_string (dk_stream_t *s, char *str)
 Write a string to stream in binary form.
int dkstream_rb_word (dk_stream_t *s, dk_word *w)
 Read word (2 bytes) binary from stream.
int dkstream_rb_uword (dk_stream_t *s, dk_uword *w)
 Read unsigned word (2 bytes) binary from stream.
int dkstream_rb_dword (dk_stream_t *s, dk_dword *d)
 Read double-word (4 bytes) binary from stream.
int dkstream_rb_udword (dk_stream_t *s, dk_udword *d)
 Read unsigned double-word (4 bytes) binary from stream.
char * dkstream_rb_string (dk_stream_t *s)
 Read string in binary form from stream.
int dkstream_puts (dk_stream_t *s, char *b)
 Write string in text form to stream.
int dkstream_puts_double_use_exp (dk_stream_t *s, double d)
 Write double in text form to stream.
int dkstream_puts_double (dk_stream_t *s, double d)
 Write double in text form to stream, exponent notation allowed.
int dkstream_puts_ul (dk_stream_t *s, unsigned long u)
 Write unsigned long in text form to stream.
int dkstream_puts_long (dk_stream_t *s, long l)
 Write long in text form to stream.
int dkstream_puts_array (dk_stream_t *s, char **a)
 Write a text (array of strings) in text form to stream.
char * dkstream_gets (dk_stream_t *s, char *b, size_t l)
 Retrieve text line from stream.
unsigned long dkstream_get_bytes_written (dk_stream_t *s)
 Get number of bytes written to the stream.
dk_stream_suffix_tdkstream_get_read_suffixes (void)
 Find file type suffixes to handle (read operations).
dk_stream_suffix_tdkstream_get_write_suffixes (void)
 Find file type suffixes to handle (write operations).
int dkstream_puts_double_no_exp (dk_stream_t *s, double d)
 Print double value to stream, avoid exponential notation.
int dkstream_puts_double_str_no_exp (dk_stream_t *s, char *t)
 Print double value in string to stream, avoid exponential notation.
void dkstream_set_double_no_exponent (dk_stream_t *s, int fl)
 Set up to deny (fl=1) or allow (fl=0) the use of exponent notation when printing double values.
int dkstream_get_double_no_exponent (dk_stream_t *s)
 Get flag for: no exponent notation for double values.


Detailed Description

Generic I/O API.

This module provides a generic I/O API allowing applications to use the same code regardless whether to write plain or compressed files (and may be network connections in the future...).

Functions in this module can be grouped into three categories:

To open a stream you should use dkstream_openfile(), dkstream_opengz(), dkstream_openbz2() and dkstream_close() instead of dkstream_new() and dkstream_delete(). If you already opened the file use dkstream_for_file(), dkstream_for_gz() or dkstream_for_bz2() to create a dk_stream_t.

Unless otherwise stated, int functions in this module return a positive number to indicate success or a true condition, 0 to indicate an error or an unfullfilled condition. Pointer functions return valid pointers on success, NULL on error.


Define Documentation

#define DK_STREAM_CMD_AT_END   8

Low-level API commands: Check whether end of input is reached.

#define DK_STREAM_CMD_FINAL   4

Low-level API commands: Flush after final write operation.

#define DK_STREAM_CMD_FINISH   5

Low-level API commands: Stream is closed now.

#define DK_STREAM_CMD_FLUSH   7

Low-level API commands: Flush.

#define DK_STREAM_CMD_GETS   9

Low-level API commands: Get string.

#define DK_STREAM_CMD_PUTS   10

Low-level API commands: Put string.

#define DK_STREAM_CMD_RDBUF   2

Low-level API commands: Read bytes into buffer.

#define DK_STREAM_CMD_REWIND   6

Low-level API commands: Rewind to start of stream data.

#define DK_STREAM_CMD_TEST   1

Low-level API commands: Test support for command.

#define DK_STREAM_CMD_WRBUF   3

Low-level API commands: Write bytes from buffer.

#define DK_STREAM_OPT_DOUBLE_NO_EXPONENT   1

Do not use exponent notation for double values.


Function Documentation

void dkstream_close ( dk_stream_t st  ) 

Releases dk_stream_t structures obtained from dkstream_openfile(), dkstream_opengz(), dkstream_openbz2(), dkstream_for_file(), dkstream_for_gz() and dkstream_for_bz2().

Parameters:
st The stream to close.

void dkstream_delete ( dk_stream_t st  ) 

Release a dk_stream_t structure obtained from dkstream_new().

Parameters:
st Stream data to release.

dk_stream_t* dkstream_for_bz2 ( BZFILE *  bzf  ) 

Open stream for already opened BZFILE.

The stream must be released using dkstream_close(). The BZFILE bzf is not closed by dkstream_close().

Parameters:
bzf The BZFILE.
Returns:
Stream to use for I/O.

dk_stream_t* dkstream_for_file ( FILE *  f  ) 

Open stream for already opened file.

The stream must be released using dkstream_close(). The file f is not closed by dkstream_close().

Parameters:
f The file.
Returns:
Stream to use for I/O.

dk_stream_t* dkstream_for_gz ( gzFile  gzf  ) 

Open stream for already gzFile.

The stream must be released using dkstream_close(). The gzFile gzf is not closed by dkstream_close().

Parameters:
gzf The gzFile.
Returns:
Stream to use for I/O.

unsigned long dkstream_get_bytes_written ( dk_stream_t s  ) 

Get number of bytes written to the stream.

Parameters:
s The stream to check.
Returns:
Number of bytes written to the stream.

int dkstream_get_double_no_exponent ( dk_stream_t s  ) 

Get flag for: no exponent notation for double values.

Parameters:
s Stream to retrieve information from.
Returns:
Flag value.

dk_stream_suffix_t* dkstream_get_read_suffixes ( void   ) 

Find file type suffixes to handle (read operations).

Returns:
Array of elements connecting a file type suffix to a stream-open function.

dk_stream_suffix_t* dkstream_get_write_suffixes ( void   ) 

Find file type suffixes to handle (write operations).

Returns:
Array of elements connecting a file type suffix to a stream open function.

char* dkstream_gets ( dk_stream_t s,
char *  b,
size_t  l 
)

Retrieve text line from stream.

Text is read from stream to the buffer until either the buffer is full or a newline is found.

Parameters:
s The stream to read from.
b The destination buffer.
l Length of buffer b in bytes.
Returns:
Pointer to buffer on success, NULL on error.

dk_stream_t* dkstream_new ( void *  data,
dk_stream_fct_t fct 
)

Create a new dk_stream_t dynamically.

The stream must be released using dkstream_delete().

Parameters:
data Data for the stream.
fct Low-level function for the stream.
Returns:
Pointer to the new dk_stream_t on success, NULL on error.

dk_stream_t* dkstream_openbz2 ( char *  n,
char *  m,
int  i,
int *  r 
)

Open stream for bzip2 compressed file.

The stream must be relased and the file must be closed using dkstream_close().

Parameters:
n Path name of the file.
m Open mode (i.e. "r", "w"...).
i Security checks to ignore (DK_SF_SEC_xxx).
r Pointer to a variable receiving the error code for failed security checks (if any).
Returns:
Stream to use for I/O.

dk_stream_t* dkstream_openfile ( char *  n,
char *  m,
int  i,
int *  r 
)

Open stream for plain file.

The stream must be relased and the file must be closed using dkstream_close().

Parameters:
n Path name of the file.
m Open mode (i.e. "r", "w"...).
i Security checks to ignore (DK_SF_SEC_xxx).
r Pointer to a variable receiving the error code for failed security checks (if any).
Returns:
Stream to use for I/O.

dk_stream_t* dkstream_opengz ( char *  n,
char *  m,
int  i,
int *  r 
)

Open stream for gzip compressed file.

The stream must be relased and the file must be closed using dkstream_close().

Parameters:
n Path name of the file.
m Open mode (i.e. "r", "w"...).
i Security checks to ignore (DK_SF_SEC_xxx).
r Pointer to a variable receiving the error code for failed security checks (if any).
Returns:
Stream to use for I/O.

int dkstream_puts ( dk_stream_t s,
char *  b 
)

Write string in text form to stream.

The string is written "as is" witout adding a trailing newline.

Parameters:
s The stream to write to.
b The string to write.
Returns:
Flag to indicate success.

int dkstream_puts_array ( dk_stream_t s,
char **  a 
)

Write a text (array of strings) in text form to stream.

A newline is appended after each array element. The array must be finished by a NULL pointer.

Parameters:
s The stream to write to.
a An array containing pointers to the strings to write.
Returns:
Flag to indicate success.

int dkstream_puts_double ( dk_stream_t s,
double  d 
)

Write double in text form to stream, exponent notation allowed.

Parameters:
s The stream to write to.
d The number to write.
Returns:
Flag to indicate success.

int dkstream_puts_double_no_exp ( dk_stream_t s,
double  d 
)

Print double value to stream, avoid exponential notation.

Parameters:
s Stream to print to.
d Value to print.
Returns:
Flag to indicate success.

int dkstream_puts_double_str_no_exp ( dk_stream_t s,
char *  t 
)

Print double value in string to stream, avoid exponential notation.

This function is not intended for use by the application programmer, it is used internally by dkstream_puts_double_no_exp().

Parameters:
s Stream to print to.
t Text buffer containing exponential notation.
Returns:
Flag to indicate success.

int dkstream_puts_double_use_exp ( dk_stream_t s,
double  d 
)

Write double in text form to stream.

Check opt for DK_STREAM_OPT_DOUBLE_NO_EXPONENT to see whether or not exponent notation is allowed.

Parameters:
s The stream to write to.
d The number to write.
Returns:
Flag to indicate success.

int dkstream_puts_long ( dk_stream_t s,
long  l 
)

Write long in text form to stream.

Parameters:
s The stream to write to.
l The value to write.
Returns:
Flag to indicate success.

int dkstream_puts_ul ( dk_stream_t s,
unsigned long  u 
)

Write unsigned long in text form to stream.

Parameters:
s The stream to write to.
u The value to write.
Returns:
Flag to indicate success.

int dkstream_rb_dword ( dk_stream_t s,
dk_dword d 
)

Read double-word (4 bytes) binary from stream.

Four bytes are read from stream and converted to host byte order.

Parameters:
s The stream to read from.
d Pointer to variable to store the result.
Returns:
Flag to indicate success.

char* dkstream_rb_string ( dk_stream_t s  ) 

Read string in binary form from stream.

Reading consists of the following steps:

  • The string length (2-byte word) is read from stream,
  • buffer memory is allocated dynamically to store string and
  • the string is read from stream into the buffer. You must release the strings memory using dk_delete() if the string is not longer needed.
    Parameters:
    s The stream to read from.
    Returns:
    Pointer to the buffer on success, NULL on error.

int dkstream_rb_udword ( dk_stream_t s,
dk_udword d 
)

Read unsigned double-word (4 bytes) binary from stream.

Four bytes are read from stream and converted to host byte order.

Parameters:
s The stream to read from.
d Pointer to variable to store the result.
Returns:
Flag to indicate success.

int dkstream_rb_uword ( dk_stream_t s,
dk_uword w 
)

Read unsigned word (2 bytes) binary from stream.

Two bytes are read from stream and converted to host byte order.

Parameters:
s The stream to read from.
w Pointer to variable to store the result.
Returns:
Flag to indicate success.

int dkstream_rb_word ( dk_stream_t s,
dk_word w 
)

Read word (2 bytes) binary from stream.

Two bytes are read from stream and converted to host byte order.

Parameters:
s The stream to read from.
w Pointer to variable to store the result.
Returns:
Flag to indicate success.

size_t dkstream_read ( dk_stream_t s,
char *  b,
size_t  l 
)

Read binary data from stream.

Parameters:
s The stream to read from.
b Pointer to buffer.
l Length of buffer in bytes.
Returns:
The number of bytes read.

void dkstream_set_double_no_exponent ( dk_stream_t s,
int  fl 
)

Set up to deny (fl=1) or allow (fl=0) the use of exponent notation when printing double values.

Parameters:
s Stream to configure.
fl New flag value.
Returns:
Flag to indicate success.

int dkstream_wb_dword ( dk_stream_t s,
dk_dword  w 
)

Write a double-word (4 bytes) to stream binary.

The double-word is converted to network byte order before it is written to the stream.

Parameters:
s The stream to write to.
w The double-word to write.
Returns:
Flag to indicate success.

int dkstream_wb_string ( dk_stream_t s,
char *  str 
)

Write a string to stream in binary form.

A string in binary form is written to the stream in 2 parts:

  • The string length (including the finalizing 0x00 byte) as unsigned word.
  • The string text including the finalizing 0x00 byte.
    Parameters:
    s The stream to write to.
    str The string to write.
    Returns:
    Flag to indicate success.

< return value

< string length from strlen()

< string length saved to stream

int dkstream_wb_udword ( dk_stream_t s,
dk_udword  w 
)

Write an unsigned double-word (4 bytes) to stream binary.

The double-word is converted to network byte order before it is written to the stream.

Parameters:
s The stream to write to.
w The double-word to write.
Returns:
Flag to indicate success.

int dkstream_wb_uword ( dk_stream_t s,
dk_uword  w 
)

Write an unsigned word (2 bytes) to stream binary.

The word is converted to network byte order before it is written to the stream.

Parameters:
s The stream to write to.
w The word to write.
Returns:
Flag to indicate success.

int dkstream_wb_word ( dk_stream_t s,
dk_word  w 
)

Write a word (2 bytes) to stream binary.

The word is converted to network byte order before it is written to the stream.

Parameters:
s The stream to write to.
w The word to write.
Returns:
Flag to indicate success.

size_t dkstream_write ( dk_stream_t s,
char *  b,
size_t  l 
)

Write binary data to stream.

Parameters:
s The stream to write to.
b Pointer to buffer containing data to write.
l Size of b in bytes.
Returns:
The number of bytes written.


Generated on Mon Jan 4 15:50:56 2010 for dklibs by  doxygen 1.5.8