A "service" is a struct of C function pointers.

It is a tool to expose a pre-exitsing set of server functions to plugins. You need the actual server functions as a starting point.

The server has all service structs defined and initialized so that the the function pointers point to the actual service implementation functions.

The server also keeps a global list of the plugin service reference structures called list_of_services.

See st_service_ref for details of what a service reference is.

The server copies of all plugin structures are filled in at compile time with the function pointers of the actual server functions that implement the service functions. References to them are stored into the relevant element of list_of_services.

Each plugin must export pointer symbols for every plugin service that the server knows about.

The plugin service pointers are initialized with the version of the plugin service that the plugin expects.

When a dynamic plugin shared object is loaded by plugin_dl_add it will iterate over list_of_services, find the plugin symbol by name, check the service version stored in that symbol against the one stored into st_service_ref and then will replace the version stored in plugin's struct pointer with the actual pointer of the server's copy of the same structure.

When that is filled in the plugin can use the newly set server structure through its local pointer to call into the service method pointers that point to the server implementation functions.

Once set to the server's structure, the plugin's service pointer value is never reset back to service version.

The plugin service header also defines a set of convenience macros that replace top level plugin service calls with the corresponding function pointer call, i.e. for service foo:

struct foo_service_st {
   int (*foo_mtd_1)(int a);
}
 
struct foo_service_st *foo_service;

a convenience macro is defined for foo_mtd_1 as follows:

#define foo_mtd_1(a) foo_service->foo_mtd_1(a)

This trick allows plugin service functions to look as top level function calls inside the plugin code.

See also: plugin_add, plugin_del, plugin_dl_add, plugin_dl_del, list_of_services, st_service_ref