doc/plugin-api.txt

   1 Plugin programming interface
   2 ****************************
   3
   4
   5 Plugin basics
   6 =============
   7
   8 The Connection Manager supports plugins for various actions. The basic plugin
   9 contains a plugin description via CONNMAN_PLUGIN_DEFINE and also init/exit
  10 callbacks defined through that description.
  11
  12 #include <connman/plugin.h>
  13
  14 static int example_init(void)
  15 {
  16         return 0;
  17 }
  18
  19 static void example_exit(void)
  20 {
  21 }
  22
  23 CONNMAN_PLUGIN_DEFINE(example, "Example plugin", CONNMAN_VERSION,
  24                                                 example_init, example_exit)
  25
  26
  27 Infrastructure for plugins
  28 ==========================
  29
  30 The Connection Manager provides a very good infrastructure for plugins to
  31 interface with the core functionalities of ConnMan. The infrastructure is
  32 well divided into the concepts of Technology, Device and Network, among
  33 others.
  34
  35 Technology infrastructure
  36 =========================
  37
  38 A Technology in ConnMan is an abstract representation of the different
  39 kinds of technologies it supports such as WiFi, Ethernet, Bluetooth and
  40 Celullar. The technologies supported are added to ConnMan through plugins, such
  41 as plugins/bluetooth.c for the Bluetooth Technology or plugins/wifi.c for the
  42 WiFi Technology. Each new technology plugin needs to register itself as a
  43 Technology with ConnMan. As an example we will take a look at the Bluetooth
  44 plugin registration. As a first step 'struct connman_technology_driver' needs
  45 to be defined:
  46
  47         static struct connman_technology_driver tech_driver = {
  48                 .name           = "bluetooth",
  49                 .type           = CONNMAN_SERVICE_TYPE_BLUETOOTH,
  50                 .probe          = bluetooth_tech_probe,
  51                 .remove         = bluetooth_tech_remove,
  52                 .set_tethering  = bluetooth_tech_set_tethering,
  53         };
  54
  55 More functions can be defined depending on the purpose of the plugin. All
  56 vtable's supported functions can be seen in include/technology.h. If a
  57 completely new technology type is added 'enum connman_service_type' in
  58 include/service.h needs to be extended accordingly. This inclusion comes in
  59 the form of Service because ultimately a new technology introduces a new
  60 Service. New technologies can also reuse existing Services types.
  61
  62 To make the Connection Manager aware of the new Technology plugin we need to
  63 register its driver by calling 'connman_technology_driver_register()' in the
  64 plugin initialization function, bluetooth_init() in this example:
  65
  66         connman_technology_driver_register(&tech_driver);
  67
  68 In this document the error check is suppressed for the sake of simplicity.
  69 All plugins should check return values in driver registration functions.
  70
  71 After this call ConnMan becomes aware of the new Technology plugin and will
  72 call the probe() method when the new technology is recognized by the system. For
  73 the Bluetooth plugin for example probe() would be called when a Bluetooth
  74 adapter is recognized. A Technology is only probed if there exists at least
  75 one device of such technology plugged into the system.
  76
  77 Complementary, the technology must be unregistered by the plugin exit function
  78 through 'connman_technology_driver_unregister()'.
  79
  80 Device infrastructure
  81 =====================
  82
  83 A Device represents a real device of a given Technology, there could be many
  84 devices per technology. To enable ConnMan to handle Devices a device driver
  85 needs to be registered. Using the Bluetooth plugin as example it would have to
  86 define a 'struct connman_device_driver':
  87
  88         static struct connman_device_driver device_driver = {
  89                 .name           = "bluetooth",
  90                 .type           = CONNMAN_DEVICE_TYPE_BLUETOOTH,
  91                 .probe          = bluetooth_device_probe,
  92                 .remove         = bluetooth_device_remove,
  93                 .enable         = bluetooth_device_enable,
  94                 .disable        = bluetooth_device_disable,
  95         };
  96
  97 And to register the driver:
  98
  99         connman_device_driver_register(&device_driver);
 100
 101 'connman_device_driver_register()' is called during the plugin initialization
 102 process, not necessarily at the plugin init function.
 103
 104 In this document the error check is suppressed for the sake of simplicity.
 105 All plugins should check return values in driver registration functions.
 106
 107 Additionally code to handle the detection of new devices needs to be written
 108 for each plugin, the bluetooth plugin does so by registering watchers for the
 109 BlueZ D-Bus interface. Once a new Bluetooth Device appears the plugin needs to
 110 notify ConnMan core by calling connman_device_create(), for the bluetooth
 111 plugin the call would be:
 112
 113         struct connman_device *device;
 114
 115         device = connman_device_create("bluetooth",
 116                                         CONNMAN_DEVICE_TYPE_BLUETOOTH)
 117
 118 ConnMan core will then register the bluetooth device as a Device entity and
 119 call the probe() function from the bluetooth plugin device driver. If a
 120 Technology entity for the Device type doesn't exist it will be created and
 121 Technology probe() function in the bluetooth technology driver is called.
 122
 123 For the Bluetooth plugin a Device represents the local Bluetooth Adapter
 124 plugged in the system.
 125
 126 To learn how to use the connman_device_*() functions such as
 127 connman_device_set_powered() and connman_device_ref() see src/device.c for
 128 its API documentation.
 129
 130 Network infrastructure
 131 ======================
 132
 133 The Connection Manager provides a means to plugins to handle the specifics of
 134 establishing/handling a connection for each type of Technology. For the
 135 bluetooth plugin a connman_network_driver needs to be registered:
 136
 137         static struct connman_network_driver network_driver = {
 138                 .name           = "bluetooth",
 139                 .type           = CONNMAN_NETWORK_TYPE_BLUETOOTH_PAN,
 140                 .probe          = bluetooth_pan_probe,
 141                 .remove         = bluetooth_pan_remove,
 142                 .connect        = bluetooth_pan_connect,
 143                 .disconnect     = bluetooth_pan_disconnect,
 144         };
 145
 146 And then call the register function:
 147
 148         connman_network_driver_register(&network_driver);
 149
 150 In this document the error check is suppressed for the sake of simplicity.
 151 All plugins should check return values in driver registration functions.
 152
 153 The next step would be the probe of a Network entity, for the bluetooth
 154 plugin this would happen when a new device that supports the PAN NAP role is
 155 paired with the system. ConnMan then calls connman_device_add_network() to
 156 associate the new Network with the existing Device entity (the local Bluetooth
 157 Adapter).
 158
 159 Then in the vtable's connect method all the needed pieces to perform a
 160 connection shall be performed.
 161
 162 To learn how to use the connman_network_*() functions such as
 163 connman_network_set_index() and connman_network_set_connected() see
 164 src/network.c for its API documentation.