KDE TechBase - User contributions [en]

Development/Tutorials/First program

2012-03-12T20:08:49Z

Yecril71pl: /* The Code */ oops, dead code

{{Template:I18n/Language Navigation Bar|Development/Tutorials/First_program}}
{{TutorialBrowser|

series=Beginner Tutorial|

name=Hello World|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://qt.nokia.com Qt], [[Getting_Started/Build|Building KDE]]|

next=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]]|

reading=[[Development/Tutorials/CMake|CMake]]
}}

==Abstract==
Your first program shall greet the world with a friendly "Hello World", what else? For that, we will use a {{class|KMessageBox}} and customise one of the buttons.
[[image:introtokdetutorial1.png|frame|center]]

{{tip|To get more information about any class you come across, Konqueror offers a quick shortcut. So to look for information about KMessageBox, just type "kde:kmessagebox" into Konqueror and you'll be taken to the documentation.}}

{{tip|
You might want to use [[qtcreator|QtCreator]] as IDE for your projects.
}}

==The Code==
All the code we need will be in one file, <tt>main.cpp</tt>. Create that file with the code below:
<syntaxhighlight lang="cpp-qt">
#include <cstdlib>

#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KMessageBox>
#include <KLocale>

int main (int argc, char *argv[])
{
KAboutData aboutData(
// The program name used internally.
"tutorial1",
// The message catalog name
// If null, program name is used instead.
0,
// A displayable program name string.
ki18n("Tutorial 1"),
// The program version string.
"1.0",
// Short description of what the app does.
ki18n("Displays a KMessageBox popup"),
// The license this code is released under
KAboutData::License_GPL,
// Copyright Statement
ki18n("(c) 2007"),
// Optional text shown in the About box.
// Can contain any information desired.
ki18n("Some text..."),
// The program homepage string.
"http://example.com/",
// The bug report email address
"submit@bugs.kde.org");

KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;
KGuiItem yesButton( i18n( "Hello" ), QString(),
i18n( "This is a tooltip" ),
i18n( "This is a WhatsThis help text." ) );
return
KMessageBox ::questionYesNo
(0, i18n( "Hello World" ), i18n( "Hello" ), yesButton )
== KMessageBox ::Yes? EXIT_SUCCESS: EXIT_FAILURE;
}
</syntaxhighlight>
The first KDE specific code we come across in this program is {{class|KAboutData}}. This is the class used to store information about the program such as a short description, authors or license information. Pretty much every KDE application should use this class.

Then we come to {{class|KCmdLineArgs}}. This is the class one would use to specify command line switches to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the {{class|KAboutData}} object we created so we can use the <tt>--version</tt> or <tt>--author</tt> switches.

Then we create a {{class|KApplication}} object. This needs to be done exactly once in each program since it is needed for things such as [[Development/Tutorials/Localization/i18n|i18n]].

Now we've done all the necessary KDE setup, we can move on to doing interesting things with our application. We're going to create a popup box but we're going to customise one of the buttons. To do this customisation, we need to use a {{class|KGuiItem}} object. The first argument in the {{class|KGuiItem}} constructor is the text that will appear on the item (in our case, a button). Then we have an option of setting an icon for the button but we don't want one so we just give it <tt>QString()</tt>. We then set the tooltip (what appears when you hover over an item) and finally the "What's This?" (accessed through right-clicking or Shift-F1) text.

Now we have our item, we can create our popup. We call the <tt>{{class|KMessageBox}}::questionYesNo()</tt> function which, by default, creates a message box with a "Yes" and a "No" button. The second argument is the text that will appear in the message box above the buttons. The third is the caption the window will have and finally we set the KGuiItem for (what would normally be) the "Yes" button to the <tt>KGuiItem yesButton</tt> we created.

Note that all user-visible text is passed through the i18n() function; this is necessary for the UI to be translatable. More information on localization can be found in the [[Development/Tutorials/Localization/i18n|localization tutorial]].

We're all done as far as the code is concerned. Now to build it and try it out.

== Build ==
You want to [[Development/Tutorials/CMake|use CMake]] for your build environment. You provide a file CMakeLists.txt, cmake uses this file to generate all Makefiles out of it.

=== CMakeLists.txt ===
Create a file named CMakeLists.txt in the same directory as main.cpp with this content:
<syntaxhighlight lang="cmake">
project (tutorial1)
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
set(tutorial1_SRCS main.cpp)
kde4_add_executable(tutorial1 ${tutorial1_SRCS})
target_link_libraries(tutorial1 ${KDE4_KDEUI_LIBS})
install(TARGETS tutorial1 ${INSTALL_TARGETS_DEFAULT_ARGS})
</syntaxhighlight>
The <tt>find_package()</tt> function locates the package that you ask it for (in this case KDE4) and sets some variables describing the location of the package's headers and libraries. In this case we will use the <tt>KDE4_INCLUDES</tt> variable which contains the path to the KDE4 header files.

In order to allow the compiler to find these files, we pass that variable to the <tt>include_directories()</tt> function which adds the KDE4 headers to the header search path.

Next we create a variable called <tt>tutorial1_SRCS</tt> using the <tt>set()</tt> function. In this case we simply set it to the name of our only source file.

Then we use <tt>kde4_add_executable()</tt> to create an executable called <tt>tutorial1</tt> from the source files listed in our <tt>tutorial1_SRCS</tt> variable. Afterwards, we link our executable to the KDE4 kdeui library using <tt>target_link_libraries()</tt> and the <tt>KDE4_KDEUI_LIBS</tt> variable which was set by the <tt>find_package()</tt> function. The line starting with <tt>install</tt> writes a default "install" target into the Makefile.

=== Make And Run ===
To compile, link and install your program, you must have several software installed, e.g. kdelibs, cmake, make and gcc-c++. To be sure you have everything, best follow [[Getting_Started/Build/Environment|this install guide]].

You can invoke CMake and make manually:
<syntaxhighlight lang="bash">
cmake . && make && make install
</syntaxhighlight>
Or, if you set up your environment as described in [[Getting_Started/Build/Environment|Getting Started/Build/Environment]], you can compile this code with:
<syntaxhighlight lang="bash">
cmakekde
</syntaxhighlight>

And launch it with:
<syntaxhighlight lang="bash">
./tutorial1
</syntaxhighlight>

==Moving On==
Now you can move on to [[Development/Tutorials/Using_KXmlGuiWindow|using KXmlGuiWindow]].

[[Category:C++]]

Development/Tutorials/First program

2012-03-12T20:07:55Z

Yecril71pl: /* The Code */ return failure on No

{{Template:I18n/Language Navigation Bar|Development/Tutorials/First_program}}
{{TutorialBrowser|

series=Beginner Tutorial|

name=Hello World|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://qt.nokia.com Qt], [[Getting_Started/Build|Building KDE]]|

next=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]]|

reading=[[Development/Tutorials/CMake|CMake]]
}}

==Abstract==
Your first program shall greet the world with a friendly "Hello World", what else? For that, we will use a {{class|KMessageBox}} and customise one of the buttons.
[[image:introtokdetutorial1.png|frame|center]]

