1 throw new Error("Description for built in functions. Must not be included!");
  2 /**
  3  * @fileOverview
  4  *    Documentation of dim namespace.
  5  */
  6 
  7 /**
  8  * @namespace
  9  *
 10  * Namespace for extension functions dealing with the DIM network.
 11  *
 12  * @author <a href="mailto:thomas.bretz@epfl.ch">Thomas Bretz</a>
 13  */
 14 var dim = { };
 15 
 16 /**
 17  *
 18  * Post a message into the dim log stream.
 19  *
 20  * It will be logged by the datalogger, displayed on the console
 21  * and in the smartfact web-gui.
 22  *
 23  * @param argument
 24  *     Any kind of argument can be given. If it is not a String, it
 25  *     is converted using the toString() member function.
 26  *
 27  * @param [. . .]
 28  *     Any number of additional arguments. Each argument will appear in
 29  *     a new line.
 30  *
 31  * @example
 32  *     dim.log("Five="+5, "--- new line ---");
 33  *
 34  */
 35 dim.log = function() { /* [native code] */ }
 36 
 37 /**
 38  *
 39  * Posts a message to the dim network with alarm severity.
 40  *
 41  * Similar to dim.log, but the message is posted to the network
 42  * with alarm severity. This means that it is displayed in red
 43  * and the smartfact web-gui will play an alarm sound.
 44  * The alarm state will stay valid (displayed in the web-gui) until it
 45  * is reset.
 46  *
 47  * @param argument
 48  *     Any kind of argument can be given. If it is not a String, it
 49  *     is converted using the toString() member function.
 50  *
 51  * @param [. . .]
 52  *     Any number of additional arguments. Each argument will appear as
 53  *     individual alarm.
 54  *
 55  * @example
 56  *     dim.alarm("Alarm for 30 seconds!");
 57  *     v8.sleep(30000);
 58  *     dim.alarm();
 59  */
 60 dim.alarm = function() { /* [native code] */ }
 61 
 62 /**
 63  *
 64  * Send a dim command to a dim client.
 65  *
 66  * @param {String} commandId
 67  *     The command id is a string and usually compiles like
 68  *     'SERVER/COMMAND'
 69  *
 70  * @param argument
 71  *     Any kind of argument can be given. Arguments are internally
 72  *     converted into strings using toString() and processed as
 73  *     if they were typed on th console.
 74  *
 75  * @param [. . .]
 76  *     Any number of additional arguments.
 77  *
 78  * @example
 79  *     dim.send('DRIVE_CONTROL/TRACK_SOURCE 0.5 180 "Mrk 421"');
 80  *     dim.send('DRIVE_CONTROL/TRACK_SOURCE', 0.5, 180, 'Mrk 421');
 81  *
 82  * @returns
 83  *     A boolean value is returned whether the command was succesfully
 84  *     posted into the network or not. Note that true does by no means
 85  *     mean that the command was sucessfully received or even processed.
 86  */
 87 dim.send = function() { /* [native code] */ }
 88 
 89 /**
 90  * Returns the state of the given server.
 91  *
 92  * @param {String} name
 93  *     The name of the server of which you want to get the state.
 94  *
 95  * @throws
 96  *    If number or type of arguments is wrong
 97  *
 98  * @returns {Object}
 99  *     An object with the properties 'index' {Integer} and 'name' {String}
100  *     is returned if a connection to the server is established and
101  *     state information have been received, 'undefined' otherwise. If
102  *     the time of the last state change is available, it is stored
103  *     in the 'property'. If a server disconnected, a valid object will
104  *     be returned, but without any properties.
105  */
106 dim.state = function() { /* [native code] */ }
107 
108 /**
109  * Wait for the given state of a server.
110  *
111  * Note that the function is internally asynchornously checking the
112  * state, that means that theoretically, a state could be missed if
113  * it changes too fast. If this can happen callbacks have to be used.
114  *
115  * @param {String} name
116  *     The name of the server of which you want to wait for a state.
117  *     The name must not contain quotation marks. To wait for
118  *     "not the given state", prefix the server name with an
119  *     exclamation mark, e.g. "!DIM_CONTROL"
120  *
121  * @param {String,Integer} state
122  *     The state you want to wait for. It can either be given as an Integer
123  *     or as the corresponding short name. If given as String it must
124  *     not contain quotation marks.
125  *
126  * @param {Integer} [timeout]
127  *     An optional timeout. If no timeout is given or a timeout of undefined,
128  *     waiting will not stop until the condition is fulfilled. A timeout
129  *     of 0 is allowed and will essentially just check if the server is
130  *     in this state or not. If a negative value is given, exceptions are
131  *     suppressed and false is returned in case of timeout. As timeout
132  *     the absolute value is used.
133  *
134  * @throws
135  *    <li> If number or type of arguments is wrong
136  *    <li> If no connection to the server is established or no state
137  *         has been received yet. This is identical to dim.state()
138  *         returning 'undefined' (only in case a positive timeout 
139  *         is given)
140  *
141  * @returns {Boolean}
142  *     true if the state was achived within the timeout, false otherwise.
143  */
144 dim.wait = function() { /* [native code] */ }
145 
146 /**
147  *
148  * Returns a list of all known state of a given server.
149  *
150  * The returned object has all states with their index as property.
151  * Each state is returned as a String object with the property description.
152  *
153  * @param {String} [server='DIM_CONTROL']
154  *     Name of the server for which states should be listed.
155  *     The states of the DIM_CONTROl server are the default.
156  *
157  * @throws
158  *    If number or type of arguments is wrong
159  *
160  * @type Object[StringObject]
161  *
162  * @example
163  *     var states = dim.getStates("SERVER");
164  *     console.out(JSON.stringify(states));
165  *     for (var index in states)
166  *         console.out(index+"="+states[index]+": "+states[index].description);
167  */
168 dim.getStates = function() { /* [native code] */ }
169 
170 /**
171  *
172  * Returns a description for one service
173  *
174  * The returned array has objects with the properties: name, description and unit. The last
175  * two are optional. The array itself has the properties name, server, service, isCommand
176  * and optionally format.
177  *
178  * @param {String} service
179  *     String specifying the name of the service to be returned.
180  *
181  * @throws
182  *    If number or type of arguments is wrong
183  *
184  * @type {Description}
185  *
186  * @example
187  *     var s = dim.getDescription("TNG_WEATHER/DATA");
188  *     console.out("Name="+s.name);
189  *     console.out("Server="+s.server);
190  *     console.out("Service="+s.service);
191  *     console.out("Format="+s.format);
192  *     console.out("Description="+s.name);
193  *     console.out("IsCommand="+s.isCommand);
194  *     console.out(JSON.stringify(s));
195  */
196 dim.getDescription = function() { /* [native code] */ }
197 
198 /**
199  *
200  * Returns a list of all known services
201  *
202  * The returned array has objects with the properties: name, server, service, command
203  * and (optional) format.
204  *
205  * @param {String} [service='*']
206  *     String a service has to start with to be returned. The default is to return
207  *     all available services. An empty string or '*' are wildcards for all
208  *     services.
209  *
210  * @param {Boolean} [isCommand=undefined]
211  *     If no second argument is specified, data services and commands are returned.
212  *     With true, only commands, with false, only data-services are returned.
213  *
214  * @throws
215  *    If number or type of arguments is wrong
216  *
217  * @type Array[Object]
218  *
219  * @example
220  *     // Return all services of the FAD_CONTROL starting with E
221  *     var services = dim.getServices("FAD_CONTROL/E");
222  *     console.out(JSON.stringify(services));
223  */
224 dim.getServices = function() { /* [native code] */ }
225 
226 /**
227  *
228  * Callback in case of state changes.
229  *
230  * To install a callback in case the state of a server changes. set
231  * the corresponding property of this array to a function. The argument
232  * provided to the function is identical with the object returned
233  * by dim.state(). In addition the name of the server is added
234  * as the 'name' property and the comment sent with the state change
235  * as 'comment' property. For the code executed, the same rules apply
236  * than for a thread created with Thread.<P>
237  *
238  * If a state change is defined for a server for which no callback
239  * has been set, the special entry '*' is checked.
240  *
241  *
242  * @type Array[Function]
243  *
244  * @example
245  *     dim.onchange['*'] = function(state) { console.out("State change from "+state.name+" received"); }
246  *     dim.onchange['DIM_CONTROL'] = function(state) { console.out(JSON.stringify(state); }
247  *     ...
248  *     delete dim.onchange['DIM_CONTROL']; // to remove the callback
249  *
250  */
251 dim.onchange = [];
252 
253 
254 /**
255  * DIM version number
256  *
257  * @constant
258  * @type Integer
259  */
260 dim.version = 0;
261