grapes / include / chunkbuffer.h @ master
History | View | Annotate | Download (3.65 KB)
1 |
#ifndef CHUNKBUFFER_H
|
---|---|
2 |
#define CHUNKBUFFER_H
|
3 |
|
4 |
/**
|
5 |
* @file chunkbuffer.h
|
6 |
*
|
7 |
* @brief This is the chunk buffer of the peer.
|
8 |
*
|
9 |
* The chunks buffer is responsible for storing the chunks received by a
|
10 |
* peer. Each chunk is stored until the chunk buffer decides to discard it
|
11 |
* (for example, when some kind of playout delay is expired), then it
|
12 |
* is removed from the buffer. The buffer makes its chunks available to
|
13 |
* the output module and to the scheduler, in form of an ordered list (chunks
|
14 |
* are ordered by timestamp). Since every chunk has a timestamp and a
|
15 |
* sequence number (the chunk ID), the chunk buffer's clients
|
16 |
* (scheduler and output module) can easily check if there are gaps in the
|
17 |
* list.
|
18 |
* See @link cb_test.c cb_test.c @endlink for an usage example
|
19 |
*
|
20 |
*/
|
21 |
|
22 |
/** @example cb_test.c
|
23 |
*
|
24 |
* A test program showing how to use the chunk buffer API.
|
25 |
*
|
26 |
*/
|
27 |
|
28 |
#define E_CB_OLD -1 /**< The chunk is too old */ |
29 |
#define E_CB_DUPLICATE -2 /**< The chunk is already in the buffer */ |
30 |
|
31 |
/**
|
32 |
* Structure describing a chunk buffer. This is an opaque type.
|
33 |
*/
|
34 |
typedef struct chunk_buffer ChunkBuffer; |
35 |
|
36 |
|
37 |
/**
|
38 |
* Allocate a chunk buffer.
|
39 |
*
|
40 |
* Allocate and initialise a chunk buffer structure, and return a pointer to
|
41 |
* it.
|
42 |
*
|
43 |
* @param config a text string containing some configuration parameters for
|
44 |
* the buffer, such as the playout delay and maybe some additional
|
45 |
* parameters (estimated size of the buffer, etc...)
|
46 |
* @return a pointer to the allocated chunk buffer in case of success, NULL
|
47 |
* otherwise
|
48 |
*/
|
49 |
struct chunk_buffer *cb_init(const char *config); |
50 |
|
51 |
/**
|
52 |
* Add a chunk to a buffer.
|
53 |
*
|
54 |
* Insert a chunk in the given buffer. One or more chunks can be removed
|
55 |
* from the buffer (if necessary, and according to the internal logic of
|
56 |
* the chunk buffer) to create space for the new one.
|
57 |
*
|
58 |
* @param cb a pointer to the chunk buffer
|
59 |
* @param c a pointer to the descriptor of the chunk to be inserted in the
|
60 |
* buffer
|
61 |
* @return >=0 in case of success, < 0 in case of failure
|
62 |
*/
|
63 |
int cb_add_chunk(struct chunk_buffer *cb, const struct chunk *c); |
64 |
|
65 |
/**
|
66 |
* Get the chunks from a buffer.
|
67 |
*
|
68 |
* Provide an (ordered) list of the chunks which are currently stored in
|
69 |
* the specified chunk buffer. Such list is stored in a C arrary (so,
|
70 |
* after calling chunks_array = cb_get_chunks(cb), chunks_array[i]
|
71 |
* contains the i^th chunk).
|
72 |
* Chunks are ordered by increasing chunk ID.
|
73 |
*
|
74 |
* @param cb a pointer to the chunks buffer
|
75 |
* @param n a pointer to an integer variable where number of chunks
|
76 |
* will be stored
|
77 |
* @return the chunks array if there are no failures and the buffer is not
|
78 |
* empty, NULL if the buffer is empty or in case of error (in case
|
79 |
* of error, n < 0; if the buffer is empty, n = 0).
|
80 |
*/
|
81 |
struct chunk *cb_get_chunks(const struct chunk_buffer *cb, int *n); |
82 |
|
83 |
/**
|
84 |
* Clear a chunk buffer
|
85 |
*
|
86 |
* Remove all the chunks from the specified chunk buffer.
|
87 |
*
|
88 |
* @param cb a pointer to the chunk buffer
|
89 |
* @return >= 0 in case of success, < 0 in case of error.
|
90 |
*/
|
91 |
int cb_clear(struct chunk_buffer *cb); |
92 |
|
93 |
/**
|
94 |
* Destroy a chunk buffer
|
95 |
*
|
96 |
* Remove all the chunks from the specified chunk buffer,
|
97 |
* and free all the memory dynamically allocated to it.
|
98 |
*
|
99 |
* @param cb a pointer to the chunk buffer
|
100 |
*/
|
101 |
void cb_destroy(struct chunk_buffer *cb); |
102 |
|
103 |
|
104 |
/*
|
105 |
* HA Functions
|
106 |
*/
|
107 |
|
108 |
/**
|
109 |
* Get a specific chunk from a buffer
|
110 |
*
|
111 |
* Provide one single chunk from the specified chunkbuffer,
|
112 |
* with the requested identifier.
|
113 |
*
|
114 |
* @param cb a pointer to the chunk buffer
|
115 |
* @param id the identifier of the chunk to be returned
|
116 |
* @return a pointer to the requested chunk
|
117 |
*/
|
118 |
const struct chunk *cb_get_chunk(const struct chunk_buffer *cb, int id); |
119 |
|
120 |
#endif /* CHUNKBUFFER_H */ |