CamelSeekableStream
3
CAMEL Library

# CamelSeekableStream

## Synopsis

    struct              CamelSeekableStream;
    enum                CamelStreamSeekPolicy;
    #define             CAMEL_STREAM_UNBOUND
    off_t               camel_seekable_stream_seek          (CamelSeekableStream *stream,
                                                             off_t offset,
                                                             CamelStreamSeekPolicy policy);
    off_t               camel_seekable_stream_tell          (CamelSeekableStream *stream);
    int                 camel_seekable_stream_set_bounds    (CamelSeekableStream *stream,
                                                             off_t start,
                                                             off_t end);

## Description

## Details

### struct CamelSeekableStream

    struct CamelSeekableStream {
    	CamelStream parent_object;

    	off_t position;		/* current postion in the stream */
    	off_t bound_start;	/* first valid position */
    	off_t bound_end;	/* first invalid position */
    };

### enum CamelStreamSeekPolicy

    typedef enum {
    	CAMEL_STREAM_SET = SEEK_SET,
    	CAMEL_STREAM_CUR = SEEK_CUR,
    	CAMEL_STREAM_END = SEEK_END
    } CamelStreamSeekPolicy;

### CAMEL_STREAM_UNBOUND

    #define CAMEL_STREAM_UNBOUND (~0)

### camel_seekable_stream_seek ()

    off_t               camel_seekable_stream_seek          (CamelSeekableStream *stream,
                                                             off_t offset,
                                                             CamelStreamSeekPolicy policy);

Seek to the specified position in `stream`.

If `policy` is CAMEL_STREAM_SET, seeks to `offset`.

If `policy` is CAMEL_STREAM_CUR, seeks to the current position plus `offset`.

If `policy` is CAMEL_STREAM_END, seeks to the end of the stream plus `offset`.

Regardless of `policy`, the stream's final position will be clamped to the range specified by its lower and upper bounds, and the stream's eos state will be updated.

`stream` :

  a CamelStream object

`offset` :

  offset value

`policy` :

  what to do with the offset

Returns :

  new position, `-1` if operation failed.

### camel_seekable_stream_tell ()

    off_t               camel_seekable_stream_tell          (CamelSeekableStream *stream);

Get the current position of a seekable stream.

`stream` :

  a CamelSeekableStream object

Returns :

  the current position of the stream.

### camel_seekable_stream_set_bounds ()

    int                 camel_seekable_stream_set_bounds    (CamelSeekableStream *stream,
                                                             off_t start,
                                                             off_t end);

Set the range of valid data this stream is allowed to cover. If there is to be no `end` value, then `end` should be set to CAMEL_STREAM_UNBOUND.

`stream` :

  a CamelSeekableStream object

`start` :

  the first valid position

`end` :

  the first invalid position, or CAMEL_STREAM_UNBOUND

Returns :

  %-1 on error.