ivy.std_api module

Implements the standard Ivy API.

You can refer to the example code pyhello.py for an example of use.

All methods in this module are frontends to a ivy.IvyServer instance, stored in the module’s attributes _IvyServer.

Connecting to/disconnecting from the Ivy bus:

Bindings:

Inspecting the Ivy bus:

Interacting with other Ivy clients:

Timers:

Copyright (c) 2005-2021 Sebastien Bigaret <sebastien.bigaret@telecom-bretagne.eu>

ivy.std_api.IvyBindDirectMsg(on_msg_fct)

Registers a method that should be called each time someone sends us a direct message

ivy.std_api.IvyBindMsg(on_msg_fct, regexp)

Registers a method that should be called each time a message matching regexps is sent on the Ivy bus.

Returns:an id identifying the binding, that can be used to unregister it (see IvyUnbindMsg())
ivy.std_api.IvyBindPong(on_pong_fct)

Registers a method that should be called when we receive a PONG message. When receiving a PONG message in replying of a PING message we sent (see IvySendPing()), this method is called with three arguments:

  • the first one is the IvyClient object sorresponding to the agent sending the message;
  • the second one is the time elapsed between the sending of the ping and the receiving of the pong.
ivy.std_api.IvyBindRegexpChange(regexp_change_callback)
ivy.std_api.IvyGetApplication(name)

Returns the Ivy client registered on the bus under the given name.

Warning

if multiple applications are registered w/ the same name only one is returned

Returns:an ivy.ivy.IvyClient object
ivy.std_api.IvyGetApplicationHost(client)

Equivalent to client.fqdn. IP address is stored under client.ip, and port number under client.port

Parameters:client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
ivy.std_api.IvyGetApplicationList()

Returns the names of the applications that are currently connected

ivy.std_api.IvyGetApplicationMessages(client)

Returns all subscriptions for that client

Parameters:client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
Returns:list of tuples (idx, regexp)
ivy.std_api.IvyGetApplicationName(client)

Equivalent to client.agent_name

Parameters:client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
ivy.std_api.IvyInit(agent_name, ready_msg=None, main_loop_type_ignored=0, on_cnx_fct=<function void_function>, on_die_fct=<function void_function>)

Initializes the module. This method should be called exactly once before any other method is called.

ivy.std_api.IvyMainLoop()

Simulates the original main loop: simply waits for the server termination.

Note that while the original API requires this to be called, this module does NOT rely in any way on this method. In particular, a client is fully functional and begins to receive messages as soon as the IvyStart() method is called.

ivy.std_api.IvySendDieMsg(client)

Sends a “die” message to client, instructing him to terminate.

Parameters:client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
ivy.std_api.IvySendDirectMsg(client, num_id, msg)

Sends a message directly to an other Ivy client, with the supplied numerical id and message.

Parameters:
  • client: an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
  • num_id: an additional integer to use. It may, or may not, be meaningful, this only depends on the usage your application makes of it, the Ivy protocol itself does not care and simply transmits it along with the message.
  • msg: the message to send
ivy.std_api.IvySendError(client, num_id, error_msg)

Sends an “error” message to client

Parameters:
  • client: an ivy.ivy.IvyClient object, as returned by IvyGetApplication()
  • num_id: an additional integer to use. It may, or may not, be meaningful, this only depends on the usage your application makes of it, the Ivy protocol itself does not care and simply transmits it along with the message.
  • error_msg: the message to send
ivy.std_api.IvySendMsg(msg)

Sends a message on the bus

ivy.std_api.IvySendPing(client)

Sends a PING message to the client. See also: IvyBindPong()

ivy.std_api.IvySetPongCallback(on_pong_fct)

alias for IvyBindPong() (IvySetPongCallback is the name used in ivy-c)

ivy.std_api.IvyStart(ivybus=None)

Starts the Ivy server and fully activate the client. Please refer to the discussion in IvyMainLoop() ‘s documentation.

ivy.std_api.IvyStop()

Notifies the other participants on the bus that this agent is signing off, and properly terminates the underlying listening thread. When this method returns, the agent is disconnected from the bus.

ivy.std_api.IvyTimerModify(timer_id, delay)

Modifies a timer’s delay. Note that the modification will happen after the next tick.

Parameters:
  • timer_id: id of the timer to modify, as returned by IvyTimerRepeatAfter()
  • delay: the delay, in milliseconds, between ticks
ivy.std_api.IvyTimerRemove(timer_id)

Stops and removes a given timer.

Parameters:timer_id – id of the timer, as returned by IvyTimerRepeatAfter()
ivy.std_api.IvyTimerRepeatAfter(count, delay, callback)

Creates and activates a new timer

Parameters:
  • count: nb of time to repeat the loop, 0 (zero) for an endless loop
  • delay: the delay between ticks, in milliseconds
  • callback: the function to call on every tick. That function is called without any parameters.
Returns:

the timer’s id
ivy.std_api.IvyUnBindMsg(binding_id)

Unregisters a binding. This is the same as IvyUnbindMsg(), except that it is named like in the Java API (unBindMsg()). If in doubt, use IvyUnbindMsg() preferably.

Parameters:binding_id – the binding’s id, as previously returned by IvyBindMsg().
Returns:the regexp corresponding to the unsubscribed binding
Raises:KeyError – if no such subscription can be found
ivy.std_api.IvyUnbindMsg(binding_id)

Unregisters a binding.

Parameters:binding_id – the binding’s id, as previously returned by py:func:IvyBindMsg.
Returns:the regexp corresponding to the unsubscribed binding
Raises:KeyError – if no such subscription can be found

New in version 3.2.