1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
#pragma once
#include "common.h"
#include "types.h"
/// @file resolver.h Stream resolution functions
/** @defgroup continuous_resolver The lsl_continuous_resolver
* @ingroup resolve
*
* Streams can be resolved at a single timepoint once (@ref resolve) or continuously in the
* background.
* @{
*/
/**
* Construct a new #lsl_continuous_resolver that resolves all streams on the network.
*
* This is analogous to the functionality offered by the free function lsl_resolve_streams().
* @param forget_after When a stream is no longer visible on the network (e.g. because it was shut
* down), this is the time in seconds after which it is no longer reported by the resolver.
*
* The recommended default value is 5.0.
*/
extern LIBLSL_C_API lsl_continuous_resolver lsl_create_continuous_resolver(double forget_after);
/**
* Construct a new lsl_continuous_resolver that resolves all streams with a specific value for a given
* property.
*
* This is analogous to the functionality provided by the free function lsl_resolve_byprop()
* @param prop The #lsl_streaminfo property that should have a specific value (e.g., "name", "type",
* "source_id", or "desc/manufaturer").
* @param value The string value that the property should have (e.g., "EEG" as the type property).
* @param forget_after When a stream is no longer visible on the network (e.g., because it was shut
* down), this is the time in seconds after which it is no longer reported by the resolver.
* The recommended default value is 5.0.
*/
extern LIBLSL_C_API lsl_continuous_resolver lsl_create_continuous_resolver_byprop(const char *prop, const char *value, double forget_after);
/**
* Construct a new lsl_continuous_resolver that resolves all streams that match a given XPath 1.0
* predicate.
*
* This is analogous to the functionality provided by the free function lsl_resolve_bypred()
* @param pred The predicate string, e.g.
* `"name='BioSemi'" or "type='EEG' and starts-with(name,'BioSemi') and count(info/desc/channel)=32"`
* @param forget_after When a stream is no longer visible on the network (e.g., because it was shut
* down), this is the time in seconds after which it is no longer reported by the resolver.
* The recommended default value is 5.0.
*/
extern LIBLSL_C_API lsl_continuous_resolver lsl_create_continuous_resolver_bypred(const char *pred, double forget_after);
/**
* Obtain the set of currently present streams on the network (i.e. resolve result).
*
* @param res A continuous resolver (previously created with one of the
* lsl_create_continuous_resolver() functions).
* @param buffer A user-allocated buffer to hold the current resolve results.<br>
* @attention It is the user's responsibility to either destroy the resulting streaminfo objects or
* to pass them back to the LSL during during creation of an inlet.
* @attention The stream_infos returned by the resolver are only short versions that do not include
* the lsl_get_desc() field (which can be arbitrarily big).
*
* To obtain the full stream information you need to call lsl_get_info() on the inlet after you have
* created one.
* @param buffer_elements The user-provided buffer length.
* @return The number of results written into the buffer (never more than the provided # of slots)
* or a negative number if an error has occurred (values corresponding to #lsl_error_code_t).
*/
extern LIBLSL_C_API int32_t lsl_resolver_results(lsl_continuous_resolver res, lsl_streaminfo *buffer, uint32_t buffer_elements);
/// Destructor for the continuous resolver.
extern LIBLSL_C_API void lsl_destroy_continuous_resolver(lsl_continuous_resolver res);
/// @}
/** @defgroup resolve Resolving streams on the network
* @{*/
/**
* Resolve all streams on the network.
*
* This function returns all currently available streams from any outlet on the network.
* The network is usually the subnet specified at the local router, but may also include a multicast
* group of machines (given that the network supports it), or a list of hostnames.<br>
* These details may optionally be customized by the experimenter in a configuration file
* (see page Network Connectivity in the LSL wiki).
* This is the default mechanism used by the browsing programs and the recording program.
* @param[out] buffer A user-allocated buffer to hold the resolve results.
* @attention It is the user's responsibility to either destroy the resulting streaminfo objects or
* to pass them back to the LSL during during creation of an inlet.
*
* @attention The stream_info's returned by the resolver are only short versions that do not include
* the lsl_get_desc() field (which can be arbitrarily big).
* To obtain the full stream information you need to call lsl_get_info() on the inlet after you have
* created one.
* @param buffer_elements The user-provided buffer length.
* @param wait_time The waiting time for the operation, in seconds, to search for streams.
* The recommended wait time is 1 second (or 2 for a busy and large recording operation).
* @warning If this is too short (<0.5s) only a subset (or none) of the outlets that are present on
* the network may be returned.
* @return The number of results written into the buffer (never more than the provided # of slots)
* or a negative number if an error has occurred (values corresponding to lsl_error_code_t).
*/
extern LIBLSL_C_API int32_t lsl_resolve_all(lsl_streaminfo *buffer, uint32_t buffer_elements, double wait_time);
/**
* Resolve all streams with a given value for a property.
*
* If the goal is to resolve a specific stream, this method is preferred over resolving all streams
* and then selecting the desired one.
* @param[out] buffer A user-allocated buffer to hold the resolve results.
* @attention It is the user's responsibility to either destroy the resulting streaminfo objects or
* to pass them back to the LSL during during creation of an inlet.
*
* @attention The stream_info's returned by the resolver are only short versions that do not include
* the lsl_get_desc() field (which can be arbitrarily big). To obtain the full stream information
* you need to call lsl_get_info() on the inlet after you have created one.
* @param buffer_elements The user-provided buffer length.
* @param prop The streaminfo property that should have a specific value (`"name"`, `"type"`,
* `"source_id"`, or, e.g., `"desc/manufaturer"` if present).
* @param value The string value that the property should have (e.g., "EEG" as the type).
* @param minimum Return at least this number of streams.
* @param timeout Optionally a timeout of the operation, in seconds (default: no timeout).
* If the timeout expires, less than the desired number of streams (possibly none) will be returned.
* @return The number of results written into the buffer (never more than the provided # of slots)
* or a negative number if an error has occurred (values corresponding to #lsl_error_code_t).
*/
extern LIBLSL_C_API int32_t lsl_resolve_byprop(lsl_streaminfo *buffer, uint32_t buffer_elements, const char *prop, const char *value, int32_t minimum, double timeout);
/**
* Resolve all streams that match a given predicate.
*
* Advanced query that allows to impose more conditions on the retrieved streams;
* the given string is an [XPath 1.0 predicate](http://en.wikipedia.org/w/index.php?title=XPath_1.0)
* for the `<info>` node (omitting the surrounding []'s)
* @param[out] buffer A user-allocated buffer to hold the resolve results.
* @attention It is the user's responsibility to either destroy the resulting streaminfo objects or
* to pass them back to the LSL during during creation of an inlet.
*
* @attention The stream_info's returned by the resolver are only short versions that do not include
* the lsl_get_desc() field (which can be arbitrarily big). To obtain the full stream information
* you need to call lsl_get_info() on the inlet after you have created one.
* @param buffer_elements The user-provided buffer length.
* @param pred The predicate string, e.g.
* `name='BioSemi'` or `type='EEG' and starts-with(name,'BioSemi') and count(info/desc/channel)=32`
* @param minimum Return at least this number of streams.
* @param timeout Optionally a timeout of the operation, in seconds (default: no timeout).
* If the timeout expires, less than the desired number of streams (possibly none)
* will be returned.
* @return The number of results written into the buffer (never more than the provided # of slots)
* or a negative number if an error has occurred (values corresponding to lsl_error_code_t).
*/
extern LIBLSL_C_API int32_t lsl_resolve_bypred(lsl_streaminfo *buffer, uint32_t buffer_elements, const char *pred, int32_t minimum, double timeout);
/// @}
|
