DCOP(3) User Contributed Perl Documentation DCOP(3)NAMEDCOP - Perl extension for communcation with KDE's DCOP server
SYNOPSIS
use DCOP;
my $client = new DCOP; $client->attach(); $running_apps = $client->reg‐
isteredApplications(); $client->send("kmail", "KMailIface", "check‐
Mail()");
my $kmail = $client->createObject("kmail", "KMailIface"); $kmail->open‐
Composer("fred@outer.space",
undef,
undef,
"This is a mail initiated by DCOP.pm",
0,
"file:/home/joe/file/with/mail/to/send");
DESCRIPTION
The Desktop COmmunication Protocol is used by almost every KDE applica‐
tion and is a lightweight but powerful IPC mechanism. For more informa‐
tion look at
http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html
This Perl extension can be used to send commands to any currently reg‐
istered DCOP application, as well as query which apps are registered
and what interfaces with what functions they offer. Additionally you
can use DCOP::Object to trigger DCOP sends or calls as native methods
of DCOP::Object (see the secion on Autoload Magic below).
Creation, Attachment and Registration
Creating a DCOP client is as simple as it gets:
use DCOP;
$client = new DCOP;
That's it. Some arguments to new are planned for future releases.
After creation the client is not attached to the server. The easiest
way to establish a connection is
$client->attach();
which registers your DCOP client anonymously. To register with a well
known name use:
$client->registerAs("fred");
NOTE: registerAs is currently disabled
To close the connection, simply call
$client->detach();
Hello World!
Now that you have your client registered with the server, either anony‐
mously or by name, you can use it to query information about other reg‐
istered applications. To get a list with names of all clients, use:
$client->registeredApplications();
To retrieve the Qt object hierarchy of an application, call
$client->remoteObjects($appname);
Similarly you can get a list of supported interfaces with
$client->remoteIterfaces($appname, $objectname);
And to know what you can do with all these nice interfaces, learn about
their functions:
$client->remoteFunctions($appname, $objectname);
Let them do something
To simply dispatch a command neglecting its return value, use
$client->send($appname, $objectname, $function, ...);
If you're interested in the return value, consider call:
$client->call($appname, $objectname, $function, ...);
Autoload Magic
A much more intuitive way to use send and call is via DCOP::Object.
This class is not intended for explicit instantiation and is merely a
very small autoload stub. To get a DCOP::Object, simply call
$obj = $client->createObject($appname [, $objectname]);
The returned $obj is a DCOP::Object "bound" to the specified applica‐
tion and object (or the app's default object if $objectname is omitted
or undef). This DCOP::Object has only two known methods, _app() and
_object() which return the application and object name respectively and
are merely for internal use. Any other method you call will be looked
up in the functions() list of the target object. So, if you created it
e.g. with
$obj = $client->createObject("kmail", "KMailIface");
You can simply invoke
$obj->checkMail();
instead of
$client->send("kmail", "KMailIface", "checkMail()");
Detailed Reference
sub new(); [ class method ]
takes no arguments by now and returns a blessed reference to a new DCOP
client.
sub attach();
returns a true value if the attachment succeeded or undef on error.
sub detach();
returns a true value if the client was successfully detached or undef
on error.
sub isAttached();
returns true or undef whether the client is attached or not.
sub registerAs($appId [, $addPID]); CURRENTLY DISABLED
registers the client with the name $appId or $appId with a number
appended if a client by that name already exists. If $addPID is true,
the PID of the client is appended to the appId, seperated by a hyphen.
If addPID is ommited, it defaults to true. To not add a PID, specify
undef or zero. registerAs returns the actual appId after the PID or
possibly a sequence number has been added. If you call this method on
an already attached or registered client, the old appId will be
replaced with the new one.
sub isRegistered(); CURRENTLY DISABLED
like isAttached but returns true only if the client used registerAs.
sub appId();
returns the appId the client is known as or undef if it's not regis‐
tered or only attached anonymously.
sub send($app, $object, $function [, ...])
dispatches a function call without waiting for completion and thus
without retrieving a return value. Returns true if a matching object
has been found or undef otherwise. $app is the name of a registered
application, $object the name of an object implemented by $app or undef
for the default object, $function is the signature of the function to
be called. Any following arguments are passed as parameters to the
called function. Make sure that they match the function's signature in
count and types (see Datatypes below) or your program will die. (This
will be configurable in later versions)
sub call($app, $object, $function [, ...])
like send, but blocks until the called function returns and supplies
the return value of that function (see Datatypes below). In scalar con‐
text, the value returned is the function's return value, in list con‐
text call returns a two element list with the first item set to the
function's repturn value and the second set to true or undef according
to success or failure of the DCOP call.
sub findObject
not really implemented, yet.
sub emitDCOPSignal
dito.
sub isApplicationRegistered($app)
returns true if an application with the given name is known to the DCOP
server or otherwise undef.
sub registeredApplications()
returns a reference to an array with the names of all currently regis‐
tered applications. On error it returns undef.
sub remoteObjects($app)
returns a reference to an array with the names of the objects supported
by the named application. On error it returns undef.
sub remoteInterfaces($app, $object)
returns a reference to an array with the names of the interfaces sup‐
ported by the given application and object. On error it returns undef.
sub remoteFunctions($app, $object)
returns a reference to an array with the names of the functions the
specified interface supports. The functions are returned as their sig‐
natures with parameter names and return type like
QCStringList functions()
sub normalizeSignature($signature)
removes extraneous whitespace from a function signature.
sub canonicalizeSignature($signature)
mostly for internal use. Calls normalizeSignature and then strips
parameter names and return type from it.
Datatypes
The following datatypes are currently supported in arguments to send
and call and as return values:
* int mapped to scalar
* QCString mapped to scalar
* QString (no Unicode support yet, just latin 1) mapped to scalar
* QCStringList mapped to a reference to an array of scalars.
* QStringList mapped to a reference to an array of scalars.
* QPoint (untested) mapped to a reference to a two elemtent array [$x,
$y] named value support via hash planned.
* QSize (untested) mapped to a reference to a two elemtent array
[$width, $height] named value support via hash planned.
* QRect (untested) mapped to a reference to a four elemtent array
[$left, $top, $width, $height] named value support via hash planned
(including alternative right and bottom / width height)
* KURL (only QString url() now) mapped to scalar
* DCOPRef (partially) mapped to DCOP::Object, methods like isNull()
missing.
BUGS Most probably many. A lot of memory leaks I fear, but that has to be
proven. There are many important features missing also. By now, it is
not possible to use DCOP.pm to receive DCOP messages. That is planned.
AUTHOR
Malte Starostik, malte@kde.org
SEE ALSOperl(1).
perl v5.8.8 2005-09-10 DCOP(3)
