grapes / include / chunkbuffer.h @ master
History | View | Annotate | Download (3.65 KB)
1 | 40be1074 | Luca Abeni | #ifndef CHUNKBUFFER_H
|
---|---|---|---|
2 | #define CHUNKBUFFER_H
|
||
3 | |||
4 | /**
|
||
5 | * @file chunkbuffer.h
|
||
6 | *
|
||
7 | 7fcd5e5c | MarcoBiazzini | * @brief This is the chunk buffer of the peer.
|
8 | 40be1074 | Luca Abeni | *
|
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 | 260312ee | Luca Abeni | * 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 | 40be1074 | Luca Abeni | */
|
27 | |||
28 | 8ba11988 | Luca Abeni | #define E_CB_OLD -1 /**< The chunk is too old */ |
29 | #define E_CB_DUPLICATE -2 /**< The chunk is already in the buffer */ |
||
30 | 830aa993 | Csaba Kiraly | |
31 | 40be1074 | Luca Abeni | /**
|
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 | 4affd2bf | MarcoBiazzini | * after calling chunks_array = cb_get_chunks(cb), chunks_array[i]
|
71 | 40be1074 | Luca Abeni | * contains the i^th chunk).
|
72 | 79a13823 | Csaba Kiraly | * Chunks are ordered by increasing chunk ID.
|
73 | 40be1074 | Luca Abeni | *
|
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 | c3ed3606 | Luca Abeni | /**
|
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 | 87cee676 | Luca Abeni | |
104 | /*
|
||
105 | * HA Functions
|
||
106 | */
|
||
107 | 4affd2bf | MarcoBiazzini | |
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 | 87cee676 | Luca Abeni | const struct chunk *cb_get_chunk(const struct chunk_buffer *cb, int id); |
119 | |||
120 | 40be1074 | Luca Abeni | #endif /* CHUNKBUFFER_H */ |