-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathPLUGINS.html
2417 lines (2044 loc) · 99.2 KB
/
PLUGINS.html
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
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>The VDR Plugin System</title>
<style type="text/css">
html, body {
background-color: white;
}
.blurb {
font-style: italic;
font-weight: bold;
text-align: center;
}
.center {
text-align: center;
}
.code {
background-color: #F0F0F0;
}
.modified {
background-color: #FFDDDD;
}
modified {
background-color: #FFDDDD;
}
</style>
</head>
<body>
<div class="center">
<h1>The VDR Plugin System</h1>
<b>Version 2.7</b>
<p>
Copyright © 2021 Klaus Schmidinger<br>
<a href="mailto:[email protected]">[email protected]</a><br>
<a href="https://www.tvdr.de">www.tvdr.de</a>
</div>
<p>
VDR provides an easy to use plugin interface that allows additional functionality
to be added to the program by implementing a dynamically loadable library file.
This interface allows programmers to develop additional functionality for VDR completely
separate from the core VDR source, without the need of patching the original
VDR code (and all the problems of correlating various patches).
<p>
This document is divided into two parts, the first one describing the
<a href="#Part I - The External Interface"><i>external</i> interface</a>
of the plugin system, and the second one describing the
<a href="#Part II - The Internal Interface"><i>internal</i> interface</a>.
The <i>external</i> interface handles everything necessary for a plugin to get hooked into the core
VDR program and present itself to the user.
The <i>internal</i> interface provides the plugin code access to VDR's internal data
structures and allows it to hook itself into specific areas to perform special actions.
<hr>
<h1>Table Of Contents</h1>
<ul>
<li><a href="#Part I - The External Interface">Part I - The External Interface</a>
<ul>
<li><a href="#Quick start">Quick start</a>
<li><a href="#The name of the plugin">The name of the plugin</a>
<li><a href="#The plugin directory structure">The plugin directory structure</a>
<li><a href="#Initializing a new plugin directory">Initializing a new plugin directory</a>
<li><a href="#The actual implementation">The actual implementation</a>
<li><a href="#Construction and Destruction">Construction and Destruction</a>
<li><a href="#Version number">Version number</a>
<li><a href="#Description">Description</a>
<li><a href="#Command line arguments">Command line arguments</a>
<li><a href="#Command line help">Command line help</a>
<li><a href="#Getting started">Getting started</a>
<li><a href="#Shutting down">Shutting down</a>
<li><a href="#Logging">Logging</a>
<li><a href="#Main menu entry">Main menu entry</a>
<li><a href="#User interaction">User interaction</a>
<li><a href="#Housekeeping">Housekeeping</a>
<li><a href="#Activity">Activity</a>
<li><a href="#Wakeup">Wakeup</a>
<li><a href="#Setup parameters">Setup parameters</a>
<li><a href="#The Setup menu">The Setup menu</a>
<li><a href="#Additional files">Additional files</a>
<li><a href="#Internationalization">Internationalization</a>
<li><a href="#Custom services">Custom services</a>
<li><a href="#SVDRP commands">SVDRP commands</a>
<li><a href="#Locking">Locking</a>
<li><a href="#Loading plugins into VDR">Loading plugins into VDR</a>
<li><a href="#Building the distribution package">Building the distribution package</a>
</ul>
<li><a href="#Part II - The Internal Interface">Part II - The Internal Interface</a>
<ul>
<li><a href="#Status monitor">Status monitor</a>
<li><a href="#Players">Players</a>
<li><a href="#Receivers">Receivers</a>
<li><a href="#Filters">Filters</a>
<li><a href="#The On Screen Display">The On Screen Display</a>
<li><a href="#Skins">Skins</a>
<li><a href="#Themes">Themes</a>
<li><a href="#Devices">Devices</a>
<li><a href="#Positioners">Positioners</a>
<li><a href="#Audio">Audio</a>
<li><a href="#Remote Control">Remote Control</a>
<li><a href="#Conditional Access">Conditional Access</a>
<li><a href="#Electronic Program Guide">Electronic Program Guide</a>
<li><a href="#The video directory">The video directory</a>
</ul>
</ul>
<hr><h1 class="center"><a name="Part I - The External Interface">Part I - The External Interface</a></h1>
<hr><h2><a name="Quick start">Quick start</a></h2>
<div class="blurb">Can't wait, can't wait!</div><p>
Actually you should read this entire document before starting to work with VDR plugins,
but you probably want to see something happening right away <tt>;-)</tt>
<p>
So, for a quick demonstration of the plugin system, there is a sample plugin called
"hello" that comes with the VDR source. To test drive this one, do the following:
<ul>
<li>change into the VDR source directory
<li><b><tt>make</tt></b> the VDR program with your usual <tt>REMOTE=...</tt> (and maybe other) options
<li>do <b><tt>make plugins</tt></b> to build the plugin
<li>run VDR with <b><tt>vdr -V</tt></b> to see the version information
<li>run VDR with <b><tt>vdr -h</tt></b> to see the command line options
<li>run VDR with <b><tt>vdr -Phello</tt></b>
<li>open VDR's main menu and select the <i>Hello</i> item
<li>open the <i>Setup</i> menu from VDR's main menu and select <i>Plugins</i>
</ul>
If you enjoyed this brief glimpse into VDR plugin handling, read through the rest of
this document and eventually write your own VDR plugin.
<hr><h2><a name="The name of the plugin">The name of the plugin</a></h2>
<div class="blurb">Give me some I.D.!</div><p>
One of the first things to consider when writing a VDR plugin is giving the thing
a proper name. This name will be used in the VDR command line in order to load
the plugin, and will also be the name of the plugin's source directory, as well
as part of the final library name.
<p>
The plugin's name should typically be as short as possible. Three letter
abbreviations like <b><tt>dvd</tt></b> (for a DVD player) or <b><tt>mp3</tt></b>
(for an MP3 player) would be good choices. It is also recommended that the name
consists of only lowercase letters and digits.
No other characters should be used here.
<p>
A plugin can access its name through the (non virtual) member function
<p><table><tr><td class="code"><pre>
const char *Name(void);
</pre></td></tr></table><p>
The actual name is derived from the plugin's library file name, as defined in the
next chapter.
<hr><h2><a name="The plugin directory structure">The plugin directory structure</a></h2>
<div class="blurb">Where is everybody?</div><p>
By default plugins are located in a directory named <tt>PLUGINS</tt> below the
VDR source directory. Inside this directory the following subdirectory structure
is used:
<p><table><tr><td class="code"><pre>
VDR/PLUGINS/src
VDR/PLUGINS/src/hello
VDR/PLUGINS/lib
VDR/PLUGINS/lib/libvdr-hello.so.1
</pre></td></tr></table><p>
The <tt>src</tt> directory contains one subdirectory for each plugin, which carries
the name of that plugin (in the above example that would be <tt>hello</tt>).
What's inside the individual source directory of a
plugin is entirely up to the author of that plugin. The only prerequisites are
that there is a <tt>Makefile</tt> that provides the targets <tt>all</tt>, <tt>install</tt> and
<tt>clean</tt>, and that a call to <tt>make all</tt> actually produces a dynamically
loadable library file for that plugin (we'll get to the details later).
The dynamically loadable library file for the plugin shall be located directly under
the plugin's source directory.
See the section <a href="#Initializing a new plugin directory">Initializing a new plugin directory</a>
for how to generate an example Makefile.
<p>
The <tt>lib</tt> directory contains the dynamically loadable libraries of all
available plugins. Note that the names of these files are created by concatenating
<p>
<table border=2>
<tr><td align=center><b><tt>libvdr-</tt></b></td><td align=center><b><tt>hello</tt></b></td><td align=center><b><tt>.so.</tt></b></td><td align=center><b><tt>1</tt></b></td></tr>
<tr><td align=center><small>VDR plugin<br>library prefix</small></td><td align=center><small>name of<br>the plugin</small></td><td align=center><small>shared object<br>indicator</small></td><td align=center><small>API version number<br>this plugin was<br>compiled for</small></td></tr>
</table>
<p>
The <i>API version number</i> refers to the plugin API version number of the VDR
version this plugin was compiled with. Compiled plugins can run with newer versions
of VDR as long as their plugin API version number is still the same as that of
the current VDR version. That way minor fixes to VDR, that don't require changes
to the VDR header files, can be made without requiring all plugins to be
recompiled.
<p>
While in earlier versions of VDR the API version number was closely related to the
VDR version number, starting with VDR version 2.7.2 the API version number was changed
from a dot separated, three part number to a single integer, completely unrelated to
the VDR version. This was done to avoid confusion.
<p>
The plugin library files can be stored in any directory. If the default organization
is not used, the path to the plugin directory has be be given to VDR through the
<b><tt>-L</tt></b> option.
<p>
The VDR <tt>Makefile</tt> contains the target <tt>plugins</tt>, which calls
<tt>make all</tt> in every directory found under <tt>VDR/PLUGINS/src</tt>,
plus the target <tt>clean-plugins</tt>, which calls <tt>make clean</tt> in
each of these directories.
<p>
If you download a plugin <a href="#Building the distribution package">package</a>
from the web, it will typically have a name like
<p>
<tt>vdr-hello-0.0.1.tgz</tt>
<p>
and will unpack into a directory named
<p>
<tt>hello-0.0.1</tt>
<p>
To use the <tt>plugins</tt> and <tt>clean-plugins</tt> targets from the VDR <tt>Makefile</tt>
you need to unpack such an archive into the <tt>VDR/PLUGINS/src</tt> directory and
create a symbolic link with the basic plugin name, as in
<p><table><tr><td class="code"><pre>
ln -s hello-0.0.1 hello
</pre></td></tr></table><p>
Since the VDR <tt>Makefile</tt> only searches for directories with names consisting
of only lowercase characters and digits, it will only follow the symbolic links, which
should lead to the current version of the plugin you want to use. This way you can
have several different versions of a plugin source (like <tt>hello-0.0.1</tt> and
<tt>hello-0.0.2</tt>) and define which one to actually use through the symbolic link.
<p>
If a plugin needs library files of its own, it can copy them to the <tt>lib</tt>
directory following the naming convention <tt>lib<i>name</i>-<i>library</i>.so.0.0.1</tt>,
where <i>name</i> is the name of the plugin, and <i>library</i> identifies the
plugin's additional library. If the plugin <tt>hello</tt> would require the two
additional libraries <tt>foo</tt> and <tt>bar</tt>, the names would be
<p>
<tt>libhello-foo.so.0.0.1</tt><br>
<tt>libhello-bar.so.0.0.1</tt>
<p>
<hr><h2><a name="Initializing a new plugin directory">Initializing a new plugin directory</a></h2>
<div class="blurb">A room with a view</div><p>
Call the Perl script <tt>newplugin</tt> from the VDR source directory to create
a new plugin directory with a <tt>Makefile</tt> and a main source file implementing
the basic derived plugin class.
You will also find a <tt>README</tt> file there with some initial text, where you
should fill in actual information about your project.
A <tt>HISTORY</tt> file is set up with an "Initial revision" entry. As your project
evolves, you should add the changes here with date and version number.
<p>
<tt>newplugin</tt> also creates a copy of the GPL license file <tt>COPYING</tt>,
assuming that you will release your work under that license. Change this if you
have other plans.
<p>
Add further files and maybe subdirectories to your plugin source directory as
necessary. Don't forget to adapt the <tt>Makefile</tt> appropriately.
<hr><h2><a name="The actual implementation">The actual implementation</a></h2>
<div class="blurb">Use the source, Luke!</div><p>
A newly initialized plugin doesn't really do very much yet.
If you <a href="#Loading plugins into VDR">load it into VDR</a> you will find a new
entry in the main menu, with the same name as your plugin (where the first character
has been converted to uppercase). There will also be a new entry named "Plugins" in
the "Setup" menu, which will bring up a list of all loaded plugins, through which you
can access each plugin's own setup parameters (if it provides any).
<p>
To implement actual functionality into your plugin you need to edit the source file
that was generated as <tt>PLUGINS/src/name.c</tt>. Read the comments in that file
to see where you can bring in your own code. The following sections of this document
will walk you through the individual member functions of the plugin class.
<p>
Depending on what your plugin shall do, you may or may not need all of the given
member functions. Except for the <tt>MainMenuEntry()</tt> function they all by default
return values that will result in no actual functionality. You can either completely
delete unused functions from your source file, or just leave them as they are.
If your plugin shall not be accessible through VDR's main menu, simply remove
(or comment out) the line implementing the <tt>MainMenuEntry()</tt> function.
<p>
At the end of the plugin's source file you will find a line that looks like this:
<p><table><tr><td class="code"><pre>
VDRPLUGINCREATOR(cPluginHello);
</pre></td></tr></table><p>
This is the "magic" hook that allows VDR to actually load the plugin into
its memory. You don't need to worry about the details behind all this.
<p>
If your plugin requires additional source files, simply add them to your plugin's
source directory and adjust the <tt>Makefile</tt> accordingly.
<p>
Header files usually contain preprocessor statements that prevent the same
file (or rather its contents, to be precise) from being included more than once, like
<p><table><tr><td class="code"><pre>
#ifndef __I18N_H
#define __I18N_H
...
#endif //__I18N_H
</pre></td></tr></table><p>
The example shown here is the way VDR does this in its core source files.
It takes the header file's name, converts it to all uppercase, replaces the
dot with an underline and precedes the whole thing with two underlines.
The GNU library header files do this pretty much the same way, except that they
usually precede the name with only one underline (there are exceptions, though).
<p>
As long as you make sure that none of your plugin's header files will be named
like one of VDR's header files, you can use the same method as VDR. However,
if you want to name a header file like one that is already existing in VDR's
source (<tt>i18n.h</tt> would be a possible candidate for this), you may want
to make sure that the macros used here don't clash. How you do this is completely
up to you. You could, for instance, prepend the macro with a <tt>'P'</tt>, as in
<tt>P__I18N_H</tt>, or leave out the trailing <tt>_H</tt>, as in <tt>__I18N</tt>,
or use a completely different way to make sure a header file is included only once.
<p>
The 'hello' example that comes with VDR makes use of <a href="#Internationalization">internationalization</a>
and implements a file named <tt>i18n.h</tt>. To make sure it won't clash with VDR's
<tt>i18n.h</tt> it uses the macro <tt>_I18N__H</tt> (one underline at the beginning
and two replacing the dot).
<hr><h2><a name="Construction and Destruction">Construction and Destruction</a></h2>
<div class="blurb">What goes up, must come down...</div><p>
The constructor and destructor of a plugin are defined as
<p><table><tr><td class="code"><pre>
cPlugin(void);
virtual ~cPlugin();
</pre></td></tr></table><p>
The <b>constructor</b> shall initialize any member variables the plugin defines, but
<b>must not access any global structures of VDR</b>.
It also must not create any threads or other large data structures. These things
are done in the
<a href="#Getting started"><tt>Initialize()</tt></a> or
<a href="#Getting started"><tt>Start()</tt></a>
function later.
Constructing a plugin object shall not have any side effects or produce any output,
since VDR, for instance, has to create the plugin objects in order to get their
command line help - and after that immediately destroys them again.
<p>
The <b>destructor</b> has to clean up any data created by the plugin.
Any threads the plugin may have created shall be stopped in the
<a href="#Shutting down"><tt>Stop()</tt></a> function.
<p>
Of course, if your plugin doesn't define any member variables that need to be
initialized (and deleted), you don't need to implement either of these functions.
<hr><h2><a name="Version number">Version number</a></h2>
<div class="blurb">Which incarnation is this?</div><p>
Every plugin must have a version number of its own, which does not necessarily
have to be in any way related to the VDR version number.
VDR requests a plugin's version number through a call to the function
<p><table><tr><td class="code"><pre>
virtual const char *Version(void) = 0;
</pre></td></tr></table><p>
Since this is a "pure" virtual function, any derived plugin class <b>must</b>
implement it. The returned string should identify this version of the plugin.
Typically this would be something like "0.0.1", but it may also contain other
information, like for instance "0.0.1pre2" or the like. The string should only
be as long as really necessary, and shall not contain the plugin's name itself.
Here's an example:
<p><table><tr><td class="code"><pre>
static const char *VERSION = "0.0.1";
const char *cPluginHello::Version(void)
{
return VERSION;
}
</pre></td></tr></table><p>
Note that the definition of the version number is expected to be located in the
main source file, and must be written as
<pre>
static const char *VERSION = ...
</pre>
<p>
just like shown in the above example. This is a convention that allows the <tt>Makefile</tt>
to extract the version number when generating the file name for the distribution archive.
<p>
A new plugin project should start with version number <tt>0.0.1</tt> and should reach
version <tt>1.0.0</tt> once it is completely operative and well tested.
<hr><h2><a name="Description">Description</a></h2>
<div class="blurb">What is it that you do?</div><p>
In order to tell the user what exactly a plugin does, it must implement the function
<p><table><tr><td class="code"><pre>
virtual const char *Description(void) = 0;
</pre></td></tr></table><p>
which returns a short, one line description of the plugin's purpose:
<p><table><tr><td class="code"><pre>
static const char *DESCRIPTION = "A friendly greeting";
virtual const char *Description(void)
{
return tr(DESCRIPTION);
}
</pre></td></tr></table><p>
Note the <tt>tr()</tt> around the <tt>DESCRIPTION</tt>, which allows the description
to be <a href="#Internationalization">internationalized</a>.
<hr><h2><a name="Command line arguments">Command line arguments</a></h2>
<div class="blurb">Taking orders</div><p>
A VDR plugin can have command line arguments just like any normal program.
If a plugin wants to react on command line arguments, it needs to implement
the function
<p><table><tr><td class="code"><pre>
virtual bool ProcessArgs(int argc, char *argv[]);
</pre></td></tr></table><p>
The parameters <tt>argc</tt> and <tt>argv</tt> have exactly the same meaning
as in a normal C program's <tt>main()</tt> function.
<tt>argv[0]</tt> contains the name of the plugin (as given in the <b><tt>-P</tt></b>
option of the <tt>vdr</tt> call).
<p>
Each plugin has its own set of command line options, which are totally independent
from those of any other plugin or VDR itself.
<p>
You can use the <tt>getopt()</tt> or <tt>getopt_long()</tt> function to process
these arguments. As with any normal C program, the strings pointed to by <tt>argv</tt>
will survive the entire lifetime of the plugin, so it is safe to store pointers to
these values inside the plugin. Here's an example:
<p><table><tr><td class="code"><pre>
bool cPluginHello::ProcessArgs(int argc, char *argv[])
{
// Implement command line argument processing here if applicable.
static struct option long_options[] = {
{ "aaa", required_argument, NULL, 'a' },
{ "bbb", no_argument, NULL, 'b' },
{ NULL }
};
int c;
while ((c = getopt_long(argc, argv, "a:b", long_options, NULL)) != -1) {
switch (c) {
case 'a': option_a = optarg;
break;
case 'b': option_b = true;
break;
default: return false;
}
}
return true;
}
</pre></td></tr></table><p>
The return value must be <i>true</i> if all options have been processed
correctly, or <i>false</i> in case of an error. The first plugin that returns
<i>false</i> from a call to its <tt>ProcessArgs()</tt> function will cause VDR
to exit.
<hr><h2><a name="Command line help">Command line help</a></h2>
<div class="blurb">Tell me about it...</div><p>
If a plugin accepts command line options, it should implement the function
<p><table><tr><td class="code"><pre>
virtual const char *CommandLineHelp(void);
</pre></td></tr></table><p>
which will be called if the user enters the <b><tt>-h</tt></b> option when starting VDR.
The returned string should contain the command line help for this plugin, formatted
in the same way as done by VDR itself:
<p><table><tr><td class="code"><pre>
const char *cPluginHello::CommandLineHelp(void)
{
// Return a string that describes all known command line options.
return " -a ABC, --aaa=ABC do something nice with ABC\n"
" -b, --bbb activate 'plan B'\n";
}
</pre></td></tr></table><p>
This command line help will be printed directly below VDR's help texts (separated
by a line indicating the plugin's name, version and description), so if you use the
same formatting as shown here it will line up nicely.
Note that all lines should be terminated with a newline character, and should
be shorter than 80 characters.
<hr><h2><a name="Getting started">Getting started</a></h2>
<div class="blurb">Let's get ready to rumble!</div><p>
If a plugin implements a function that runs in the background (presumably in a
thread of its own), or wants to make use of <a href="#Internationalization">internationalization</a>,
it needs to implement one of the functions
<p><table><tr><td class="code"><pre>
virtual bool Initialize(void);
virtual bool Start(void);
</pre></td></tr></table><p>
which are called once for each plugin at program startup.
The difference between these two functions is that <tt>Initialize()</tt> is
called early at program startup, while <tt>Start()</tt> is called after the primary
device and user interface has been set up, but before the main program loop is entered.
Inside the <tt>Start()</tt> function of any plugin it is guaranteed that the <tt>Initialize()</tt>
functions of all plugins have already been called. For many plugins it probably
doesn't matter which of these functions they implement, but it may be of importance
for, e.g., plugins that implement devices. Such plugins should create their cDevice
derived objects in <tt>Initialize()</tt>, so that other plugins can use them in their
<tt>Start()</tt> functions.
<p>
Inside this function the plugin must set up everything necessary to perform
its task. This may, for instance, be a thread that collects data from the DVB
stream, which is later presented to the user via a function that is available
from the main menu.
<p>
A return value of <i>false</i> indicates that something has gone wrong and the
plugin will not be able to perform its task. In that case, the plugin should
write a proper error message to the log file. The first plugin that returns
<i>false</i> from its <tt>Initialize()</tt> or <tt>Start()</tt> function will cause
VDR to exit.
<p>
If the plugin doesn't implement any background functionality or internationalized
texts, it doesn't need to implement either of these functions.
<hr><h2><a name="Shutting down">Shutting down</a></h2>
<div class="blurb">Stop it, right there!</div><p>
If a plugin performs any background tasks, it shall implement the function
<p><table><tr><td class="code"><pre>
virtual void Stop(void);
</pre></td></tr></table><p>
in which it shall stop them.
<p>
The <tt>Stop()</tt> function will only be called if a previous call to the
<a href="#Getting started"><tt>Start()</tt></a> function of that plugin has
returned <i>true</i>. The <tt>Stop()</tt> functions are called in the reverse order
as the <a href="#Getting started"><tt>Start()</tt></a> functions were called.
<hr><h2><a name="Logging">Logging</a></h2>
<div class="blurb">Traces in the sand...</div><p>
<p>
If the plugin should print log messages, you can use <tt>dsyslog()</tt>, <tt>isyslog()</tt> or <tt>esyslog()</tt>.<br>
<ul>
<li><tt>dsyslog()</tt> prints the log message only if the log level of vdr is set to 3.
<li><tt>isyslog()</tt> prints the log message only if the log level of vdr is set to 2 or above.
<li><tt>esyslog()</tt> prints the log message only if the log level of vdr is set to 1 or above.
</ul>
The output of this log is the syslog of the system vdr is running on.
The log message can be formatted like <tt>printf()</tt>, as in
<p><table><tr><td class="code"><pre>
esyslog("pluginname: error #%d has occurred", ErrorNumber);
</pre></td></tr></table><p>
Note that the log messages will be given as provided, the plugin's name will not
automatically be added, so make sure your log messages are obvious enough.
<p>
Only use the above logging functions for occasional log messages. Do not use
them unconditionally for frequent messages that produce long sequences of lines
in the log file every few seconds. That might make it hard to work on other plugins
or the core VDR code, watching their log entries while they are permanently
interspersed with unrelated stuff.<br>
<br>
The recommended behavior for a plugin that does logging is to implement a command
line option that controls the level of log messages, preferably '-l N, --log=N',
where 'N' is in the range 0...3, with 0 meaning no logging whatsoever, 1 log only
errors, 2 log errors and informational messages, and 3 also log debug information.<br>
<br>
If a plugin can output extensive data for special debugging purposes (either to
the log file or stdout/stderr), this should be enabled by setting proper switches
in one of its source files (see for example how the communication between VDR and
CAMs can be monitored in VDR/ci.c).<br>
<br>
Under no circumstances must a plugin print anything to stdout or stderr during
normal operation! The only exceptions being special debug information as described
above, fatal error messages that will cause VDR to abort, or if it is the sole
purpose of the plugin to display something on stdout, like for instance the
<i>skincurses</i> plugin, which displays the OSD at the console.<br>
<br>
Please make any log messages in <b>ENGLISH</b>! Logs are usually sent to the developers
of a program, and they may not be able to read them if they are in an exotic language.
<hr><h2><a name="Main menu entry">Main menu entry</a></h2>
<div class="blurb">Today's special is...</div><p>
If the plugin implements a feature that the user shall be able to access
from VDR's main menu, it needs to implement the function
<p><table><tr><td class="code"><pre>
virtual const char *MainMenuEntry(void);
</pre></td></tr></table><p>
The default implementation returns a <tt>NULL</tt> pointer, which means that
this plugin will not have an item in the main menu. Here's an example of a
plugin that will have a main menu item:
<p><table><tr><td class="code"><pre>
static const char *MAINMENUENTRY = "Hello";
const char *cPluginHello::MainMenuEntry(void)
{
return tr(MAINMENUENTRY);
}
</pre></td></tr></table><p>
The menu entries of all plugins will be inserted into VDR's main menu right
after the <i>Recordings</i> item, in the same sequence as they were given
in the call to VDR.
<hr><h2><a name="User interaction">User interaction</a></h2>
<div class="blurb">It's showtime!</div><p>
If the user selects the main menu entry of a plugin, VDR calls the function
<p><table><tr><td class="code"><pre>
virtual cOsdObject *MainMenuAction(void);
</pre></td></tr></table><p>
which can do one of three things:
<ul>
<li>Return a pointer to a <tt>cOsdMenu</tt> object which will be displayed
as a submenu of the main menu (just like the <i>Recordings</i> menu, for instance).
That menu can then implement further functionality and, for instance, could
eventually start a custom player to replay a file other than a VDR recording.
<li>Return a pointer to a <tt>cOsdObject</tt> object which will be displayed
instead of the normal menu. The derived <tt>cOsdObject</tt> can open a
<a href="#The On Screen Display">raw OSD</a> from within its <tt>Show()</tt>
function (it should not attempt to do so from within its constructor, since
at that time the OSD is still in use by the main menu).
See the 'osddemo' example that comes with VDR for a demonstration of how this
is done.
<li>Perform a specific action and return <tt>NULL</tt>. In that case the main menu
will be closed after calling <tt>MainMenuAction()</tt>.
</ul>
<b>
It is very important that a call to <tt>MainMenuAction()</tt> returns as soon
as possible! As long as the program stays inside this function, no other user
interaction is possible. If a specific action takes longer than a few seconds,
the plugin should launch a separate thread to do this.
</b>
<hr><h2><a name="Housekeeping">Housekeeping</a></h2>
<div class="blurb">Chores, chores...</div><p>
From time to time a plugin may want to do some regular tasks, like cleaning
up some files or other things. In order to do this it can implement the function
<p><table><tr><td class="code"><pre>
virtual void Housekeeping(void);
</pre></td></tr></table><p>
which gets called when VDR is otherwise idle. The intervals between subsequent
calls to this function are not defined. There may be several hours between two
calls (if, for instance, there are recordings or replays going on) or they may
be as close as ten seconds. The only thing that is guaranteed is that there are
at least ten seconds between two subsequent calls to the <tt>Housekeeping()</tt>
function of the same plugin.
<p>
<b>
It is very important that a call to <tt>Housekeeping()</tt> returns as soon
as possible! As long as the program stays inside this function, no other user
interaction is possible. If a specific action takes longer than a few seconds,
the plugin should launch a separate thread to do this.
</b>
<hr><h2><a name="Activity">Activity</a></h2>
<div class="blurb">Now is not a good time!</div><p>
If a plugin is running a background task that should be finished before shutting
down the system, it can implement the function
<p><table><tr><td class="code"><pre>
virtual cString Active(void);
</pre></td></tr></table><p>
which shall return an empty string if it is ok to shut down, and a proper message
if not:
<p><table><tr><td class="code"><pre>
cString cDoSomethingPlugin::Active(void)
{
if (busy)
return tr("Doing something");
return NULL;
}
</pre></td></tr></table><p>
The message should be short and should indicate what is currently going on.
It will be presented to the user as a confirmation message, followed by a
hyphen and a "shut down anyway?" prompt, as in
<p>
<b>Doing something - shut down anyway?</b>
<p>
All plugins will be queried, and the first one that returns a non empty
string will cause the confirmation message to be shown. If the user confirms
the prompt by pressing the "Ok" button, the rest of the plugins will also
be queried, and further prompts may show up. If all prompts have been confirmed,
the shutdown will take place. As soon as one prompt is not confirmed, no
further plugins will be queried and no shutdown will be done.
<hr><h2><a name="Wakeup">Wakeup</a></h2>
<div class="blurb">Wake me up before you go-go</div><p>
If a plugin wants to schedule activity for a later time, or wants to perform
periodic activity at a certain time at night, and if VDR shall wake up from
shutdown at that time, the plugin can implement the function
<p><table><tr><td class="code"><pre>
virtual time_t WakeupTime(void);
</pre></td></tr></table><p>
which shall return the time of the next custom wakeup time, or 0 if no wakeup
is planned. VDR will pass the most recent wakeup time of all plugins, or the next
timer time, whichever comes first, to the shutdown script. The following sample
will wake up VDR every night at 1:00:
<p><table><tr><td class="code"><pre>
time_t MyPlugin::WakeupTime(void)
{
time_t Now = time(NULL);
time_t Time = cTimer::SetTime(Now, cTimer::TimeToInt(100));
if (Time <= Now)
Time = cTimer::IncDay(Time, 1);
return Time;
}
</pre></td></tr></table><p>
After wakeup, the plugin shall continue to return the wakeup time and shall
return a string when <tt>Active()</tt> is called at that time, otherwise VDR may shut down
again instantly. If <tt>WakeupTime()</tt> returns a time that is not in
the future, the time will be ignored.
<hr><h2><a name="Setup parameters">Setup parameters</a></h2>
<div class="blurb">Remember me...</div><p>
If a plugin requires its own setup parameters, it needs to implement the following
functions to handle these parameters:
<p><table><tr><td class="code"><pre>
virtual cMenuSetupPage *SetupMenu(void);
virtual bool SetupParse(const char *Name, const char *Value);
</pre></td></tr></table><p>
The <tt>SetupMenu()</tt> function shall return the plugin's <a href="#The Setup menu"><i>Setup</i> menu</a>
page, where the user can adjust all the parameters known to this plugin.
<p>
<tt>SetupParse()</tt> will be called for each parameter the plugin has
previously stored in the global setup data (see below). It shall return
<i>true</i> if the parameter was parsed correctly, <i>false</i> in case of
an error. If <i>false</i> is returned, an error message will be written to
the log file (and program execution will continue).
A possible implementation of <tt>SetupParse()</tt> could look like this:
<p><table><tr><td class="code"><pre>
bool cPluginHello::SetupParse(const char *Name, const char *Value)
{
// Parse your own setup parameters and store their values.
if (!strcasecmp(Name, "GreetingTime")) GreetingTime = atoi(Value);
else if (!strcasecmp(Name, "UseAlternateGreeting")) UseAlternateGreeting = atoi(Value);
else
return false;
return true;
</pre></td></tr></table><p>
It is important to make sure that the parameter names are exactly the same as
used in the <a href="#The Setup menu"><i>Setup</i> menu</a>'s <tt>Store()</tt> function.
<p>
The plugin's setup parameters are stored in the same file as VDR's parameters.
In order to allow each plugin (and VDR itself) to have its own set of parameters,
the <tt>Name</tt> of each parameter will be preceded with the plugin's
name, as in
<p>
<tt>hello.GreetingTime = 3</tt>
<p>
The prefix will be handled by the core VDR setup code, so the individual
plugins need not worry about this.
<p>
To store its values in the global setup, a plugin has to call the function
<p><table><tr><td class="code"><pre>
void SetupStore(const char *Name, <i>type</i> Value);
</pre></td></tr></table><p>
where <tt>Name</tt> is the name of the parameter (<tt>"GreetingTime"</tt> in the above
example, without the prefix <tt>"hello."</tt>) and <tt>Value</tt> is a simple data type (like
<tt>char *</tt>, <tt>int</tt> etc).
Note that this is not a function that the individual plugin class needs to implement!
<tt>SetupStore()</tt> is a non-virtual member function of the <tt>cPlugin</tt> class.
<p>
To remove a parameter from the setup data, call <tt>SetupStore()</tt> with the appropriate
name and without any value, as in
<p>
<tt>SetupStore("GreetingTime");</tt>
<p>
The VDR menu "Setup/Plugins" will list all loaded plugins with their name,
version number and description. Selecting an item in this list will bring up
the plugin's "Setup" menu if that plugin has implemented the <tt>SetupMenu()</tt>
function.
<p>
Finally, a plugin doesn't have to implement the <tt>SetupMenu()</tt> if it only
needs setup parameters that are not directly user adjustable. It can use
<tt>SetupStore()</tt> and <tt>SetupParse()</tt> without presenting these
parameters to the user.
<hr><h2><a name="The Setup menu">The Setup menu</a></h2>
<div class="blurb">Have it your way!</div><p>
To implement a <i>Setup</i> menu, a plugin needs to derive a class from
<tt>cMenuSetupPage</tt> and implement its constructor and the pure virtual
<tt>Store()</tt> member function:
<p><table><tr><td class="code"><pre>
int GreetingTime = 3;
int UseAlternateGreeting = false;
class cMenuSetupHello : public cMenuSetupPage {
private:
int newGreetingTime;
int newUseAlternateGreeting;
protected:
virtual void Store(void);
public:
cMenuSetupHello(void);
};
cMenuSetupHello::cMenuSetupHello(void)
{
newGreetingTime = GreetingTime;
newUseAlternateGreeting = UseAlternateGreeting;
Add(new cMenuEditIntItem( tr("Greeting time (s)"), &newGreetingTime));
Add(new cMenuEditBoolItem(tr("Use alternate greeting"), &newUseAlternateGreeting));
}
void cMenuSetupHello::Store(void)
{
SetupStore("GreetingTime", GreetingTime = newGreetingTime);
SetupStore("UseAlternateGreeting", UseAlternateGreeting = newUseAlternateGreeting);
}
</pre></td></tr></table><p>
In this example we have two global setup parameters (<tt>GreetingTime</tt> and <tt>UseAlternateGreeting</tt>).
The constructor initializes two private members with the values of these parameters, so
that the <i>Setup</i> menu can work with temporary copies (in order to discard any changes
if the user doesn't confirm them by pressing the "Ok" button).
After this the constructor adds the appropriate menu items, using internationalized texts
and the addresses of the temporary variables. That's all there is to initialize a <i>Setup</i>
menu - the rest will be done by the core VDR code.
<p>
Once the user has pressed the "Ok" button to confirm the changes, the <tt>Store()</tt> function will
be called, in which all setup parameters must be actually stored in VDR's global setup data.
This is done by calling the <tt>SetupStore()</tt> function for each of the parameters.
The <i>Name</i> string given here will be used to identify the parameter in VDR's
<tt>setup.conf</tt> file, and will be automatically prepended with the plugin's name.
<p>
Note that in this small example the new values of the parameters are copied into the
global variables within each <tt>SetupStore()</tt> call. This is not mandatory, however.
You can first assign the temporary values to the global variables and then do the
<tt>SetupStore()</tt> calls, or you can define a class or struct that contains all
your setup parameters and use that one to copy all parameters with one single statement
(like VDR does with its cSetup class).
<hr><h2><a name="Additional files">Additional files</a></h2>
<div class="blurb">I want my own stuff!</div><p>
There may be situations where a plugin requires files of its own. While the plugin is
free to store such files anywhere it sees fit, it might be a good idea to put them in a common
place, preferably where such data already exists.
<p>
<i>configuration files</i>, maybe for data that can't be stored in the simple
<a href="#Setup parameters">setup parameters</a> of VDR, or maybe because it needs to
launch other programs that simply need a separate configuration file.
<p>
<i>cache files</i>, to store data so that future requests for that data can be served faster. The data
that is stored within a cache might be values that have been computed earlier or duplicates of
original values that are stored elsewhere.
<p>
<i>resource files</i>, for providing additional files, like pictures, movie clips or channel logos.
<p>
Therefore VDR provides the functions
<p><table><tr><td class="code"><pre>
const char *ConfigDirectory(const char *PluginName = NULL);
const char *CacheDirectory(const char *PluginName = NULL);
const char *ResourceDirectory(const char *PluginName = NULL);
</pre></td></tr></table><p>
each of which returns a string containing the directory that VDR uses for its own
files (defined through the options in the call to VDR), extended by
<tt>"/plugins"</tt>. So assuming the VDR configuration directory is <tt>/video</tt>
(the default if no <tt><b>-c</b></tt> or <tt><b>-v</b></tt> option is given),
a call to <tt>ConfigDirectory()</tt> will return <tt>/video/plugins</tt>. The first
call to <tt>ConfigDirectory()</tt> will automatically make sure that the <tt>plugins</tt>
subdirectory will exist. If, for some reason, this cannot be achieved, <tt>NULL</tt>
will be returned.
The behavior of <tt>CacheDirectory()</tt> and <tt>ResourceDirectory()</tt> is similar.
<p>
The additional <tt>plugins</tt> directory is used to keep files from plugins apart
from those of VDR itself, making sure there will be no name clashes. If a plugin
needs only one extra file, it is suggested that this file be named <tt>name.*</tt>,
where <i>name</i> shall be the name of the plugin.
<p>
If a plugin needs more than one such file, it is suggested that the plugin stores
these in a subdirectory of its own, named after the plugin. To easily get such a name
the functions can be given an additional string that will be appended to the returned
directory name, as in
<p><table><tr><td class="code"><pre>
const char *MyConfigDir = ConfigDirectory(Name());
</pre></td></tr></table><p>
where <tt>Name()</tt> is the member function of the plugin class that returns the
plugin's name. Again, VDR will make sure that the requested directory will exist
(or return <tt>NULL</tt> in case of an error).
<p>
<b>
The returned strings are statically allocated and will be overwritten by subsequent calls!
</b>
<p>
The <tt>ConfigDirectory()</tt>, <tt>CacheDirectory()</tt> and <tt>ResourceDirectory()</tt>
functions are static member functions of the <tt>cPlugin</tt> class. This allows them to be
called even from outside any member function of the derived plugin class, by writing
<p><table><tr><td class="code"><pre>
const char *MyConfigDir = cPlugin::ConfigDirectory();
</pre></td></tr></table><p>
<hr><h2><a name="Internationalization">Internationalization</a></h2>
<div class="blurb">Welcome to Babylon!</div><p>
If a plugin displays texts to the user, it should prepare for internationalization
of these texts. All that is necessary for this is to mark every text that is
presented to the user as translatable, as in
<p><table><tr><td class="code"><pre>
const char *s = tr("Hello world!");
</pre></td></tr></table><p>
The text given here must be the English version, and the returned pointer is either
a translated version (if available) or the original string.
Texts are searched for in the domain registered for this plugin.
If a plugin wants to make use of texts defined by the core VDR code, it can use
the special <tt>trVDR()</tt> macro to mark these texts without having them
appear in its own translation file.
<p>
Sometimes texts are stored in an array, in which case they need to be marked
differently, using the trNOOP() macro. The actual translation is then done
when such a text is used, as in
<p><table><tr><td class="code"><pre>
const char *Texts = {
trNOOP("First text"),
trNOOP("Second text"),
trNOOP("Third one")
};
for (int i = 0; i < 3; i++)
MyFunc(tr(Texts[i]));
</pre></td></tr></table><p>
<p>
The system VDR is running on may use a character encoding where a single character
(or <i>symbol</i>) consists of more than one byte (UTF-8, as opposed to, for instance,
ISO8859-1, where every character is represented by a single byte in memory).
In order to make sure a plugin works regardless of the character encoding the current
system uses, the VDR core code provides several functions and macros that allow accessing
text strings transparently without knowing whether this is a single or multi byte