# dklibs 1.26.0

- Overview
- Download
- Download / Installation
- Installation from source on Windows systems
- Usage
- FAQ
- Change log
- Other projects
- Tutorial
- Developer docu
- stc
- tracecc and trana
- tracecc GUI
- tracecc PDF man.
- API: sort and search
- API: Generic I/O
- Preferences
- File search
- Font configuration
- LaTeX encodings
- Security

## API: Generic I/O

- Overview
- Handler function commands

### Overview

To use other I/O mechanisms than already supported with the dkstreams module you have to provide two functions:

- a handler function (sometimes referred to as callback function) and
- a function to open I/O resources and create a stream.

The dkstream_...() functions use the dk_stream_api_t to pass arguments to the handler function and to obtain the result.
The handler function must be of type
void handler_function(dk_stream_api_t *apiptr);
The function has to check whether apiptr is a valid pointer. A pointer to the dk_stream_t originating the handler request can be retrieved as

    dk_stream_t *s;
    s = (dk_stream_t *)(apiptr->strm);

The assisting data pointer can be retrieved from

    s->data

The assisting data pointer is allowed to be NULL if the handler function can work without additional data.

### Handler function commands

The apiptr->cmd component contains an int value to indicate the type of the request.

- DK_STREAM_CMD_TEST
  Check whether or not a request type is supported.
  This command is primarily used to check for a functionality like fgets() reading until the end of line.

  Function invokation: | (apiptr->params).cmd | The command to check for. An int value as used in the request type.

  Function return:

  apiptr->return_value

  - 1
    on success (command can be handled)
  - 0
    on error (command can not be handled)

- DK_STREAM_CMD_AT_END
  Check whether end of readable data is reached (no more data available).

  Function return:

  apiptr->return_value

  - 1
    if end of data is reached
  - 0
    if there is still data available

- DK_STREAM_CMD_FGETS
  Read a line of text (finished by newline) into a buffer.

  Function invokation: | (apiptr->params).buffer | Start address of buffer.
  | (apiptr->params).length | Buffer length in bytes.

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

- DK_STREAM_CMD_RDBUF
  Read bytes into buffer.

  Function invokation: | (apiptr->params).buffer | Start address of buffer.
  | (apiptr->params).length | Buffer length in bytes.

  Function return:

  apiptr->return_value

  - 1
    on success (any data was read)
  - 0
    on error.

  | (apiptr->results).used | Number of bytes successfully read, only set if return_value indicates success..

- DK_STREAM_CMD_FPUTS
  Write a string.

  Function invokation: | (apiptr->params).buffer | Start address of string.

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

  | (apiptr->results).used | Number of bytes written, set only if return_value indicates success..

- DK_STREAM_CMD_WRBUF
  Write a buffer to stream.

  Function invokation: | (apiptr->params).buffer | Start address of buffer.
  | (apiptr->params).length | Buffer length in bytes.

  Function return:

  apiptr->return_value

  - 1
    on (at least partial) success
  - 0
    on error (not any byte written).

  | (apiptr->results).used | Number of bytes written, only set if return_value indicates success..

- DK_STREAM_CMD_FLUSH
  Perform intermediate flush if possible.
  I/O operations on files and gzipped files can perform flushes before end of data is reached.
  Some encoding mechanisms (i.e. ASCII85 used in PS level 2 and 3) handle fixed block sizes only (except the final block). In these cases you must not perform intermediate flushes.

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

- DK_STREAM_CMD_FINAL
  Perform final flush before closing the stream. No further data will be written. Encoding mechanisms with fixed block sizes can now handle the possibly incomplete final block.

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

- DK_STREAM_CMD_REWIND
  Rewind the stream to start reading at the beginning.

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

- DK_STREAM_CMD_FINISH
  Flush and close the stream, release all resources which were allocated by the dkstream_open_...() function. This is invoked as a part of dkstream_close().

  Function return:

  apiptr->return_value

  - 1
    on success
  - 0
    on error.

The dkstream_open_...() function must open/allocate I/O resources. This allocation must result in on variable (possibly a struct). Next the dkstream_new() function is called, a pointer to the new variable and a pointer to the handler function must be provided.

In dkstream_close() the handler function is called with DK_STREAM_CMD_FINISH. This is the point to flush output and close/deallocate the resources before dkstream_close() calls dkstream_delete().

See dkstream_openfile() in the ``dkstream.c'' module as an example.