{{tip|To get more information about any class you come across, Konqueror offers a quick shortcut. So to look for information about KMessageBox, just type "kde:kmessagebox" into Konqueror and you'll be taken to the documentation.}}

{{tip|
You might want to use [[qtcreator|QtCreator]] as IDE for your projects.
}}

==The Code==
All the code we need will be in one file, <tt>main.cpp</tt>. Create that file with the code below:
<syntaxhighlight lang="cpp-qt">
#include <cstdlib>

#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KMessageBox>
#include <KLocale>

int main (int argc, char *argv[])
{
KAboutData aboutData(
// The program name used internally.
"tutorial1",
// The message catalog name
// If null, program name is used instead.
0,
// A displayable program name string.
ki18n("Tutorial 1"),
// The program version string.
"1.0",
// Short description of what the app does.
ki18n("Displays a KMessageBox popup"),
// The license this code is released under
KAboutData::License_GPL,
// Copyright Statement
ki18n("(c) 2007"),
// Optional text shown in the About box.
// Can contain any information desired.
ki18n("Some text..."),
// The program homepage string.
"http://example.com/",
// The bug report email address
"submit@bugs.kde.org");

KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;
KGuiItem yesButton( i18n( "Hello" ), QString(),
i18n( "This is a tooltip" ),
i18n( "This is a WhatsThis help text." ) );
return
KMessageBox ::questionYesNo
(0, i18n( "Hello World" ), i18n( "Hello" ), yesButton )
== KMessageBox ::Yes? EXIT_SUCCESS: EXIT_FAILURE;
return 0;
}
</syntaxhighlight>
The first KDE specific code we come across in this program is {{class|KAboutData}}. This is the class used to store information about the program such as a short description, authors or license information. Pretty much every KDE application should use this class.

Then we come to {{class|KCmdLineArgs}}. This is the class one would use to specify command line switches to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the {{class|KAboutData}} object we created so we can use the <tt>--version</tt> or <tt>--author</tt> switches.

Then we create a {{class|KApplication}} object. This needs to be done exactly once in each program since it is needed for things such as [[Development/Tutorials/Localization/i18n|i18n]].

Now we've done all the necessary KDE setup, we can move on to doing interesting things with our application. We're going to create a popup box but we're going to customise one of the buttons. To do this customisation, we need to use a {{class|KGuiItem}} object. The first argument in the {{class|KGuiItem}} constructor is the text that will appear on the item (in our case, a button). Then we have an option of setting an icon for the button but we don't want one so we just give it <tt>QString()</tt>. We then set the tooltip (what appears when you hover over an item) and finally the "What's This?" (accessed through right-clicking or Shift-F1) text.

Now we have our item, we can create our popup. We call the <tt>{{class|KMessageBox}}::questionYesNo()</tt> function which, by default, creates a message box with a "Yes" and a "No" button. The second argument is the text that will appear in the message box above the buttons. The third is the caption the window will have and finally we set the KGuiItem for (what would normally be) the "Yes" button to the <tt>KGuiItem yesButton</tt> we created.

Note that all user-visible text is passed through the i18n() function; this is necessary for the UI to be translatable. More information on localization can be found in the [[Development/Tutorials/Localization/i18n|localization tutorial]].

We're all done as far as the code is concerned. Now to build it and try it out.

== Build ==
You want to [[Development/Tutorials/CMake|use CMake]] for your build environment. You provide a file CMakeLists.txt, cmake uses this file to generate all Makefiles out of it.

=== CMakeLists.txt ===
Create a file named CMakeLists.txt in the same directory as main.cpp with this content:
<syntaxhighlight lang="cmake">
project (tutorial1)
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
set(tutorial1_SRCS main.cpp)
kde4_add_executable(tutorial1 ${tutorial1_SRCS})
target_link_libraries(tutorial1 ${KDE4_KDEUI_LIBS})
install(TARGETS tutorial1 ${INSTALL_TARGETS_DEFAULT_ARGS})
</syntaxhighlight>
The <tt>find_package()</tt> function locates the package that you ask it for (in this case KDE4) and sets some variables describing the location of the package's headers and libraries. In this case we will use the <tt>KDE4_INCLUDES</tt> variable which contains the path to the KDE4 header files.

In order to allow the compiler to find these files, we pass that variable to the <tt>include_directories()</tt> function which adds the KDE4 headers to the header search path.

Next we create a variable called <tt>tutorial1_SRCS</tt> using the <tt>set()</tt> function. In this case we simply set it to the name of our only source file.

Then we use <tt>kde4_add_executable()</tt> to create an executable called <tt>tutorial1</tt> from the source files listed in our <tt>tutorial1_SRCS</tt> variable. Afterwards, we link our executable to the KDE4 kdeui library using <tt>target_link_libraries()</tt> and the <tt>KDE4_KDEUI_LIBS</tt> variable which was set by the <tt>find_package()</tt> function. The line starting with <tt>install</tt> writes a default "install" target into the Makefile.

=== Make And Run ===
To compile, link and install your program, you must have several software installed, e.g. kdelibs, cmake, make and gcc-c++. To be sure you have everything, best follow [[Getting_Started/Build/Environment|this install guide]].

You can invoke CMake and make manually:
<syntaxhighlight lang="bash">
cmake . && make && make install
</syntaxhighlight>
Or, if you set up your environment as described in [[Getting_Started/Build/Environment|Getting Started/Build/Environment]], you can compile this code with:
<syntaxhighlight lang="bash">
cmakekde
</syntaxhighlight>

And launch it with:
<syntaxhighlight lang="bash">
./tutorial1
</syntaxhighlight>

==Moving On==
Now you can move on to [[Development/Tutorials/Using_KXmlGuiWindow|using KXmlGuiWindow]].

[[Category:C++]]

Projects/PIM/KDE 4-related bugs

2012-02-14T11:11:39Z

Yecril71pl: green is too dark

== Major bugs / Showstoppers ==
{| border="1"
! Small description !! Additional comments !! Status
|-
|Kontact plugin selection totally broken||kdelibs [http://bugs.kde.org/show_bug.cgi?id=152326 bug 152326] and [http://bugs.kde.org/show_bug.cgi?id=152495 bug 152495] ||not started
|-style="background:lightgreen"
|KNode: Can't post messages, refused with "You cannot post an empty message."||Needs to be fixed before release||claimed to be fixed, was kdelibs bug
|-
|Akregator: Articles appear in wrong feed, articles get randomly marked as unread again||[https://bugs.kde.org/show_bug.cgi?id=161313 Bug report]||not started
|}

== Bugs ==
=== Kontact ===
{| border="1"
! Small description !! Additional comments !! Status
|-
|Mainwindow size changes when switching components|| || not started
|-
|"Reverse name with comma" setting of KAddressbook doesn't seem to be honored by KMail's composer||||not started
|-
|Progressbar takes too much space||||not started
|-
|Wrong layout for configure dialog: side pane does not have enough space||||[http://bugs.kde.org/show_bug.cgi?id=152326 kdelibs bug]
|-
|"xx contacts matching" message of the addressbook component added to the wrong place in the status bar||||not started
|-
|Unable to change date range of special dates plugin||||not started
|-
|Date in summary no longer right-aligned||||not started
|}

=== KOrganizer ===
{| border="1"
! Small description !! Additional comments !! Status
|-style="background:lightgreen"
|Creating all-day events does not have any effect||||fixed
|-style="background:lightgreen"
|Changing month in date-picker in top-left corner: Layout is changed because of different length of month names||||fixed
|-style="background:lightgreen"
|Date-picker in top-left corner: Year has semicolon (2,008 instead of 2008)||||fixed
|}

=== KMail ===

See also the bugzilla reports, KDE4 specifc bugs can be viewed with
[https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=kmail&version=1.9.50&version=1.9.51&version=1.10.0&version=1.9.52&version=SVN+trunk+%28KDE+4%29&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_severity=critical&bug_severity=grave&bug_severity=major&bug_severity=crash&bug_severity=normal&bug_severity=minor&bugidtype=include&bug_id=&votes=&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&order=Reuse+same+sort+as+last+time&cmdtype=doit this query]

Open reports with patches: [https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=PATCH&long_desc_type=allwordssubstr&long_desc=&product=kmail&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bugidtype=include&bug_id=&votes=&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&order=Reuse+same+sort+as+last+time&cmdtype=doit Query]

If you are not a developer, please don't report bugs here, there is not enough space for meaningful reports; use bugs.kde.org instead.

{| border="1"
! Small description !! Additional comments !! Status
|-style="background:lightgreen"
|Editor: HTML Toolbar does not have "Standard" as default bullet type, the combobox is empty.||||fixed
|-
|Template Config: Dialog size changes when changing shortcut||||not started
|-style="background:lightgreen"
|After checking mail with POP3, clicking a message results in many setMsg() calls, which is slow||Multiple connects?||fixed
|-style="background:lightgreen"
|Composer: HTML toolbar should be in separate row||||fixed
|-
|Crash when canceling POP3 check quickly||Somewhere in scheduler||not started
|-style="background:lightgreen"
|<message> and <body> filter criteria missing||||fixed
|-style="background:lightgreen"
|Some messages (fetched with POP) have strange character as last char of subject in message list||||fixed
|-style="background:lightgreen"
|No longer possible to expand folder without selecting it||according to till. Not seen on r827329||fixed
|-
|POP3: Fetching mail does not work when precommand is enabled||||not started
|-style="background:lightgreen"
|POP account dialog: editing "filter if greater than xx bytes" keyboard input broken||KDELIBS bugs really, but very annoying. Used in other places as well.||fixed
|-
|Composer: When sending message, the dialog that shows the used encryption keys has a broken layout||||not started
|-
|Appearance options: Message List->Custom Format: Layout broken||||not started
|-
|Shortcut configured in stand-alone KMail are not loaded in Kontact - and the other way round||||not started
|-style="background:lightgreen"
|Editor: Spellchecking config: Language change does not update the words marked with red||||fixed
|-style="background:lightgreen"
|Editor: Add/Remove quote char does not work for > 1 line or HTML text||||fixed
|-style="background:lightgreen"
|Editor: HTML toolbar enabled by default, state not correctly saved and inconsistent||||fixed
|-style="background:lightgreen"
|Editor: Editing draft/outgoing message causes HTML garbage to appear||||Fixed
|-style="background:lightgreen"
|Editor: Changing identity: Signature not changed when in HTML mode||||fixed
|-style="background:lightgreen"
|Editor: When writing new mail in HTML mode, no newline is added in front of the signature separator||||fixed
|-style="background:lightgreen"
|Editor: Quoted HTML text (after reply) no longer green||||fixed
|-style="background:lightgreen"
|Editor: Toggle fixed font does not work||||fixed
|-style="background:lightgreen"
|Editor: Right-clicking selects word||||fixed
|-style="background:lightgreen"
|Editor: Tabs show as spaces||||seems fixed
|-style="background:lightgreen"
|Editor: Mails are sent as HTML with incorrect content-type||||Fixed
|-
|Crash when deleting mail in maildir folder ||Two slightly different stack traces: http://pastebin.ca/800711 http://pastebin.ca/800740||not started
|-
|Crash when changing tag shortcut.||Set a shortcut, apply, reset the shortcut, apply, then set back the old one -> crash||not started
|-style="background:lightgreen"
|Incorrect mainwindow size||resize() should be called in kmmainwin, not kmmainwidget||fixed
|-
|Pasting obsocufated mail address like "null at kde dot org" in 'to' line no longer changes it to real address||Seems not possible to fix, see [http://thread.gmane.org/gmane.comp.kde.devel.pim/20997 this thread]||not started
|-style="background:lightgreen"
|Toggling unread column with right click on header: Action state not updated||||fixed
|-style="background:lightgreen"
|inbox folder not created until restart when creating first pop account||||feature, not a bug :)
|-
|The composer needs to be restarted to see new addressbooks||||not started
|-style="background:lightgreen"
|POP filter dialog too small||||fixed
|-
|"Create Task" in stand-alone KMail does not start KOrganizer||The dbus autostarter in kdelibs does not work for some reason||not started
|-style="background:lightgreen"
|Initial column sizes of the folder tree wrong||Size and unread column should be hidden by default||fixed
|-style="background:lightgreen"
|D-Bus interface broken, incorrect and incomplete port||See [http://article.gmane.org/gmane.comp.kde.devel.pim/20563 here] and [http://article.gmane.org/gmane.comp.kde.devel.pim/20592 here]||mostly fixed
|-
|"Mark Message" entry in context menu sometimes takes several seconds to pop up||||not started
|-
|Alternate background colors in message list no longer there||Will probably be fixed in the SoC by Szymon||not started
|-
|Folder shortcuts don't work after restart if they were conflicting with another shortcut||||not started
|-
|Adding filter actions or folder shortcut actions manually to the toolbar does not work||does not survive a restart||not started
|-
|Tag shortcuts don't show up in "Configure Shortcuts" dialog||||not started
|-
|Renaming a transport: Identity config UI not updated immediately||||not started
|-
|When deleting attachments, the message list selection is lost||||not started
|-
|Arrow not drawn for toolbar actions which have more sub-actions, like "Check Mail"||Probably kdelibs bug||Reported [http://bugs.kde.org/show_bug.cgi?id=151697 here]
|-
|Startup wizard: Layout of the "check what the server supports" page wrong for long server names||||not started
|-
|Shortcut dialog: Tag and template actions are not shown||||not started
|-style="background:lightgreen"
|Fancy header: Spam status bar image broken||||fixed
|-style="background:lightgreen"
|Missing icons||||Are reported [[Projects/Oxygen/Missing_Icons|here]]
|--style="background:lightgreen"
|-style="background:lightgreen"
|Pressing some keys (se for me) in the folder select dialog causes it to freeze. Seems to be infinite repaint chain bug.||||can't reproduce anymore. Fixed?
|-style="background:lightgreen"
|Closing composer: When asked to save as draft, message is NOT saved||Possible dataloss||seems fixed, can't reproduce anymore
|}

=== KAddressbook ===

{| border="1"
! Small description !! Additional comments !! Status
|-style="background:lightgreen"
|Incorrect background color in right pane: gray background on white background||||fixed
|-style="background:lightgreen"
|When editing a person, I got a crash in kabcore.cpp:681, addr.resource() is valid, but addr.resource()->readOnly() points to bad memory.||||fixed
|-style="background:lightgreen"
|Cannot change the name of standard addressbook resource||||fixed
|-style="background:lightgreen"
|Cannot save addressbook for standard resource (std.vcf)|| reported by toma ||fixed
|-
|Crash when exiting kaddressbook after editing contact.||d->mManager is 0 in kdepimlibs/kabc/addressbook.cpp:443||not started
|-style="background:lightgreen"
|Crash when changing settings||DBUS message caused crash. I have uncommented it for now. Could it be removed? (s. kcmconfigs/addresseewidget.cpp:205||fixed
|-style="background:lightgreen"
|Crash when resizing main window and jump button bar is enabled||||fixed
|-style="background:lightgreen"
|Status of checkboxes is not saved in KPIM::AddresseeView||in kdepim/libkdepim/addresseeview.cpp||worksforme
|}

=== KNode ===

{| border="1"
! Small description !! Additional comments !! Status
|-style="background:lightgreen"
|New Account dialog: Redundant slider next to port settings||||fixed
|-style="background:lightgreen"
|New Account dialog: Silently drops settings if no account name was entered||Should use the server name if left empty||fixed (r739089)
|-
|Shortcuts (eg. v for View Source) do not work||||not started
|-style="background:lightgreen"
|Wrong homepage in about dialog||Should be http://kontact.kde.org/knode/ instead of http://knode.sourceforge.net//||fixed
|-
|Missing icons in folder list, menus, and configure dialog||Some of these might already exist for KMail, else see http://techbase.kde.org/Projects/Oxygen/Missing_Icons||not started
|-
|Too many items in toolbar||With the captions, the toolbar spans two rows, even on 1280x1024||not started
|-
|Splitter position between message display and message list not restored correctly||||not started
|}

[[Category:PIM]]

Thread:Talk:Policies/Licensing Policy/GFDL 1.2 is listed twice

2012-01-27T19:26:33Z

Yecril71pl: they differ only in KDE approval

There are two identical bullets in §8 describing [[GFDL]] 1.2, they differ only in [[KDE]] approval. Why is that? Is it a way of legally saying that unapproved licenses are allowed?

Should it be assumed that documentation that bears no licensing metadata is [[GFDL]]?

Thread:Talk:Policies/Licensing Policy/GFDL 1.2 is listed twice

2012-01-25T12:25:30Z

Yecril71pl: New thread: GFDL 1.2 is listed twice

There are two identical bullets in §8 describing GFDL 1.2, they differ only in letter spacing. Why is that?

Should it be assumed that documentation that bears no licensing metadata is GFDL?

Help:Contents

2011-03-26T22:22:16Z

Yecril71pl: /* Wiki Syntax */ link titles

{{Template:I18n/Language Navigation Bar|Help:Contents}}

Before you start to add or change content, please read:
* [[Help:Contribute|Contributing to TechBase]]
* [[Help:Wiki Structure|Wiki Structure]]
* [[Help:Wiki Translation|Translation into other Languages]]
* [[KDE_TechBase:Migrate_content|Migrating Content]]
* [[KDE_TechBase:Contributors|List of active contributors]], also contact points

== Wiki Syntax ==
To get started with the MediaWiki syntax, read:
* [http://en.wikipedia.org/wiki/Help:Editing Help on Editing]
* [http://meta.wikimedia.org/wiki/Help:Table Wikitables]
* [http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax Syntax for displaying images]
* [http://en.wikipedia.org/wiki/Help:Magic_words Magic words]

* [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet The most important commands]
* How to [[KDE TechBase:Migrate content|Migrate content]]

== Tips ==
; Syntax highlighting
: Wrap your C++ Qt/KDE code snippets in <TT ><code cpp></TT >, <TT ><code cpp n></TT >, <TT ><code cpp-qt></TT > and <TT ></code></TT > to get syntax highlighting (<TT >cpp</TT > for C++, <TT >cpp-qt</TT > for Qt) and numbered lines (<TT >n</TT >). Replace <TT >cpp</TT > with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages the language used], e.g. <TT >ruby</TT > for Ruby and <TT >python</TT > for Python (soon). Use <TT >ini</TT > for {{path|.desktop}} files, <TT >xml</TT > for XML files. Use plain <TT ><code></TT > for wikitext (for now).

== New Templates ==
To get a list of pages using a template, go to corresponding template page (e.g. [[Template:movepage]]) and click "''What links here''" in the toolbox.

; [[Template:movepage|<nowiki>{{movepage|url}}</nowiki>]]
: Use this template to mark a page as not finished.

; [[Template:Improve|<nowiki>{{improve|explanation}}</nowiki>]]
: Pages which need cleanups or contain empty sections and/or todos are marked with this template. Add an explanation if you want (optional)

; [[Template:tip|<nowiki>{{tip|text}}</nowiki>]]
: Use this template to add a tip for the reader.

; [[Template:note|<nowiki>{{note|text}}</nowiki>]]
: Use this template to add an explanatory note.

; [[Template:warning|<nowiki>{{warning|text}}</nowiki>]]
: Use this template to add a warning.

; [[Template:qt|<nowiki>{{qt|class-name}}</nowiki>]] and [[Template:qt3|<nowiki>{{qt3|class-name}}</nowiki>]]
: Use this template to generate a link to a Qt class, e.g. QWidget. For Qt3 classes use <nowiki>{{qt3|class-name}}</nowiki>

; [[Template:class|<nowiki>{{class|class-name}}</nowiki>]]
: Use this template to generate a link to a KDE class, e.g. KDialog.

; [[Template:path|<nowiki>{{path|path-or-filename}}</nowiki>]]
: Use this template for paths and filenames, this way all of them have a consistent style.

; [[Template:bug|<nowiki>{{bug|123456}}</nowiki>]]
: Use this template to automatically create a link to KDE's bugzilla.

; [[Template:KDE3|<nowiki>{{KDE3}}</nowiki>]]
: Use this template to mark the content of a page as applicable for either KDE 3. Don't tag technology agnostic pages. For KDE4 content, use <nowiki>[[Category:KDE4]]</nowiki>.

; [[Template:TutorialBrowser|<nowiki>{{TutorialBrowser|series|name|pre|next|reading}}</nowiki>]]
: A template for tutorial navigation

; [[Template:Box|<nowiki>{{Box|caption|text|width|float}}</nowiki>]]
: Use this template to create a box with a caption and a text. The width parameter is optional and can be specified absolute (400px) or relative (50%). The last parameter is the float value, which is also optional and defaults to center.

Help:Contents

2011-03-26T22:14:25Z

Yecril71pl: better link titles

{{Template:I18n/Language Navigation Bar|Help:Contents}}

Before you start to add or change content, please read:
* [[Help:Contribute|Contributing to TechBase]]
* [[Help:Wiki Structure|Wiki Structure]]
* [[Help:Wiki Translation|Translation into other Languages]]
* [[KDE_TechBase:Migrate_content|Migrating Content]]
* [[KDE_TechBase:Contributors|List of active contributors]], also contact points

== Wiki Syntax ==
To get started with the MediaWiki syntax, read:
* http://en.wikipedia.org/wiki/Help:Editing
* http://meta.wikimedia.org/wiki/Help:Table
* http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax
* http://en.wikipedia.org/wiki/Help:Magic_words

[The most important commands are summarized in the [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet Wikipedia Cheatsheet]. Information about how to migrate content [KDE TechBase:Migrate_content|can be found here].
]
--[[User:OpenIDUser83|OpenIDUser83]] 11:15, 1 March 2011 (UTC)

== Tips ==
; Syntax highlighting
: Wrap your C++ Qt/KDE code snippets in <TT ><code cpp></TT >, <TT ><code cpp n></TT >, <TT ><code cpp-qt></TT > and <TT ></code></TT > to get syntax highlighting (<TT >cpp</TT > for C++, <TT >cpp-qt</TT > for Qt) and numbered lines (<TT >n</TT >). Replace <TT >cpp</TT > with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages the language used], e.g. <TT >ruby</TT > for Ruby and <TT >python</TT > for Python (soon). Use <TT >ini</TT > for {{path|.desktop}} files, <TT >xml</TT > for XML files. Use plain <TT ><code></TT > for wikitext (for now).

== New Templates ==
To get a list of pages using a template, go to corresponding template page (e.g. [[Template:movepage]]) and click "''What links here''" in the toolbox.

; [[Template:movepage|<nowiki>{{movepage|url}}</nowiki>]]
: Use this template to mark a page as not finished.

; [[Template:Improve|<nowiki>{{improve|explanation}}</nowiki>]]
: Pages which need cleanups or contain empty sections and/or todos are marked with this template. Add an explanation if you want (optional)

; [[Template:tip|<nowiki>{{tip|text}}</nowiki>]]
: Use this template to add a tip for the reader.

; [[Template:note|<nowiki>{{note|text}}</nowiki>]]
: Use this template to add an explanatory note.

; [[Template:warning|<nowiki>{{warning|text}}</nowiki>]]
: Use this template to add a warning.

; [[Template:qt|<nowiki>{{qt|class-name}}</nowiki>]] and [[Template:qt3|<nowiki>{{qt3|class-name}}</nowiki>]]
: Use this template to generate a link to a Qt class, e.g. QWidget. For Qt3 classes use <nowiki>{{qt3|class-name}}</nowiki>

; [[Template:class|<nowiki>{{class|class-name}}</nowiki>]]
: Use this template to generate a link to a KDE class, e.g. KDialog.

; [[Template:path|<nowiki>{{path|path-or-filename}}</nowiki>]]
: Use this template for paths and filenames, this way all of them have a consistent style.

; [[Template:bug|<nowiki>{{bug|123456}}</nowiki>]]
: Use this template to automatically create a link to KDE's bugzilla.

; [[Template:KDE3|<nowiki>{{KDE3}}</nowiki>]]
: Use this template to mark the content of a page as applicable for either KDE 3. Don't tag technology agnostic pages. For KDE4 content, use <nowiki>[[Category:KDE4]]</nowiki>.

; [[Template:TutorialBrowser|<nowiki>{{TutorialBrowser|series|name|pre|next|reading}}</nowiki>]]
: A template for tutorial navigation

; [[Template:Box|<nowiki>{{Box|caption|text|width|float}}</nowiki>]]
: Use this template to create a box with a caption and a text. The width parameter is optional and can be specified absolute (400px) or relative (50%). The last parameter is the float value, which is also optional and defaults to center.

Help:Contents

2011-03-26T22:12:30Z

Yecril71pl: style

{{Template:I18n/Language Navigation Bar|Help:Contents}}

Before you start to add or change content, please read:
* [[Help:Contribute|Contribute to TechBase]]
* [[Help:Wiki Structure|Wiki Structure]]
* [[Help:Wiki Translation|Translation into other Languages]]
* [[KDE_TechBase:Migrate_content|Migrate Content]]
* [[KDE_TechBase:Contributors|List of active contributors]], also contact points

== Wiki Syntax ==
To get started with the MediaWiki syntax, read:
* http://en.wikipedia.org/wiki/Help:Editing
* http://meta.wikimedia.org/wiki/Help:Table
* http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax
* http://en.wikipedia.org/wiki/Help:Magic_words

[The most important commands are summarized in the [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet Wikipedia Cheatsheet]. Information about how to migrate content [KDE TechBase:Migrate_content|can be found here].
]
--[[User:OpenIDUser83|OpenIDUser83]] 11:15, 1 March 2011 (UTC)

== Tips ==
; Syntax highlighting
: Wrap your C++ Qt/KDE code snippets in <TT ><code cpp></TT >, <TT ><code cpp n></TT >, <TT ><code cpp-qt></TT > and <TT ></code></TT > to get syntax highlighting (<TT >cpp</TT > for C++, <TT >cpp-qt</TT > for Qt) and numbered lines (<TT >n</TT >). Replace <TT >cpp</TT > with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages the language used], e.g. <TT >ruby</TT > for Ruby and <TT >python</TT > for Python (soon). Use <TT >ini</TT > for {{path|.desktop}} files, <TT >xml</TT > for XML files. Use plain <TT ><code></TT > for wikitext (for now).

== New Templates ==
To get a list of pages using a template, go to corresponding template page (e.g. [[Template:movepage]]) and click "''What links here''" in the toolbox.

; [[Template:movepage|<nowiki>{{movepage|url}}</nowiki>]]
: Use this template to mark a page as not finished.

; [[Template:Improve|<nowiki>{{improve|explanation}}</nowiki>]]
: Pages which need cleanups or contain empty sections and/or todos are marked with this template. Add an explanation if you want (optional)

; [[Template:tip|<nowiki>{{tip|text}}</nowiki>]]
: Use this template to add a tip for the reader.

; [[Template:note|<nowiki>{{note|text}}</nowiki>]]
: Use this template to add an explanatory note.

; [[Template:warning|<nowiki>{{warning|text}}</nowiki>]]
: Use this template to add a warning.

; [[Template:qt|<nowiki>{{qt|class-name}}</nowiki>]] and [[Template:qt3|<nowiki>{{qt3|class-name}}</nowiki>]]
: Use this template to generate a link to a Qt class, e.g. QWidget. For Qt3 classes use <nowiki>{{qt3|class-name}}</nowiki>

; [[Template:class|<nowiki>{{class|class-name}}</nowiki>]]
: Use this template to generate a link to a KDE class, e.g. KDialog.

; [[Template:path|<nowiki>{{path|path-or-filename}}</nowiki>]]
: Use this template for paths and filenames, this way all of them have a consistent style.

; [[Template:bug|<nowiki>{{bug|123456}}</nowiki>]]
: Use this template to automatically create a link to KDE's bugzilla.

; [[Template:KDE3|<nowiki>{{KDE3}}</nowiki>]]
: Use this template to mark the content of a page as applicable for either KDE 3. Don't tag technology agnostic pages. For KDE4 content, use <nowiki>[[Category:KDE4]]</nowiki>.

; [[Template:TutorialBrowser|<nowiki>{{TutorialBrowser|series|name|pre|next|reading}}</nowiki>]]
: A template for tutorial navigation

; [[Template:Box|<nowiki>{{Box|caption|text|width|float}}</nowiki>]]
: Use this template to create a box with a caption and a text. The width parameter is optional and can be specified absolute (400px) or relative (50%). The last parameter is the float value, which is also optional and defaults to center.

Development/Tutorials/Services/Traders

2010-11-30T10:39:45Z

Yecril71pl: /* String Matching Operators */ ktraderclient

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Services/Traders}}

{{TutorialBrowser|

series=Services|

name=Finding Services Using Trader Queries|

pre=[[../Introduction|Introduction to the Services Framework]]|

next=[[../Plugins|Creating and Loading Plugins Using KService]]|

}}

== Abstract ==

It is often desirable to be able to find specific types of services or services with specific features or designations. KDE provides a simple yet powerful query language to accomplish this called the KTrader Query Language.

== A Tale of Two Traders ==

KDE provides two classes that act as "traders". A trader takes a query and returns a set of services that match those constraints. There is one trader for plugins and other add-ons: {{class|KServiceTypeTrader}}, and one for mimetypes: {{class|KMimetypeTrader}}. Characteristics for both are similar: they have same syntax for querying, offer a singleton pattern accessor, return {{class|KService}}::Ptrs, as well as other similarities. So while this tutorial concentrates primarily on the {{class|KServiceTypeTrader}}, much of the content is applicable to the mimetype trader as well.

== Service Types ==

{{class|KServiceTypeTrader}} is used to locate individual components such as application plugins, screensavers, and control panels that are registered with the system. The primary concept used here, is that of the "service type". Each set of services has a unique service type, which makes it very easy to locate the sort of component needed.

This means that, each kind of application plugin is uniquely namespaced within the set of all services. So, it is trivial to locate plugins for a given application, without having to worry about getting another application's plugin in the list.

Examples of service types include:
*KParts/ReadWritePart
*KTextEditor/Document
*ScreenSaver
*TerminalEmulator
*UserAgentStrings
*ThumbCreator
*KDevelop/Plugin

There is no limit to the number of service types that a given application may use or register. Of course, service types are not limited to plugins and may be used for any sort of data component.

Creating new service types is covered in the next tutorial of this series:
[[Development/Tutorials/Services/Plugins|Creating and Loading Plugins Using KService]]

== Basic KServiceTypeTrader Usage ==

The service trader is always accessed via the <tt>self()</tt> singleton accessor. With the {{class|KServiceTypeTrader}} in hand, we can then do one of three things:
*'''query''': query for a list of services ordered according to the user's preferences (if any)
*'''defaultOffers''': request all services, unsorted
*'''preferredService''': request the preferred service of a given type

The code to do this is very straight forward:
<code cppqt>
KService::List services;
KServiceTypeTrader* trader = KServiceTypeTrader::self();

services = trader->query("KParts/ReadWritePart");
foreach (KService::Ptr service, services) {
kDebug() << "read write part" << service->name();
}

services = trader->defaultOffers("ThumbCreator");
if (services.isEmpty()) {
kDebug() << "no services found for ThumbCreator!";
}

KService::Ptr service = trader->preferredService("KDevelop/Plugin");
if (!service) {
kDebug() << "no preferred service found for KDevelop/Plugin";
}
</code>

In each case zero or more services are returned that are now usable for locating, describing and loading the item it represents.

== The KTrader Query Language ==

The above examples are quite simplistic and are not detailed enough for many application needs. For instance, we may only want to list plugins for a certain category, that are associated with a particular mimetype, or that have a specific plugin name. This is where the query language comes in.

The query language itself is designed to be human readable and flexible. <tt>{{class|KServiceTypeTrader}}::query</tt> optionally takes a query, in addition to the service type, and uses that to provide more fine-grained searches. So, for example, we'll modify the earlier example in the following way:

<code cppqt>
KService::List services ;
KServiceTypeTrader* trader = KServiceTypeTrader::self();

QString constraint = "'text/plain' in MimeTypes and "
"('KOfficePart' in ServiceTypes or "
" 'oasis' ~ [X-KDE-ExtraNativeMimeTypes])";
services = trader->query("KParts/ReadWritePart", constraint);

foreach (KService::Ptr service, services) {
kDebug() << "read write part" << service->name();
}
</code>

This code will look for a KPart that is both capable of reading/writing plain text files and is also a KOffice component, or can simply read ODF document formats.

Errors in queries are reported via debug output to console at runtime.

=== Order of Operations ===

The query string is evaluated left to right, one section at a time. Sections are divided by boolean operators (see below) or by parentheses ('()'), which serve as grouping characters.

=== Literals ===

Three types of literals are supported by the KTrader Query Language:
*'''strings''': character strings, which must be enclosed in single quotes (')
*'''booleans''': TRUE or FALSE
*'''signed integers'''
*'''signed floating point numbers'''

=== Identifiers ===

Identifiers in a query string are mapped to entries listed in the service's <tt>.desktop</tt> file. For example, "Name" is the name of the service, "ServiceTypes" is a list of the service types it supports.

Identifiers may only contain alphanumeric characters and the '-' character.
Identifiers that do not start with an alphabetical character or that contain non-alphanumeric characters must be enclosed in brackets, e.g. [X-KDE-Init].

There are also three special identifiers:

*'''DesktopEntryName''' stands for the filename of the service desktop entry without its extension. This can be useful to exclude some specific services.
*'''DesktopEntryPath''' stands for the relative or full path to the .desktop file, see {{class|KService}}::desktopEntryPath.
*'''Library''': a synonym for [X-KDE-Library] in the .desktop file.

An identifier can be checked for existence with the '''exist''' operator, e.g. "exist [X-KDE-Library]". This is especially useful when checking for the value of an identifier with a default value. For example, if MyProp is a property with type boolean, one might write "not exist MyProp or MyProp" to match MyProp with a default of "true".

<code cppqt>
QString term = "konq";
QString query = QString("exist Exec and ((exist Keywords and '%1' ~subin Keywords) or (exist GenericName and '%1' ~~ GenericName) or (exist Name and '%1' ~~ Name))").arg(term);
KService::List services = KServiceTypeTrader::self()->query("Application", query);
foreach (KService::Ptr service, services) {
kDebug() << service->name();
}
</code>

=== Comparison Operators ===

The following comparison operators can be used to compare values of any of the supported data types:

*'''==''': equality
*'''!=''': inequality
*'''<''': less than
*'''<=''': less than or equal to
*'''>''': greater than
*'''>=''': greater than or equal to

=== Mathematical Operators ===

The following mathematical operators can be used with numerical types:

* '''+'''
* '''-'''
* '''*'''
* '''/'''

=== Boolean Operators ===

The following boolean operators are supported:

* '''and'''
* '''or'''
* '''not'''

=== String Matching Operators ===

The string matching operators all return a boolean value, indicating success or failure.

String comparisons are done using the following operators:

*'''==''': equality, case sensitive
*'''=~''': equality, case insensitive
*'''!=''': inequality, case sensitive
*'''!~''': inequality, case insensitive

Sub-string matching can be accomplished by using the following operators:

* '''~''': contains, e.g. "'Bar' ~ 'FooBarBaz'" is true
* '''~~''': contains with case insensitive matching, e.g. "'Bar' ~~ 'FoobarBaz'" is true

Some properties, such as MimeTypes and ServiceTypes, are lists of strings. These lists can be searched using the following operators:

* '''in''': the list contains the string, e.g. "'MyApp/Plugin' in ServiceTypes'"
* '''~in''': the list contains the string, with case insensitive matching
* '''subin''': the list contains the string as a substring of one of the entries, e.g. "'Plugin' subin ServiceTypes'"
* '''~subin''': the list contains the string as a substring of one of the entries, with case insensitive matching

== Command line tool ==
* ktraderclient --mimetype <var >mimetype</var > --servicetype <var >servicetype</var > --constraint <var >constraint</var >

KDE System Administration/KDE Filesystem Hierarchy

2010-11-30T10:19:39Z

Yecril71pl: /* Directory Tree */ share/applications/

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} {{path|share/applications/}}|| apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} {{path|share/doc/kde/HTML/<var >lang</var >/<var >package</var >}}|| html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/cache-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/var/tmp/kdecache-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (<tt >ksycoca</tt > and <tt >ksycocastamp</tt >) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[[#Directory Tree]] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory {{path|share/wallpapers/}} is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the <TT >kdeglobals</TT > configuration file in the <TT >[Directories]</TT > section.
To do so assign one or more directories to the key <TT >dir_</TT > followed by the
name of the resource.
Multiple directories are separated by commas (<TT >,</TT >).

==== Adding a Resource Directory ====

To add the directory {{path|/data/photos}} to the wallpaper resource, put the
following two lines in <TT >kdeglobals</TT >:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

Development/Tutorials/Solid/Device Actions

2010-09-15T21:34:17Z

Yecril71pl: /* Installing actions */ where is above

== Introduction ==

The '''Device Notifier''' is a plasmoid that is responsible for handling device events. When new data device is inserted or detected by '''Solid''', it gets added to the Device Notifier menu. Each device has a set of ''actions'' the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier offers you to play that CD using '''Amarok'''. The default actions are not a part of '''Plasma'''; rather, each one is installed by the application that handles the action, and goes away when the application is removed.

You can add your own actions and modify existing ones using the '''Device Actions''' system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

== Anatomy of an action ==

An Action file is a desktop configuration file similar to the following one:
<code ini>
[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'
Type=Service
Actions=Play;

[Desktop Action Play]
Name=Play Audio CD with Amarok
Name[fr]=Jouer CD Audio avec Amarok
# names in other languages
Icon=amarok
Exec=amarok --cdplay %f
</code >

== Actions and devices ==

The '''Device Notifier''' gets the devices and their corresponding actions by interrogating its data engine called '''hotplug'''. The '''hotplug''' data engine gets the set of devices from '''Solid''' and the set of actions from the subdirectories {{path|./solid/actions}} relative to the application settings path in '''KDE'''. The set of actions pertaining to each device is then obtained by evaluating the Solid Predicate specified in the action against the physical and logical properties of the device; if the predicate holds, the action is included.

== Action predicates ==
The predicate for each action is specified in the entry <TT >X-KDE-Solid-Predicate</TT >. The syntax of the predicate allows to construct an object of class '''Solid::Predicate''' out of it.

Atomic predicates can be of the form
* <TT ><VAR >DeviceClass</VAR >.<VAR>attribute</VAR > == <VAR >value</VAR ></TT >
* <TT ><VAR >DeviceClass</VAR >.<VAR >attribute</VAR > & <VAR >value</VAR ></TT >
the latter form meaning that the Solid attribute may have a set of values, and the specified value must be a part of that set.

For example, the predicate <TT >OpticalDisc.availableContent & 'Audio'</TT > means that the device medium is an optical disc and that it contains audio tracks and possibly something else, while the hypothetical predicate <TT >OpticalDisc.availableContent == 'Audio'</TT > means that a matching device contains audio tracks and nothing else.

Atomic predicates can be composed using the keywords <TT >AND</TT > and <TT >OR</TT > and parentheses. In practice, it is easiest to create a custom action with '''System Settings''' and peek the description from the custom action desktop file (within the user profile directory).

== Executing actions ==
A matching action can be selected for execution by the user. When that happens, the command line in the Exec key of the action is executed given the device as a parameter. The location and value of the parameter is specified in the following way:
<DL
><DT ><TT >%f</TT ><DD >Device mount point location, if applicable
<DT ><TT >%d</TT ><DD >Device special file path
<DT ><TT >%i</TT
><DD >Device identifier, as if returned by the command <TT >solid-hardware</TT ></DL >

So you are free to choose whatever command syntax your application supports. Note, however, that the forms <TT >%d</TT > and <TT >%i</TT > are deprecated by the Free Desktop standard and may be discontinued.

== Installing actions ==
You install system-wide actions in the directory where the '''hotplug''' data engine will look for them (see [[#Actions and devices|above]]). The action is available immediately after installation.

Development/Tutorials/Solid/Device Actions

2010-09-15T21:33:03Z

Yecril71pl: /* Executing actions */ Installing

== Introduction ==

The '''Device Notifier''' is a plasmoid that is responsible for handling device events. When new data device is inserted or detected by '''Solid''', it gets added to the Device Notifier menu. Each device has a set of ''actions'' the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier offers you to play that CD using '''Amarok'''. The default actions are not a part of '''Plasma'''; rather, each one is installed by the application that handles the action, and goes away when the application is removed.

You can add your own actions and modify existing ones using the '''Device Actions''' system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

== Anatomy of an action ==

An Action file is a desktop configuration file similar to the following one:
<code ini>
[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'
Type=Service
Actions=Play;

[Desktop Action Play]
Name=Play Audio CD with Amarok
Name[fr]=Jouer CD Audio avec Amarok
# names in other languages
Icon=amarok
Exec=amarok --cdplay %f
</code >

== Actions and devices ==

The '''Device Notifier''' gets the devices and their corresponding actions by interrogating its data engine called '''hotplug'''. The '''hotplug''' data engine gets the set of devices from '''Solid''' and the set of actions from the subdirectories {{path|./solid/actions}} relative to the application settings path in '''KDE'''. The set of actions pertaining to each device is then obtained by evaluating the Solid Predicate specified in the action against the physical and logical properties of the device; if the predicate holds, the action is included.

== Action predicates ==
The predicate for each action is specified in the entry <TT >X-KDE-Solid-Predicate</TT >. The syntax of the predicate allows to construct an object of class '''Solid::Predicate''' out of it.

Atomic predicates can be of the form
* <TT ><VAR >DeviceClass</VAR >.<VAR>attribute</VAR > == <VAR >value</VAR ></TT >
* <TT ><VAR >DeviceClass</VAR >.<VAR >attribute</VAR > & <VAR >value</VAR ></TT >
the latter form meaning that the Solid attribute may have a set of values, and the specified value must be a part of that set.

For example, the predicate <TT >OpticalDisc.availableContent & 'Audio'</TT > means that the device medium is an optical disc and that it contains audio tracks and possibly something else, while the hypothetical predicate <TT >OpticalDisc.availableContent == 'Audio'</TT > means that a matching device contains audio tracks and nothing else.

Atomic predicates can be composed using the keywords <TT >AND</TT > and <TT >OR</TT > and parentheses. In practice, it is easiest to create a custom action with '''System Settings''' and peek the description from the custom action desktop file (within the user profile directory).

== Executing actions ==
A matching action can be selected for execution by the user. When that happens, the command line in the Exec key of the action is executed given the device as a parameter. The location and value of the parameter is specified in the following way:
<DL
><DT ><TT >%f</TT ><DD >Device mount point location, if applicable
<DT ><TT >%d</TT ><DD >Device special file path
<DT ><TT >%i</TT
><DD >Device identifier, as if returned by the command <TT >solid-hardware</TT ></DL >

So you are free to choose whatever command syntax your application supports. Note, however, that the forms <TT >%d</TT > and <TT >%i</TT > are deprecated by the Free Desktop standard and may be discontinued.

== Installing actions ==
You install system-wide actions in the directory where the '''hotplug''' data engine will look for them (see above). The action is available immediately after installation.

Development/Tutorials/Solid/Device Actions

2010-09-15T21:30:37Z

Yecril71pl: /* Action predicates */ executing actions

Development/Tutorials/Solid/Device Actions

2010-09-15T21:15:56Z

Yecril71pl: /* Atomic predicates */ composite actions

Development/Tutorials/Solid/Device Actions

2010-09-15T21:11:59Z

Yecril71pl: /* Action predicates */

== Introduction ==

The '''Device Notifier''' is a plasmoid that is responsible for handling device events. When new data device is inserted or detected by '''Solid''', it gets added to the Device Notifier menu. Each device has a set of ''actions'' the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier offers you to play that CD using '''Amarok'''. The default actions are not a part of '''Plasma'''; rather, each one is installed by the application that handles the action, and goes away when the application is removed.

You can add your own actions and modify existing ones using the '''Device Actions''' system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

== Anatomy of an action ==

An Action file is a desktop configuration file similar to the following one:
<code ini>
[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'
Type=Service
Actions=Play;

[Desktop Action Play]
Name=Play Audio CD with Amarok
Name[fr]=Jouer CD Audio avec Amarok
# names in other languages
Icon=amarok
Exec=amarok --cdplay %f
</code >

== Actions and devices ==

The '''Device Notifier''' gets the devices and their corresponding actions by interrogating its data engine called '''hotplug'''. The '''hotplug''' data engine gets the set of devices from '''Solid''' and the set of actions from the subdirectories {{path|./solid/actions}} relative to the application settings path in '''KDE'''. The set of actions pertaining to each device is then obtained by evaluating the Solid Predicate specified in the action against the physical and logical properties of the device; if the predicate holds, the action is included.

== Action predicates ==
The predicate for each action is specified in the entry <TT >X-KDE-Solid-Predicate</TT >. The syntax of the predicate allows to construct an object of class '''Solid::Predicate''' out of it.

=== Atomic predicates ===
Atomic predicates can be of the form
* <TT ><VAR >DeviceClass</VAR >.<VAR>attribute</VAR > == <VAR >value</VAR ></TT >
* <TT ><VAR >DeviceClass</VAR >.<VAR >attribute</VAR > & <VAR >value</VAR ></TT >
the latter form meaning that the Solid attribute may have a set of values, and the specified value must be a part of that set.

For example, the predicate <TT >OpticalDisc.availableContent & 'Audio'</TT > means that the device medium is an optical disc and that it contains audio tracks and possibly something else, while the hypothetical predicate <TT >OpticalDisc.availableContent == 'Audio'</TT > means that a matching device contains audio tracks and nothing else.

Development/Tutorials/Solid/Device Actions

2010-09-15T21:11:15Z

Yecril71pl: /* Actions and devices */ Predicates

== Introduction ==

The '''Device Notifier''' is a plasmoid that is responsible for handling device events. When new data device is inserted or detected by '''Solid''', it gets added to the Device Notifier menu. Each device has a set of ''actions'' the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier offers you to play that CD using '''Amarok'''. The default actions are not a part of '''Plasma'''; rather, each one is installed by the application that handles the action, and goes away when the application is removed.

You can add your own actions and modify existing ones using the '''Device Actions''' system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

== Anatomy of an action ==

An Action file is a desktop configuration file similar to the following one:
<code ini>
[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'
Type=Service
Actions=Play;

[Desktop Action Play]
Name=Play Audio CD with Amarok
Name[fr]=Jouer CD Audio avec Amarok
# names in other languages
Icon=amarok
Exec=amarok --cdplay %f
</code >

== Actions and devices ==

The '''Device Notifier''' gets the devices and their corresponding actions by interrogating its data engine called '''hotplug'''. The '''hotplug''' data engine gets the set of devices from '''Solid''' and the set of actions from the subdirectories {{path|./solid/actions}} relative to the application settings path in '''KDE'''. The set of actions pertaining to each device is then obtained by evaluating the Solid Predicate specified in the action against the physical and logical properties of the device; if the predicate holds, the action is included.

== Action predicates ==
The predicate for each action is specified in the entry <TT >X-KDE-Solid-Predicate</TT >. The syntax is of the predicate allows to construct an object of class '''Solid::Predicate''' out of it.

=== Atomic predicates ===
Atomic predicates can be of the form
* <TT ><VAR >DeviceClass</VAR >.<VAR>attribute</VAR > == <VAR >value</VAR ></TT >
* <TT ><VAR >DeviceClass</VAR >.<VAR >attribute</VAR > & <VAR >value</VAR ></TT >
the latter form meaning that the Solid attribute may have a set of values, and the specified value must be a part of that set.

For example, the predicate <TT >OpticalDisc.availableContent & 'Audio'</TT > means that the device medium is an optical disc and that it contains audio tracks and possibly something else, while the hypothetical predicate <TT >OpticalDisc.availableContent == 'Audio'</TT > means that a matching device contains audio tracks and nothing else.

Development/Tutorials/Solid/Device Actions

2010-09-15T20:58:44Z

Yecril71pl: /* Introduction */ Anatomy

Development/Tutorials/Solid/Device Actions

2010-09-15T20:33:26Z

Yecril71pl: Introduction

== Introduction ==
The Device Notifier is a plasmoid that is responsible for handling device events. When new data device is inserted or detected by Solid, it gets added to the Device Notifier menu. Each device has a set of actions the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier offers you to play that CD using Amarok. The default actions are not a part of Plasma; each one is installed by the application that handles the action, and goes away when the application is removed.

You can add your own actions and modify existing ones using the Device Actions system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

Development/Tutorials/Plasma

2010-09-15T20:21:11Z

Yecril71pl: /* Theme development */ Creating a Device Notifier action

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== Plasma Programming with C++ ==

;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Plasma Programming with JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Plasma Programming with Python ==

;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

== Plasma Programming with Ruby ==
;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

== Plasma Programming with Web Technologies (HTML/JS/CSS etc) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration ==

;[[Development/Tutorials/Plasma/Device Notifier|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

== Theme development ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

== Presentation Slides==
http://chani.wordpress.com/2009/04/25/quick-update-for-my-presentation/ Victory Calendar -- also link to websvn plasma playground in the odp file.

User talk:Yecril71pl

2010-09-14T19:49:43Z

Yecril71pl: /* Bug: code cpp-qt n does not work */

== Sidebar ==

[[MediaWiki:Sidebar]] is not fully translated into Polish. The translated messages should land in MediaWiki:''message''/pl. Since only [[Project:Administrators]] can edit those messages, I am placing the text into the talk pages.

* [[MediaWiki:navigation/pl]]
** mainpage|[[MediaWiki:Home/pl]]
** helppage|[[MediaWiki:help/pl]]
** recentchanges-url|[[MediaWiki:recentchanges/pl]]

* [[MediaWiki:Sections/pl]]
** Getting_Started|[[MediaWiki:Getting started/pl]]
** Development|[[MediaWiki:Development/pl]]
** Schedules|[[MediaWiki:Schedules/pl]]
** Policies|[[MediaWiki:Policies/pl]]
** Contribute|[[MediaWiki:Contribute/pl]]
** Projects|[[MediaWiki:Projects/pl]]

--[[User:Yecril71pl|Yecril71pl]] 16:05, 14 September 2010 (UTC)

== Bug: code cpp-qt n does not work ==

<code cpp-zz >a;</code >
<code cpp-qt n>a;</code >

User talk:Yecril71pl

2010-09-14T19:42:26Z

Yecril71pl: /* Bug: code cpp-qt n does not work */ new section

Help:Contents

2010-09-14T19:41:05Z

Yecril71pl: /* Tips */ language codes reference

{{Template:I18n/Language Navigation Bar|Help:Contents}}

Before you start to add or change content, please read the articles about the
* [[Help:Contribute|Contribute to TechBase]]
* [[Help:Wiki Structure|Wiki Structure]]
* [[Help:Wiki Translation|Translation into other Languages]]
* [[KDE_TechBase:Migrate_content|Migrate Content]]
* [[KDE_TechBase:Contributors|List of active contributors]], also contact points

== Wiki Syntax ==
To get started with the MediaWiki syntax, read
* http://en.wikipedia.org/wiki/Help:Editing
* http://meta.wikimedia.org/wiki/Help:Table
* http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax
* http://en.wikipedia.org/wiki/Help:Magic_words

The most important commands are summarized in the [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet Wikipedia Cheatsheet]. Information about how to migrate content [[KDE TechBase:Migrate_content|can be found here]].

== Tips ==
; Syntax highlighting
: Wrap your C++ Qt/KDE code snippets in <TT ><code cpp></TT >, <TT ><code cpp n></TT >, <TT ><code cpp-qt></TT > and <TT ></code></TT > to get syntax highlighting (<TT >cpp</TT > for C++, <TT >cpp-qt</TT > for Qt) and numbered lines (<TT >n</TT >). Replace <TT >cpp</TT > with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages the language used], e.g. <TT >ruby</TT > for Ruby and <TT >python</TT > for Python (soon). Use <TT >ini</TT > for {{path|.desktop}} files, <TT >xml</TT > for XML files. Use plain <TT ><code></TT > for wikitext (for now).

== New Templates ==
To get a list of pages using a template, go to corresponding template page (e.g. [[Template:movepage]]) and click "''What links here''" in the toolbox.

; [[Template:movepage|<nowiki>{{movepage|url}}</nowiki>]]
: Use this template to mark a page as not finished.

; [[Template:Improve|<nowiki>{{improve|explanation}}</nowiki>]]
: Pages which need cleanups or contain empty sections and/or todos are marked with this template. Add an explanation if you want (optional)

; [[Template:tip|<nowiki>{{tip|text}}</nowiki>]]
: Use this template to add a tip for the reader.

; [[Template:note|<nowiki>{{note|text}}</nowiki>]]
: Use this template to add an explanatory note.

; [[Template:warning|<nowiki>{{warning|text}}</nowiki>]]
: Use this template to add a warning.

; [[Template:qt|<nowiki>{{qt|class-name}}</nowiki>]] and [[Template:qt3|<nowiki>{{qt3|class-name}}</nowiki>]]
: Use this template to generate a link to a Qt class, e.g. QWidget. For Qt3 classes use <nowiki>{{qt3|class-name}}</nowiki>

; [[Template:class|<nowiki>{{class|class-name}}</nowiki>]]
: Use this template to generate a link to a KDE class, e.g. KDialog.

; [[Template:path|<nowiki>{{path|path-or-filename}}</nowiki>]]
: Use this template for paths and filenames, this way all of them have a consistent style.

; [[Template:bug|<nowiki>{{bug|123456}}</nowiki>]]
: Use this template to automatically create a link to KDE's bugzilla.

; [[Template:KDE3|<nowiki>{{KDE3}}</nowiki>]]
: Use this template to mark the content of a page as applicable for either KDE 3. Don't tag technology agnostic pages. For KDE4 content, use <nowiki>[[Category:KDE4]]</nowiki>.

; [[Template:TutorialBrowser|<nowiki>{{TutorialBrowser|series|name|pre|next|reading}}</nowiki>]]
: A template for tutorial navigation

; [[Template:Box|<nowiki>{{Box|caption|text|width|float}}</nowiki>]]
: Use this template to create a box with a caption and a text. The width parameter is optional and can be specified absolute (400px) or relative (50%). The last parameter is the float value, which is also optional and defaults to center.

Help:Wiki Translation

2010-09-14T19:11:45Z

Yecril71pl: /* Step 3: Language Navigation Bar */ style

{{Template:I18n/Language Navigation Bar|Help:Wiki_Translation}}
This article describes how to '''translate articles into other languages'''. Please make sure to also read the last section called [[#Important Notes|important notes]].

== Step 1: Language Abbreviations ==

As an example let us assume you want to translate the following page to german:
* [[Development/Tutorials]]
The language abbreviation for german is '''de''', thus, all articles will have the ending " (de)" (with a leading space).

Reference: [http://translatewiki.net/wiki/Special:SupportedLanguages list of language abbreviations].

== Step 2: Create the Article ==

Sometimes a link in the language navigation bar already exists. In that case, simply [http://support.mozilla.com/en/kb/Browsing+basics#clicking_a_link follow the link] you want to translate. Otherwise, create the article manually:
* [[Development/Tutorials (de)]]
'''As initial content simply use the content of the corresponding english page'''. This way, no content is missing, and other readers can help with the translation.

== Step 3: Language Navigation Bar ==

The article must contain the following template line in order to show the language navigation bar:
<CODE>{{Template:I18n/Language Navigation Bar|Development/Tutorials}}</CODE>
This magic line expands to the language navigation bar for the article [[Development/Tutorials]]. Note, that the line does not contain the language abbreviation.

== Step 4: Language Missing? ==

If the language is missing, please search for the right abbreviation (see Step 1). In the example above this abbreviation is " (de)".

Edit [[Template:I18n/Language Navigation Bar]] and add a line for the language you want to translate:
<nowiki>[[{{{1}}}_(de)|Deutsch]]</nowiki>
Replace 'de' by the language abbreviation and adapt the visible name.

== Important Notes ==

As the wiki uses [[Help:Wiki Structure|subpages]] it is likely that translators run into the following issue.

Assume the following pages exist:
1. Development/Tutorials
2. Development/Tutorials/Debugging
Further assume you want to translate (1) to german (postfix ''de'').

The final page will be
3. Development/Tutorials_(de)
The english content of (2) uses relative wiki links like <tt>/Debugging</tt>. Translating ''Debugging'' in (3) might result in
Development/Tutorials_(de)/Debugging # wrong, or
Development/Tutorials_(de)/Debugging_(de) # wrong
'''This is wrong.'''

The rule of thumb is that the language abbreviation always appears at the very end of the article, that is the '''right link''' is supposed to be
Development/Tutorials/Debugging_(de)
So be sure you adapt the links in the article to use absolute paths everywhere (i.e. no leading slash '/' in the wiki links).

== Quality Assurance ==

The system administrators and contributors try to keep a close watch at the content, but with foreign languages this is sometimes getting hard. It would be good, if you '''add yourself to the Watch list''' (just click ''Watch''). That way you will be noticed by mail whenever the article was changed. This will help to keep the wiki clean of e.g. spam, which unfortunately already happened.

Also, consider to '''add yourself to the [[KDE_TechBase:Contributors#Translation_Teams|translation teams]]'''.

Help:Wiki Translation (pl)

2010-09-14T19:10:20Z

Yecril71pl: /* Krok 3.: Pasek nawigacji językowej */ styl

{{Template:I18n/Language Navigation Bar|Help:Wiki Translation}}
== Krok 1.: Skróty nazw języków ==

Przyjmijmy dla przykładu, że chcecie przetłumaczyć następującą stronę na polski:
* [[Development/Tutorials]]
Skrót nazwy języka polskiego to '''pl''', więc przetłumaczone artykuły mają nazwy kończące się na " (pl)" (z odstępem z przodu).

Patrzcie: [http://translatewiki.net/wiki/Special:SupportedLanguages spis nazw języków].

== Krok 2.: Tworzenie artykułu ==

Nieraz potrzebny odnośnik istnieje już na pasku wyboru języka. W tym wypadku po prostu wybierzcie odnośnik do strony tłumaczenia; inaczej utwórzcie tłumaczenie ręcznie:
* [[Development/Tutorials (pl)]]
'''Jako pierwotna zawartość tłumaczenia niech posłuży zawartość strony pierwotnej po angielsku.'''. W ten sposób nie utracicie nic z zawartości. Pamiętajcie, że inni użytkownicy również mogą pomóc w tłumaczeniu.

== Krok 3.: Pasek nawigacji językowej ==

Aby pokazał się pasek nawigacji językowej, artykuł musi zawierać następujące wywołanie wzorca:
<CODE >{{Template:I18n/Language Navigation Bar|Development/Tutorials}}</CODE >
To czarodziejskie zaklęcie rozwija się do paska nawigacji językowej dla artykułu [[Development/Tutorials]]. Uwaga: parametr wzorca nie zawiera skrótu nazwy języka.

{{translating|pl}}

Help:Wiki Translation (pl)

2010-09-14T19:06:48Z

Yecril71pl: /* Krok 2.: Tworzenie artykułu */ Krok 3.

{{Template:I18n/Language Navigation Bar|Help:Wiki Translation}}
== Krok 1.: Skróty nazw języków ==

Przyjmijmy dla przykładu, że chcecie przetłumaczyć następującą stronę na polski:
* [[Development/Tutorials]]
Skrót nazwy języka polskiego to '''pl''', więc przetłumaczone artykuły mają nazwy kończące się na " (pl)" (z odstępem z przodu).

Patrzcie: [http://translatewiki.net/wiki/Special:SupportedLanguages spis nazw języków].

== Krok 2.: Tworzenie artykułu ==

Nieraz potrzebny odnośnik istnieje już na pasku wyboru języka. W tym wypadku po prostu wybierzcie odnośnik do strony tłumaczenia; inaczej utwórzcie tłumaczenie ręcznie:
* [[Development/Tutorials (pl)]]
'''Jako pierwotna zawartość tłumaczenia niech posłuży zawartość strony pierwotnej po angielsku.'''. W ten sposób nie utracicie nic z zawartości. Pamiętajcie, że inni użytkownicy również mogą pomóc w tłumaczeniu.

== Krok 3.: Pasek nawigacji językowej ==

Aby pokazał się pasek nawigacji językowej, artykuł musi zawierać następujące wywołanie wzorca:
* <TT ><nowiki>{{Template:I18n/Language Navigation Bar|Development/Tutorials}}</nowiki></TT >
To czarodziejskie zaklęcie rozwija się do paska nawigacji językowej dla artykułu [[Development/Tutorials]]. Uwaga: parametr wzorca nie zawiera skrótu nazwy języka.

{{translating|pl}}

Help:Wiki Translation

2010-09-14T18:47:47Z

Yecril71pl: /* Step 2: Create the Article */ "click" is mouse-centric

{{Template:I18n/Language Navigation Bar|Help:Wiki_Translation}}
This article describes how to '''translate articles into other languages'''. Please make sure to also read the last section called [[#Important Notes|important notes]].

== Step 1: Language Abbreviations ==

As an example let us assume you want to translate the following page to german:
* [[Development/Tutorials]]
The language abbreviation for german is '''de''', thus, all articles will have the ending " (de)" (with a leading space).

Reference: [http://translatewiki.net/wiki/Special:SupportedLanguages list of language abbreviations].

== Step 2: Create the Article ==

Sometimes a link in the language navigation bar already exists. In that case, simply [http://support.mozilla.com/en/kb/Browsing+basics#clicking_a_link follow the link] you want to translate. Otherwise, create the article manually:
* [[Development/Tutorials (de)]]
'''As initial content simply use the content of the corresponding english page'''. This way, no content is missing, and other readers can help with the translation.

== Step 3: Language Navigation Bar ==

The article must contain the following template line in order to show the language navigation bar:
* <nowiki>{{Template:I18n/Language Navigation Bar|Development/Tutorials}}</nowiki>
This magic line expands to the language navigation bar for the article <tt>Development/Tutorials</tt>. Note, that the line does not contain the language abbreviation.

== Step 4: Language Missing? ==

If the language is missing, please search for the right abbreviation (see Step 1). In the example above this abbreviation is " (de)".

Edit [[Template:I18n/Language Navigation Bar]] and add a line for the language you want to translate:
<nowiki>[[{{{1}}}_(de)|Deutsch]]</nowiki>
Replace 'de' by the language abbreviation and adapt the visible name.

== Important Notes ==

As the wiki uses [[Help:Wiki Structure|subpages]] it is likely that translators run into the following issue.

Assume the following pages exist:
1. Development/Tutorials
2. Development/Tutorials/Debugging
Further assume you want to translate (1) to german (postfix ''de'').

The final page will be
3. Development/Tutorials_(de)
The english content of (2) uses relative wiki links like <tt>/Debugging</tt>. Translating ''Debugging'' in (3) might result in
Development/Tutorials_(de)/Debugging # wrong, or
Development/Tutorials_(de)/Debugging_(de) # wrong
'''This is wrong.'''

The rule of thumb is that the language abbreviation always appears at the very end of the article, that is the '''right link''' is supposed to be
Development/Tutorials/Debugging_(de)
So be sure you adapt the links in the article to use absolute paths everywhere (i.e. no leading slash '/' in the wiki links).

== Quality Assurance ==

The system administrators and contributors try to keep a close watch at the content, but with foreign languages this is sometimes getting hard. It would be good, if you '''add yourself to the Watch list''' (just click ''Watch''). That way you will be noticed by mail whenever the article was changed. This will help to keep the wiki clean of e.g. spam, which unfortunately already happened.

Also, consider to '''add yourself to the [[KDE_TechBase:Contributors#Translation_Teams|translation teams]]'''.

Help:Wiki Translation (pl)

2010-09-14T17:21:13Z

Yecril71pl: /* Krok 1: Skróty nazw języków */ Krok 2.

Help:Wiki Translation

2010-09-14T17:14:09Z

Yecril71pl: /* Step 1: Language Abbreviations */ a better list

{{Template:I18n/Language Navigation Bar|Help:Wiki_Translation}}
This article describes how to '''translate articles into other languages'''. Please make sure to also read the last section called [[#Important Notes|important notes]].

== Step 1: Language Abbreviations ==

As an example let us assume you want to translate the following page to german:
* [[Development/Tutorials]]
The language abbreviation for german is '''de''', thus, all articles will have the ending " (de)" (with a leading space).

Reference: [http://translatewiki.net/wiki/Special:SupportedLanguages list of language abbreviations].

== Step 2: Create the Article ==

Sometimes a link in the language navigation bar already exists. In that case, simply click on the link you want to translate. Otherwise, create the article manually:
* [[Development/Tutorials (de)]]
'''As initial content simply use the content of the corresponding english page'''. This way, no content is missing, and other readers can help with the translation.

== Step 3: Language Navigation Bar ==

The article must contain the following template line in order to show the language navigation bar:
* <nowiki>{{Template:I18n/Language Navigation Bar|Development/Tutorials}}</nowiki>
This magic line expands to the language navigation bar for the article <tt>Development/Tutorials</tt>. Note, that the line does not contain the language abbreviation.

== Step 4: Language Missing? ==

If the language is missing, please search for the right abbreviation (see Step 1). In the example above this abbreviation is " (de)".

Edit [[Template:I18n/Language Navigation Bar]] and add a line for the language you want to translate:
<nowiki>[[{{{1}}}_(de)|Deutsch]]</nowiki>
Replace 'de' by the language abbreviation and adapt the visible name.

== Important Notes ==

As the wiki uses [[Help:Wiki Structure|subpages]] it is likely that translators run into the following issue.

Assume the following pages exist:
1. Development/Tutorials
2. Development/Tutorials/Debugging
Further assume you want to translate (1) to german (postfix ''de'').

The final page will be
3. Development/Tutorials_(de)
The english content of (2) uses relative wiki links like <tt>/Debugging</tt>. Translating ''Debugging'' in (3) might result in
Development/Tutorials_(de)/Debugging # wrong, or
Development/Tutorials_(de)/Debugging_(de) # wrong
'''This is wrong.'''

The rule of thumb is that the language abbreviation always appears at the very end of the article, that is the '''right link''' is supposed to be
Development/Tutorials/Debugging_(de)
So be sure you adapt the links in the article to use absolute paths everywhere (i.e. no leading slash '/' in the wiki links).

== Quality Assurance ==

The system administrators and contributors try to keep a close watch at the content, but with foreign languages this is sometimes getting hard. It would be good, if you '''add yourself to the Watch list''' (just click ''Watch''). That way you will be noticed by mail whenever the article was changed. This will help to keep the wiki clean of e.g. spam, which unfortunately already happened.

Also, consider to '''add yourself to the [[KDE_TechBase:Contributors#Translation_Teams|translation teams]]'''.

Help:Wiki Translation (pl)

2010-09-14T17:11:37Z

Yecril71pl: /* Krok 1: Skróty nazw języków */ spis nazw

{{Template:I18n/Language Navigation Bar|Help:Wiki Translation}}
== Krok 1: Skróty nazw języków ==

Przyjmijmy dla przykładu, że chcecie przetłumaczyć następującą stronę na polski:
* [[Development/Tutorials]]
Skrót nazwy języka polskiego to '''pl''', więc przetłumaczone artykuły mają nazwy kończące się na " (pl)" (z odstępem z przodu).

Patrzcie: [http://translatewiki.net/wiki/Special:SupportedLanguages spis nazw języków].
{{translating|pl}}

Help:Wiki Translation (pl)

2010-09-14T16:45:27Z

Yecril71pl: translation stub

{{Template:I18n/Language Navigation Bar|Help:Wiki Translation}}
== Krok 1: Skróty nazw języków ==

Przyjmijmy dla przykładu, że chcecie przetłumaczyć następującą stronę na polski:
* [[Development/Tutorials]]
Skrót nazwy języka polskiego to '''pl''', więc przetłumaczone artykuły mają nazwy kończące się na " (pl)" (z odstępem z przodu).

Patrzcie: [http://www.opticentre.net/FAQ/Languages/List-of-language-abbreviations/ spis nazw języków].
{{translating|pl}}

Template:Translating/pl

2010-09-14T16:41:30Z

Yecril71pl: plural

Strona w trakcie tłumaczenia. Rzetelne informacje są w oryginale angielskim. Pomóżcie tłumaczyć.

Template:Translating

2010-09-14T16:37:42Z

Yecril71pl: includeonly

<includeonly>
{{translating/{{{1}}}}}</includeonly>

Template:Translating

2010-09-14T16:34:05Z

Yecril71pl: parametrize by language

{{translating/{{{1}}}}}

Template:Translating

2010-09-14T16:31:09Z

Yecril71pl: created

{{translating/en}}

Template:Translating/pl

2010-09-14T16:29:24Z

Yecril71pl: created

Strona w trakcie tłumaczenia. Rzetelne informacje są w oryginale angielskim. Pomóż tłumaczyć.

Template:Translating/en

2010-09-14T16:27:00Z

Yecril71pl: created

Page under translation. Please use the English version for reference. Please help.

MediaWiki talk:Projects/pl

2010-09-14T16:09:26Z

Yecril71pl: Projekty

== Projekty ==

--[[User:Yecril71pl|Yecril71pl]] 16:09, 14 September 2010 (UTC)

MediaWiki talk:Contribute/pl

2010-09-14T16:08:46Z

Yecril71pl: Dołącz

== Dołącz ==

--[[User:Yecril71pl|Yecril71pl]] 16:08, 14 September 2010 (UTC)

MediaWiki talk:Policies/pl

2010-09-14T16:07:52Z

Yecril71pl: Zasady

== Zasady ==

--[[User:Yecril71pl|Yecril71pl]] 16:07, 14 September 2010 (UTC)

MediaWiki talk:Schedules/pl

2010-09-14T16:07:20Z

Yecril71pl: Rozkłady

== Rozkłady ==

--[[User:Yecril71pl|Yecril71pl]] 16:07, 14 September 2010 (UTC)

User talk:Yecril71pl

2010-09-14T16:05:28Z

Yecril71pl: Sidebar

KDE TechBase:Administrators

2010-09-14T16:00:33Z

Yecril71pl: +fragment id

#REDIRECT [[KDE TechBase:Contributors#Administrators]]

MediaWiki talk:Development/pl

2010-09-14T15:50:22Z

Yecril71pl: Rozwój

== Rozwój ==

--[[User:Yecril71pl|Yecril71pl]] 15:50, 14 September 2010 (UTC)

MediaWiki talk:Getting started/pl

2010-09-14T15:49:28Z

Yecril71pl: Jak zacząć

== Jak zacząć ==

--[[User:Yecril71pl|Yecril71pl]] 15:49, 14 September 2010 (UTC)

MediaWiki talk:Sections/pl

2010-09-14T15:48:23Z

Yecril71pl: Działy

== Działy ==

--[[User:Yecril71pl|Yecril71pl]] 15:48, 14 September 2010 (UTC)

MediaWiki talk:Home/pl

2010-09-14T15:47:26Z

Yecril71pl: Strona główna

== Strona główna ==

--[[User:Yecril71pl|Yecril71pl]] 15:47, 14 September 2010 (UTC)

MediaWiki talk:Sitenotice

2010-09-14T15:42:18Z

Yecril71pl: Interlink please

== Interlink please ==

I would say that TechBase is a [http://www.mediawiki.org/ Wiki].
--[[User:Yecril71pl|Yecril71pl]] 15:42, 14 September 2010 (UTC)

User talk:Danimo

2010-09-14T15:03:17Z

Yecril71pl: /* Wiki software revealed */ new section

==CAPTCHAs that won't go away==
Aseigo [[Talk:Main_Page#Something_wrong_with_the_CAPTCHAs|suggested]] that I ask you about this. Everytime I make an edit, it claims that I am adding a URL, and wants me to do some math. Is it even supposed to do this to registered users? In any case, ''most'' times I am not adding a url at all, and I tire of the systems inordinate appetite for elementary arithmetic. Can this be fixed? Thanks. --[[User:Axiom|Axiom]] 20:27, 28 March 2007 (CEST)

== <nowiki>{{file}}</nowiki> ==

As you asked me, I removed all the occurrences of <nowiki>{{file}}</nowiki> with <nowiki>{{path}}</nowiki>, and removed the obsolete template <nowiki>{{file}}</nowiki>. -- [[user:Pino|pino]] 02:16, 29 May 2007 (CEST)

:There is also a template called <nowiki>{{module}}</nowiki> for KDE modules (kdelibs, kdebase), etc. I initially used path here, too, and thought that's enough. It's not widely used, only by 2 articles. Maybe we should replace it by path again? What do you think? --[[User:Dhaumann|Dhaumann]] 09:14, 29 May 2007 (CEST)

::I agree. --[[User:Danimo|Danimo]] 09:28, 29 May 2007 (CEST)

::Or maybe link it to the module page in the apidocs (e.g [http://api.kde.org/4.0-api/kdelibs-apidocs/ kdelibs])? --[[User:Milliams|milliams]] 14:47, 29 May 2007 (CEST)

:::Good idea, <nowiki>{{kdelibs}}, {{kdebase}}</nowiki> etc... +1 from my side :) --[[User:Dhaumann|Dhaumann]] 15:11, 29 May 2007 (CEST)

::::Sounds good. Or how about <nowiki>{{module|foo}}</nowiki> linking to http://api.kde.org/4.0-api/foo-apidocs/? I don't know how flexible this method is though? --[[User:Milliams|milliams]] 19:41, 29 May 2007 (CEST)

:::::+1 on [[User:Milliams|milliams]]' idea --[[user:Pino|pino]] 21:35, 29 May 2007 (CEST)

==Assistance needed for new contributor to Techbase==
Hi. My name is Thor, I am a new contributor to KDE and I am looking to provide some help with regard to one of the KDE Games, KTuberling (The Potato dude). I am a Polyglot, and work in many different languages, and I have noticed on issues of KTuberling that even with correct software in place, certain speech selections do not function (Notably; Serbian and Danish). I have been working on these for a while and would like to obtain source code for the Tuberling to try and correct the error. Could you tell me please how I find out who is working on what, and what they are doing to it? Thanks and Regards. [[User:ThunderGod|ThunderGod]] 15:40, 30 December 2007 (CET)
:The best place to find assistance with this is by visiting the #kdegames or #kde-edu channels on irc.freenode.org or by sending an joining the KDE Games mailing list at [https://mail.kde.org/mailman/listinfo/kde-games-devel https://mail.kde.org/mailman/listinfo/kde-games-devel]. I believe tsdgeos (Albert Astals Cid) is the best person to speak to. --[[User:Milliams|milliams]] 17:13, 30 December 2007 (CET)

== More readable URLs ==

At the moment all links on this site are in the form [http://techbase.kde.org/index.php?title=Development/Tutorials http://techbase.kde.org/index.php?title=Development/Tutorials]. I think it would make the site much more readable to convert these links into something like [http://techbase.kde.org/Development/Tutorials http://techbase.kde.org/Development/Tutorials]. Now, as you can see, if you click on that link it does indeed work and takes you to the same page (so you've obviously got mod_rewrite working correctly) so the problem is that mediawiki itself isn't formatting it's links to take advantage of this. I think you basically need to do step 2 from [http://www.mediawiki.org/wiki/Manual:Short_URL#Setup_steps here]. --[[User:Milliams|milliams]] 14:53, 18 April 2008 (CEST)
:It seems this is working now. Thanks a lot :) --[[User:Milliams|milliams]] 14:34, 28 April 2008 (CEST)

== Remove my account ==

Please remove my account; i'd like to choose another username. Thank you. [[User:Krf|KRF]]

:Mediawiki has no concept of user account deletion, since that would mess up the history. Just create a new user and add redirects from your current user accounts user page. --[[User:Danimo|Danimo]] 17:55, 20 April 2008 (CEST)

Okay, would be nice if you could make my username uppercase then... Some database tweaking maybe? ;). No need to answer this, you can remove my entry when you've read it. Thank you anyway. [[User:Krf|KRF]]

== Hidden search button text in french localized ktechbase==

When switching ktechbase language to french the button search text is really too small. I have read somewhere that the css file will use fixed width for a while so changing the search button width from 4em to 6em will fix that small issue.

== The problem with images in article ==

When adding the existing image file i can't save the whole article. 

Article: http://techbase.kde.org/Projects/Plasma/Plasmoids_(ru) 

Adding image (ex. kickoff.png), typing the code, saving and got "http://techbase.kde.org/index.php?title=Projects/Plasma/Plasmoids_(ru)&action=submit" and  a blank page. When i reload a page, i've got old text back, without any changes. Using Firefox 3.0. Can save only the text. What can we do about it? Thanks. 

== Where can I post a patch? ==

My article on building the dependencies for KDE-4.x:

http://techbase.kde.org/Getting_Started/Build/KDE4/LFS#QCA-2.0.2_.28crypto_add_on_for_Qt.29

requires a patch for a file that will not build. Is there somewhere on the TechBase site where I can post this? Currently it is linked to my private web site and I would rather not have that.

[[User:JRT|JRT]] 10:56, 13 September 2009 (UTC)

== Wiki software revealed ==

=== Powered by please ===
It would be nice to reveal the software used in the [http://www.mediawiki.org/wiki/Manual:Footer page footer]. [http://techbase.kde.org/skins/common/images/poweredby_mediawiki_88x31.png (with this image)]

[http://www.mediawiki.org/wiki/MediaWiki Powered by MediaWiki]

=== Database configuration bug ===
See e.g. <URL:{{fullurl:złocień}}>:
<BLOCKQUOTE >

<h4 STYLE="COLOR: BLACK" >Database error</h4>
A database query syntax error has occurred.
This may indicate a bug in the software.
The last attempted database query was:
<blockquote><tt>(SQL query hidden)</tt></blockquote>

from within function "<tt>Article::pageData</tt>".
MySQL returned error "<tt>1267: Illegal mix of collations (latin1_bin,IMPLICIT) and (utf8_unicode_ci,COERCIBLE) for operation '=' (localhost)</tt>".

</BLOCKQUOTE >

This should never happen, compare <URL:http://www.mediawiki.org/wiki/Z%C5%82ocie%C5%84>. This problem will prevents Wiki for having non-Western-European page names in translations. The most probable cause is a misconfiguration of the database engine; however, it is also worth noting that the current MediaWiki software is [http://lists.wikimedia.org/pipermail/mediawiki-announce/2010-July/000092.html 1.16] whereas you are using 1.14 (from HTML metadata, otherwise unmentioned), so maybe it would be time to upgrade?

--[[User:Yecril71pl|Yecril71pl]] 15:03, 14 September 2010 (UTC)

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T13:07:29Z

Yecril71pl: /* Adding Lookup Locations */ fix ref

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/cache-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/var/tmp/kdecache-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (<tt >ksycoca</tt > and <tt >ksycocastamp</tt >) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[[#Directory Tree]] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory {{path|share/wallpapers/}} is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the <TT >kdeglobals</TT > configuration file in the <TT >[Directories]</TT > section.
To do so assign one or more directories to the key <TT >dir_</TT > followed by the
name of the resource.
Multiple directories are separated by commas (<TT >,</TT >).

==== Adding a Resource Directory ====

To add the directory {{path|/data/photos}} to the wallpaper resource, put the
following two lines in <TT >kdeglobals</TT >:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:59:40Z

Yecril71pl: /* Sockets */ will not run with nbsp

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/cache-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/var/tmp/kdecache-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (<tt >ksycoca</tt > and <tt >ksycocastamp</tt >) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:58:52Z

Yecril71pl: /* Temporary Files */ will not run with nbsp

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/cache-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/var/tmp/kdecache-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (<tt >ksycoca</tt > and <tt >ksycocastamp</tt >) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:57:52Z

Yecril71pl: /* Cache Files */ Parameter style

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/cache-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/var/tmp/kdecache-<VAR >$USER</VAR >/}}

The command <tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (<tt >ksycoca</tt > and <tt >ksycocastamp</tt >) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:55:41Z

Yecril71pl: /* Temporary Files */ parameter style

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/tmp-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/kde-<VAR >$USER</VAR >/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:54:44Z

Yecril71pl: /* Sockets */ parameter style

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|<VAR >$KDEHOME</VAR >/socket-<VAR >$HOSTNAME</VAR >}}

Default destination: {{path|/tmp/ksocket-<VAR >$USER</VAR >/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|$KDEHOME/tmp-<HOSTNAME>}}

Default destination: {{path|/tmp/kde-<USER>/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:51:54Z

Yecril71pl: /* Directory Tree */ links

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<VAR >$HOSTNAME</VAR >}} || [[#Sockets|socket]] || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<VAR >$HOSTNAME</VAR >}} || [[#Temporary Files|tmp]] || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<VAR >$HOSTNAME</VAR >}} || [[#Cache Files|cache]] || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|$KDEHOME/socket-<HOSTNAME>}}

Default destination: {{path|/tmp/ksocket-<USER>/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|$KDEHOME/tmp-<HOSTNAME>}}

Default destination: {{path|/tmp/kde-<USER>/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:45:15Z

Yecril71pl: /* Directory Tree */ variants

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib<var >64</var >/}} || lib || Used for KDE libraries.
|-
| {{path|lib<var >64</var >/kde3<var ></var >/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<HOSTNAME>}} || socket || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<HOSTNAME>}} || tmp || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<HOSTNAME>}} || cache || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|$KDEHOME/socket-<HOSTNAME>}}

Default destination: {{path|/tmp/ksocket-<USER>/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|$KDEHOME/tmp-<HOSTNAME>}}

Default destination: {{path|/tmp/kde-<USER>/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:34:14Z

Yecril71pl: /* KDEROOTHOME */ <var >4</var >

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde<var >4</var > is appended. Usually that results in <tt>/root/.kde<var >4</var ></tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib/}} || lib || Used for KDE libraries.
|-
| {{path|lib/kde3/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<HOSTNAME>}} || socket || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<HOSTNAME>}} || tmp || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<HOSTNAME>}} || cache || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|$KDEHOME/socket-<HOSTNAME>}}

Default destination: {{path|/tmp/ksocket-<USER>/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|$KDEHOME/tmp-<HOSTNAME>}}

Default destination: {{path|/tmp/kde-<USER>/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

KDE System Administration/KDE Filesystem Hierarchy

2010-09-14T12:32:22Z

Yecril71pl: /* KDEHOME */ kde<var >4</var >

{{Template:I18n/Language Navigation Bar|KDE_System_Administration/KDE_Filesystem_Hierarchy}}

== Introduction ==
KDE defines a filesystem hierarchy that is used by the KDE environment
itself as well as all KDE applications. In general, KDE stores all its
files in a fixed directory tree.

By default, there are two such directory trees: one at the system
level and one at the user level in the user's home directory. However,
as a system administrator you can create additional trees.

KDE and KDE applications look up files by scanning the directory trees
in order of precedence. When a file is
present in multiple directory trees, the file from the first-listed
tree takes precedence.
Normally, the tree located in the user's home directory has the highest
precedence. This is also the directory tree that changes are
written to.

For configuration files, the story is slightly
different. If multiple configuration files with the same name are found in the directory
trees, their content is combined. The precedence order
of the directory trees plays a role here: when two files define the same
configuration key, the file with the highest precedence determines which
value is used for the key.

== Location of the Directory Trees ==

The location of the KDE Directory Trees is determined by a number of
environment variables, each of which is covered below.

=== KDEHOME ===
The <tt>KDEHOME</tt> environment variable determines the location of the user-level
directory tree and is used by KDE applications for creating and saving
files. This directory tree has the highest precedence; files or settings
found in this directory tree will take precedence over any files or settings
found in other directory trees.

This directory tree is, as the name suggests, normally located in the user's home directory. If this environment variable is not defined, the default location <tt>$HOME/.kde<var >4</var ></tt> is used.

If the environment variable has a value that starts with a tilde (~), the tilde is replaced with the user's home directory at runtime. In order to use this, care must be taken to add proper quoting, otherwise the shell might do the expansion, resulting in undesired behavior in combination with <tt>su</tt>.

=== KDEROOTHOME ===
In order to prevent problems with applications that run as root saving
files with root access permissions in the user's home directory, the <tt>KDEROOTHOME</tt>
environment variable has been introduced in the KDE 3.x series. Applications
that run with uid 0 (root) will use this variable to determine the location of
the user level directory and where to save their files. If this variable is
not defined, the root user's home directory is looked up in the password
file and .kde is appended. Usually that results in <tt>/root/.kde</tt> .

=== KDEDIRS ===
It is possible to specify multiple system-level directory trees. This allows groups of users to each dedicate a directory to their group. Such an additional directory tree can contain additional applications, specialized application resources or a specific set of default configurations suitable for the group. Specifying default configurations this way instead of using a /etc/skel construction has the advantage that changes in the default configuration can be made after the user's account has been created.

The directories in $KDEDIRS should be separated with a colon (:). The directories are listed in order of precedence: the first directory has the highest precedence, the last one has the lowest precedence.

Since a group-level directory tree should normally override any settings present at the system level, one should list the group-level directory tree before the system level directory tree.

In general communication, references to the directory trees are made in
terms of $KDEHOME to indicate the applicable user-level directory tree,
and in terms of $KDEDIRS to indicate any of the system-level directory trees.

==== Example ====

A staff member at a university could have the following settings:

<code>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

In this example the user settings are saved under the .kde3 directory
in the user's home directory. Applications that run as root will save their
settings to /root/.kde3. KDE 3 has been installed to /opt/kde3 but there is
also an additional directory tree located at /opt/kde_staff. Configuration
files under that directory will take precedence over the ones in the /opt/kde3
system directories. /opt/kde_staff could contain additional applications that
should only be available to staff members.

== Directory Tree ==

Each directory tree used by KDE has a fixed directory structure. However, directories
that are not relevant for a certain tree can be left out. For example,
directories used for temporary files are usually only found under $KDEHOME but
not in any other directory tree.

The KDE runtime environment combines the subdirectories found under the
various directory trees and refers to them as a single KDE resource. The
KDE resource name is listed in the tables below.

There are three broad categories: files that are
CPU/architecture-specific, files that are host-specific and files that are not specific with
regard to host, CPU or architecture.

CPU/architecture-specific directories:

{|
|-
! Directory !! KDE resource !! Description
|-
| {{path|bin/}} || exe || Used for KDE executables.
|-
| {{path|cgi-bin/}} || cgi || CGI scipts that can be used by the KDE Help Center.
|-
| {{path|lib/}} || lib || Used for KDE libraries.
|-
| {{path|lib/kde3/}} || module || This directory contains components, plugins and other runtime loadable objects for use by KDE 3.x applications.
|}

The following are host-specific directories. They are only available under
$KDEHOME and are normally symlinked to locations outside the $KDEHOME
directory tree.

{|
! Directory !! KDE resource !! Description
|-
| {{path|socket-<HOSTNAME>}} || socket || This directory contains communication sockets. The filesystem used by $KDEHOME may not be suitable for communication sockets. For that reason this directory is symlinked to another location by default.
|-
| {{path|tmp-<HOSTNAME>}} || tmp || This directory is used for temporary files. The filesystem used by $KDEHOME may be on a network, so, for performance reasons, this directory is symlinked by default to a location more likely to be on a local filesystem.
|-
| {{path|cache-<HOSTNAME>}} || cache || New in KDE 3.2. This directory is used for cached information such as HTTP objects, formatted help pages and the system configuration cache (ksycoca).

Since this is non-essential information, this directory is
symlinked to a location outside $KDEHOME by default to make it easier
to make backups of other information and reclaim diskspace.
|}

The majority of directories involves data that is not CPU-, architecture- or
host-specific. All these directories are prefixed with {{path|share/}}:

{|
! Directory !! KDE resource !! Description
|-
| {{path|share/applnk/}} || apps || Contains .desktop files describing the KDE menu.
|-
| {{path|share/apps/}} || data || Contains application-specific data files. Each application has a subdirectory here for storing its files.
|-
| {{path|share/config/}} || config || Contains configuration files. Configuration files are normally named after the application they belong to, followed by "rc". There are also files that are specific to a component and as such referenced by all applications that use that component. A special case is "kdeglobals": this file is read by all KDE applications.
|-
| {{path|share/config/session/}} || - || This directory is used by session management and is normally only available under $KDEHOME. At the end of a session, KDE applications store their state here. The file names start with the name of the application followed by a number. The session manager "ksmserver" stores references to these numbers when saving a session in "ksmserverrc".
|-
| {{path|share/doc/HTML/}} || html || Documentation of KDE applications is stored here. Documentation is categorized by language and the application it belongs to.

Normally, at least two files can be found in a directory: "index.docbook", which contains the documentation in the unformatted docbook format, and "index.cache.bz2", which contains the same documentation formatted as bzip2 compressed HTML. The HTML version is used by khelpcenter; if the HTML version is missing, it will regenerate it from the docbook version, but this is a time-consuming process.
|-
| {{path|share/icons/}} || icon || Icons are stored under this directory, categorized by theme, dimension and usage category.
|-
| {{path|share/mimelnk/}} || mime || Up until KDE4, .desktop files that describe MIME types were stored in this directory.
|-
| {{path|share/mime/}} || mime || Starting with KDE4, desktop files that describe MIME types are stored in this directory. This data is shared by other software as well and is part of a freedesktop.org specification.
|-
| {{path|share/services/}} {{path|share/kde4/services/}} || services || This directory contains .desktop files that describe services. Services and Applications are very similar; the major difference is that a Service is usually used by other Services or Applications, while an Application is in general started by the user. Services do not appear in the KDE menu.
|-
| {{path|share/servicetypes/}} {{path|share/kde4/servicetypes/}} || servicetypes || This directory contains .desktop files that describe service types. A service type usually represents a certain programming interface. Applications and Services include the servicetypes that they provide in their .desktop files.
|-
| {{path|share/sounds/}} || sound || This directory contains sound files.
|-
| {{path|share/templates/}} || templates || This directory contains templates for creating files of various types. A template consists of a .desktop file that describes the file and includes a reference to a file in the .source subdirectory. The templates in this directory appear in the "Create New" menu available on the desktop and in the file browser. When a user selects a template from the menu, its source file is copied.
|-
| {{path|share/wallpapers/}} || wallpaper || This directory contains images that can be used as background pictures.
|}

== Outside the Directory Tree ==

As mentioned in the description of the directory tree, there are three host-specific directories that are usually symlinked to other locations. If the directories do not already exist, the following symlinks and directories will be created using the <tt>lnusertemp</tt> utility. Since both <tt>/tmp</tt> and <tt>/var/tmp</tt> are world writable, there is a possibility that one of the mentioned directories already exists but is owned by another user. In that case, the <tt>lnusertemp</tt> utility will create a new directory with an alternative name and link to that instead.

=== Sockets ===
Symlink: {{path|$KDEHOME/socket-<HOSTNAME>}}

Default destination: {{path|/tmp/ksocket-<USER>/}}

<tt>lnusertemp socket</tt> creates a directory for local communication sockets and point a symlink to it. The combined length of the directory name and the name of any communication socket should not exceed 106 characters. By default this directory is created under <tt>/tmp</tt>, but other locations can be used by setting the KDETMP environment variable.

=== Temporary Files ===
Symlink: {{path|$KDEHOME/tmp-<HOSTNAME>}}

Default destination: {{path|/tmp/kde-<USER>/}}

<tt>lnusertemp tmp</tt> creates a directory for temporary files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

=== Cache Files ===
Symlink: {{path|$KDEHOME/cache-<HOSTNAME>}}

Default destination: {{path|/var/tmp/kdecache-<USER>/}}

<tt>lnusertemp cache</tt> creates a directory for cache files and points a symlink to it. For performance reasons it is recommended to have this directory on a local filesystem, but this is not strictly necessary.

The system configuration cache (ksycoca and ksycocastamp) is located in here. It is recommended NOT to delete these files during boot since that will slow down the startup of KDE.

By default this directory is created under <tt>/var/tmp</tt>, other locations
can be used by setting the KDEVARTMP environment variable.

== Adding Lookup Locations ==

KDE applications look up data files using the resource names listed in the
[#dir_structure Directory Tree] section. The KDE runtime
environment translates these names to actual directories
by combining the locations of the directory trees with the directories
listed in the tables.

==== Defining Search Paths ====

A user has the following directory tree settings:

<code>
KDEHOME='~/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</code>

When an application now looks for a "wallpaper" file, the directory "share/wallpapers/" is added to each of the
directory trees. All of the
resulting directories are then searched for the file:

<code>
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

By adding more directory tree to the KDEDIRS environment variable
it is possible to expand the number of directories that are being searched.
Sometimes it is desirable to include only a single directory in a search
but not a whole directory tree. Additional directories can be configured
in the kdeglobals configuration file in the "Directories" section.
To do so assign one or more directories to the key "dir_" followed by the
name of the resource. Multiple directories are separated by commas (,).

==== Adding a Resource Directory ====

To add the directory /data/photos to the wallpaper resource, put the
following two lines in kdeglobals:

<code ini>
[Directories]
dir_wallpaper=/data/photos
</code>

When the application now looks for wallpaper files, it will look in the
following locations:

<code>
/data/photos
~/.kde3/share/wallpapers/
/opt/kde_staff/share/wallpapers/
/opt/kde3/share/wallpapers/
</code>

File:Shell Scripting with KDE Dialogs passivepopup dlg.png

2010-09-13T19:01:05Z

Yecril71pl: Window screen shot of the passive popup kdialog example [1]. Created with GIMP ___ [1] <URL:http://techbase.kde.org/Development/Tutorials/Shell_Scripting_with_KDE_Dialogs#Example_11._--passivepopup_dialog_box>

Window screen shot of the passive popup kdialog example [1].
Created with GIMP
___
[1] <URL:http://techbase.kde.org/Development/Tutorials/Shell_Scripting_with_KDE_Dialogs#Example_11._--passivepopup_dialog_box>

Development/Tutorials/Debugging/How to create useful crash reports

2010-09-12T21:37:45Z

Yecril71pl: /* Preparing your KDE packages */ openSUSE migrated

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Debugging/How to create useful crash reports}}
==Introduction==

This document describes how to reproduce a useful backtrace of crashing KDE applications. First, some general information is given. Then, we will describe for several distributions how to prepare your KDE packages and gaining the backtrace. This should be enough for most people.
There are additional sections on how to create backtraces with the GNU Debugger and with Valgrind, which are in some cases useful.

==How to create useful crash reports==

A good crash report at [http://bugs.kde.org Bugzilla] consists of two parts: a '''description''' of how to reproduce the crash and a '''backtrace''' of the crash. With one of those elements missing, it is much harder (if not impossible) for developers to tackle the problem.

A description should consist of more than only "it crashed". Try to describe everything you did prior to the crash. Did you click on a button, opened a particular website or file which caused problems? That little detail which may look useless to you may be useful for the developer, so just write it down.

A more insightful article on how to write good bug descriptions is available [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html at this link], please read that before reporting bugs.

Don't attach the backtrace to the bug report. Instead, simply paste it. This way it is much easier for developers to search for duplicate reports, because attachments will not be searched.

If you paste a backtrace to a report, make sure you strip all but one or two of the
(no debugging symbols found)
lines from the backtrace as they make it harder to read.

Even though pasting backtraces directly is preferred over adding an attachment, please do not paste other things like logs (valgrind, strace or terminal output) or example data (mails, HTML files and so on). Use attachments for these items.

===Backtraces===

Backtraces are essential. They may look meaningless to you, but they might actually contain a wealth of useful information. A backtrace describes which functions were called prior to the crash, so that developers may track down in which function the mess started. Having good backtraces has a downside: [[Development/Tutorials/Debugging/Debugging_symbols|libraries and executables occupy much more disk space than their optimized counter parts]]. That's the reason why many distros choose to install stripped files, '''which results in useless backtraces''':

(no debugging symbols found)
Using host libthread_db library "/lib/tls/i686/cmov/libthread_db.so.1".
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
[Thread debugging using libthread_db enabled]
[New Thread -1233848624 (LWP 12212)]
[New Thread -1255081072 (LWP 12820)]
[New Thread -1240921200 (LWP 12819)]
[New Thread -1266680944 (LWP 12818)]
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
0xffffe410 in __kernel_vsyscall ()
#0 0xffffe410 in __kernel_vsyscall ()
#1 0xb6a1210b in ?? () from /lib/tls/i686/cmov/libpthread.so.0
#2 0xb6a85afe in ?? () from /usr/lib/libX11.so.6
#3 0x00000003 in ?? ()
#4 0x082149c0 in ?? ()
#5 0x00003ffc in ?? ()
#6 0x00000000 in ?? ()

But no worries, with some modifications you can create full blown backtraces for KDE applications.

===Preparing your KDE packages===

If your distribution has debugging-enabled packages, install them.

It is easy to see which debug packages you are missing from looking at the backtrace. For example, take the following line from a backtrace:

#6 0xb7975bdc in ?? () from /usr/lib/libkmailprivate.so.4

The <tt>??</tt> indicates that the library <tt>libkmailprivate.so.4</tt> does not have debug information, which might be available in separate debug packages. In this case, it is pretty easy to guess that you need to install debug packages for KMail to get a better backtrace.

Sometimes, you need to install more than one debug package to get a good backtrace. This depends on how the distribution splits up the packages. For example, for some distributions it is enough to install the debug package for <tt>kdepim</tt> to get enough debugging information for a crash in KMail, for other distributions there is an additional debug package just for KMail.

Here's a list of how to obtain debug packages for some distributions:

*'''Debian''' - Debian offers <tt>-dbg</tt> packages to easy create useful backtraces. Just install the corresponding <tt>-dbg</tt> package. e.g. <tt>kdepim-dbg</tt> for KMail crashes. The dependencies of -dbg makes sure to pull in the other right packages (kdelibs-dbg, gdb, and so on).
*'''FreeBSD ports''' - Please refer to the [http://freebsd.kde.org/faq.php#AKDEapplicationcrashedandIwanttofileabugreportathttpbugskdeorgbutthebacktraceintheKDECrashManagerisuselessWhatcanIdo KDE on FreeBSD FAQ].
*'''Gentoo''' - Gentoo has its [http://www.gentoo.org/proj/en/qa/backtraces.xml own document] describing how to proceed.
*'''Mandriva''' - Mandriva 2007.0 and up has additional debugging packages for all of KDE (in fact, for all of its packages). Just install the corresponding <tt>-debug</tt> package, like <tt>kdebase-debug</tt> and <tt>kdemultimedia-debug</tt>. You probably want to install <tt>kdelibs-debug</tt> anyways.
** Note: the <tt>-debug</tt> packages are in separate repositories. For instance, for all packages in <tt>main</tt>, you'll find the debugging package in repository <tt>debug_main</tt>.
*'''Kubuntu/Ubuntu''' - The Ubuntu family makes things quite easy. Every official KDE module has an additional package in the repository, suffixed with <tt>-dbg</tt>. Always install <tt>kdelibs5-dbg</tt>, because all KDE applications use kdelibs (kdelibs-dbg for KDE 3 applications). Then you should install a -dbg package for the application which crashed. For example if KOrganizer crashed you should install <tt>kdepim-dbg</tt> as well. If the program is not from an official KDE module and has no -dbg package, you can install the -dbgsym package from the repository listed on this [https://wiki.kubuntu.org/DebuggingProgramCrash Debugging Program Crashes] page.
**During the Ubuntu development cycle the Apport crash handler is turned on which will report crashes to launchpad.net and do the backtrace for you, if you would rather use the KDE crash handler turn Apport off in /etc/defaults/apport
**Starting with Lucid Lynx (10.04) Kubuntu will be forwarding all non kubuntu specific bugs upstream and had disabled Apport so that DrKonqui will be th edefault crash handler.
*'''openSUSE''' - You should only install the <tt>-debuginfo</tt> packages, for example: <tt>kdepimlibs4-debuginfo</tt>. You can find these packages in [http://en.opensuse.org/KDE/Repositories KDE repositories]. There is also a dedicated [http://en.opensuse.org/openSUSE:Bugreport_application_crashed openSUSE debugging page].
*'''Fedora''' - In Fedora you just need to do:
*# <tt>yum provides "/usr/lib/libkmailprivate.so.4"</tt> to find out which package provides that file;
*# <tt>debuginfo-install kdepim</tt> as root to install debug packages for that package (dependencies included).
*:A complete and detailed guide for Fedora is available in [http://fedoraproject.org/wiki/StackTraces this document] describing how to proceed. Fedora uses a separate debuginfo repository that has to be enabled. Also consider <tt>auto-update-debug-info</tt> yum plugin to keep debuginfo packages up to date.

If your distribution doesn't have debugging-enabled packages for KDE, you'll have to compile KDE from sources:

* If you're using KDE 3, then at the configure stage, you should supply the parameter <tt>--enable-debug=full</tt> in order to build debug symbols in the resulting files.
* If you're using KDE 4, then at the cmake stage, you should supply the parameter <tt>-DCMAKE_BUILD_TYPE=debugfull</tt>. If you want to specify your own CXXFLAGS, then use <tt>-DCMAKE_BUILD_TYPE=None CMAKE_CXX_FLAGS="-O0 -g"</tt>. You can change the CMAKE_CXX_FLAGS as appropriate for your needs.

Then it's just <tt>make</tt> and <tt>make install</tt> as you're used to.

===Crash!===

Now it's time to crash your application. The KDE Crash Dialog should appear right after the crash, which shows the Backtrace tab.

[[Image:Kde-crash-handler.png|center|300px|KDE Crash Dialog]]

Click that tab and wait for a minute. This process may take quite some memory, so things may go sluggish all of a sudden. But the result should look much better. For example:

Using host libthread_db library "/lib/libthread_db.so.1".
[Thread debugging using libthread_db enabled]
[New Thread -1232783168 (LWP 7604)]
[KCrash handler]
#6 0x0806be76 in TreeMapItem::parent (this=0x0)
at /home/bram/KDE/kde3/kdeaddons/konq-plugins/fsview/treemap.h:285
#7 0x08065fea in TreeMapItemList::compareItems (this=0xbfec04a8, item1=0x0,
item2=0x0)
at /home/bram/KDE/kde3/kdeaddons/konq-plugins/fsview/treemap.cpp:720
#8 0xb7281619 in QGList::operator== () from /usr/qt/3/lib/libqt-mt.so.3
#9 0x0806d498 in QPtrList<TreeMapItem>::operator== (this=0xbfec04a8,
list=@0xbfec0468) at /usr/qt/3/include/qptrlist.h:74
#10 0x08062e18 in TreeMapWidget::mousePressEvent (this=0xbfec03ac,
e=0xbfebff1c)
at /home/bram/KDE/kde3/kdeaddons/konq-plugins/fsview/treemap.cpp:1840
#11 0xb7004a63 in QWidget::event () from /usr/qt/3/lib/libqt-mt.so.3
#12 0xb6f6bca7 in QApplication::internalNotify ()
from /usr/qt/3/lib/libqt-mt.so.3
#13 0xb6f6ca88 in QApplication::notify () from /usr/qt/3/lib/libqt-mt.so.3
#14 0xb7725a84 in KApplication::notify (this=0xbfec055c, receiver=0xbfec03ac,
event=0xbfebff1c)
at /home/bram/KDE/kde3/kdelibs/kdecore/kapplication.cpp:550
#15 0xb6f0bfd2 in QETWidget::translateMouseEvent ()
from /usr/qt/3/lib/libqt-mt.so.3
#16 0xb6f0b8b0 in QApplication::x11ProcessEvent ()
from /usr/qt/3/lib/libqt-mt.so.3
#17 0xb6f1b761 in QEventLoop::processEvents () from /usr/qt/3/lib/libqt-mt.so.3
#18 0xb6f82831 in QEventLoop::enterLoop () from /usr/qt/3/lib/libqt-mt.so.3
#19 0xb6f826b6 in QEventLoop::exec () from /usr/qt/3/lib/libqt-mt.so.3
#20 0xb6f6b72f in QApplication::exec () from /usr/qt/3/lib/libqt-mt.so.3
#21 0x0805181e in main (argc=134673960, argv=0xffffffff)
at /home/bram/KDE/kde3/kdeaddons/konq-plugins/fsview/main.cpp:55

This looks better, right? It shows memory addresses, the source files and line numbers and the parameters passed to functions. Which make it more helpful to the developer where to look for the problem.

{{note|You '''need''' GDB installed to get the backtrace of a crash. Please read the next section to know what GDB is, and how to install it.}}

===Retrieving a backtrace with GDB===

In some cases, it is not possible to create a backtrace with the KDE Crash Dialog. This may be caused by an application which entered an infinite loop, or the crash dialog did not appear at all for some reason. You can try to grab a backtrace with <tt>gdb</tt>, the [http://sourceware.org/gdb/ GNU Debugger]. GDB is widely available through distribution packages.

Invoking GDB differs from the situation. You can run an application from inside gdb, or attach gdb to an already running process. The latter may be useful when an application already has entered an infinite loop. But we will first start with running an application inside gdb. From the shell, run:

$ gdb someKDEapp

The GDB prompt will appear. Note that this does not start the application itself, you should run it by invoking the <tt>run</tt> command:

(gdb) run

This will run the application like you are used to, and you can work with it like normal (it only consumes far more memory and may feel sluggish). Now it's time to reproduce your crash. When you succeed, the application just closes and you should return to your GDB prompt. Now it's time to run the 'backtrace' command:

{{note|Some KDE applications (such as JuK and KTorrent) have special code to ensure that there is only one running instance of the application at a time. For these applications you should type in "run --nofork" at the (gdb) prompt instead of "run" because otherwise gdb will try to debug the wrong process. If you are unsure as to whether to use --nofork just try it. If the application says it's an unknown option you can remove --nofork.}}

(gdb) thread apply all backtrace

This should give a good backtrace which can be posted at the KDE Bugzilla.

In case you want to attach to an existing process, run the following command in the shell:

$ gdb someKDEapp pid

where ''pid'' is the process ID of the process you want to attach to. Once attached, and the process is in an infinite loop, after using the 'backtrace' command again a useful backtrace will appear. You can use 'continue' command to let the application run again and press Ctrl+C in gdb to be able to again enter commands.

===Retrieving a backtrace with Valgrind===

When it comes to crashes, [http://www.valgrind.org Valgrind] is also a useful tool to create a backtrace. It's not a substitution for GDB, but rather a supplement.

When you run an application in valgrind, every piece of memory read or written by the application is being checked. Valgrind will report erroneous memory operations in the standard output or in a log file. Since most crashes are due to an invalid memory read, valgrind can be useful to track down where the problem occurs.

{{note|Valgrind consists of several tools in order to check or profile an application. For this article, we only use memcheck, the default tool when valgrind is being invoked.}}

Like GDB, Valgrind makes running an application much slower, while consuming a lot more resources.

Start the application within valgrind:

$ valgrind --log-file=someKDEapp someKDEapp

Now reproduce the crash. As soon as this happens, the application and valgrind will terminate. What's left is a file named <tt>someKDEapp.pid</tt> where ''pid'' is replaced by the process ID of the valgrind process. The file may list more errors than the one causing the crash. Here's the bit causing the crash which corresponds to the GDB backtrace above:

==23292== Invalid read of size 4
==23292== at 0x806BD9E: TreeMapItem::parent() const (treemap.h:285)
==23292== by 0x8065FB9: TreeMapItemList::compareItems(void*, void*) (treemap.cpp:720)
==23292== by 0x50AC618: QGList::operator==(QGList const&) const (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x806D3BF: QPtrList<TreeMapItem>::operator==(QPtrList<TreeMapItem> const&) const (qptrlist.h:74)
==23292== by 0x8062DE7: TreeMapWidget::mousePressEvent(QMouseEvent*) (treemap.cpp:1840)
==23292== by 0x4E2FA62: QWidget::event(QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x4D96CA6: QApplication::internalNotify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x4D97A87: QApplication::notify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x4809AC3: KApplication::notify(QObject*, QEvent*) (kapplication.cpp:550)
==23292== by 0x4D36FD1: QETWidget::translateMouseEvent(_XEvent const*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x4D368AF: QApplication::x11ProcessEvent(_XEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== by 0x4D46760: QEventLoop::processEvents(unsigned) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==23292== Address 0x2C is not stack'd, malloc'd or (recently) free'd

But to be sure, just attach the whole log file to the crash report.

Development/

2010-09-11T18:53:43Z

Yecril71pl: recreated b/c ref at <URL:http://www.kde.org/developerplatform/>

#REDIRECT [[Development]]

Development/Architecture/KDE3/KHTML

2010-05-29T12:55:44Z

Yecril71pl: technology hyperlinks

== KHTML - KDE's HTML library ==

<tt>KHTML</tt> is an [http://www.w3.org/TR/REC-xml/ XML]/[http://www.w3.org/TR/html401/ HTML4] compliant HTML library, with support for [http://www.w3.org/TR/REC-DOM-Level-1/ DOM],
[http://java.sun.com/docs/books/tutorial/deployment/applet/index.html Java], [http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-262.pdf JavaScript] and Cascading Style Sheets ([http://www.w3.org/TR/CSS2/ CSS]).

You can get an overview of <tt>KHTML</tt>'s current capabilities [http://www.konqueror.org/konq-browser.html here.]

== Small example ==

Using <tt>KHTML</tt> in your program is quite easy. The following example shows
you a complete application with which you can already browse the web:

<code cppqt>
#include <khtml.h>
#include <kapp.h>

int main(int argc, char *argv[])
{
KApplication a(argc, argv, "testkhtml");

KHTMLWidget *html = new KHTMLWidget;
html->resize(800,500);
//html->setJScriptEnabled(true);
html->setJavaEnabled(true);
//html->setFollowsLinks(false);

a.setTopWidget(html);
html->setURLCursor(QCursor(PointingHandCursor));
html->openURL(argv[1]);

QWidget::connect(html, SIGNAL(setTitle(const QString &)),
html, SLOT(setCaption(const QString &)));
html->show();
a.exec();
}
</code>

This small example already gives you a functional browser, that lets you browse
the web (you'll need the <tt>kio_http</tt> executable from KDE though to access
non local files). Just try <tt>testkhtml http://www.kde.org</tt> and you will
get a widget showing KDE's home page.

<tt>KHTML</tt> has a lot of functionality. Almost everything you'll ever need
can be accessed through the member functions of the class KHTMLWidget.

== Document Object Model (DOM) ==

<tt>KHTML</tt> provides a mostly complete implementation of
[http://www.w3.org/DOM/ Dom Level 1 and 2].

The DOM is an implementation using internal classes to hold the document's data.
The classes accessing the DOM are using a refcounting scheme to hold the data.
Thus the DOM does the memory management for you. You can just use the classes
defined in the DOM header files to access parts of the document. As long as you
don't use pointers, you will not get memory leaks.

You can easily access the document being shown by the
<tt>KHTMLWidget::document()</tt> method, from where you can
get access to every part of the document.

== Java ==

Thanks to the work of Richard Moore, <tt>KHTML</tt> can display Java applets.
Java is not enabled by default, but you can do so by using
<tt>KHTMLWidget::setEnableJava(true);</tt>, and setting the environment variable
<tt>CLASSPATH</tt> to:

CLASSPATH=$KDEDIR/share/apps/kjava/kjava-classes.zip:$JDK_DIR/lib

You will need to have the java developers kit installed though. I tested it
with JDK-1.1.7, and don't know if it'll run with other versions of JDK or with
Kaffe.

== JavaScript (ECMA-Script) ==

The JavaScript support aims at compliance with the ECMAScript Language
specification [http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM ECMA-262] 3rd edition.
This roughly equals JavaScript 1.5.

== Cascading Style Sheets (CSS) ==

Cascading style sheets 2.1 are mostly supported now.

''Initial Author:'' [mailto:knoll@kde.org Lars Knoll]

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

Development/Tutorials/KIO Slaves/Hello World

2010-05-26T21:58:49Z

Yecril71pl: /* Test it */ command line access

= Understanding =
A kioslave allows you to represent any kind of storage in a way you want. As an example, the kio_http kioslave loads data from the network over the http (protocol) and shows it rendered as html. Technically, a kioslave is a shared object plus its description. E.g. the imap4 kioslave consist of the following files:
tweedleburg:/usr/local # find -iname "*imap4*"
./lib/kde4/kio_imap4.so
./share/kde4/services/imap4.protocol

= The files =
We want to write a "hello world" kioslave here. This can be seen as a learning exercise and as a template for future programming projects.

== CMakeLists.txt ==
<pre>
PROJECT( tutorial )
FIND_PACKAGE(KDE4 REQUIRED)
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

set(kio_hello_PART_SRCS
hello.cpp)

kde4_add_plugin(kio_hello ${kio_hello_PART_SRCS})

target_link_libraries(kio_hello ${KDE4_KIO_LIBS})

install(TARGETS kio_hello DESTINATION ${PLUGIN_INSTALL_DIR})

########### install files ###############

install(FILES hello.protocol DESTINATION ${SERVICES_INSTALL_DIR})
</pre>

== hello.h ==
<code cppqt>
#ifndef HELLO_H
#define HELLO_H

#include <kio/slavebase.h>

/**
This class implements a hello-world kioslave
*/
class hello : public KIO::SlaveBase
{
public:
hello( const QByteArray &pool, const QByteArray &app );
void get( const KUrl &url );
};

#endif
</code>

== hello.cpp ==
<code cppqt>
#include "hello.h"
#include <kdebug.h>
#include <kcomponentdata.h>

extern "C" int KDE_EXPORT kdemain( int argc, char **argv )
{
kDebug(7000) << "Entering function";
KComponentData instance( "kio_hello" );

if (argc != 4)
{
fprintf( stderr, "Usage: kio_hello protocol domain-socket1 domain-socket2\n");
exit( -1 );
}
hello slave( argv[2], argv[3] );
slave.dispatchLoop();
return 0;
}

void hello::get( const KUrl &url )
{
kDebug(7000) << "Entering function";
mimeType( "text/plain" );
QByteArray str( "Hello_world" );
data( str );
finished();
kDebug(7000) << "Leaving function";
}

hello::hello( const QByteArray &pool, const QByteArray &app )
: SlaveBase( "hello", pool, app ) {}
</code>

== hello.protocol ==
[Protocol]
DocPath=kioslave/kio_hello.html
exec=kio_hello
input=none
output=filesystem
protocol=hello
reading=true

== Compile the stuff ==
Create a new Folder "build":
<code>
mkdir build
cd build
</code>
Run cmake and make
<code>
cmake ..
make
</code>

now you can install it (maybe you should use an experimental setup?)
<code>
make install
</code>

If you should want to do this by hand:

g++ -shared -lkdeui -lkio -lkdecore -fPIC -I/usr/local/include hello.cpp -o kio_hello.so

''this does not complile if the qt headers are not in /usr/local/include''

''On my system I could fix it by changing -I/usr/local/include to -I/usr/include/qt4''
== Install the stuff ==

now you can install it (maybe you should use an experimental setup?)
<code>
make install
</code>

or if you want to install it to your system:
<code>
sudo make install
</code>

Of course you can also do this by hand

Find out where your protocols are lying:
kde4-config --path services
/usr/share/kde4/services/

kde4-config --path module
/usr/lib64/kde4/

cp kio_hello.so /usr/local/lib/kde4/
cp kio_hello.so /usr/lib64/kde4/
cp kio_hello.protocol /usr/share/kde4/services/

= Test it =
== in Konqueror ==
Start kinfocenter, choose hello as protocol. If this is possible, start konqueror, type hello:/// into the URL bar.
== on the command line ==
kioclient 'cat' 'hello:///'

Development/Architecture/DCOP

2010-05-22T22:17:28Z

Yecril71pl: /* Performance Tests */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject:: process (const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt (i);
QDataStream reply (replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug ("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp -> dcopClient() -> beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing (myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp
-> dcopClient() -> endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream (params, IO_WriteOnly);
stream << pid;
kapp -> dcopClient() -> emitDCOPSignal ("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal (0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod (QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main (int argc, char **argv)
{
KApplication *app;

app = new KApplication (argc, argv, "testit");
return app -> exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:15:42Z

Yecril71pl: /* Using the dcopidl compiler */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject:: process (const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt (i);
QDataStream reply (replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug ("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp -> dcopClient() -> beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing (myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp
-> dcopClient() -> endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream (params, IO_WriteOnly);
stream << pid;
kapp -> dcopClient() -> emitDCOPSignal ("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal (0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod (QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:13:46Z

Yecril71pl: /* DCOP Signals */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject:: process (const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt (i);
QDataStream reply (replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug ("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp -> dcopClient() -> beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing (myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp
-> dcopClient() -> endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream (params, IO_WriteOnly);
stream << pid;
kapp -> dcopClient() -> emitDCOPSignal ("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal (0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:12:10Z

Yecril71pl: /* Processing Received Calls with Transactions */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject:: process (const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt (i);
QDataStream reply (replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug ("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp -> dcopClient() -> beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing (myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp
-> dcopClient() -> endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:09:47Z

Yecril71pl: /* Receiving Data via DCOP */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject:: process (const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg (data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self -> doIt (i);
QDataStream reply (replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug ("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp->dcopClient()->beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing( myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp->dcopClient()->endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:07:58Z

Yecril71pl: /* Sending Data to a Remote Application */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client -> send ("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug ("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt (i);
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp->dcopClient()->beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing( myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp->dcopClient()->endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:06:26Z

Yecril71pl: /* Sending Data to a Remote Application */ replace entities

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client->send("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg (data, IO_WriteOnly);
arg << 5;
if (!client -> call ("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply (replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print ("the result is: %s", result. latin1());
} else
qDebug ("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject ("someAppId", "fooObject/barObject");
DCOPReply reply = barObject. call ("doIt", 5);
if (!reply. isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply). latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt (i);
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp->dcopClient()->beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing( myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp->dcopClient()->endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:03:00Z

Yecril71pl: /* Establishing the Connection */ unmark >

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client -> registerAs (kApp -> name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client->send("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client->call("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply(replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print("the result is: %s",result.latin1());
} else
qDebug("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject("someAppId", "fooObject/barObject");
DCOPReply reply = barObject.call("doIt", 5);
if (!reply.isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply).latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt (i);
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp->dcopClient()->beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing( myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp->dcopClient()->endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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

Development/Architecture/DCOP

2010-05-22T22:01:08Z

Yecril71pl: s/cppqt3/cpp-qt/

<div style="border: 1px solid #2090ff; padding: 1em 1em 1em 1em; background-color:#f8f8ff; align:center;">

'''DCOP: Desktop COmmunications Protocol'''

[mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] October 14, 1999

Revised and extended by [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>] Mar 29, 2000

HTMLized by Hans Meine [mailto:rastajoe@gmx.net Hans Meine <rastajoe@gmx.net>] May 25, 2000

Added a DCOPRef example: Tim Jansen May 12, 2003
</div>

== Demotivation and Background ==

'''Note that new features may not be developed for DCOP. The successor for DCOP is D-Bus'''

The motivation behind building a protocol like DCOP is simple. For
the past year, we have been attempting to enable interprocess
communication between KDE applications. KDE already has an extremely
simple IPC mechanism called KWMcom, which is (was!) used for communicating
between the panel and the window manager for instance. It is about as
simple as it gets, passing messages via X Atoms. For this reason it
is limited in the size and complexity of the data that can be passed
(X atoms must be small to remain efficient) and it also makes it so
that X is required. CORBA was thought to be a more effective IPC/RPC
solution. However, after a year of attempting to make heavy use of
CORBA in KDE, we have realized that it is a bit slow and memory
intensive for simple use. It also has no authentication available.

What we really needed was an extremely simple protocol with basic
authorization, along the lines of MIT-MAGIC-COOKIE, as used by X. It
would not be able to do NEARLY what CORBA was able to do, but for the
simple tasks required it would be sufficient. Some examples of such
tasks might be an application sending a message to the panel saying,
"I have started, stop displaying the 'application starting' wait
state," or having a new application that starts query to see if any
other applications of the same name are running. If they are, simply
call a function on the remote application to create a new window,
rather than starting a new process.

== Implementation ==

DCOP is a simple IPC/RPC mechanism built to operate over sockets.
Either unix domain sockets or tcp/ip sockets are supported. DCOP is
built on top of the Inter Client Exchange (ICE) protocol, which comes
standard as a part of X11R6 and later. It also depends on Qt, but
beyond that it does not require any other libraries. Because of this,
it is extremely lightweight, enabling it to be linked into all KDE
applications with low overhead.

=== Model ===

The model is simple. Each application using DCOP is a client. They
communicate to each other through a DCOP server, which functions like
a traffic director, dispatching messages/calls to the proper
destinations. All clients are peers of each other.

Two types of actions are possible with DCOP: "send and forget"
messages, which do not block, and "calls," which block waiting for
some data to be returned.

Any data that will be sent is serialized (marshalled, for you CORBA
fellows) using the built-in {{qt3|QDataStream}} operators available in all of
the Qt classes. This is fast and easy. In fact it's so little work
that you can easily write the marshalling code by hand. In addition,
there's a simple IDL-like compiler available (dcopidl and dcopidl2cpp)
that generates stubs and skeletons for you. Using the dcopidl compiler
has the additional benefit of type safety.

This HOWTO describes the manual method first and covers the dcopidl
compiler later.

=== Managing DCOP Connections Manually ===

==== Establishing the Connection ====

{{class|KApplication|kdelibs|3.5}} has gained a method called "KApplication::dcopClient()"
which returns a pointer to a DCOPClient instance. The first time this
method is called, the client class will be created. {{class|DCOPClient|kdelibs|3.5}}s have
unique identifiers attached to them which are based on what
KApplication::name() returns. In fact, if there is only a single
instance of the program running, the appId will be equal to
KApplication::name().

To actually enable DCOP communication to begin, you must use
DCOPClient::attach(). This will attempt to attach to the DCOP server.
If no server is found or there is any other type of error, attach()
will return false. KApplication will catch a dcop signal and display an
appropriate error message box in that case.

After connecting with the server via DCOPClient::attach(), you need to
register this appId with the server so it knows about you. Otherwise,
you are communicating anonymously. Use the
DCOPClient::registerAs(const QCString &name) to do so. In the simple
case:

<code cpp-qt>
/*
* returns the appId that is actually registered, which _may_ be
* different from what you passed
*/
appId = client->registerAs(kApp->name());
</code>

If you never retrieve the DCOPClient pointer from KApplication, the
object will not be created and thus there will be no memory overhead.

You may also detach from the server by calling DCOPClient::detach().
If you wish to attach again you will need to re-register as well. If
you only wish to change the ID under which you are registered, simply
call DCOPClient::registerAs() with the new name.

KUniqueApplication automatically registers itself to DCOP. If you
are using KUniqueApplication you should not attach or register
yourself, this is already done. The appId is by definition
equal to kapp->name(). You can retrieve the registered DCOP client
by calling kapp->dcopClient().

==== Sending Data to a Remote Application ====

To actually communicate, you have one of two choices. You may either
call the "send" or the "call" method. Both methods require three
identification parameters: an application identifier, a remote object,
a remote function. Sending is asynchronous (i.e. it returns immediately)
and may or may not result in your own application being sent a message at
some point in the future. Then "send" requires one and "call" requires
two data parameters.

The remote object must be specified as an object hierarchy. That is,
if the toplevel object is called "fooObject" and has the child
"barObject", you would reference this object as "fooObject/barObject".
Functions must be described by a full function signature. If the
remote function is called "doIt", and it takes an int, it would be
described as "doIt(int)". Please note that the return type is not
specified here, as it is not part of the function signature (or at
least the C++ understanding of a function signature). You will get
the return type of a function back as an extra parameter to
DCOPClient::call(). See the section on call() for more details.

In order to actually get the data to the remote client, it must be
"serialized" via a {{qt3|QDataStream}} operating on a {{qt3|QByteArray}}. This is how
the data parameter is "built". A few examples will make clear how this
works.

Say you want to call "doIt" as described above, and not block (or wait
for a response). You will not receive the return value of the remotely
called function, but you will not hang while the RPC is processed either.
The return value of send() indicates whether DCOP communication succeeded
or not.

<code cpp-qt>
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client->send("someAppId", "fooObject/barObject", "doIt(int)",
data))
qDebug("there was some error using DCOP.");
</code>

OK, now let's say we wanted to get the data back from the remotely
called function. You have to execute a call() instead of a send().
The returned value will then be available in the data parameter "reply".
The actual return value of call() is still whether or not DCOP
communication was successful.

<code cpp-qt>
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg << 5;
if (!client->call("someAppId", "fooObject/barObject", "doIt(int)",
data, replyType, replyData))
qDebug("there was some error using DCOP.");
else {
QDataStream reply(replyData, IO_ReadOnly);
if (replyType == "QString") {
QString result;
reply >> result;
print("the result is: %s",result.latin1());
} else
qDebug("doIt returned an unexpected type of reply!");
}
</code>

''N.B.:'' You cannot call() a method belonging to an application which has
registered with an unique numeric id appended to its textual name (see
dcopclient.h for more info). In this case, DCOP would not know which
application it should connect with to call the method. This is not an issue
with send(), as you can broadcast to all applications that have registered
with appname-<numeric_id> by using a wildcard (e.g. 'konsole-*'), which
will send your signal to all applications called 'konsole'.

Since KDE 3.1 there is an even easier way to make a DCOP call:
{{class|DCOPRef|kdelibs|3.5}}. Then you only need to create a DCOPRef to the object
and as long as the function does not use unusual argument types,
calling the function is as easy as this:

<code cpp-qt>
DCOPRef barObject("someAppId", "fooObject/barObject");
DCOPReply reply = barObject.call("doIt", 5);
if (!reply.isValid())
qDebug("there was some error using DCOP.");
else {
print("the result is: %s", ((QString)reply).latin1());
}
</code>

==== Receiving Data via DCOP ====

Currently the only real way to receive data from DCOP is to multiply
inherit from the normal class that you are inheriting (usually some
sort of QWidget subclass or QObject) as well as the DCOPObject class.
DCOPObject provides one very important method: DCOPObject::process().
This is a pure virtual method that you must implement in order to
process DCOP messages that you receive. It takes a function
signature, QByteArray of parameters, and a reference to a QByteArray
for the reply data that you must fill in.

Think of DCOPObject::process() as a sort of dispatch agent. In the
future, there will probably be a precompiler for your sources to write
this method for you. However, until that point you need to examine
the incoming function signature and take action accordingly. Here is
an example implementation.

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &replyType, QByteArray &replyData)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt (i);
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
replyType = "QString";
return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}
</code>

==== Processing Received Calls with Transactions ====

If your applications is able to process incoming function calls
right away the above code is all you need. When your application
needs to do more complex tasks you might want to do the processing
out of 'process' function call and send the result back later when
it becomes available.

For this you can ask your DCOPClient for a transactionId. You can
then return from the 'process' function and when the result is
available finish the transaction. In the mean time your application
can receive incoming DCOP function calls from other clients.

Such code could like this:

<code cpp-qt>
bool BarObject::process(const QCString &fun, const QByteArray &data,
QCString &, QByteArray &)
{
if (fun == "doIt(int)") {
QDataStream arg(data, IO_ReadOnly);
int i; // parameter
arg >> i;
QString result = self->doIt(i);

DCOPClientTransaction *myTransaction;
myTransaction = kapp->dcopClient()->beginTransaction();

// start processing...
// Calls slotProcessingDone when finished.
startProcessing( myTransaction, i);

return true;
} else {
qDebug("unknown function call to BarObject::process()");
return false;
}
}

slotProcessingDone(DCOPClientTransaction *myTransaction, const QString &result)
{
QCString replyType = "QString";
QByteArray replyData;
QDataStream reply(replyData, IO_WriteOnly);
reply << result;
kapp->dcopClient()->endTransaction(myTransaction, replyType, replyData);
}
</code>

==== DCOP Signals ====

Sometimes a component wants to send notifications via DCOP to other
components but does not know which components will be interested in these
notifications. One could use a broadcast in such a case but this is a very
crude method. For a more sophisticated method DCOP signals have been invented.

DCOP signals are very similair to Qt signals, there are some differences
though. A DCOP signal can be connected to a DCOP function. Whenever the DCOP
signal gets emitted, the DCOP functions to which the signal is connected are
being called. DCOP signals are, just like Qt signals, one way. They do not
provide a return value.

A DCOP signal originates from a DCOP Object/DCOP Client combination (sender).
It can be connected to a function of another DCOP Object/DCOP Client
combination (receiver).

There are two major differences between connections of Qt signals and
connections of DCOP signals. In DCOP, unlike Qt, a signal connections can
have an anonymous sender and, unlike Qt, a DCOP signal connection can be
non-volatile.

With DCOP one can connect a signal without specifying the sending DCOP Object
or DCOP Client. In that case signals from any DCOP Object and/or DCOP Client
will be delivered. This allows the specification of certain events without
tying oneself to a certain object that implementes the events.

Another DCOP feature are so called non-volatile connections. With Qt signal
connections, the connection gets deleted when either sender or receiver of
the signal gets deleted. A volatile DCOP signal connection will behave the
same. However, a non-volatile DCOP signal connection will not get deleted
when the sending object gets deleted. Once a new object gets created with
the same name as the original sending object, the connection will be restored.
There is no difference between the two when the receiving object gets deleted,
in that case the signal connection will always be deleted.

A receiver can create a non-volatile connection while the sender doesn't (yet)
exist. An anonymous DCOP connection should always be non-volatile.

The following example shows how KLauncher emits a signal whenever it notices
that an application that was started via KLauncher terminates.

; Example:

<code cpp-qt>
QByteArray params;
QDataStream stream(params, IO_WriteOnly);
stream << pid;
kapp->dcopClient()->emitDCOPSignal("clientDied(pid_t)", params);
</code>

The task manager of the KDE panel connects to this signal. It uses an
anonymous connection (it doesn't require that the signal is being emitted
by KLauncher) that is non-volatile:

; Example:

<code cpp-qt>
connectDCOPSignal(0, 0, "clientDied(pid_t)", "clientDied(pid_t)", false);
</code>

It connects the clientDied(pid_t) signal to its own clientDied(pid_t) DCOP
function. In this case the signal and the function to call have the same name.
This isn't needed as long as the arguments of both signal and receiving function
match. The receiving function may ignore one or more of the trailing arguments
of the signal. E.g. it is allowed to connect the clientDied(pid_t) signal to
a clientDied(void) DCOP function.

=== Using the dcopidl compiler ===

dcopidl makes setting up a DCOP server easy. Instead of having to implement
the process() method and unmarshalling (retrieving from QByteArray) parameters
manually, you can let dcopidl create the necessary code on your behalf.

This also allows you to describe the interface for your class in a
single, separate header file.

Writing an IDL file is very similar to writing a normal C++ header. An
exception is the keyword 'ASYNC'. It indicates that a call to this
function shall be processed asynchronously. For the C++ compiler, it
expands to 'void'.

; Example:

<code cpp-qt>
#ifndef MY_INTERFACE_H
#define MY_INTERFACE_H

#include <dcopobject.h>

class MyInterface : virtual public DCOPObject
{
K_DCOP

k_dcop:

virtual ASYNC myAsynchronousMethod(QString someParameter) = 0;
virtual QRect mySynchronousMethod() = 0;
};

#endif
</code>

As you can see, you're essentially declaring an abstract base class, which
virtually inherits from DCOPObject.

If you're using the standard KDE build scripts, then you can simply add this file (which you would call {{path|MyInterface.h}}) to your sources directory. Then you edit your {{path|Makefile.am}}, adding 'MyInterface.skel' to your SOURCES list and {{path|MyInterface.h}} to include_HEADERS.

The build scripts will use dcopidl to parse {{path|MyInterface.h}}, converting it to an XML description in {{path|MyInterface.kidl}}. Next, a file called {{path|MyInterface_skel.cpp}} will automatically be created, compiled and linked with your binary.

The next thing you have to do is to choose which of your classes will implement the interface described in {{path|MyInterface.h}}. Alter the inheritance of this class such that it virtually inherits from {{path|MyInterface}}. Then add declarations to your class interface similar to those on {{path|MyInterface.h}}, but virtual, not pure virtual.

; Example:

<code cpp-qt>
class MyClass: public QObject, virtual public MyInterface
{
Q_OBJECT

public:
MyClass();
~MyClass();

ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

Note: (Qt issue) Remember that if you are inheriting from {{qt3|QObject}}, you must place it first in the list of inherited classes.

In the implementation of your class' ctor, you must explicitly initialize
those classes from which you are inheriting from. This is, of course, good
practise, but it is essential here as you need to tell DCOPObject the name of
the interface which your are implementing.

; Example:

<code cpp-qt>
MyClass::MyClass()
: QObject(),
DCOPObject("MyInterface")
{
// whatever...
}
</code>

Now you can simply implement the methods you have declared in your interface,
exactly the same as you would normally.

; Example:

<code cpp-qt>
void MyClass::myAsynchronousMethod(QString someParameter)
{
qDebug("myAsyncMethod called with param `" + someParameter + "'");
}
</code>

It is not necessary (though very clean) to define an interface as an
abstract class of its own, like we did in the example above. We could
just as well have defined a k_dcop section directly within MyClass:

<code cpp-qt>
class MyClass: public QObject, virtual public DCOPObject
{
Q_OBJECT
K_DCOP

public:
MyClass();
~MyClass();

k_dcop:
ASYNC myAsynchronousMethod(QString someParameter);
QRect mySynchronousMethod();
};
</code>

In addition to skeletons, dcopidl2cpp also generate stubs. Those make
it easy to call a DCOP interface without doing the marshalling
manually. To use a stub, add {{path|MyInterface.stub}} to the SOURCES list of
your {{path|Makefile.am}}. The stub class will then be called MyInterface_stub.

=== Inter-user communication ===

Sometimes it might be interesting to use DCOP between processes
belonging to different users, e.g. a frontend process running
with the user's id, and a backend process running as root.

To do this, two steps have to be taken:
* both processes need to talk to the same DCOP server
* proper authentication must be ensured

For the first step, you simply pass the server address (as
found in .DCOPserver) to the second process. For the authentication,
you can use the ICEAUTHORITY environment variable to tell the
second process where to find the authentication information.
(Note that this implies that the second process is able to
read the authentication file, so it will probably only work
if the second process runs as root. If it should run as another
user, a similar approach to what kdesu does with xauth must
be taken. In fact, it would be a very good idea to add DCOP
support to kdesu!)

For example
ICEAUTHORITY=~user/.ICEauthority kdesu root -c kcmroot -dcopserver `cat ~user/.DCOPserver`

will, after kdesu got the root password, execute kcmroot as root, talking
to the user's dcop server.

'''NOTE:''' DCOP communication is not encrypted, so please do not
pass important information around this way.

== Performance Tests ==

A few back-of-the-napkin tests folks:

Code:
<code cpp-qt>
#include <kapp.h>

int main(int argc, char **argv)
{
KApplication *app;

app = new KApplication(argc, argv, "testit");
return app->exec();
}
</code>

Compiled with:
g++ -O2 -o testit testit.cpp -I$QTDIR/include -L$QTDIR/lib -lkdecore

on Linux yields the following memory use statistics:
VmSize: 8076 kB
VmLck: 0 kB
VmRSS: 4532 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

If I create the KApplication's DCOPClient, and call attach() and
registerAs(), it changes to this:
VmSize: 8080 kB
VmLck: 0 kB
VmRSS: 4624 kB
VmData: 208 kB
VmStk: 20 kB
VmExe: 4 kB
VmLib: 6588 kB

Basically it appears that using DCOP causes 100k more memory to be
resident, but no more data or stack. So this will be shared between all
processes, right? 100k to enable DCOP in all apps doesn't seem bad at
all. :)

OK now for some timings. Just creating a KApplication and then exiting
(i.e. removing the call to KApplication::exec) takes this much time:

0.28user 0.02system 0:00.32elapsed 92%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1084major+62minor)pagefaults 0swaps

I.e. about 1/3 of a second on my PII-233. Now, if we create our DCOP
object and attach to the server, it takes this long:

0.27user 0.03system 0:00.34elapsed 87%CPU (0avgtext+0avgdata 0maxresident)k
0inputs+0outputs (1107major+65minor)pagefaults 0swaps

I.e. about 1/3 of a second. Basically DCOPClient creation and attaching
gets lost in the statistical variation ("noise"). I was getting times
between .32 and .48 over several runs for both of the example programs, so
obviously system load is more relevant than the extra two calls to
DCOPClient::attach and DCOPClient::registerAs, as well as the actual
DCOPClient constructor time.

== Conclusion ==

Hopefully this document will get you well on your way into the world
of inter-process communication with KDE! Please direct all comments
and/or suggestions to [mailto:pbrown@kde.org Preston Brown <pbrown@kde.org>] and [mailto:ettrich@kde.org Matthias Ettrich <ettrich@kde.org>].

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