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  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  18  * KIND, either express or implied.
  19  *
  20  ****************************************************************************/
  21
  22 #ifndef _BUFFERING_H_
  23 #define _BUFFERING_H_
  24
  25 #include <sys/types.h>
  26 #include <stdbool.h>
  27 #include "appevents.h"
  28
  29
  30 enum data_type {
  31     TYPE_UNKNOWN = 0, /* invalid type indicator */
  32     TYPE_ID3,
  33     TYPE_CODEC,
  34     TYPE_PACKET_AUDIO,
  35     TYPE_ATOMIC_AUDIO,
  36     TYPE_CUESHEET,
  37     TYPE_BITMAP,
  38 };
  39
  40 /* Error return values */
  41 #define ERR_HANDLE_NOT_FOUND    -1
  42 #define ERR_BUFFER_FULL         -2
  43 #define ERR_INVALID_VALUE       -3
  44 #define ERR_FILE_ERROR          -4
  45 #define ERR_HANDLE_NOT_DONE     -5
  46 #define ERR_UNSUPPORTED_TYPE    -6
  47
  48
  49 /* Initialise the buffering subsystem */
  50 void buffering_init(void);
  51
  52 /* Reset the buffering system */
  53 bool buffering_reset(char *buf, size_t buflen);
  54
  55
  56 /***************************************************************************
  57  * MAIN BUFFERING API CALLS
  58  * ========================
  59  *
  60  * bufopen   : Reserve space in the buffer for a given file
  61  * bufalloc  : Open a new handle from data that needs to be copied from memory
  62  * bufclose  : Close an open handle
  63  * bufseek   : Set handle reading index, relatively to the start of the file
  64  * bufadvance: Move handle reading index, relatively to current position
  65  * bufftell  : Return the handle's file read position
  66  * bufread   : Copy data from a handle to a buffer
  67  * bufgetdata: Obtain a pointer for linear access to a "size" amount of data
  68  * bufgettail: Out-of-band get the last size bytes of a handle.
  69  * bufcuttail: Out-of-band remove the trailing 'size' bytes of a handle.
  70  *
  71  * NOTE: bufread and bufgetdata will block the caller until the requested
  72  * amount of data is ready (unless EOF is reached).
  73  * NOTE: Tail operations are only legal when the end of the file is buffered.
  74  ****************************************************************************/
  75
  76 #define BUF_MAX_HANDLES         256
  77
  78 int bufopen(const char *file, size_t offset, enum data_type type,
  79             void *user_data);
  80 int bufalloc(const void *src, size_t size, enum data_type type);
  81 bool bufclose(int handle_id);
  82 int bufseek(int handle_id, size_t newpos);
  83 int bufadvance(int handle_id, off_t offset);
  84 off_t bufftell(int handle_id);
  85 ssize_t bufread(int handle_id, size_t size, void *dest);
  86 ssize_t bufgetdata(int handle_id, size_t size, void **data);
  87 ssize_t bufgettail(int handle_id, size_t size, void **data);
  88 ssize_t bufcuttail(int handle_id, size_t size);
  89
  90 /***************************************************************************
  91  * SECONDARY FUNCTIONS
  92  * ===================
  93  *
  94  * buf_handle_data_type: return the handle's data type
  95  * buf_is_handle: is the handle valid?
  96  * buf_pin_handle: Disallow/allow handle movement. Handle may still be removed.
  97  * buf_handle_offset: Get the offset of the first buffered byte from the file
  98  * buf_request_buffer_handle: Request buffering of a handle
  99  * buf_set_base_handle: Tell the buffering thread which handle is currently read
 100  * buf_length: Total size of ringbuffer
 101  * buf_used: Total amount of buffer space used (including allocated space)
 102  * buf_back_off_storage: tell buffering thread to take it easy
 103  ****************************************************************************/
 104
 105 enum data_type buf_handle_data_type(int handle_id);
 106 ssize_t buf_handle_remaining(int handle_id);
 107 bool buf_is_handle(int handle_id);
 108 ssize_t buf_handle_offset(int handle_id);
 109 void buf_request_buffer_handle(int handle_id);
 110 void buf_set_base_handle(int handle_id);
 111 size_t buf_length(void);
 112 size_t buf_used(void);
 113 bool buf_pin_handle(int handle_id, bool pin);
 114 bool buf_signal_handle(int handle_id, bool signal);
 115 #ifdef HAVE_IO_PRIORITY
 116 void buf_back_off_storage(bool back_off);
 117 #endif
 118
 119 /* Settings */
 120 enum {
 121     BUFFERING_SET_WATERMARK = 1,
 122     BUFFERING_SET_CHUNKSIZE,
 123 };
 124 void buf_set_watermark(size_t bytes);
 125 size_t buf_get_watermark(void);
 126
 127 /* Debugging */
 128 struct buffering_debug {
 129     int num_handles;
 130     size_t buffered_data;
 131     size_t wasted_space;
 132     size_t data_rem;
 133     size_t useful_data;
 134     size_t watermark;
 135 };
 136 void buffering_get_debugdata(struct buffering_debug *dbgdata);
 137
 138 #endif