DCOP - Perl extension for communcation with KDE's DCOP
       server


SYNOPSIS

       use DCOP;

       my $client = new DCOP; $client->attach(); $running_apps =
       $client->registeredApplications(); $client->send("kmail",
       "KMailIface", "checkMail()");

       my $kmail = $client->createObject("kmail", "KMailIface");
       $kmail->openComposer("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 application and is a lightweight but powerful IPC
       mechanism. For more information look at

       http://developer.kde.org/documenta­
       tion/library/2.0-api/dcop/HOWTO.html

       This Perl extension can be used to send commands to any
       currently registered 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:

       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 anonymously or by name, you can use it to query
       information about other registered 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 inter­
       faces, 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

       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 pos­
       sibly 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

       registerAs.

       sub appId();

       returns the appId the client is known as or undef if it's
       not registered 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 context, the value returned is
       the function's return value, in list context call returns
       a two element list with the first item set to the func­
       tion'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 cur­
       rently registered applications.  On error it returns
       undef.

       sub remoteObjects($app)

       returns a reference to an array with the names of the

       returns undef.

       sub remoteInterfaces($app, $object)

       returns a reference to an array with the names of the
       interfaces supported 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 signatures 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 argu­
       ments 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.

           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 miss­
       ing also. By now, it is not possible to use DCOP.pm to
       receive DCOP messages. That is planned."  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.starostik@t-online.de


SEE ALSO

       perl(1).


Man(1) output converted with man2html