Dhaumann: Development/Architecture/KDE 3 Architecture/Services moved to Development/Architecture/KDE3/Services

2007-03-11T21:36:14Z

Development/Architecture/KDE 3 Architecture/Services moved to Development/Architecture/KDE3/Services

Dhaumann: Category:Architecture

2007-01-23T09:36:50Z

Category:Architecture

CuCullin: Category KDE3

2007-01-10T02:35:27Z

Category KDE3

Dhaumann: port of http://developer.kde.org/documentation/library/kdeqt/kde3arch/services.html

2007-01-08T11:35:42Z

port of http://developer.kde.org/documentation/library/kdeqt/kde3arch/services.html

New page

'''KDE's Services and Service Types'''

== What are KDE services? ==

The notion of a ''service'' is a central concept in KDE's modular architecture.
There is no strict technical implementation connected with this term - services
can be plugins in the form of shared libraries, or they can be programs
controlled via [[../DCOP|DCOP]]. By claiming to be of a certain
''service type'', a service promises to implement certain APIs or features.
In C++ terms, one can think of a service type as an abstract class, and a service
as an implementation of that interface.

The advantage of this separation is clear: An application utilizing a service
type does not have to know about possible implementations of it. It just uses
the APIs associated with the service type. In this way, the used service can be
changed without affecting the application. Also, the user can configure which
services he prefers for certain features.

Some examples:

*The HTML rendering engine used in Konqueror is an embedabble component that implements the service types KParts/ReadOnlyPart and Browser/View.
*In KDevelop HEAD, most functionality is packaged in plugins with the service type KDevelop/Part. At startup, all services with this type are loaded, such that you can extend the IDE in a very flexible way.
*In the icon view, Konqueror displays - if enabled - thumbnail pictures of images, HTML pages, PDF and text files. This ability can be extended. If you want it to display preview pictures of your own data files with some MIME type, you can implement a service with service type ThumbCreator.

Obviously, a service is not only characterized by the service types it
implements, but also by some ''properties''. For example, a ThumbCreator
does not only claim to implement the C++ class with the ThumbCreator, it
also has a list of MIME types it is responsible for. Similarly, KDevelop
parts have the programming language they support as a property. When
an application requests a service type, it can also list constraints on
the properties of the service. In the above example, when KDevelop loads
the plugins for a Java project, it asks only for the plugins which have
Java as the programming language property. For this purpose, KDE contains
a full-blown CORBA-like ''trader'' with a complex query language.

== Defining service types ==

New service types are added by installing a description of them
into the directory {{path|KDEDIR/share/servicetypes}}. In an automake framework,
this can be done with this Makefile.am snippet:

kde_servicetypesdir_DATA = kdeveloppart.desktop
EXTRA_DIST = $(kde_servicetypesdir_DATA)

The definition kdeveloppart.desktop of a KDevelop part looks as follows:

[Desktop Entry]
Type=ServiceType
X-KDE-ServiceType=KDevelop/Part
Name=KDevelop Part

[PropertyDef::X-KDevelop-Scope]
Type=QString

[PropertyDef::X-KDevelop-ProgrammingLanguages]
Type=QStringList

[PropertyDef::X-KDevelop-Args]
Type=QString

In addition to the usual entries, this example demonstrates how you declare
that a service has some properties. Each property definition corresponds
to a group <tt>[PropertyDef::name]</tt> in the configuration file. In
this group, the <tt>Type</tt> entry declares the type of the property.
Possible types are everything that can be stored in a
{{qt3|QVariant}}.

== Defining shared library services ==

Service definitions are stored in the directory {{path|KDEDIR/share/services}}:

kde_servicesdir_DATA = kdevdoxygen.desktop
EXTRA_DIST = $(kde_servicesdir_DATA)

The content of the following example file kdevdoxygen.desktop defines
the KDevDoxygen plugin with the service type KDevelop/Part:

[Desktop Entry]
Type=Service
Comment=Doxygen
Name=KDevDoxygen
ServiceTypes=KDevelop/Part
X-KDE-Library=libkdevdoxygen
X-KDevelop-ProgrammingLanguages=C,C++,Java
X-KDevelop-Scope=Project

