Statistics
| Branch: | Revision:

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 */