source: roaraudio/include/libroar/ltm.h @ 5381:430b1d26e12d

Last change on this file since 5381:430b1d26e12d was 5381:430b1d26e12d, checked in by phi, 12 years ago

updated copyright years

File size: 6.0 KB
Line 
1//ltm.h:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2010-2012
5 *
6 *  This file is part of libroar a part of RoarAudio,
7 *  a cross-platform sound system for both, home and professional use.
8 *  See README for details.
9 *
10 *  This file is free software; you can redistribute it and/or modify
11 *  it under the terms of the GNU General Public License version 3
12 *  as published by the Free Software Foundation.
13 *
14 *  libroar is distributed in the hope that it will be useful,
15 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *  GNU General Public License for more details.
18 *
19 *  You should have received a copy of the GNU General Public License
20 *  along with this software; see the file COPYING.  If not, write to
21 *  the Free Software Foundation, 51 Franklin Street, Fifth Floor,
22 *  Boston, MA 02110-1301, USA.
23 *
24 *  NOTE for everyone want's to change something and send patches:
25 *  read README and HACKING! There a addition information on
26 *  the license of this document you need to read before you send
27 *  any patches.
28 *
29 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
30 *  or libpulse*:
31 *  The libs libroaresd, libroararts and libroarpulse link this lib
32 *  and are therefore GPL. Because of this it may be illegal to use
33 *  them with any software that uses libesd, libartsc or libpulse*.
34 */
35
36#ifndef _LIBROARLTM_H_
37#define _LIBROARLTM_H_
38
39#include "libroar.h"
40
41// forward declaration for return type of roar_ltm_get().
42// you must not access members directly.
43struct roar_ltm_result;
44
45/* Register streams for LTM.
46 * Takes
47 * - connection to server,
48 * - used MT (monitoring type),
49 * - used window,
50 * - array of streams,
51 * - length of the array of streams.
52 * Returns -1 on error or 0 on no error.
53 *
54 * Registration is stacked.
55 * This means that if you register a stream twice you need to unregister it twice.
56 * This is because maybe clients may witch to use LTM and it would be bad
57 * if the first client which disconnects would remove the LTM from the stream.
58 */
59int roar_ltm_register(struct roar_connection * con, int mt, int window, int * streams, size_t slen);
60
61/* Unregister streams from LTM.
62 * This function works just like roar_ltm_register() just that it
63 * unregisters the streams again.
64 *
65 * The set of streams you unregister in one stream does not need to be
66 * the same as the set you registered. It is perfectly valid to just
67 * unregister a subset. or a larger set of streams.
68 *
69 * The given mt must match. If it does not the behavior is undefined.
70 * The server may refuse the request or just unregister the given bits.
71 * you should not do this.
72 *
73 * you must not unregister streams which got deleted by the server.
74 */
75int roar_ltm_unregister(struct roar_connection * con, int mt, int window, int * streams, size_t slen);
76
77/* Read values for LTM from the server.
78 * This function takes:
79 * - The connection to the server,
80 * - the monitoring types you request,
81 * - the window you request data from,
82 * - an array of streams you want data for,
83 * - the length of the streams array,
84 * - an old result of this function.
85 *
86 * It returns a pointer to an result object or NULL on error.
87 *
88 * The MT is allowed to not match the registered mt but must not
89 * contain more bits than registered. In most causes this match
90 * the registered MT.
91 *
92 * The window must match the window used then streams got registered.
93 *
94 * The list of streams must not match a single registration.
95 * but all streams must be registered with at least the bits used in mt
96 * set at registration.
97 *
98 * The old result is taken so this function does not need to always
99 * allocate new memory. If the given result is as big as needed to store
100 * the new result it is overwritten or freed and re-allocated if it is
101 * too small.
102 * If you do not have a old result set pass NULL.
103 *
104 * If you no longer need the result and will not call this function again
105 * you must free the result with roar_ltm_freeres().
106 */
107struct roar_ltm_result * roar_ltm_get(struct roar_connection * con, int mt, int window, int * streams, size_t slen, struct roar_ltm_result * oldresult);
108
109/* This function frees the result.
110 * This may be defined as macro. Never call the function
111 * this references as directly if this is a macro.
112 */
113#define roar_ltm_freeres(x) roar_mm_free((x))
114
115/* Get number of streams which are included in a result.
116 * returns -1 on error.
117 */
118int roar_ltm_get_numstreams(struct roar_ltm_result * res);
119
120/* Get the mt included in the given result.
121 * returns -1 on error.
122 */
123int roar_ltm_get_mt(struct roar_ltm_result * res);
124
125/* Get the window included in the given result.
126 * returns -1 on error.
127 */
128int roar_ltm_get_window(struct roar_ltm_result * res);
129
130/* Get the number of channels a stream in result has.
131 * Takes the result and the index of the stream in the result.
132 * The stream index is the index of the stream in the stream list
133 * you provided to roar_ltm_get(). This is not the stream id.
134 *
135 * returns -1 on error.
136 *
137 * You must use this function to get the number of channels for a stream
138 * and not any value you got on some other way.
139 * This is because this function returns the value in the very moment in witch the
140 * result set was collected in the server.
141 */
142int roar_ltm_get_numchans(struct roar_ltm_result * res, size_t streamidx);
143
144/* Extract a single value from the result.
145 * Takes
146 * - the result,
147 * - the mt for which you ask,
148 * - the index of the stream in the result and
149 * - The channel you request a value for.
150 *
151 * returns -1 on error.
152 *
153 * The mt parameter must not have more than one bit set.
154 *
155 * The stream index is the index of the stream in the stream list
156 * you provided to roar_ltm_get(). This is not the stream id.
157 *
158 * The channel is the channel number you ask data for.
159 * it must not be bigger than one less what roar_ltm_get_numchans() returned.
160 * (channels are counted from zero to N-1, not from 1 to N)
161 */
162int64_t roar_ltm_extract(struct roar_ltm_result * res, int mt, size_t streamidx, int channel);
163
164#endif
165
166//ll
Note: See TracBrowser for help on using the repository browser.