In addition to the usual declarations, an important entry is
<tt>X-KDE-Library</tt>. This contains the name of the libtool library (without
the <tt>.la</tt> extension). It also fixes (with the prefix <tt>init_</tt>
prepended) the name of the exported symbol in the library which returns an
object factory. For the above example, the library must contain the following
function:

<code cppqt3>
extern "C" {
void *init_libkdevdoxygen()
{
return new DoxygenFactory;
}
};
</code>

The type of the factory class DoxygenFactory depends on the specific service
type the service implements. In our example of a KDevelop plugin, the factory
must be a KDevFactory (which inherits KLibFactory). More common examples are
[http://api.kde.org/3.5-api/kdelibs-apidocs/kparts/html/classKParts_1_1Factory.html KParts::Factory]
which is supposed to produce
[http://api.kde.org/3.5-api/kdelibs-apidocs/kparts/html/classKParts_1_1ReadOnlyPart.html KParts::ReadOnlyPart]
objects or in most cases the generic
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKLibFactory.html KLibFactory].

== Using shared library services ==

In order to use a shared library service in an application, you need to obtain a
[http://api.kde.org/3.5-api/kdelibs-apidocs/kio/kio/html/classKService.html KService] object
representing it. This is discussed in the
[[../MIME Types|section about MIME types]] (and in a section about the
trader to be written :-)

With the KService object at hand, you can very simply load the library and
get a pointer to its factory object:

<code cppqt3>
KService *service = ...
QString libName = QFile::encodeName(service->library());
KLibFactory *factory = KLibLoader::self()->factory(libName);
if (!factory) {
QString name = service->name();
QString errorMessage = KLibLoader::self()->lastErrorMessage();
KMessageBox::error(0, i18n("Error while loading service %1.\n"
"The diagnostics from libtool is:\n%2")
.arg(name).arg(errorMessage);
}
</code>

From this point, the further proceeding depends again on the service type. For
generic plugins, you create objects with the method
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKLibFactory.html#a2 KLibFactory::create()].
For KParts, you must cast the factory pointer to the more specific KParts::Factory and use
its create() method:

<code cppqt3>
if (factory->inherits("KParts::Factory")) {
KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory);
QObject *obj = partFactory->createPart(parentWidget, widgetName,
parent, name,
"KParts::ReadOnlyPart");
// ...
} else {
cout << "Service does not implement the right factory" << endl;
}
</code>

== Defining DCOP services ==

A DCOP service is usually implemented as a program that is started up when it is
needed. It then goes into a loop and listens for DCOP connections. The program
may be an interactive one, but it may also run completely or for a part of its
lifetime as a daemon in the background without the user noticing it. An example
for such a daemon is <tt>kio_uiserver</tt>, which implements user interaction
such as progress dialog for the KIO library. The advantage of such a centralized
daemon in this context is that e.g. the download progress for several different
files can be shown in one window, even if those downloads were initiated from
different applications.

A DCOP service is defined differently from a shared library service. Of course,
it doesn't specify a library, but instead an executable. Also, DCOP services
do not specify a ServiceType line, because usually they are started by their
name. As additional properties, it contains two lines:

<tt>X-DCOP-ServiceType</tt> specifies the way the service is started. The value
<tt>Unique</tt> says that the service must not be started more than once. This
means, if you try to start this service (e.g. via
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKApplication.html#e5 KApplication::startServiceByName()], KDE looks whether it is already
registered with DCOP and uses the running service. If it is not registered yet,
KDE will start it up and wait until is registered. Thus, you can immediately
send DCOP calls to the service. In such a case, the service should be implemented
as a
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKUniqueApplication.html KUniqueApplication].

The value <tt>Multi</tt> for <tt>X-DCOP-ServiceType</tt> says that multiple
instances of the service can coexist, so every attempt to start the service
will create another process. As a last possibility the value <tt>None</tt>
can be used. In this case, a start of the service will not wait until it
is registered with DCOP.

<tt>X-KDE-StartupNotify</tt> should normally be set to false. Otherwise, when
the program is started, the task bar will show a startup notification, or, depending
on the user's settings, the cursor will be changed.

Here is the definition of <tt>kio_uiserver</tt>:

[Desktop Entry]
Type=Service
Name=kio_uiserver
Exec=kio_uiserver
X-DCOP-ServiceType=Unique
X-KDE-StartupNotify=false

== Using DCOP services ==

A DCOP service is started with one of several methods in the KApplication
class:

<code cppqt3>
DCOPClient *client = kapp->dcopClient();
client->attach();
if (!client->isApplicationRegistered("kio_uiserver")) {
QString error;
if (KApplication::startServiceByName("kio_uiserver",
QStringList(), &error))
cout << "Starting kioserver failed with message " << error << endl;
}
// ...
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg << true;
if (!client->call("kio_uiserver", "UIServer", "setListMode(bool)",
data, replyType, replyData))
cout << "Call to kio_uiserver failed" << endl;
// ...
</code>

Note that the example of a DCOP call given here uses explit marshalling
of arguments. Often you will want to use a stub generated by dcopidl2cpp
instead, because it is much simpler and less error prone.

In the example given here, the service was started "by name", i.e. the
first argument to KApplication::startServiceByName() is the name is
appearing in the Name line of the desktop file. An alternative is to
use KApplication::startServiceByDesktopName(), which takes the file name
of its desktop file as argument, i.e. in this case "kio_uiserver.desktop".

All these calls take a list of URLs as a second argument, which is given
to the service on the command line. The third argument is a pointer to a
QString. If starting the service fails, this argument is set to a translated
error message.

''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]

@@ Line 99: / Line 99: @@
+   }
 };
