DCOP(3pm)

1DCOP(3)               User Contributed Perl Documentation              DCOP(3)
2
3
4

NAME

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

SYNOPSIS

9       use DCOP;
10
11       my $client = new DCOP; $client->attach(); $running_apps = $client->reg‐
12       isteredApplications(); $client->send("kmail", "KMailIface", "check‐
13       Mail()");
14
15       my $kmail = $client->createObject("kmail", "KMailIface"); $kmail->open‐
16       Composer("fred@outer.space",
17                            undef,
18                            undef,
19                            "This is a mail initiated by DCOP.pm",
20                            0,
21                            "file:/home/joe/file/with/mail/to/send");
22

DESCRIPTION

24       The Desktop COmmunication Protocol is used by almost every KDE applica‐
25       tion and is a lightweight but powerful IPC mechanism. For more informa‐
26       tion look at
27
28       http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html
29
30       This Perl extension can be used to send commands to any currently reg‐
31       istered DCOP application, as well as query which apps are registered
32       and what interfaces with what functions they offer. Additionally you
33       can use DCOP::Object to trigger DCOP sends or calls as native methods
34       of DCOP::Object (see the secion on Autoload Magic below).
35
36       Creation, Attachment and Registration
37
38       Creating a DCOP client is as simple as it gets:
39
40         use DCOP;
41
42         $client = new DCOP;
43
44       That's it. Some arguments to new are planned for future releases.
45       After creation the client is not attached to the server. The easiest
46       way to establish a connection is
47
48         $client->attach();
49
50       which registers your DCOP client anonymously.  To register with a well
51       known name use:
52
53         $client->registerAs("fred");
54       NOTE: registerAs is currently disabled
55
56       To close the connection, simply call
57
58         $client->detach();
59
60       Hello World!
61
62       Now that you have your client registered with the server, either anony‐
63       mously or by name, you can use it to query information about other reg‐
64       istered applications.  To get a list with names of all clients, use:
65
66         $client->registeredApplications();
67
68       To retrieve the Qt object hierarchy of an application, call
69
70         $client->remoteObjects($appname);
71
72       Similarly you can get a list of supported interfaces with
73
74         $client->remoteIterfaces($appname, $objectname);
75
76       And to know what you can do with all these nice interfaces, learn about
77       their functions:
78
79         $client->remoteFunctions($appname, $objectname);
80
81       Let them do something
82
83       To simply dispatch a command neglecting its return value, use
84
85         $client->send($appname, $objectname, $function, ...);
86
87       If you're interested in the return value, consider call:
88
89         $client->call($appname, $objectname, $function, ...);
90
91       Autoload Magic
92
93       A much more intuitive way to use send and call is via DCOP::Object.
94       This class is not intended for explicit instantiation and is merely a
95       very small autoload stub.  To get a DCOP::Object, simply call
96
97         $obj = $client->createObject($appname [, $objectname]);
98
99       The returned $obj is a DCOP::Object "bound" to the specified applica‐
100       tion and object (or the app's default object if $objectname is omitted
101       or undef). This DCOP::Object has only two known methods, _app() and
102       _object() which return the application and object name respectively and
103       are merely for internal use. Any other method you call will be looked
104       up in the functions() list of the target object. So, if you created it
105       e.g. with
106
107         $obj = $client->createObject("kmail", "KMailIface");
108
109       You can simply invoke
110
111         $obj->checkMail();
112
113       instead of
114
115         $client->send("kmail", "KMailIface", "checkMail()");
116
117       Detailed Reference
118
119       sub new(); [ class method ]
120
121       takes no arguments by now and returns a blessed reference to a new DCOP
122       client.
123
124       sub attach();
125
126       returns a true value if the attachment succeeded or undef on error.
127
128       sub detach();
129
130       returns a true value if the client was successfully detached or undef
131       on error.
132
133       sub isAttached();
134
135       returns true or undef whether the client is attached or not.
136
137       sub registerAs($appId [, $addPID]); CURRENTLY DISABLED
138
139       registers the client with the name $appId or $appId with a number
140       appended if a client by that name already exists. If $addPID is true,
141       the PID of the client is appended to the appId, seperated by a hyphen.
142       If addPID is ommited, it defaults to true. To not add a PID, specify
143       undef or zero.  registerAs returns the actual appId after the PID or
144       possibly a sequence number has been added.  If you call this method on
145       an already attached or registered client, the old appId will be
146       replaced with the new one.
147
148       sub isRegistered(); CURRENTLY DISABLED
149
150       like isAttached but returns true only if the client used registerAs.
151
152       sub appId();
153
154       returns the appId the client is known as or undef if it's not regis‐
155       tered or only attached anonymously.
156
157       sub send($app, $object, $function [, ...])
158
159       dispatches a function call without waiting for completion and thus
160       without retrieving a return value. Returns true if a matching object
161       has been found or undef otherwise.  $app is the name of a registered
162       application, $object the name of an object implemented by $app or undef
163       for the default object, $function is the signature of the function to
164       be called.  Any following arguments are passed as parameters to the
165       called function.  Make sure that they match the function's signature in
166       count and types (see Datatypes below) or your program will die. (This
167       will be configurable in later versions)
168
169       sub call($app, $object, $function [, ...])
170
171       like send, but blocks until the called function returns and supplies
172       the return value of that function (see Datatypes below). In scalar con‐
173       text, the value returned is the function's return value, in list con‐
174       text call returns a two element list with the first item set to the
175       function's repturn value and the second set to true or undef according
176       to success or failure of the DCOP call.
177
178       sub findObject
179
180       not really implemented, yet.
181
182       sub emitDCOPSignal
183
184       dito.
185
186       sub isApplicationRegistered($app)
187
188       returns true if an application with the given name is known to the DCOP
189       server or otherwise undef.
190
191       sub registeredApplications()
192
193       returns a reference to an array with the names of all currently regis‐
194       tered applications.  On error it returns undef.
195
196       sub remoteObjects($app)
197
198       returns a reference to an array with the names of the objects supported
199       by the named application.  On error it returns undef.
200
201       sub remoteInterfaces($app, $object)
202
203       returns a reference to an array with the names of the interfaces sup‐
204       ported by the given application and object. On error it returns undef.
205
206       sub remoteFunctions($app, $object)
207
208       returns a reference to an array with the names of the functions the
209       specified interface supports.  The functions are returned as their sig‐
210       natures with parameter names and return type like
211
212         QCStringList functions()
213
214       sub normalizeSignature($signature)
215
216       removes extraneous whitespace from a function signature.
217
218       sub canonicalizeSignature($signature)
219
220       mostly for internal use. Calls normalizeSignature and then strips
221       parameter names and return type from it.
222
223       Datatypes
224
225       The following datatypes are currently supported in arguments to send
226       and call and as return values:
227
228       * int mapped to scalar
229       * QCString mapped to scalar
230       * QString (no Unicode support yet, just latin 1) mapped to scalar
231       * QCStringList mapped to a reference to an array of scalars.
232       * QStringList mapped to a reference to an array of scalars.
233       * QPoint (untested) mapped to a reference to a two elemtent array [$x,
234       $y] named value support via hash planned.
235       * QSize (untested) mapped to a reference to a two elemtent array
236       [$width, $height] named value support via hash planned.
237       * QRect (untested) mapped to a reference to a four elemtent array
238       [$left, $top, $width, $height] named value support via hash planned
239       (including alternative right and bottom / width height)
240       * KURL (only QString url() now) mapped to scalar
241       * DCOPRef (partially) mapped to DCOP::Object, methods like isNull()
242       missing.
243

BUGS Most probably many. A lot of memory leaks I fear, but that has to be

245       proven. There are many important features missing also. By now, it is
246       not possible to use DCOP.pm to receive DCOP messages. That is planned.
247

AUTHOR

249       Malte Starostik, malte@kde.org
250

NAME

SYNOPSIS

DESCRIPTION

BUGS Most probably many. A lot of memory leaks I fear, but that has to be

AUTHOR

SEE ALSO