apps/buffering.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2007 Nicolas Pennequin
  11  *
  12  * All files in this archive are subject to the GNU General Public License.
  13  * See the file COPYING in the source tree root for full license agreement.
  14  *
  15  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  16  * KIND, either express or implied.
  17  *
  18  ****************************************************************************/
  19
  20 #ifndef _BUFFERING_H_
  21 #define _BUFFERING_H_
  22
  23 #include <sys/types.h>
  24 #include <stdbool.h>
  25
  26
  27 enum data_type {
  28     TYPE_CODEC,
  29     TYPE_PACKET_AUDIO,
  30     TYPE_ATOMIC_AUDIO,
  31     TYPE_ID3,
  32     TYPE_CUESHEET,
  33     TYPE_IMAGE,
  34     TYPE_BUFFER,
  35     TYPE_UNKNOWN,
  36 };
  37
  38 /* Error return values */
  39 #define ERR_HANDLE_NOT_FOUND    -1
  40 #define ERR_BUFFER_FULL         -2
  41 #define ERR_INVALID_VALUE       -3
  42 #define ERR_FILE_ERROR          -4
  43
  44
  45 /* Initialise the buffering subsystem */
  46 void buffering_init(void);
  47
  48 /* Reset the buffering system */
  49 bool buffering_reset(char *buf, size_t buflen);
  50
  51
  52 /***************************************************************************
  53  * MAIN BUFFERING API CALLS
  54  * ========================
  55  *
  56  * bufopen   : Reserve space in the buffer for a given file
  57  * bufalloc  : Open a new handle from data that needs to be copied from memory
  58  * bufclose  : Close an open handle
  59  * bufseek   : Set handle reading index, relatively to the start of the file
  60  * bufadvance: Move handle reading index, relatively to current position
  61  * bufread   : Copy data from a handle to a buffer
  62  * bufgetdata: Obtain a pointer for linear access to a "size" amount of data
  63  *
  64  * NOTE: bufread and bufgetdata will block the caller until the requested
  65  * amount of data is ready (unless EOF is reached).
  66  ****************************************************************************/
  67
  68 #define BUF_MAX_HANDLES         256
  69
  70 int bufopen(const char *file, size_t offset, enum data_type type);
  71 int bufalloc(const void *src, size_t size, enum data_type type);
  72 bool bufclose(int handle_id);
  73 int bufseek(int handle_id, size_t newpos);
  74 int bufadvance(int handle_id, off_t offset);
  75 ssize_t bufread(int handle_id, size_t size, void *dest);
  76 ssize_t bufgetdata(int handle_id, size_t size, void **data);
  77
  78
  79 /***************************************************************************
  80  * SECONDARY FUNCTIONS
  81  * ===================
  82  *
  83  * buf_get_offset: Get a handle offset from a pointer
  84  * buf_handle_offset: Get the offset of the first buffered byte from the file
  85  * buf_request_buffer_handle: Request buffering of a handle
  86  * buf_set_base_handle: Tell the buffering thread which handle is currently read
  87  * buf_used: Total amount of buffer space used (including allocated space)
  88  ****************************************************************************/
  89
  90 ssize_t buf_get_offset(int handle_id, void *ptr);
  91 ssize_t buf_handle_offset(int handle_id);
  92 void buf_request_buffer_handle(int handle_id);
  93 void buf_set_base_handle(int handle_id);
  94 size_t buf_used(void);
  95
  96
  97 /***************************************************************************
  98  * CALLBACK UTILITIES
  99  * ==================
 100  *
 101  * register_buffer_low_callback, unregister_buffer_low_callback:
 102  *
 103  * Register/Unregister callback functions that will get executed when the buffer
 104  * goes below the low watermark. They are executed once, then forgotten.
 105  *
 106  * NOTE: The callbacks are called from the buffering thread, so don't make them
 107  * do too much. Ideally they should just post an event to a queue and return.
 108  ****************************************************************************/
 109
 110 #define MAX_BUF_CALLBACKS 4
 111 typedef void (*buffer_low_callback)(void);
 112 bool register_buffer_low_callback(buffer_low_callback func);
 113 void unregister_buffer_low_callback(buffer_low_callback func);
 114
 115 /* Settings */
 116 enum {
 117     BUFFERING_SET_WATERMARK = 1,
 118     BUFFERING_SET_CHUNKSIZE,
 119 };
 120 void buf_set_watermark(size_t bytes);
 121
 122
 123 /* Debugging */
 124 struct buffering_debug {
 125     int num_handles;
 126     size_t buffered_data;
 127     size_t wasted_space;
 128     size_t data_rem;
 129     size_t useful_data;
 130 };
 131 void buffering_get_debugdata(struct buffering_debug *dbgdata);
 132
 133 #endif