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_BITMAP,
  34     TYPE_BUFFER,
  35     TYPE_UNKNOWN,
  36 };
  37
  38 enum callback_event {
  39     EVENT_DEFAULT,
  40     EVENT_BUFFER_LOW,
  41     EVENT_HANDLE_REBUFFER,
  42     EVENT_HANDLE_CLOSED,
  43     EVENT_HANDLE_MOVED,
  44     EVENT_HANDLE_FINISHED,
  45 };
  46
  47 /* Error return values */
  48 #define ERR_HANDLE_NOT_FOUND    -1
  49 #define ERR_BUFFER_FULL         -2
  50 #define ERR_INVALID_VALUE       -3
  51 #define ERR_FILE_ERROR          -4
  52 #define ERR_HANDLE_NOT_DONE     -5
  53
  54
  55 /* Initialise the buffering subsystem */
  56 void buffering_init(void);
  57
  58 /* Reset the buffering system */
  59 bool buffering_reset(char *buf, size_t buflen);
  60
  61
  62 /***************************************************************************
  63  * MAIN BUFFERING API CALLS
  64  * ========================
  65  *
  66  * bufopen   : Reserve space in the buffer for a given file
  67  * bufalloc  : Open a new handle from data that needs to be copied from memory
  68  * bufclose  : Close an open handle
  69  * bufseek   : Set handle reading index, relatively to the start of the file
  70  * bufadvance: Move handle reading index, relatively to current position
  71  * bufread   : Copy data from a handle to a buffer
  72  * bufgetdata: Obtain a pointer for linear access to a "size" amount of data
  73  * bufgettail: Out-of-band get the last size bytes of a handle.
  74  * bufcuttail: Out-of-band remove the trailing 'size' bytes of a handle.
  75  *
  76  * NOTE: bufread and bufgetdata will block the caller until the requested
  77  * amount of data is ready (unless EOF is reached).
  78  * NOTE: Tail operations are only legal when the end of the file is buffered.
  79  ****************************************************************************/
  80
  81 #define BUF_MAX_HANDLES         256
  82
  83 int bufopen(const char *file, size_t offset, enum data_type type);
  84 int bufalloc(const void *src, size_t size, enum data_type type);
  85 bool bufclose(int handle_id);
  86 int bufseek(int handle_id, size_t newpos);
  87 int bufadvance(int handle_id, off_t offset);
  88 ssize_t bufread(int handle_id, size_t size, void *dest);
  89 ssize_t bufgetdata(int handle_id, size_t size, void **data);
  90 ssize_t bufgettail(int handle_id, size_t size, void **data);
  91 ssize_t bufcuttail(int handle_id, size_t size);
  92
  93
  94 /***************************************************************************
  95  * SECONDARY FUNCTIONS
  96  * ===================
  97  *
  98  * buf_get_offset: Get a handle offset from a pointer
  99  * buf_handle_offset: Get the offset of the first buffered byte from the file
 100  * buf_request_buffer_handle: Request buffering of a handle
 101  * buf_set_base_handle: Tell the buffering thread which handle is currently read
 102  * buf_used: Total amount of buffer space used (including allocated space)
 103  ****************************************************************************/
 104
 105 ssize_t buf_get_offset(int handle_id, void *ptr);
 106 ssize_t buf_handle_offset(int handle_id);
 107 void buf_request_buffer_handle(int handle_id);
 108 void buf_set_base_handle(int handle_id);
 109 size_t buf_used(void);
 110
 111
 112 /***************************************************************************
 113  * CALLBACK UTILITIES
 114  * ==================
 115  *
 116  * register_buffering_callback, unregister_buffering_callback:
 117  *
 118  * Register/Unregister callback functions that will get executed when the buffer
 119  * goes below the low watermark. They are executed once, then forgotten.
 120  *
 121  * NOTE: The callbacks are called from the buffering thread, so don't make them
 122  * do too much. Ideally they should just post an event to a queue and return.
 123  ****************************************************************************/
 124
 125 #define MAX_BUF_CALLBACKS 4
 126 typedef void (*buffering_callback)(enum callback_event ev, int value);
 127 bool register_buffering_callback(buffering_callback func);
 128 void unregister_buffering_callback(buffering_callback func);
 129
 130 /* Settings */
 131 enum {
 132     BUFFERING_SET_WATERMARK = 1,
 133     BUFFERING_SET_CHUNKSIZE,
 134 };
 135 void buf_set_watermark(size_t bytes);
 136
 137
 138 /* Debugging */
 139 struct buffering_debug {
 140     int num_handles;
 141     size_t buffered_data;
 142     size_t wasted_space;
 143     size_t data_rem;
 144     size_t useful_data;
 145 };
 146 void buffering_get_debugdata(struct buffering_debug *dbgdata);
 147
 148 #endif