Contents 1 Resource sharing 2 General information 3 Downloading resources 4 Uploading resources

[edit] Resource sharing

Many applications work with external resources which gives them the freedom to change or extend the behavior without requiring to change the application code itself. Others are extensible with the help of binary plugins. All these external resources should be provided in a way to the user, and the most common way is to put them on the homepage of the application, which works, but it is not so convenient to the final user to get the updates. It is much easier to get them from inside the application. Luckily KDE has the corresponding technology called KNewStuff which not only makes possible to download updates and resources, but if the application supports it, it is even possible to share a resource created by the user with other users. KNewStuff has a weak point though, that you cannot really know who created a resource when downloading, nor the maintainer of the resource repository can know who created the resource that was uploaded, and there is no corruption checking either.

Starting with KDE 3.4 and with the introduction of the KNewStuffSecure class this problems are solved. With this technology the resources can be digitally signed, an md5sum is calculated for them, so both the uploaded and downloaded resources can be verified whether they come from a safe source and person or not.

This tutorial will explain how to use KNewStuffSecure in your application to enable downloading and uploading secured resources. It will not explain the usage of KNewStuff itself and how you can set up a resource repository on the server. These informations can be found in the KNewStuff API documentation, in the KNewStuff tutorial and in the sources: kdelibs/knewstuff/README.knewstuff and kdelibs/knewstuff/data.

---

[edit] General information

Using KNewStuff itself is quite simple, and I tried to make KNewStuffSecure not more complicated. The only extra requirement is to have gpg installed in your $PATH, and for uploading of course it is preferred if you already have a GPG key that you can use for resource signing.

As gpg is not a compilation time requirement, it is suggested that you check on application startup for its presence and warn the user what he misses without it. Of course the check is performed by KNewStuffSecure as well, but I find it muchnicer to check for runtime dependencies on startup.

---

[edit] Downloading resources

The first thing you must to is to subclass the KNewStuffSecure class and implement the installResource method, which is a pure virtual method in KNewStuffSecure. Here is an example of what you should put in a header file:
Invalid language argument, "cppqt3", select one from the list:
actionscript3
ocaml-brief
dcs
cfdg
gnuplot
whitespace
lisp
cpp
xml
ocaml
prolog
reg
diff
css
providex
pixelbender
xpp
applescript
thinbasic
c
d
caddcl
freebasic
lolcode
actionscript
cpp-qt
dos
dot
sas
cmake
winbatch
hq9plus
abap
cadlisp
oobas
delphi
rebol
haskell
ruby
povray
progress
kixtart
purebasic
oberon2
email
groovy
oracle11
pascal
c_mac
lsl2
vbnet
tcl
tsql
make
cppqt
apache
matlab
sql
php-brief
klonec
lua
text
scala
m68k
bf
html4strict
autoit
scilab
autohotkey
sdlbasic
fo
oracle8
glsl
smarty
lscript
robots
io
xorg_conf
typoscript
python
visualfoxpro
nsis
z80
ada
gml
cobol
smalltalk
bibtex
csharp
apt_sources
mirc
po
gdb_backtrace
eiffel
modula3
vb
basic4gl
objc
whois
lotusformulas
genero
java
qbasic
vim
verilog
gettext
mxml
pic16
idl
klonecpp
vhdl
plsql
asm
asp
per
visualprolog
javascript
rails
php
awk
mysql
latex
powershell
locobasic
blitzbasic
erlang
bnf
java5
teraterm
intercal
mpasm
ini
boo
bash
inno
cfm
fortran
rsplus
perl
cil
scheme
lotusscript
avisynth
properties

In order to know what you should do in installResource() it is important to understand the structure of the resource you get via KNewStuffSecure. The resource is a gzipped tarball, let's call it resource.tar.gz. The resource.tar.gz contains three files:

Filename	Description
data.tar.gz	another tarball containing the actual data to be installed. The name is not fixed, it can be anything like cards.tgz, greetings.tar.gz or whatever.
signature	holds the signature for data.tar.gz
md5sum	holds the MD5 sum for the data.tar.gz

In the implementation file you have to process the data.tar.gz only, the rest is handled by KNewStuffSecure. If installing the resource means that you put the downloaded file(s) from data.tar.gz into a directory, the implementation of MyNewStuff looks like:

