1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title> Dillo Web Browser ::
Simple Plugins
</title>
<style type="text/css">
body {margin: 0}
.sidebar .items {background: #f8f8f8}
.sidebar h3 {font-size: 1em; margin: 0.4em 0 0.2em 0}
h1 {color: #67f; margin-top: 0.25em; margin-bottom: 0.25em}
h3 {color: #56f; background: #f0f0f0}
.section {background: #f8f8f8; border-color: #e8e8e8; border-style: solid; border-width: 1px; margin-bottom: 0.5em}
.section h3 {margin-top: 0; margin-bottom: 0.2em}
ul li {list-style-type: square}
</style>
</head>
<body text="black" link="blue" vlink="#403090" bgcolor="white"
style="line-height: 1.3">
<table width="100%" cellspacing="0" cellpadding="0"><tr>
<td><img src="db1.png" alt="The Dillo Web Browser">
<td width="100%">
<img src="db2.png" alt="The Dillo Web Browser" height="124" width="100%">
</table>
<table border="0" cellpadding="15" cellspacing="5" width="100%">
<tr valign="top">
<td class="sidebar">
<h3>Dillo</h3>
<div class="items">
<a href="index.html">Home</a><br>
<a href="screenshots/index.html">Screenshots</a><br>
<a href="download.html">Download</a><br>
<a href="FAQ.html" title="Frequently asked questions">FAQ</a><br>
<a href="Compatibility.html">Compatibility</a><br>
<a href="http://hg.dillo.org/dillo/raw-file/default/ChangeLog">
Changelog</a><br>
<a href="Plans.html">Current Plans</a><br>
<a href="MList.html">Mailing List</a><br>
<a href="conferences.html">Conferences</a><br>
<a href="donations.html">Donate</a><br>
</div>
<h3>Users</h3>
<div class="items">
<a href="dillo3-help.html">Help</a><br>
<a href="Icons/index.html">Icons</a><br>
<a href="help/bug_meter.html">Bug meter</a><br>
<br>
</div>
<h3>Bug Tracker</h3>
<div class="items">
<small>[currently broken]</small><br>
<!--
<a href="/bugtrack/Dbugtrack.html">Bug Track Intro</a><br>
<a href="/bugtrack/Dquery.html">View Entries</a><br>
<a href="/bugtrack/Dinsert.html">Bug Insertion</a><br>
<a href="/bugtrack/Dvolunteer.html">Volunteering</a><br>
-->
</div>
<h3>Developers</h3>
<div class="items">
<a href="developer.html">New Developer</a><br>
<a href="documentation.html">Documentation</a> *<br>
<a href="NC_design.html">Naming&Coding</a><br>
<a href="source.html">Source repository</a><br>
<a href="dpi1.html">Dpi1 Spec</a><br>
<a href="CSS.html">CSS Spec</a><br>
<a href="D_authors.html">Authors</a><br>
<a href="authors/jcid-email.html">Security contact</a><br>
</div>
<h3>Related</h3>
<div class="items">
<a href="press.html">Dillo in the Press!</a><br>
<a href="interview.html">Interview</a><br>
<a href="interview.es.html">Entrevista</a>
<img src="chile.png" alt="*"><br>
<a href="Links.html">Links</a><br>
<a href="logos/logos.html">Art</a><br>
</div>
<p>
<a href="authors/webmaster-email.html">Webmaster</a>
<p>
<a href="http://www.anybrowser.org/campaign/">
<img src="abblue.gif" width="80" height="15"
alt="anybrowser"></a>
<td valign="top" align="left" width="100%">
<h1>Simple Dillo plugins</h1>
<small>
<a href="dpi1.v7.txt">text only version</a> |
<a href="dpi1.v6.txt">previous version</a>
</small>
<p>
[<a href="http://hg.dillo.org/dillo/file/tip/doc/Dpid.txt">see also</a>
(related and less ancient)]
<hr>
<pre>
dpi1-v1.0 (draft 10, with implementation)
by: Jorge Arellano, Eric Gaudet
Jul 26, 2003
/*
This document is an hybrid between a draft and a doc. This is
because the full dpi1 spec isn't completely finished yet, but we
already have a working framework to develop with.
*/
---------------------
Simple plugins (dpi1)
---------------------
------------
Introduction
------------
Hopefully, dillo will have two types of plugins: one of a
simple nature (described in this document), that operates in a
similar way of CGIs (with some extensions), and another that
integrates interaction with the rendering engine and its widgets.
The fact is that our current rendering system, and its
associated internal layers is still under construction, makes
almost impossible to begin working on dpi2, and on the other
hand, gives an excellent oportunity to focus on dpi1 (that's also
expected to be easier to program with).
We expect dpi1 to be incrementally extensible, but also very
simple in its concept at the same time.
Please bear the simplicity concept in mind while studying this
document. That's the basis for a powerful and clean dpi spec.
----------
Motivation
----------
Dillo aims to be a small, fast and efficient web browser. This
kind of PI is designed to push out of the main code features that
usually are optional, and also some others that are required (as
bookmarks for instance).
The design idea is to keep the main code-base small and to
simplify the development of new features, by not requiring a PI
programer to know the whole internals of dillo.
This way, extensions can be easily coded, and there's also
place for developing unrelated programs that can use dillo as a
GUI!
--------
Overview
--------
Technically, the plugin program is a coprocess (an independent
program spawned by the browser) that communicates with the
browser through e certain channel.
The current implementation uses unix domain sockets:
--------- -------------> ------
| Browser | | socket | | PI |
--------- <------------- ------
Note: actually, there's a daemon manager process involved in
the communication between dillo and its PIs. It is documented in
"doc/Dpid.txt", but in the end, things work as the above diagram
shows. PI developers should read both this spec and Dpid.txt.
The main idea is to have a bidirectional channel on which the
browser and the plugin can communicate. The data flow is
encapsulated in a small but flexible protocol (dpi protocol) that
resembles HTML tags.
For instance, for sending an status message from the plugin to
the browser:
<dpi cmd='send_status_message' msg='Hello browser!'>
---------------------------
Note that with this scheme:
---------------------------
* PI-programs can be one-demand/one-response, and there's
space for multiple negotiations between the browser and the
plugin too.
* Status/progress messages can be passed back to the browser.
* Browser and plugin can request information from each other,
and they can also set data!
* It is possible to handle persistent dpi1 processes, though
not a requirement.
* It's easy to extend the protocol by adding new operations
without affecting backward compatibility.
* There's plenty of choice for PI languages.
* Plugin programs are managed with an intermediate daemon.
This makes possible having several dillo instances using the same
plugin.
-----------------
How does it work?
-----------------
In general terms, the browser starts (or contacts) the PI when
it finds something that belongs to it (as an URI), and handles it
to the PI. The PI receives the request, processes it and answers
back in the form of an HTML page, or status message, or a dpi
command.
A simple session (one-demand/one-response) can look like this:
1.- The browser finds an URI that belongs to a certain PI.
2.- The browser prepares to send the URI to the PI.
3.- The PI starts.
4.- The browser handles the URI to the PI with a dpi command.
5.- The PI makes/composes its answer (an HTML page) and sends
it back within dpi protocol datagrams.
6.- The PI acknowledges the browser when done, and optionally
exits.
-------------
Some examples
-------------
Before getting into the protocol itself, it may be ilustrative
to look at some functionality that could be handled using this
kind of PIs. For those willing to participate in the protocol
developing process, it's certainly adviced to keep these examples
in mind for testing design ideas.
1) Downloads
* current cache allocates them in memory, so handling them
to an external program (PI) has several advantages.
* the PI chooses which agent (wget, curl, ...) to use, and
sends feedback to dillo's download interface (HTML).
* Downloads don't stop if dillo crashes.
2) FTP
* to browse FTP directories (PI outputs HTML).
* Downloads using 1).
* progress messages (as loggin in, etc) can go to the
status bar.
3) Bookmarks
* The BM PI maintains the BM database (a single file!).
* The PI builds an HTML page for dillo.
* Needs coomunication with the browser (URI, titles, add
bookmark, etc).
* Some of the functions can be handled with FORMS.
* Browser may clean BM-pages out of the stack, for
them not to show in history.
* Exporting BM becomes a matter of Save-page-as!
NOTE: All of this has been already implemented (BM).
4) Preferences (AKA configuration)
* PI requests information from the browser (current prefs).
* PI commands the browser to change its "state"
* PI maintains dillorc
* As 3), may require stack-cleanning of page.
5) Info reader.
* Just a handy info to html filter (very simple).
* one-demand/one-response.
6) Doc viewer (?)
* uses an external program to convert doc to html
7) Help browser
* A PI that knows of local documentation, presents an index
and probably a search feature!
8) A handler PI for "mailto:".
(...)
Well, that's the idea of simple PI. A way of extending dillo to
suit end-user needs, without requiring extensive knowledge of its
internals. Note also that these extensions don't make into the
core of the browser.
-------------------------
Developing a dillo plugin
-------------------------
I think the best way to get started will be to explain the
basics of "dillo <=> PI" communication, then review the already
implemented tags of the dpi protocol, give some tips, and finally
let you examine the code of the already developed plugins.
* Don't forget to read: "doc/Dpid.txt" (inside the tarball).
-----------------
Dpi communication
-----------------
------------
dillo => PI:
------------
There're three ways:
1.- dpi tag
2.- static URL
3.- dynamic URL (with form data)
Note that all of them are in fact dpi tags, the division is
made to separate some concepts.
1.- The first one is for any specific dpi command sent from
the browser to a PI. For example:
<dpi cmd='add_bookmark' url='http://here.org' title='Here!'>
2.- The second one usually refers an URL "inside" the PI's
scope. It commands the PI to do something (usually to send back a
page). For intance:
<dpi cmd='open_url' url='dpi:/bm/'>
In this case the PI must react sending the main page for the
user's bookmarks.
3.- The third one is the most versatile. It sends back (to the
PI) all the data associated with a FORM that was most usually
sent by the PI itself before. For instance:
<dpi cmd='open_url'
url='dpi:/bm/modify?operation=modify&submit=submit.&s1=on'>
(all in a single line)
That's how the PI knows we want to modify the first section
name of the bookmarks file.
------------
PI => dillo:
------------
There're two ways:
1.- dpi tag
2.- HTML page
1.- The first one is the generic mechanism and usually serves
to command the browser. For instance:
<dpi cmd='send_status_message' msg='Bookmark added!'>
2.- The second one tells the browser we'll send an HTML page.
<dpi cmd='start_send_page' url='dpi:/bm/'>
------------
The protocol
------------
Amazingly (if you've already tried the bookmarks PI), all its
functionallity is carried on with these few dpi tags:
dillo => PI:
<dpi cmd='open_url' url='%s'>
<dpi cmd='add_bookmark' url='%s' title='%s'>
<dpi cmd='chat' msg='%s'>
PI => dillo:
<dpi cmd='start_send_page' url='%s'>
<dpi cmd='send_status_message' msg='%s'>
<dpi cmd='reload_request' url='%s'>
<dpi cmd='chat' msg='%s'>
So it is NOT that hard!
----------------------------
Tips for developing a new PI
----------------------------
First, examine the above mentioned protocol tags, then read
the code of hello.c ("Hello world" PI) and figure out its work.
You should also have read Dpid.txt at this point.
After that, it'll be clear what the basic skeleton is, and how
to send back a page to dillo.
The next step is to make a FORM, get some data from the user,
and to send back a new page that manipulates the input data. For
this:
1.- Design an HTML page with the form
2.- Design an HTML page with the desired answer skeleton
3.- Make your PI send the form as the main page
(as an answer to "dpi:/mydpi/", for instance)
Once you have that, you'll need to process the input data:
4.- Make your PI print what it receives so it becomes clear
what you're dealing with.
5.- Either try to process it right away, or study how it's
done in the 'Bmsrv_parse_buf' function of the bookmarks
PI.
Now you have the parsed data:
5.- Manipulate it somehow
6.- Build the answer page and send it back
If you made this far, the rest will be clear enough from
studying the commented bookmarks' code!
If you don't want to make a form-based PI, but one that spawns
another process you may start looking in the ftp PI.
-------------------------------------
What's missing in this implementation
-------------------------------------
1.- Some dpi commands
(This is good in the sense of a protocol being finished
when the last uneeded commands are removed! :)
2.- PI start/initialization.
3.- All the menu handling (from PI to browser) is to be
defined
(there're some ideas about these near the end)
1.- Dpi commands
----------------
From the set of dpi commands, I want to comment two:
start_send_page:
<dpi cmd='start_send_page' length='%d'>
This was meant to encapsulate HTML chunks of certain length.
The final chunk should be marked with length='0' or something
akin. The main purpose of it is to allow communication after the
HTML page is sent. That way, for instance, the bookmarks plugin
could send a staus message adding more information about a
performed operation (as "Deleted 3 bookmarks").
The only reason I didn't code it from the start was to get to
a working framework as fast a s possible. It's not hard though.
Currently the dpi framework uses 'start_send_page' wich
assumes that all the following data, up to EOF, is part of the
HTML page.
send_data:
This will be a generic way of exchanging information. Useful
for sending/setting preferences for instance. Very similar to the
previous command, and much like the current 'chat' command.
BTW, the 'chat' command is not necessary (just gave a look to
the funny and irrelevant talk between dillo and the bm PI!). It
was just a way of testing bidirectional data exchange.
If you need to send/request some data, feel free to use 'chat'
until 'send_data' is implemented.
2.- PI start/initialization
---------------------------
There's a lot more info about it in the following pages. A
polished interface for registering/launching plugins is yet to be
developed.
We want dillo and dpid to be able to add, remove and upgrade
plugins in a clear and transparent way. We're working on it...
3.- Menu handling
-----------------
Just read the following section!.
----------
------------------------
SECTION II
(this is the draft part)
------------------------
This section is mainly a gathering of ideas about what's not
yet implemented:
1.- Dpi commands
2.- Menus
3.- PI initialization
4.- Plugins options
5.- Plan
6.- Future extensions
7.- Final notes
------------
Dpi commands
------------
NOTE: this commands list is just a set of ideas. It doesn't
mean they will be implemented. We gather them here just to keep
track of the interesting ideas they bring.
dillo -> PI
-----------
CMD : DpiAbort
::
Sent by dillo to abort an "in-progress" plugin. Dillo might send
a "kill -9" command to the PI if it doesn't answer.
(most probably dillo will ask the dpid to kill a PI, and the dpid
itself will send a kill signal to the PI).
CMD : DpiBye
::
The plugin is commanded to quit (after it's done).
It may be used to end a "resident" PI that's doing nothing.
Plugins can end and exit when finished or keep sleeping, but they
MUST acknowledge dillo when they're done on a per client basis.
CMD : DpiError
::
Sent by dillo when a command is not understood.
PI -> dillo
-----------
CMD : DpiRequestInfo
::
Sent to the browser to request information.
For instance:
- Dillo version
- title of current page
- URL of current page
- preferences (the whole preferences as text)
- All active colors (background, text, link, visited link)
CMD : DpiSetData
::
Sent to the browser to change its "state".
Example: preferences, menus.
CMD : DpiDone
::
Sent by the PI when finished servicing a client.
-----
Menus
-----
Menus need to be defined thinking on the needs of current and
future PIs. The may not require menu entries (as the FTP PI), may
require a single menu entry, or a whole menu, or a button.
The key point here is to provide simple support for menus, and
not to complicate the protocol with seldom required features.
<< simplified menu registration protocol --EG
Main goals:
- a plugin may or may not want to be registered in the menus
when initializing: menus are optionnal.
- a plugin may want to change some or all its menus entries at
runtime.
- the plugins menu looks like this: there's a "Plugins" menu in
dillo's menubar, where all plugins are shown, provided they
asked for it during the init stage. Then it's up to the plugin
to ask this entry to be an url or a submenu.
Commands:
CMD : DpiMenu
Menu commands:
- insert: add an entry named <string> just after the entry ID. Dillo
must answer with the new entry ID.
- delete: delete an entry ID and all dependent sub-menus.
- modify: modity the <string> of an entry.
- submenu: make an entry a submenu.
- url: give <string> as the url to be called when the menu entry is
clicked.
>>
-----------------
PI initialization
-----------------
The main problem with running each PI everytime dillo starts is
the added startup time. If, for instance, there's a PERL and a
Python PI, the time increase is too much.
We're working on a scheme that avoids running each plugin when
dillo starts. It has a "pluginsrc" kind of file with information
about each PI. The whole work is done by dpid, but there'll be a
control program for the user interface. Something like:
dpidc [register | upgrade | stop | ...]
dpidc communicates with dpid using the same service request
socket that dillo currently uses. All the operations will be
defined with dpip tags.
What I like from this approach is that it is very flexible and
can be implemented incrementally ("dpidc register" is enough to
start).
It also avoids the burden of having to periodically check the
dpis directory structure for changes or updates.
It also lets shell scripts an easy way to do the "dirty" work
of installing dpis; this may help building a dillo package for
certain distros.
For instance, these commands may be added to the protocol:
dillo -> dpi:
CMD : DpiInit
::
It should include some challenge data to assert it's a dpi.
and from dpi->dillo:
CMD : DpiInitAnswer
::
Data is composed of a list of name=value pairs separated with ';'
just like in an URL (it must answer the challenge).
Example:
Name="bookmarks";prefix="bm";MenuEntry="View Bookmarks"
---------------
Plugins options
---------------
There're two different things here, the PI registration data
(managed by dpid in the 'pluginsrc' file for every PI), and the
specific options a specific PI-program may provide for tunning
its behaviour. The later one should be managed by the PI program
itself.
----
Plan
----
Currently the dpi framework has working dpis for: bookmarks,
ftp, downloads and hello.
The plan is to polish&stabilize both, the dpis and the
framwork, with a view to 0.8.0 release.
-----------------
Future extensions (needs a lot more thought)
-----------------
1.- Postfixed call to a Dillo-plugin
Dillo plugins registered as such will be called if the loaded
page's <extension> in "<url>.<extension>" matches a Dillo-plugin
registration, or if the PI has registered the same MIME type of
that content, and thus the PI acts as a file-processing filter.
Dillo will call the Dillo-plugin sending to it the whole
loaded file, and expecting some data back. This can be used as a
file-to-html filter.
Example: "http://my.server.org/mydirectory/myfile.rtf" will
render the rtf file as html if a Dillo-plugin has registered
itself as dealing with "rtf" files.
-----------
Final notes
-----------
The draft part of this material is not "written on stone", but
provided as a structural basis on which to develop the simple PI
protocol. Please take it with a pinch of salt, in the best spirit
of a RFC.
As you can see, there's plenty of material here, and
discussing threads can get very large if posts are not carefully
thought of. Please take your time to study and fully understand
the material, and only submit well backed/tested ideas.
Thanks a lot to all of those that have contributed in making
dpi1 possible!
</pre>
<hr>
</td>
</tr>
</table>
</body>
</html>
|
