diff options
Diffstat (limited to 'doc/plugin-api.txt')
-rw-r--r-- | doc/plugin-api.txt | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/doc/plugin-api.txt b/doc/plugin-api.txt index b39c043a..616938b8 100644 --- a/doc/plugin-api.txt +++ b/doc/plugin-api.txt @@ -22,3 +22,143 @@ static void example_exit(void) CONNMAN_PLUGIN_DEFINE(example, "Example plugin", CONNMAN_VERSION, example_init, example_exit) + + +Infrastructure for plugins +========================== + +The Connection Manager provides a very good infrastructure for plugins to +interface with the core functionalities of ConnMan. The infrastructure is +well divided into the concepts of Technology, Device and Network, among +others. + +Technology infrastructure +========================= + +A Technology in ConnMan is an abstract representation of the different +kinds of technologies it supports such as WiFi, Ethernet, Bluetooth and +Celullar. The technologies support are added to ConnMan through plugins, such +as plugins/bluetooth.c for the Bluetooth Technology or plugins/wifi.c for the +WiFi Technology. Each new technology plugin needs to register itself as a +Technology with ConnMan. As an example we will take a look at the Bluetooth +plugin registration. As a first step 'struct connman_technology_driver' needs +to be defined: + + static struct connman_technology_driver tech_driver = { + .name = "bluetooth", + .type = CONNMAN_SERVICE_TYPE_BLUETOOTH, + .probe = bluetooth_tech_probe, + .remove = bluetooth_tech_remove, + .set_tethering = bluetooth_tech_set_tethering, + }; + +More functions can be defined depending on the purpose of the plugin. All +vtable's supported functions can be seen in include/technology.h. If a +completely new technology type is added 'enum connman_service_type' in +include/service.h needs to be extended accordingly. This inclusion comes in +the form of Service because ultimately a new technology introduces a new +Service. New technologies can also reuse existing Services types. + +To make the Connection Manager aware of the new Technology plugin we need to +register its driver by calling 'connman_technology_driver_register()' in the +plugin initialization function, bluetooth_init() in this example: + + connman_technology_driver_register(&tech_driver); + +In this document the error check is supressed for the sake of simplicity. +All plugins should check return values in driver registration functions. + +After this call ConnMan becomes aware of the new Technology plugin and will +call the probe() method when the new technology is recognized by the system. For +the Bluetooth plugin for example probe() would be called when a Bluetooth +adapter is recognized. A Technology is only probed if there exists at least +one device of such technology plugged into the system. + +Complementary, the technology must be unregistered on the plugin exit function +through 'connman_technology_driver_unregister()'. + +Device infrastructure +===================== + +A Device represents a real device of a given Technology, there could be many +devices per technology. To enable ConnMan to handle Devices a device driver +needs to be registered. Using the Bluetooth plugin as example it would have to +define a 'struct connman_device_driver': + + static struct connman_device_driver device_driver = { + .name = "bluetooth", + .type = CONNMAN_DEVICE_TYPE_BLUETOOTH, + .probe = bluetooth_device_probe, + .remove = bluetooth_device_remove, + .enable = bluetooth_device_enable, + .disable = bluetooth_device_disable, + }; + +And to register the driver: + + connman_device_driver_register(&device_driver); + +'connman_device_driver_register()' is called during the plugin initialization +process, not necessarily at the plugin init function. + +In this document the error check is supressed for the sake of simplicity. +All plugins should check return values in driver registration functions. + +Additionally code to handle the detection of new devices needs to be written +for each plugin, the bluetooth plugin does so by registering watchers for the +BlueZ D-Bus interface. Once a new Bluetooth Device appears the plugin needs to +notify ConnMan core by calling connman_device_create(), for the bluetooth +plugin the call would be: + + struct connman_device *device; + + device = connman_device_create("bluetooth", + CONNMAN_DEVICE_TYPE_BLUETOOTH) + +ConnMan core will then register the bluetooth device as a Device entity and +call the probe() function from the bluetooth plugin device driver. If a +Technology entity for the Device type doesn't exist it will be created and +Technology probe() function in the bluetooth technology driver is called. + +For the Bluetooth plugin a Device represents the local Bluetooth Adapter +plugged in the system. + +To learn how to use the connman_device_*() functions such as +connman_device_set_powered() and connman_device_ref() see src/device.c for +its API documentation. + +Network infrastructure +====================== + +The Connection Manager provides a mean to plugins handle the specifics of +establishing/handling a connection for each type of Technology. For the +bluetooth plugin a connman_network_driver needs to be registered: + + static struct connman_network_driver network_driver = { + .name = "bluetooth", + .type = CONNMAN_NETWORK_TYPE_BLUETOOTH_PAN, + .probe = bluetooth_pan_probe, + .remove = bluetooth_pan_remove, + .connect = bluetooth_pan_connect, + .disconnect = bluetooth_pan_disconnect, + }; + +And then call the register function: + + connman_network_driver_register(&network_driver); + +In this document the error check is supressed for the sake of simplicity. +All plugins should check return values in driver registration functions. + +The next step would be the probe of a Network entity, for the bluetooth +plugin this would happen when a new device that supports the PAN NAP role is +paired with the system. ConnMan then call connman_device_add_network() to +associate the new Network with the existing Device entity (the local Bluetooth +Adapter). + +Then in the vtable's connect method all the needed pieces to perform a +connection shall be perfomed. + +To learn how to use the connman_network_*() functions such as +connman_network_set_index() and connman_network_set_connected() see +src/network.c for its API documentation. |