Overview

Service Client Manager (scm in short) is a meta service client that manages all other local service clients. It will be started automatically when the server starts. And it scans service_clients sub-directory in XMMS2 config dir for service client description files. Each file inside that directory is considered a description file for a single service client, with the name of the file as the name of the service client. This file describes the path of the executable file, arguments passing to that file, if it needs to be launched automatically, service descriptions, versions and method descriptions of a service client. So that clients can query for installed service clients' information even if they are not registered to the server at the moment. Furthermore, clients can control a service client by issuing launch and shutdown requests to scm, or toggle the auto option of the service client. When the server shuts down, scm checks if all local service clients have shut down. If not, it will wait until time out and then kill those which are still running. Otherwise, scm will terminate normally after several seconds.

Remote service clients are not managed by scm. Since they cannot be shut down or launched remotely, and it is impossible to check for the presence of the executable files, it is unnecessary for scm to manage them.

Service client should place a config file with the filename the same as the its own name under service_clients sub-directory in XMMS2 config dir on installation. And on uninstallation, the corresponding config file should be removed as well. scm reads in all config files on startup every time. Besides, scm can also monitor changes made to any config files during runtime. By default, scm will use libinotify kernel feature if you are using a kernel later than 2.6.13. Otherwise, periodic polling method is chosen. Monitoring feature can be enabled/disabled by changing scm configuration. This is discussed in the following section. If you have disabled monitoring feature, but do not want to restart scm in order to read in the changes, you can force scm to check for any changes by issuing a method call to the "poll" method.

Note: Although service client API provides a shutdown feature as well, namely xmmsc_service_shutdown(), it is crucially different from the one provided by scm. For service clients which are managed by scm, you can either try to send a shutdown request by calling xmmsc_service_shutdown() or ask scm to shut it down for you. However, service client has the right to ignore the shutdown request. So xmmsc_service_shutdown() may not always work as expected. In this case, scm will force the service client to shutdown by killing the process if it ignores the shutdown request. To be clear, if you need guaranteed shutdown, use the one provided by scm. This only applies to service clients which are managed by scm!

Configuration

scm is configurable by setting three configvals in the server's config file manually or using configval API. All of the configvals are located in "clients" section and under "scm" client name.

One of them, "monitor", controls whether or not scm should monitor service client config dir using libinotify (if using kernel later than 2.6.13) or by periodic polling (the period is set to 10 seconds by default). The value for this configval can either be "yes" or "no". It is set to "no" by default.

Another configval, "timeout", is the timeout value scm should wait before killing a service client after shutdown request is sent. The value is in milliseconds (1/1000ths of a second). It is set to 10 seconds by default.

The last one, "period", sets the time interval between each polling if periodic polling is used. Like the previous configval, the value is in milliseconds. The default value is also 10 seconds.

Config File Structure

Config file should be placed under service_clients sub-directory in XMMS2 config dir on installation of the service client if it resides on the same machine as the server does. And the name of the config file should be the same as that of the service client. Config file must contain the following information.

• path to the executable file
• service name(s)
• method name(s) and description(s)

The following table shows the keywords and descriptions for each keyword supported by scm.

Keyword	Description	Type
path	path to the executable file	string
argv	command-line arguments to pass to the executable file	string
auto	if the service client should be launched automatically	"yes" or "no"
[service name]	service name should be surrounded by brackets	string
description	service descriptions	string
major	major version of service	unsigned integer
minor	minor version of service	unsigned integer

Here is an example of what a config file should look like. Note that "path", "argv" (if any) and "auto" should always come first. Because after "[service name]", every line is considered to be service related information until the next "[service name]".

Contents of file "shutdown"

path=/home/username/xmms2-tutorial/c/service_client/shutdown auto=no [Dummy service] description=This is testing service 1. major=1 minor=0 Dummy method=This is a dummy method.

You may have noticed that I do not have "argv" in the config file, because it is optional and I do not need to pass the executable file any argument. For describing method, method name should show up as the keyword, and method description is on the right hand side of the equal sign.

scm API

There are several services provided by scm, se.xmms.scm.management, se.xmms.scm.query and se.xmms.scm.misc, which deals with service client management, querying service client information and scm-specific configurations, respectively.

Management

se.xmms.scm.management provides the following methods.

Method Name	Description
launch	Launch a service client
shutdown	Shutdown a service client
change_argv	Change the command-line argument to pass to a service client
toggle_autostart	If a service client should be launched automatically

The following tables list argument and return types of each method described above. Return types are separated by an empty line.

Name	Type	Description	Required
client_name	string	client name	yes
ret	uint32	1 for success	yes

Name	Type	Description	Required
client_name	string	client name	yes
ret	uint32	1 for success	yes

Name	Type	Description	Required
client_name	string	client name	yes
argv	string	command-line arguments to pass to the service client	yes
ret	uint32	1 for success	yes

Name	Type	Description	Required
client_name	string	client name	yes
auto	uint32	If the service client should be launched automatically	yes
ret	uint32	1 for success	yes

Querying

se.xmms.scm.query provides the following methods.

Method Name	Description
sc_ids	List the names of all installed service clients
sc	List details of an installed service client
service_ids	List the names of all services of a service client
service	List details of a service
method_ids	List the names of all methods of a service
method	List details of a method
lookup_client	Search for all service clients which provide the given service

The following tables list argument and return types of each method described above. Return types are separated by an empty line.

Name	Type	Description	Required
ids	string list	a list of all installed service clients' names	no

Name	Type	Description	Required
client_name	string	client name	yes
argv	string	command-line arguments to pass to the service client	yes
auto	uint32	If the service client should be launched automatically	yes
services	uint32	number of services the service client provides	yes

Name	Type	Description	Required
client_name	string	client name	yes
ids	string list	a list of the names of all services the service client provides	no

Name	Type	Description	Required
client_name	string	client name	yes
service_name	string	service name	yes
desc	string	service description	yes
major	uint32	service major version	yes
minor	uint32	service minor version	yes
registered	uint32	if the service is registered on the server	yes
methods	uint32	number of methods the service provides	yes

Name	Type	Description	Required
client_name	string	client name	yes
service_name	string	service name	yes
ids	string list	a list of the names of all methods the service provides	no

Name	Type	Description	Required
client_name	string	client name	yes
service_name	string	service name	yes
method_name	string	method name	yes
desc	string	method description	yes
registered	uint32	if the method is registered on the server	yes

Name	Type	Description	Required
service_name	string	service name	yes
ids	string list	a list of the names of all service clients which provide the service	no

Miscellaneous

se.xmms.scm.misc provides the following method.

Method Name	Description
poll	Force the manager to check for any changes in config dir

The "poll" method does not need any arguments and it does not return any values, either.

Go back to Service Client Summary.