/*
 * Copyright 2013 MongoDB, Inc.
 *
 * 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.
 */


#ifndef BSON_READER_H
#define BSON_READER_H


#if !defined (BSON_INSIDE) && !defined (BSON_COMPILATION)
# error "Only <bson.h> can be included directly."
#endif


#include "bson-compat.h"
#include "bson-oid.h"
#include "bson-types.h"


BSON_BEGIN_DECLS


#define BSON_ERROR_READER_BADFD 1


/*
 *--------------------------------------------------------------------------
 *
 * bson_reader_read_func_t --
 *
 *       This function is a callback used by bson_reader_t to read the
 *       next chunk of data from the underlying opaque file descriptor.
 *
 *       This function is meant to operate similar to the read() function
 *       as part of libc on UNIX-like systems.
 *
 * Parameters:
 *       @handle: The handle to read from.
 *       @buf: The buffer to read into.
 *       @count: The number of bytes to read.
 *
 * Returns:
 *       0 for end of stream.
 *       -1 for read failure.
 *       Greater than zero for number of bytes read into @buf.
 *
 * Side effects:
 *       None.
 *
 *--------------------------------------------------------------------------
 */

typedef ssize_t (*bson_reader_read_func_t) (void  *handle, /* IN */
                                            void  *buf,    /* IN */
                                            size_t count); /* IN */


/*
 *--------------------------------------------------------------------------
 *
 * bson_reader_destroy_func_t --
 *
 *       Destroy callback to release any resources associated with the
 *       opaque handle.
 *
 * Parameters:
 *       @handle: the handle provided to bson_reader_new_from_handle().
 *
 * Returns:
 *       None.
 *
 * Side effects:
 *       None.
 *
 *--------------------------------------------------------------------------
 */

typedef void (*bson_reader_destroy_func_t) (void *handle); /* IN */


bson_reader_t *bson_reader_new_from_handle  (void                       *handle,
                                             bson_reader_read_func_t     rf,
                                             bson_reader_destroy_func_t  df);
bson_reader_t *bson_reader_new_from_fd      (int                         fd,
                                             bool                        close_on_destroy);
bson_reader_t *bson_reader_new_from_file    (const char                 *path,
                                             bson_error_t               *error);
bson_reader_t *bson_reader_new_from_data    (const uint8_t              *data,
                                             size_t                      length);
void           bson_reader_destroy          (bson_reader_t              *reader);
void           bson_reader_set_read_func    (bson_reader_t              *reader,
                                             bson_reader_read_func_t     func);
void           bson_reader_set_destroy_func (bson_reader_t              *reader,
                                             bson_reader_destroy_func_t  func);
const bson_t  *bson_reader_read             (bson_reader_t              *reader,
                                             bool                       *reached_eof);
off_t          bson_reader_tell             (bson_reader_t              *reader);
void           bson_reader_reset            (bson_reader_t              *reader);

BSON_END_DECLS


#endif /* BSON_READER_H */