-</code>
+</syntaxhighlight>
 The type of the factory class DoxygenFactory depends on the specific service
@@ Line 132: / Line 132: @@
                          .arg(name).arg(errorMessage);
+}
-</code>
+</syntaxhighlight>
 From this point, the further proceeding depends again on the service type. For
@@ Line 150: / Line 150: @@
      cout << "Service does not implement the right factory" << endl;
+}
-</code>
+</syntaxhighlight>
 == Defining DCOP services ==
@@ Line 221: / Line 221: @@
    cout << "Call to kio_uiserver failed" << endl;
 // ...
-</code>
+</syntaxhighlight>
 Note that the example of a DCOP call given here uses explit marshalling

← Older revision		Revision as of 09:36, 23 January 2007
Line 242:		Line 242:

	[[Category:KDE3]]		[[Category:KDE3]]
		+	[[Category:Architecture]]

← Older revision		Revision as of 02:35, 10 January 2007
Line 240:		Line 240:

	''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]		''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]
		+
		+	[[Category:KDE3]]

Development/Architecture/KDE3/Services - Revision history

Neverendingo: Text replace - "" to ""

Neverendingo: Text replace - "`" to ""`

Dhaumann: Development/Architecture/KDE 3 Architecture/Services moved to Development/Architecture/KDE3/Services

Dhaumann: Category:Architecture

CuCullin: Category KDE3

Dhaumann: port of http://developer.kde.org/documentation/library/kdeqt/kde3arch/services.html

@@ Line 92: / Line 92: @@
 function:
-<code cppqt3>
+<syntaxhighlight lang="cpp-qt">
 extern "C" {
    void *init_libkdevdoxygen()
@@ Line 121: / Line 121: @@
 get a pointer to its factory object:
-<code cppqt3>
+<syntaxhighlight lang="cpp-qt">
 KService *service = ...
 QString libName = QFile::encodeName(service->library());
@@ Line 140: / Line 140: @@
 its create() method:
-<code cppqt3>
+<syntaxhighlight lang="cpp-qt">
 if (factory->inherits("KParts::Factory")) {
    KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory);
@@ Line 203: / Line 203: @@
 class:
-<code cppqt3>
+<syntaxhighlight lang="cpp-qt">
 DCOPClient *client = kapp->dcopClient();
 client->attach();