Statistics
| Branch: | Revision:

grapes / include / chunkbuffer.h @ 79a13823

History | View | Annotate | Download (3.42 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
 */
19

    
20
#define E_CB_OLD -1
21
#define E_CB_DUPLICATE -2
22

    
23
/**
24
 * Structure describing a chunk buffer. This is an opaque type.
25
 */
26
typedef struct chunk_buffer ChunkBuffer;
27

    
28

    
29
/**
30
 * Allocate a chunk buffer.
31
 *
32
 * Allocate and initialise a chunk buffer structure, and return a pointer to
33
 * it.
34
 *
35
 * @param config a text string containing some configuration parameters for
36
 *        the buffer, such as the playout delay and maybe some additional
37
 *        parameters (estimated size of the buffer, etc...)
38
 * @return a pointer to the allocated chunk buffer in case of success, NULL
39
 *         otherwise
40
 */
41
struct chunk_buffer *cb_init(const char *config);
42

    
43
/**
44
 * Add a chunk to a buffer.
45
 *
46
 * Insert a chunk in the given buffer. One or more chunks can be removed
47
 * from the buffer (if necessary, and according to the internal logic of
48
 * the chunk buffer) to create space for the new one.
49
 *
50
 * @param cb a pointer to the chunk buffer
51
 * @param c a pointer to the descriptor of the chunk to be inserted in the
52
 *        buffer
53
 * @return >=0 in case of success, < 0 in case of failure
54
 */
55
int cb_add_chunk(struct chunk_buffer *cb, const struct chunk *c);
56

    
57
/** 
58
 * Get the chunks from a buffer.
59
 *
60
 * Provide an (ordered) list of the chunks which are currently stored in
61
 * the specified chunk buffer. Such list is stored in a C arrary (so,
62
 * after calling chunks_array = cb_get_chunks(cb), chunks_array[i]
63
 * contains the i^th chunk).
64
 * Chunks are ordered by increasing chunk ID.
65
 *
66
 * @param cb a pointer to the chunks buffer
67
 * @param n a pointer to an integer variable where number of chunks
68
 *        will be stored
69
 * @return the chunks array if there are no failures and the buffer is not
70
 *         empty, NULL if the buffer is empty or in case of error (in case
71
 *         of error, n < 0; if the buffer is empty, n = 0).
72
 */
73
struct chunk *cb_get_chunks(const struct chunk_buffer *cb, int *n);
74

    
75
/**
76
 * Clear a chunk buffer
77
 *
78
 * Remove all the chunks from the specified chunk buffer.
79
 *
80
 * @param cb a pointer to the chunk buffer
81
 * @return >= 0 in case of success, < 0 in case of error.
82
 */
83
int cb_clear(struct chunk_buffer *cb);
84

    
85
/**
86
 * Destroy a chunk buffer
87
 *
88
 * Remove all the chunks from the specified chunk buffer,
89
 * and free all the memory dynamically allocated to it.
90
 *
91
 * @param cb a pointer to the chunk buffer
92
 */
93
void cb_destroy(struct chunk_buffer *cb);
94

    
95

    
96
/*
97
 * HA Functions
98
 */
99

    
100
/**
101
 * Get a specific chunk from a buffer
102
 *
103
 * Provide one single chunk from the specified chunkbuffer,
104
 * with the requested identifier.
105
 *
106
 * @param cb a pointer to the chunk buffer
107
 * @param id the identifier of the chunk to be returned
108
 * @return a pointer to the requested chunk
109
*/
110
const struct chunk *cb_get_chunk(const struct chunk_buffer *cb, int id);
111

    
112
#endif        /* CHUNKBUFFER_H */