Statistics
| Branch: | Revision:

napa-baselibs / include / repoclient.h @ 507372bb

History | View | Annotate | Download (13.1 KB)

1
#ifndef _REPOCLIENT_H
2
#define _REPOCLIENT_H
3

    
4
/** @file repoclient.h
5
 * 
6
 * Client-side interface for the Repository.
7
 *
8
 * Peers access the Repository for querying measurement results (PeerIDs satisfying a given query)
9
 * and publish MeasurementRecords generated by their Monitoring modules.
10
 * The following data structures and function definitions facilitate this (client-side) access to a repository.
11
 * 
12
 * Overall considerations:
13
        -# In the prototype, the Repository operates as a cental network resource (server). However, peers
14
may execute several repoclient instances, and connect to several Repository servers at the same time.
15
and has its own executable program, to be run independent of other NAPA processes. 
16
        -# The repository controller uses an internal network protocol for querying and publishing (inserting) measurement records, and this API defines the client side of this protocol.
17
        -# The following kinds of queries are supported:
18
                -# Metadata query: list of available (or implemented/supported) 
19
measurement kinds (measurementIDs)
20
                -# Peer-Query: resulting a list of peers, satisfying the supplied condition 
21
on measurement values, ordered by a supplied linear function over measurements
22
                -# Measurement value query: returning measurement record(s) for a given PeerID 
23
        -# The design of the repository client API follows the reactive, event-based pattern: function calls are
24
        aynchronous, i.e. the caller passes a <i>callback</i> function which is called when the result becomes 
25
        available. Consequently, all calls are non-blocking and return immediately.
26
 *
27
 * <b>Repository Protocol Description</b>
28
 * 
29
 * Internally, the Repository uses a HTTP-based client-server network protocol.
30
 * All protocol operations are text-encoded as HTTP GET operations.
31
 * Additionally, there is a HTTP POST based interface for PUBLISH operations where batch publish requests can be sent.
32
 * Clients connect to Respository servers over a well-known TCP port, and issue HTTP requests as described below.
33
 * Operation success or failure is indicated with a standard HTTP error code, 200 (HTTP OK) for success, or a standard
34
 * HTTP error code such as 403 (Bad Request), 404 (Not Found) or 500 (Internal Server Error).
35
 *
36
 * Repository server answers (if any) are always of MIME type "plain/text".
37
 *
38
 * Protocol elements and encodings:
39
         - <b>Pubish</b> Used to publish measurement results (a MeasurementRecord) into the Repository.
40
                - Encoding: <tt>http://reposerver:port/Publish?originator=o&targetA=a&targetB=b&publish_name=n&value=v&string_value=s&channel=c&timestamp=ts</tt><br>
41
                where each argument represents the corresponding field from MeasurementRecord. 
42
                All values are interpreted as strings, except <i>value</i> (double) and <i>timestamp</i>, which is
43
                encoded by one of the following encodings:
44
                        - an integer (seconds since 1970-01-01 00:00:00) 
45
                        - using the format YYYY-MM-DD_HH24:mm:ss 
46
                        - using the word <tt>now</tt><br> (default if timestamp is missing)
47
                Mandatory arguments are: <i>originator</i>, <i>targetA</i>, <i>publish_name</i>. 
48
                Omitted values default to NULL (or NaN for <i>value</i>
49
                Alternative (HTTP POST) encoding: <tt>http://reposerver:port/BatchPublish</tt>
50
                The POST DATA contains text-encoded MeasurementRecords of the same format as used with the GET
51
                method (i.e. starting with originator=o...)
52
                - Returns: a HTTP error code, 200 for OK.
53
        - <b>ListMeasurementNames</b> is used to obtain a list of measurement names the Repository has data for.
54
                - Encoding: <tt>http://reposerver:port/ListMeasurementNames?maxresults=m&channel=c</tt><br>
55
                - Returns: a HTTP error code, 200 for OK and the textual names of MeasurementNames, one item per line.
56
                  At most <i>m</i> items are returned ((unlimited if m <= 0, which is the default if m is omitted).
57
        - <b>GetPeers</b> is used to obtain a list of peers satisfying given criteria. 
58
                - Encoding: <tt>http://reposerver:port/GetPeers?maxresults=m&constraints=mtype,min,max;mtype,min,max;...&ranking=mtype,w;mtype,w...&channel=c</tt><br>
59
                <i>constraints</i> and <i>ranking</i> tuples correspond to Constraint and Ranking specifications 
60
                (each tuple is separated by a semicolon), and <i>maxresults</i>
61
                specifies the maximum number of peers to return (unlimited if m <= 0, which is the default if m is omitted).
62
                All parameters are optional. If no Ranking is specified, the results are returned in random order.
63
                - Returns: a HTTP error code, 200 for OK and the PeerIDs of the peers found, one item per line.
64
        - <b>CountPeers</b> Similar to GetPeers, just returns the number of matching PeerIDs
65
                - Encoding: <tt>http://reposerver:port/CountPeers?maxresults=n&c=mtype,min,max;...&r=mtype,w;...&channel=c</tt><br>
66
                - Returns: a HTTP error code, 200 for OK and the number PeerIDs (a single integer followed by a newline)
67
        - <b>GetMeasurements</b> Used to obtain entire measurement records
68
                - Encoding: <tt>http://reposerver:port/GetMeasurements?maxresults=m&originator=o&targetA=a&targetB=b&publish_name=n&channel=c</tt><br>
69
                where all parameters are optional and function as filters, except for <i>maxresults</i>, which has the
70
                same meaning as in the above functions.
71
                - Returns: a HTTP error code, 200 for OK and the MeasurementRecords found, one item per line,
72
                in the same format what is used for the Publish call.  Missing (NULL-valued) fields are omitted.
73
*/
74

    
75
#include        "napa.h"
76
#include        "mon.h"
77

    
78
/** Constraints are used in GetPeer and CountPeer functions to specify matching criteria for numeric-value MeasurementRecords */
79
typedef struct {
80
        /** Measurement identifier */
81
        char *published_name;
82
        /** String equality value. If not NULL, minValue and maxValue are ignored */
83
        char *strValue;
84
        /** Minimum value */
85
        double minValue;
86
        /** Maximum value */
87
        double maxValue;
88
} Constraint;
89

    
90
/** Ranking is used to order the result set of GetPeer queries. */
91
typedef struct {
92
        /** Ranking measurement identifier */
93
        char *published_name;
94
        /** Ranking measurement weight */
95
        double weight;
96
} Ranking;
97

    
98
/** Callback for returning the result of repListMeasurementNames call.
99

100
  @param rep handle of the repository client.
101
  @param id handle of the particular request (assigned by the repListMeasurementNames call)
102
  @param cbarg arbitrary user-provided parameter for the callback
103
  @param result result array, to be freed by the callback.
104
  @param nResults number of entries in result
105
  @see repListMeasurementNames
106
*/
107
typedef void (*cb_repListMeasurementNames)(HANDLE rep, HANDLE id, void *cbarg, char **result, int nResults);
108

    
109
/** Callback for returning the result of repGetPeers call.
110

111
  @param rep handle of the repository client.
112
  @param id handle of the particular request (assigned by the repGetPeers call)
113
  @param cbarg arbitrary user-provided parameter for the callback
114
  @param result result array, to be freed by the callback.
115
  @param nResults number of entries in result
116
  @see repGetPeers 
117
*/
118
typedef void (*cb_repGetPeers)(HANDLE rep, HANDLE id, void *cbarg, char **result, int nResults);
119

    
120
/** Callback for returning the result of repCountPeers call.
121

122
  @param rep handle of the repository client.
123
  @param id handle of the particular request (assigned by the repCountPeers call)
124
  @param cbarg arbitrary user-provided parameter for the callback
125
  @param nPeers result
126
  @see repCountPeers 
127
*/
128
typedef void (*cb_repCountPeers)(HANDLE rep, HANDLE id, void *cbarg, int nPeers);
129

    
130
/** Callback for returning the results of a repGetMeasurements call.
131

132
  @param rep handle of the repository client.
133
  @param id handle of the particular request (assigned by the repGetMeasurements call)
134
  @param cbarg arbitrary user-provided parameter for the callback
135
  @param result result array, to be freed by the callback.
136
  @param nResults number of entries in result
137
  @see repGetMeasurements
138
*/
139
typedef void (*cb_repGetMeasurements)(HANDLE rep, HANDLE id, void *cbarg, MeasurementRecord *result, int nResults);
140

    
141
/** Callback for informing about the completion of a publish call 
142

143
  @param rep handle of the repository client.
144
  @param id handle of the particular request (assigned by the publish call)
145
  @param cbarg arbitrary user-provided parameter for the callback
146
  @param result result code, 0 on success
147
  @see repPublish 
148
*/
149
typedef void (*cb_repPublish)(HANDLE rep, HANDLE id, void *cbarg, int result);
150

    
151
#ifdef __cplusplus
152
extern "C" {
153
#endif
154
/**
155
  Initialize the repository client library.
156

157
  Needs to be called upon bootstapping the application (prior to the first repOpen call)
158

159
  @param config the relevant configuration file section
160
*/
161
void repInit(const char *config);
162

    
163
/**
164
  Open a repository client instance to a given repository server.
165

166
  @param server repository server address in addr:port format, e.g. 192.168.1.1:9832 or myserver.org:1234
167
  @param publish_period batch publish accumulated records this often. If 0, publish each record immediately.
168
  @return HANDLE if successful, NULL on error
169
  @see repClose
170
*/
171
HANDLE repOpen(const char *server, int publish_period);
172

    
173
/**
174
  Close the repository client instance.
175

176
  Closes the client instance and frees allocated resources.
177
  @param repoclient the instance to be closed.
178
  @see repInit
179
*/
180
void repClose(HANDLE repoclient);
181

    
182
/**
183
  Query the list of available(stored) MeasurementNames.
184

185
  Use this function to list what MeasurementNames are stored by this repository.
186

187
  @param rep the repository instance to be queried
188
  @param cb callback for returning the results
189
  @param cbarg arbitrary user-provided parameter for the callback
190
  @param maxResults  return at most maxResults MeasurementNames
191
  @param ch channel filter, can be NULL for any channel
192
  @return the id for identifying the result in the callback or NULL on error
193
*/
194
HANDLE repListMeasurementNames(HANDLE rep, cb_repListMeasurementNames cb, void *cbarg, int maxResults, const char *ch);
195

    
196
/** 
197
  Query the repository for a list of Peers satisfying given criteria.
198

199
  This is the main use case for the repository client: use this function to obtain a list of peers, where
200
  each peer satisfies the following:
201
        - There are measurement records available for it of the MeasurementName s specified in cons
202
        - The values of these measurements are within the range specified by the constraints
203
  The resulting list is ordered by a linear function composed of the Ranking list (each measurement value
204
  is multiplied by the weight assigned to the particular MeasurementName and these numbers are summed for
205
  each peer.
206

207
  @param rep the repository instance to be queried
208
  @param cb callback for returning the results
209
  @param cbarg arbitrary user-provided parameter for the callback
210
  @param maxPeers return at most n PeerIDs
211
  @param cons array of Constraints
212
  @param clen length of cons array
213
  @param ranks  array of Rankings
214
  @param rlen length of ranks array
215
  @param ch channel filter, can be NULL for any channel
216
  @return the id for identifying the result in the callback or NULL on error
217
  @see repCountPeers
218
*/
219
HANDLE repGetPeers(HANDLE rep,cb_repGetPeers cb, void *cbarg, int maxPeers, Constraint *cons, int clen, Ranking *ranks, int rlen, const char *ch);
220

    
221
/** 
222
  Count the number of Peers satisfying given criteria.
223

224
  This function is similar to repGetPeers, just instead of returning the actual list of Peers, only counts them.
225

226
  @param rep the repository instance to be queried
227
  @param cb callback for returning the result
228
  @param cbarg arbitrary user-provided parameter for the callback
229
  @param cons array of Constraints
230
  @param clen length of cons array
231
  @param ch channel filter, can be NULL for any channel
232
  @return the id for identifying the result in the callback or NULL on error
233
*/
234
HANDLE repCountPeers(HANDLE rep, cb_repCountPeers cb, void *cbarg, Constraint *cons, int clen, const char *ch);
235

    
236
/** 
237
  Publish a measurementrecord to the given repository.
238

239
  The monitoring layer uses this function to publish measurement records to the Repository.
240
  @param rep the repository instance to be queried
241
  @param cb callback for returning the result (optional, NULL if not needed)
242
  @param cbarg arbitrary user-provided parameter for the callback
243
  @param r the record containing measurement values.
244
  @return the id for identifying the result in the callback or NULL on error
245
*/
246
HANDLE repPublish(HANDLE rep, cb_repPublish cb, void *cbarg, MeasurementRecord *r);
247

    
248
/**
249
  Get MeasurementRecord entries from the Repository.
250

251
  @param rep the repository instance to be queried
252
  @param cb callback for returning the result (optional, NULL if not needed)
253
  @param cbarg arbitrary user-provided parameter for the callback
254
  @param maxResults maximum number of MeasurementRecords to return (unlimited if <= 0)
255
  @param originator originator filter
256
  @param targetA targetA filter
257
  @param id MeasurementName filter
258
  @param channel channel filter, can be NULL for any channel
259
  @return the id for identifying the result in the callback or NULL on error
260
*/
261
HANDLE repGetMeasurements(HANDLE rep, cb_repGetMeasurements cb, void *cbarg, int maxResults, const char *originator, const char *targetA, const char *targetB, const char *measurementName, const char *channel);
262

    
263
/** 
264
  Helper function for debugging.
265

266
  @param r the record to be printed
267
  @result Textual format in a statically allocated buffer.
268
*/
269
const char *measurementrecord2str(const MeasurementRecord r);
270

    
271
#ifdef __cplusplus
272
}
273
#endif
274

    
275
#endif
276

    
277