Invalid language argument, "cppqt3", select one from the list:
actionscript3
ocaml-brief
dcs
cfdg
gnuplot
whitespace
lisp
cpp
xml
ocaml
prolog
reg
diff
css
providex
pixelbender
xpp
applescript
thinbasic
c
d
caddcl
freebasic
lolcode
actionscript
cpp-qt
dos
dot
sas
cmake
winbatch
hq9plus
abap
cadlisp
oobas
delphi
rebol
haskell
ruby
povray
progress
kixtart
purebasic
oberon2
email
groovy
oracle11
pascal
c_mac
lsl2
vbnet
tcl
tsql
make
cppqt
apache
matlab
sql
php-brief
klonec
lua
text
scala
m68k
bf
html4strict
autoit
scilab
autohotkey
sdlbasic
fo
oracle8
glsl
smarty
lscript
robots
io
xorg_conf
typoscript
python
visualfoxpro
nsis
z80
ada
gml
cobol
smalltalk
bibtex
csharp
apt_sources
mirc
po
gdb_backtrace
eiffel
modula3
vb
basic4gl
objc
whois
lotusformulas
genero
java
qbasic
vim
verilog
gettext
mxml
pic16
idl
klonecpp
vhdl
plsql
asm
asp
per
visualprolog
javascript
rails
php
awk
mysql
latex
powershell
locobasic
blitzbasic
erlang
bnf
java5
teraterm
intercal
mpasm
ini
boo
bash
inno
cfm
fortran
rsplus
perl
cil
scheme
lotusscript
avisynth
properties

As you can see the name of the resource tarball you have to install is in "m_tarName". The above code installs the files from m_tarName to $KDEHOME/share/appname/stuff. Of course, you must provide the real appname there.

You are free to do other installation methods, depending on your needs. In some cases it may be just enough to copy the resource tarball somewhere. This part of the code depends completely on the type of the resource and your application.

Now how to initiate a download? You have to do three things:

• create a MyNewStuff object
• connect the signal installFinished() to a slot to do things what you want after the install is done
• call downloadResource() for the MyNewStuff object

Example:
Invalid language argument, "cppqt3", select one from the list:
actionscript3
ocaml-brief
dcs
cfdg
gnuplot
whitespace
lisp
cpp
xml
ocaml
prolog
reg
diff
css
providex
pixelbender
xpp
applescript
thinbasic
c
d
caddcl
freebasic
lolcode
actionscript
cpp-qt
dos
dot
sas
cmake
winbatch
hq9plus
abap
cadlisp
oobas
delphi
rebol
haskell
ruby
povray
progress
kixtart
purebasic
oberon2
email
groovy
oracle11
pascal
c_mac
lsl2
vbnet
tcl
tsql
make
cppqt
apache
matlab
sql
php-brief
klonec
lua
text
scala
m68k
bf
html4strict
autoit
scilab
autohotkey
sdlbasic
fo
oracle8
glsl
smarty
lscript
robots
io
xorg_conf
typoscript
python
visualfoxpro
nsis
z80
ada
gml
cobol
smalltalk
bibtex
csharp
apt_sources
mirc
po
gdb_backtrace
eiffel
modula3
vb
basic4gl
objc
whois
lotusformulas
genero
java
qbasic
vim
verilog
gettext
mxml
pic16
idl
klonecpp
vhdl
plsql
asm
asp
per
visualprolog
javascript
rails
php
awk
mysql
latex
powershell
locobasic
blitzbasic
erlang
bnf
java5
teraterm
intercal
mpasm
ini
boo
bash
inno
cfm
fortran
rsplus
perl
cil
scheme
lotusscript
avisynth
properties

Just a note: "appname/resourcetype" is in free form, it identifies the type of the resource. See the standard KNewStuff documentation for details.

---

[edit] Uploading resources

Uploading is simple as well. You just have to create the data.tar.gz (which is specific for your application) and call uploadResource(fileName), where fileName points to the created data tarball.

Example:
Invalid language argument, "cppqt3", select one from the list:
actionscript3
ocaml-brief
dcs
cfdg
gnuplot
whitespace
lisp
cpp
xml
ocaml
prolog
reg
diff
css
providex
pixelbender
xpp
applescript
thinbasic
c
d
caddcl
freebasic
lolcode
actionscript
cpp-qt
dos
dot
sas
cmake
winbatch
hq9plus
abap
cadlisp
oobas
delphi
rebol
haskell
ruby
povray
progress
kixtart
purebasic
oberon2
email
groovy
oracle11
pascal
c_mac
lsl2
vbnet
tcl
tsql
make
cppqt
apache
matlab
sql
php-brief
klonec
lua
text
scala
m68k
bf
html4strict
autoit
scilab
autohotkey
sdlbasic
fo
oracle8
glsl
smarty
lscript
robots
io
xorg_conf
typoscript
python
visualfoxpro
nsis
z80
ada
gml
cobol
smalltalk
bibtex
csharp
apt_sources
mirc
po
gdb_backtrace
eiffel
modula3
vb
basic4gl
objc
whois
lotusformulas
genero
java
qbasic
vim
verilog
gettext
mxml
pic16
idl
klonecpp
vhdl
plsql
asm
asp
per
visualprolog
javascript
rails
php
awk
mysql
latex
powershell
locobasic
blitzbasic
erlang
bnf
java5
teraterm
intercal
mpasm
ini
boo
bash
inno
cfm
fortran
rsplus
perl
cil
scheme
lotusscript
avisynth
properties

Here createUploadResource() creates the data tarball and returns the name with path to the created tarball.

That is all. I hope you will find this tutorial useful.