1 """
2 Implements the standard Ivy API.
3
4 You can refer to the example code ``pyhello.py`` for an example of use.
5
6 All methods in this module are frontends to a `ivy.IvyServer` instance, stored
7 in the module's attributes `_IvyServer`.
8
9 :group Connecting to/disconnecting from the Ivy bus:
10 IvyInit, IvyStart,IvyMainLoop, IvyStop
11 :group Bindings: IvyBindMsg, IvyUnBindMsg, IvyBindDirectMsg
12 :group Inspecting the Ivy bus:
13 IvyGetApplicationList, IvyGetApplication, IvyGetApplicationName,
14 IvyGetApplicationHost
15 :group Interacting with other Ivy clients:
16 IvySendMsg, IvySendDieMsg, IvySendDirectMsg
17 :group Timers: IvyTimerRepeatAfter, IvyTimerModify, IvyTimerRemove
18
19 Copyright (c) 2005-2011 Sebastien Bigaret <sbigaret@users.sourceforge.net>
20 """
21
22 _IvyServer=None
23
24 from ivy import IvyApplicationConnected, IvyApplicationDisconnected
25 from ivy import IvyRegexpAdded, IvyRegexpRemoved
26 from ivy import void_function
27
40
41
43 """
44 Starts the Ivy server and fully activate the client. Please refer to the
45 discussion in `IvyMainLoop()` 's documentation.
46 """
47 assert _IvyServer != None
48 _IvyServer.start(ivybus)
49
50
52 """
53 Simulates the original main loop: simply waits for the server termination.
54
55 Note that while the original API requires this to be called, this module
56 does NOT rely in any way on this method. In particular, a client is
57 fully functional and begins to receive messages as soon as the `IvyStart()`
58 method is called.
59 """
60 assert _IvyServer != None
61 _IvyServer.server_termination.wait()
62
63
67
68
70 """
71 Registers a method that should be called each time a message matching
72 regexps is sent on the Ivy bus.
73
74 :return: an id identifying the binding, that can be used to unregister it
75 (see `IvyUnBindMsg()`)
76 """
77 assert _IvyServer != None
78 return _IvyServer.bind_msg(on_msg_fct, regexp)
79
81 """
82 Registers a method that should be called each time someone sends us
83 a direct message
84
85 """
86 assert _IvyServer != None
87 return _IvyServer.bind_direct_msg(on_msg_fct)
88
90 """
91 Unregisters a binding
92
93 :param id: the binding's id, as previously returned by `IvyBindMsg()`.
94 :return: the regexp corresponding to the unsubscribed binding
95 :except KeyError: if no such subscription can be found
96 """
97 assert _IvyServer != None
98 return _IvyServer.unbind_msg(id)
99
105
112
114 """
115 Sends a "die" message to `client`, instructing him to terminate.
116
117 :param client: an `ivy.IvyClient` object, as returned by
118 `IvyGetApplication()`
119 """
120 assert _IvyServer != None
121 client.send_die_message()
122
123
125 """
126 Sends a message directly to an other Ivy client, with the supplied
127 numerical id and message.
128
129 :Parameters:
130 - `client`: an `ivy.IvyClient` object, as returned by
131 `IvyGetApplication()`
132 - `num_id`: an additional integer to use. It may, or may not, be
133 meaningful, this only depends on the usage your application makes of
134 it, the Ivy protocol itself does not care and simply transmits it
135 along with the message.
136 - `msg`: the message to send
137 """
138 assert _IvyServer != None
139 client.send_direct_message(num_id, msg)
140
141
143 """
144 Sends an "error" message to `client`
145
146 :Parameters:
147 - `client`: an `ivy.IvyClient` object, as returned by
148 `IvyGetApplication()`
149 - `num_id`: an additional integer to use. It may, or may not, be
150 meaningful, this only depends on the usage your application makes of
151 it, the Ivy protocol itself does not care and simply transmits it
152 along with the message.
153 - `error_msg`: the message to send
154 """
155 assert _IvyServer != None
156 client.send_error(num_id, error_msg)
157
158
165
167 """
168 Returns all subscriptions for that client
169
170 :param client: an `ivy.IvyClient` object, as returned by
171 `IvyGetApplication()`
172 :return: list of tuples (idx, regexp)
173 """
174 return client.get_regexps()
175
177 """
178 Returns the Ivy client registered on the bus under the given name.
179
180 .. warning:: if multiple applications are registered w/ the same name only
181 one is returned
182
183 :returns: an `ivy.IvyClient` object
184 """
185 assert _IvyServer != None
186 clients = _IvyServer.get_client_with_name(name)
187 return clients and clients[0] or None
188
190 """
191 Equivalent to ``client.agent_name``
192
193 :param client: an `ivy.IvyClient` object, as returned by
194 `IvyGetApplication()`
195 """
196 return client.agent_name
197
199 """
200 Equivalent to ``client.fqdn``. IP address is stored under ``client.ip``,
201 and port number under ``client.port``
202
203 :param client: an `ivy.IvyClient` object, as returned by
204 `IvyGetApplication()`
205 """
206 return client.fqdn
207
208
209 _timers={}
211 """
212 Creates and activates a new timer
213
214 :Parameters:
215 - `count`: nb of time to repeat the loop, ``0`` (zero) for an endless loop
216 - `delay`: the delay between ticks, in milliseconds
217 - `callback`: the function to call on every tick. That function is
218 called without any parameters.
219
220 :return: the timer's id
221 """
222 assert _IvyServer != None
223 from ivy import IvyTimer
224
225 cb = lambda timer, callback=callback: callback()
226 timer = IvyTimer(_IvyServer, count, delay, cb)
227 _timers[timer.id]=timer
228 timer.start()
229 return timer.id
230
231
233 """
234 Modifies a timer's delay. Note that the modification will happen after
235 the next tick.
236
237 :Parameters:
238 - `timer_id`: id of the timer to modify, as returned by
239 `IvyTimerRepeatAfter()`
240 - `delay`: the delay, in milliseconds, between ticks
241 """
242 _timers[timer_id].delay = delay
243
244
246 """
247 Stops and removes a given timer.
248
249 :param timer_id: id of the timer, as returned by `IvyTimerRepeatAfter`
250 """
251 from ivy import IvyTimer
252 timer = _timers[timer_id]
253 timer.abort = True
254 del _timers[timer_id]
255
256
257
258
259
260
261 """
262 # copy/paste for quick tests w/ ivyprobe
263 from ivy.std_api import *
264 IvyInit('Test', 'test welcome', 0)
265 IvyStart()
266 def onmsgproc(*larg):
267 print larg
268
269 IvyBindMsg(onmsgproc, '(.*)')
270 IvyGetApplicationList()
271 app=IvyGetApplication('IVYPROBE')
272 IvyGetApplicationName(app)
273 IvyGetApplicationHost(app)
274 IvySendDirectMsg(app, 765, 'glop')
275 IvySendDieMsg(app)
276 """
277