client doc

Introduction to the splonebox Client

A client is essentially a plug-in for the splonebox. It is able to register some functions at the core and execute functions that have bin registered by other plug-ins. In the future, clients are supposed to implement functions to check and analyze a network and its devices. This library helps developing such plug-ins without the effort of implementing and understanding the splonebox specific mechanisms.

Creating a Client

A client (or plug-in) is created using the Plugin class.

from Splonecli.Api.plugin import Plugin

my_plugin = Plugin("<apikey>", "<name>", "<desc>", "<author>", "license")

• api key: Api key (This is currently an identifier for the plug-in but should be irrelevant in future releases)
• name: Name of the plug-in
• desc: Description of the plug-in
• author: Author of the plug-in
• license: License of the plug-in

Debugging

You may initialize your plug-in with the optional debugging=True parameter. This will output some information using pythons built-in logging module.

Plugin("<apikey>", "<name>", "<desc>", "<author>", "license", debugging=True)

Connecting and Registering at the Core

After you created your Plugin object, connecting and registering the plug-in, is quite simple.

import Splonecli.Api.plugin.RemoteError


my_plugin.connect("hostname", <port>) # connects to the splonebox
try:
  my_plugin.register() # registers at the splonebox
except RemoteError as e:
  print(e)

If the register call fails, a RemoteError exception is raised.

Note: The register call is blocking by default!

Adding Remote Functions

If you define a remote function you need to specify the argument types using ctypes.* and annotations. Don't worry, it's quite simple!

import ctypes

from Splonecli.Api.plugin import RemoteFunction


@RemoteFunction
def add(a: ctypes.int64, b: ctypes.int64):
  """Adds two numbers"""
  return a + b

That's it! Supportet types are: ctypes.c_bool, ctypes.c_byte, ctypes.c_uint64, ctypes.c_int64, ctypes.c_double, ctypes.c_char_p, ctypes.c_long (c_char_p represents a string).

** Make sure to import the files with @RemoteFunction decorators somewhere! The python interpreter can't guess where to look for these :)**

Whatever you return will be sent back as a result to the caller. If you raise a RemoteException the error code and message will also be sent to the caller. Other exceptions will be ignored.

Calling a Remote Function

To call a remote function you use the plug-ins run method. Let's call the "add function" we registered earlier:

# ... make sure plug-in is registered and connected!
# Note here as well, the apikey should be obsolete soon
result = plug.run("<apikey>", "add", [5,11])

res = result.get_result() # blocking by default

if(res[0] == -1):
  # handle error
  print(res[1][0]) # error number
  print(res[1][1]) # error message
else:
  assert(res[1][0] == 16)

The Result class has some methods you should check out.

Note: Run calls are asynchronous by default!