Changeset 4294:d924eca8d99f in roaraudio


Ignore:
Timestamp:
08/31/10 03:12:53 (14 years ago)
Author:
phi
Branch:
default
Phase:
public
Message:

added more infos on the usage of the functions

File:
1 edited

Legend:

Unmodified
Added
Removed
  • include/libroar/ltm.h

    r4293 r4294  
    3939#include "libroar.h" 
    4040 
     41// forward declaration for return type of roar_ltm_get(). 
     42// you must not access members directly. 
    4143struct roar_ltm_result; 
    4244 
     45/* Register streams for LTM. 
     46 * Takes 
     47 * - connection to server, 
     48 * - used MT (monetoring 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 becaue maybe clients may wich to use LTM and it would be bad 
     57 * if the first client which disconnects would remove the LTM from the stream. 
     58 */ 
    4359int 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 musst match. If it does not the behavor 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 */ 
    4475int roar_ltm_unregister(struct roar_connection * con, int mt, int window, int * streams, size_t slen); 
    4576 
     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 registred 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 registred 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 */ 
    46107struct roar_ltm_result * roar_ltm_get(struct roar_connection * con, int mt, int window, int * streams, size_t slen, struct roar_ltm_result * oldresult); 
    47108 
     109/* This function frees the result. 
     110 * This may be defined as macro. Never call the function 
     111 * this refrences as directly if this is a macro. 
     112 */ 
    48113#define roar_ltm_freeres(x) roar_mm_free((x)) 
    49114 
     115/* Get number of streams which are included in a result. 
     116 * returns -1 on error. 
     117 */ 
    50118int 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 */ 
    51123int 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 */ 
    52128int roar_ltm_get_window(struct roar_ltm_result * res); 
    53129 
     130/* Get the number of channels a stream in result has. 
     131 * Thakes 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 becaue this function returns the value in the very moment in witch the 
     140 * result set was collected in the server. 
     141 */ 
    54142int roar_ltm_get_numchans(struct roar_ltm_result * res, int streamidx); 
     143 
     144/* Extract a single value from the result. 
     145 * Thakes 
     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() retruned. 
     160 * (channels are counted from zero to N-1, not from 1 to N) 
     161 */ 
    55162int64_t roar_ltm_extract(struct roar_ltm_result * res, int mt, int streamidx, int channel); 
    56163 
Note: See TracChangeset for help on using the changeset viewer.