/* Copyright 2006 Garrett Rooney.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file etl_stream.h
 * @brief Functions for manipulating streams of bytes
 */

#ifndef ETL_STREAM_H
#define ETL_STREAM_H

#include <stddef.h>
#include <stdbool.h>

#include "etl_error.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** An abstract stream data type. */
typedef struct etl_stream_t etl_stream_t;

/** Callback that implements @c etl_stream_read. */
typedef etl_error_t *(*etl_stream_read_func_t)(void *baton,
                                               char *buffer,
                                               size_t *len);

/** Callback that implements @c etl_stream_write. */
typedef etl_error_t *(*etl_stream_write_func_t)(void *baton,
                                                const char *data,
                                                size_t *len);

/** Callback that implements @c etl_stream_destroy. */
typedef void (*etl_stream_destroy_func_t)(void *baton);

/** Create a new stream from @a rfunc, @a wfunc, @a dfunc, and @a baton. */
etl_stream_t *
etl_stream_create(etl_stream_read_func_t rfunc,
                  etl_stream_write_func_t wfunc,
                  etl_stream_destroy_func_t dfunc,
                  void *baton);

/** Read @a *len bytes to @a buffer from @a stream. */
etl_error_t *
etl_stream_read(etl_stream_t *stream, char *buffer, size_t *len);

/** Write @a *len bytes from @a buffer to @a stream. */
etl_error_t *
etl_stream_write(etl_stream_t *stream, const char *data, size_t *len);

/** Destroy @a stream. */
void
etl_stream_destroy(etl_stream_t *stream);

/**
 * Read a line from @a stream, up to a maximum of @a *len bytes, storing
 * them in @a buffer, and setting @a *eof to @c true if EOF is hit.
 */
etl_error_t *
etl_stream_readline(etl_stream_t *stream,
                    char *buffer,
                    size_t *len,
                    bool *eof);

/** A @c printf style write to @a stream. */
etl_error_t *
etl_stream_printf(etl_stream_t *stream, const char *fmt, ...);

enum {
  /** Open for read. */
  etl_stream_open_read = 0x01,

  /** Open for write. */
  etl_stream_open_write = 0x02,

  /** Create the file. */
  etl_stream_open_create = 0x04,

  /** Open for append. */
  etl_stream_open_append = 0x08,

  /** Truncate the file. */
  etl_stream_open_truncate = 0x10
};

/**
 * Open a stream that points to @a filename.
 *
 * @a flags controls read/write/create/append/truncate behavior.
 */
etl_error_t *
etl_stream_file_open(etl_stream_t **stream,
                     const char *filename,
                     int flags);

/** Open a stream that writes to standard output. */
etl_error_t *
etl_stream_stdout_open(etl_stream_t **stream);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* ETL_STREAM_H */