The DCOP Interface

Caution: This documentation refers to K3b version 0.12 and above.

The K3b DCOP interface

K3b comes with a quite usable DCOP interface which allows it to control K3b from another application or from a script. In the latter case this is done with the dcop command line tool. The K3b DCOP interface mainly deals with the projects.

There are two interfaces. The default interface called K3bInterface which allows to create new projects, open tool dialogs (like the CD Copy dialog), and get references to the open projects. The second and most important interface is the K3bProjectInterface and it comes in mainly two different flavors: the K3bDataProjectInterface (to handle data CD and DVD projects) and the K3bAudioProjectInterface (to handle Audio CD projects).

K3bInterface (the default K3b DCOP interface)

The default K3bInterface provides methods to open the different too dialogs like copyCD, formatDVD, and methods for creating new projects, open projects, and so on.

DCOPRef createDataCDProject()
DCOPRef createAudioCDProject()
DCOPRef createMixedCDProject()
DCOPRef createVideoCDProject()
DCOPRef createMovixCDProject()
DCOPRef createDataDVDProject()
DCOPRef createVideoDVDProject()
DCOPRef createMovixDVDProject()
DCOPRef openProject(KURL url)
QValueList projects()
DCOPRef currentProject()
void copyCd()
void copyDvd()
void eraseCdrw()
void formatDvd()
void burnCdImage(KURL url)
void burnDvdImage(KURL url)

All createXXXProject and the currentProject methods return a DCOP reference to a K3b project through a K3bProjectInterface as described below.

DCOPRef(k3b,K3bProject-0)

Alternatively to the createXXXProject DCOP methods you may create a project using the command line:

# k3b --audiocd

and then get a reference to this project with

# dcop k3b K3bInterface currentProject

Using this reference it is possible to manipulate the project using the K3bProjectInterface.

The K3bProjectInterface

The K3bProjectInterface provides a common interface for all project types:

QString projectType()
void addUrls(KURL::List urls)
void addUrl(KURL url)
int length()
KIO::filesize_t size()
void burn()

Apart from that there are enhanced interfaces for data and audio projects.

The K3bDataProjectInterface

void createFolder(QString name)
void createFolder(QString name,QString parent)
void addUrl(KURL url,QString parent)
void addUrls(KURL::List urls,QString parent)
void removeItem(QString path)
void renameItem(QString path,QString newName)
void setVolumeID(QString id)
bool isFolder(QString path)
QStringList children(QString path)

Using this interface it is possible to fill a data project with files and folders from a script or determine the contents of a data projects.

The following script for example creates a new data project, adds several folders to the project, and adds files to the newly created folders:

#!/bin/bash
PROJECT=$(dcop k3b K3bInterface createDataCDProject)
dcop $PROJECT createFolder test
dcop $PROJECT createFolder foo
dcop $PROJECT createFolder bar /foo
dcop $PROJECT addUrl /home/trueg/somefile.txt /foo/bar

To do the same thing when it is unknown if K3b is running or not we can use the power of KUniqueApplication and simply start K3b:

k3b --datacd
PROJECT=$(dcop k3b K3bInterface currentProject)

When using the K3bInterface in C++ code KApplication provides a nice way to make sure K3b is running:

// start the process and block until it returnes
// one may also test the return value on success
KApplication::startServiceByDesktopName( "k3b" );

// now use DCOP to do the stuff (the tricky part)
QByteArray replyData;
QCString replyType;
KApplication::dcopClient()->call( "k3b", 
                                  "K3bInterface",
                                  "currentProject", 
                                  QByteArray(),
                                  replyType,
                                  replyData,
                                  false,
                                  -1 );
QDataStream reply( replyData, IO_ReadOnly );
DCOPRef ref;
reply >> ref;

// now we can simply use the DCOPRef (the easy part)
ref.call( "createFolder", QString("test") );

The K3bAudioProjectInterface

The K3bAudioProjectInterface provides a way to set and determine the CD-Text of and audio project. This way it is for example possible to create a cover from a K3b audio project.

int trackCount()
QString title()
QString artist()
QString trackTitle(int trackNum)
QString trackArtist(int trackNum)
void setTitle(QString title)
void setArtist(QString artist)
void setTrackTitle(int trackNum,QString title)
void setTrackArtist(int trackNum,QString artist)

The track number always starts at one.