Bump version numbers for 3.13
[maemo-rb.git] / apps / buffering.h
blob6d5279423367d7b3d1f05621661e68ab7d496688
1 /***************************************************************************
2 * __________ __ ___.
3 * Open \______ \ ____ ____ | | _\_ |__ _______ ___
4 * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
5 * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
6 * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
7 * \/ \/ \/ \/ \/
8 * $Id$
10 * Copyright (C) 2007 Nicolas Pennequin
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.
17 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
18 * KIND, either express or implied.
20 ****************************************************************************/
22 #ifndef _BUFFERING_H_
23 #define _BUFFERING_H_
25 #include <sys/types.h>
26 #include <stdbool.h>
27 #include "config.h"
28 #include "appevents.h"
31 enum data_type {
32 TYPE_UNKNOWN = 0, /* invalid type indicator */
33 TYPE_ID3,
34 TYPE_CODEC,
35 TYPE_PACKET_AUDIO,
36 TYPE_ATOMIC_AUDIO,
37 TYPE_CUESHEET,
38 TYPE_BITMAP,
41 /* Error return values */
42 #define ERR_HANDLE_NOT_FOUND -1
43 #define ERR_BUFFER_FULL -2
44 #define ERR_INVALID_VALUE -3
45 #define ERR_FILE_ERROR -4
46 #define ERR_HANDLE_NOT_DONE -5
47 #define ERR_UNSUPPORTED_TYPE -6
50 /* Initialise the buffering subsystem */
51 void buffering_init(void) INIT_ATTR;
53 /* Reset the buffering system */
54 bool buffering_reset(char *buf, size_t buflen);
57 /***************************************************************************
58 * MAIN BUFFERING API CALLS
59 * ========================
61 * bufopen : Reserve space in the buffer for a given file
62 * bufalloc : Open a new handle from data that needs to be copied from memory
63 * bufclose : Close an open handle
64 * bufseek : Set handle reading index, relatively to the start of the file
65 * bufadvance: Move handle reading index, relatively to current position
66 * bufftell : Return the handle's file read position
67 * bufread : Copy data from a handle to a buffer
68 * bufgetdata: Obtain a pointer for linear access to a "size" amount of data
69 * bufgettail: Out-of-band get the last size bytes of a handle.
70 * bufcuttail: Out-of-band remove the trailing 'size' bytes of a handle.
72 * NOTE: bufread and bufgetdata will block the caller until the requested
73 * amount of data is ready (unless EOF is reached).
74 * NOTE: Tail operations are only legal when the end of the file is buffered.
75 ****************************************************************************/
77 #define BUF_MAX_HANDLES 256
79 int bufopen(const char *file, size_t offset, enum data_type type,
80 void *user_data);
81 int bufalloc(const void *src, size_t size, enum data_type type);
82 bool bufclose(int handle_id);
83 int bufseek(int handle_id, size_t newpos);
84 int bufadvance(int handle_id, off_t offset);
85 off_t bufftell(int handle_id);
86 ssize_t bufread(int handle_id, size_t size, void *dest);
87 ssize_t bufgetdata(int handle_id, size_t size, void **data);
88 ssize_t bufgettail(int handle_id, size_t size, void **data);
89 ssize_t bufcuttail(int handle_id, size_t size);
91 /***************************************************************************
92 * SECONDARY FUNCTIONS
93 * ===================
95 * buf_handle_data_type: return the handle's data type
96 * buf_is_handle: is the handle valid?
97 * buf_pin_handle: Disallow/allow handle movement. Handle may still be removed.
98 * buf_handle_offset: Get the offset of the first buffered byte from the file
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 ****************************************************************************/
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_set_base_handle(int handle_id);
110 size_t buf_length(void);
111 size_t buf_used(void);
112 bool buf_pin_handle(int handle_id, bool pin);
113 bool buf_signal_handle(int handle_id, bool signal);
114 #ifdef HAVE_IO_PRIORITY
115 void buf_back_off_storage(bool back_off);
116 #endif
118 /* Settings */
119 enum {
120 BUFFERING_SET_WATERMARK = 1,
121 BUFFERING_SET_CHUNKSIZE,
123 void buf_set_watermark(size_t bytes);
124 size_t buf_get_watermark(void);
126 /* Debugging */
127 struct buffering_debug {
128 int num_handles;
129 size_t buffered_data;
130 size_t wasted_space;
131 size_t data_rem;
132 size_t useful_data;
133 size_t watermark;
135 void buffering_get_debugdata(struct buffering_debug *dbgdata);
137 #endif