-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.upnp.html
7221 lines (7034 loc) · 811 KB
/
service.upnp.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
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>111 Device Service Specification for UPnP™ Technology - OSGi Compendium 8</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
<link rel="home" href="index.html" title="OSGi Compendium" />
<link rel="up" href="index.html" title="OSGi Compendium" />
<link rel="prev" href="service.wireadmin.html" title="108 Wire Admin Service Specification" />
<link rel="next" href="service.component.html" title="112 Declarative Services Specification" />
<meta name="Section-title" content="111 Device Service Specification for UPnP™ Technology" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="shortcut icon" href="images/favicon.png" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="css/custom.css" />
<link rel="stylesheet" type="text/css" href="css/github.css" />
<link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Ubuntu:regular,bold&subset=Latin" /><script type="text/javascript" src="js/highlight.pack.js"></script><script type="text/javascript" src="js/main.js"></script></head>
<body>
<div id="fullbody">
<div id="header">
<div class="menu-top-container"></div>
<div id="shadow-block"><a class="logo" href="index.html"><img src="images/OSGi.svg" alt="OSGi Working Group Documentation" /><h1>OSGi Compendium Release 8</h1></a></div>
</div>
<div id="mobile-menu-icon">⋮</div>
<div id="column-two">
<div id="content">
<div id="scrollable">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<td width="20%" align="left"><a accesskey="p" href="service.wireadmin.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.component.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter">
<div xmlns="" class="titlepage">
<div>
<div>
<h1 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="service.upnp"></a><span xmlns="" class="number">111</span> Device Service Specification for UPnP™ Technology
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp" title="111.16 org.osgi.service.upnp">Version 1.2</a></p>
</div>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e24701"></a><span xmlns="" class="number">111.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>The UPnP Device Architecture specification provides the protocols
for a peer-to-peer network. It specifies how to join a network and how
devices can be controlled using XML messages sent over HTTP. The OSGi
specifications address how code can be download and managed in a remote
system. Both standards are therefore fully complimentary. Using an OSGi
Framework to work with UPnP enabled devices is therefore a very successful
combination.
</p>
<p>This specification specifies how OSGi bundles can be developed that
interoperate with UPnP™ (Universal Plug and Play) devices and UPnP control
points. The specification is based on the UPnP Device Architecture and
does not further explain the UPnP specifications. The UPnP specifications
are maintained by <a xmlns="" class="xref" href="service.upnp.html#i1586441" title="Open Connectivity Foundation">[1] <em>Open Connectivity Foundation</em></a>.
</p>
<p>UPnP™ is a trademark of the UPnP Implementers Corporation.</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e24712"></a><span xmlns="" class="number">111.1.1</span> Essentials
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Scope</em></span> - This specification is limited to
device control aspects of the UPnP specifications. Aspects
concerning the TCP/IP layer, like DHCP and limited TTL, are not
addressed.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Transparency</em></span> - OSGi services should be
made available to networks with UPnP enabled devices in a
transparent way.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Network Selection</em></span> - It must be possible
to restrict the use of the UPnP protocols to a selection of the
connected networks. For example, in certain cases OSGi services that
are UPnP enabled should not be published to the Wide Area Network
side of a gateway, nor should UPnP devices be detected on this
WAN.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Event handling</em></span> - Bundles must be able to
listen to UPnP events.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Export OSGi services as UPnP devices</em></span> -
Enable bundles that make a service available to UPnP control
points.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Implement UPnP Control Points</em></span> - Enable
bundles that control UPnP devices.
</p>
</li>
</ul>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1527768"></a><span xmlns="" class="number">111.1.2</span> Entities
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>UPnP Base Driver</em></span> - The bundle that
implements the bridge between OSGi and UPnP networks. This entity is
not represented as a service.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Root Device</em></span> -A physical device can
contain one or more root devices. Root devices contain one ore more
devices. A root device is modeled with a <code class="code">UPnPDevice</code>
object, there is no separate interface defined for root
devices.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Device</em></span> - The representation of a
UPnP device. A UPnP device may contain other UPnP devices and UPnP
services. This entity is represented by a <code class="code">UPnPDevice</code>
object. A device can be local (implemented in the Framework) or
external (implemented by another device on the net).
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Service</em></span> -A UPnP device consists of a
number of services. A UPnP service has a number of UPnP state
variables that can be queried and modified with actions. This
concept is represented by a <code class="code">UPnPService</code> object.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Action</em></span> - A UPnP service is
associated with a number of actions that can be performed on that
service and that may modify the UPnP state variables. This entity is
represented by a <code class="code">UPnPAction</code> object.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP State Variable</em></span> - A variable
associated with a UPnP service, represented by a
<code class="code">UPnPStateVariable</code> object.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Local State Variable</em></span> - Extends the
<code class="code">UPnPStateVariable</code> interface when the state variable is
implemented locally. This interface provides access to the actual
value.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Event Listener Service</em></span> - A listener
to events coming from UPnP devices.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Host</em></span> - The machine that hosts the
code to run a UPnP device or control point.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Control Point</em></span> - A UPnP device that
is intended to control UPnP devices over a network. For example, a
UPnP remote controller.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Icon</em></span> - A representation class for an
icon associated with a UPnP device.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UPnP Exception</em></span> - An exception that
delivers errors that were discovered in the UPnP layer.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>UDN</em></span> - Unique Device Name, a name that
uniquely identifies the a specific device.
</p>
</li>
</ul>
</div>
<div class="figure"><a xmlns="" class="anchor" id="d0e24833"></a><p class="title"><strong>Figure <span xmlns="" class="number">111</span>.1 UPnP Service Specification class Diagram org.osgi.service.upnp
package</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/111-upnp-classes.png" align="middle" width="630" height="382" alt="UPnP Service Specification class Diagram org.osgi.service.upnp package" /></div>
</div>
</div><br class="figure-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e24839"></a><span xmlns="" class="number">111.1.3</span> Operation Summary
</h3>
</div>
</div>
</div>
<p>To make a UPnP service available to UPnP control points on a
network, an OSGi service object must be registered under the
<code class="code">UPnPDevice</code> interface with the Framework. The UPnP driver
bundle must detect these UPnP Device services and must make them
available to the network as UPnP devices using the UPnP protocol.
</p>
<p>UPnP devices detected on the local network must be detected and
automatically registered under the <code class="code">UPnPDevice</code> interface
with the Framework by the UPnP driver implementation bundle.
</p>
<p>A bundle that wants to control UPnP devices, for example to
implement a UPnP control point, should track UPnP Device services in the
OSGi service registry and control them appropriately. Such bundles
should not distinguish between resident or remote UPnP Device
services.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e24854"></a><span xmlns="" class="number">111.2</span> UPnP Specifications
</h2>
</div>
</div>
</div>
<p>The UPnP DA is intended to be used in a broad range of device from
the computing (PCs printers), consumer electronics (DVD, TV, radio),
communication (phones) to home automation (lighting control, security) and
home appliances (refrigerators, coffee makers) domains.
</p>
<p>For example, a UPnP TV might announce its existence on a network by
broadcasting a message. A UPnP control point on that network can then
discover this TV by listening to those announce messages. The UPnP
specifications allow the control point to retrieve information about the
user interface of the TV. This information can then be used to allow the
end user to control the remote TV from the control point, for example turn
it on or change the channels.
</p>
<p>The UPnP specification supports the following features:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Detect and control a UPnP standardized
device</em></span>. In this case the control point and the remote
device share a priori knowledge about how the device should be
controlled. The UPnP Forum intends to define a large number of these
standardized devices.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Use a user interface description</em></span>. A UPnP
control point receives enough information about a device and its
services to automatically build a user interface for it.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Programmatic Control</em></span>. A program can
directly control a UPnP device without a user interface. This control
can be based on detected information about the device or through a
priori knowledge of the device type.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Allows the user to browse a web page supplied by the
device</em></span>. This web page contains a user interface for the
device that be directly manipulated by the user. However, this option
is not well defined in the UPnP Device Architecture specification and
is not tested for compliance.
</p>
</li>
</ul>
</div>
<p>The UPnP Device Architecture specification and the OSGi Framework
provide <span class="emphasis"><em>complementary</em></span> functionality. The UPnP Device
Architecture specification is a data communication protocol that does not
specify where and how programs execute. That choice is made by the
implementations. In contrast, the OSGi Framework specifies a (managed)
execution point and does not define what protocols or media are supported.
The UPnP specification and the OSGi specifications are fully complementary
and do not overlap.
</p>
<p>From the OSGi perspective, the UPnP specification is a communication
protocol that can be implemented by one or more bundles. This
specification therefore defines the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>How an OSGi bundle can implement a service that is exported to
the network via the UPnP protocols.
</p>
</li>
<li class="listitem">
<p>How to find and control services that are available on the local
network.
</p>
</li>
</ul>
</div>
<p>The UPnP specifications related to the assignment of IP addresses to
new devices on the network or auto-IP self configuration should be handled
at the operating system level. Such functions are outside the scope of
this specification.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e24900"></a><span xmlns="" class="number">111.2.1</span> UPnP Base Driver
</h3>
</div>
</div>
</div>
<p>The functionality of the UPnP service is implemented in a UPnP
<span class="emphasis"><em>base driver</em></span>. This is a bundle that implements the
UPnP protocols and handles the interaction with bundles that use the
UPnP devices. A UPnP base driver bundle must provide the following
functions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Discover UPnP devices on the network and map each discovered
device into an OSGi registered UPnP Device service.
</p>
</li>
<li class="listitem">
<p>Present UPnP marked services that are registered with the OSGi
Framework on one or more networks to be used by other
computers.
</p>
</li>
</ul>
</div>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e24915"></a><span xmlns="" class="number">111.3</span> UPnP Device
</h2>
</div>
</div>
</div>
<p><a xmlns="" class="anchor" id="i1365305"></a>The principle entity of the UPnP specification is
the UPnP device. There is a UPnP <span class="emphasis"><em>root device</em></span> that
represents a physical appliance, such as a complete TV. The root device
contains a number of sub-devices. These might be the tuner, the monitor,
and the sound system. Each sub-device is further composed of a number of
UPnP services. A UPnP service represents some functional unit in a device.
For example, in a TV tuner it can represent the TV channel selector. <a xmlns="" class="xref" href="service.upnp.html#i1264660" title="Figure 111.2 UPnP device hierarchy">Figure <span class="number">111</span>.2 on page </a> illustrates
this hierarchy.
</p>
<div class="figure"><a xmlns="" class="anchor" id="i1264660"></a><p class="title"><strong>Figure <span xmlns="" class="number">111</span>.2 UPnP device hierarchy</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/111-device-hierarchy.png" align="middle" width="436" height="192" alt="UPnP device hierarchy" /></div>
</div>
</div><br class="figure-break" /><p>Each UPnP service can be manipulated with a number of UPnP actions.
UPnP actions can modify the state of a UPnP state variable that is
associated with a service. For example, in a TV there might be a state
variable <span class="emphasis"><em>volume</em></span>. There are then actions to set the
volume, to increase the volume, and to decrease the volume.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e24936"></a><span xmlns="" class="number">111.3.1</span> Root Device
</h3>
</div>
</div>
</div>
<p>The UPnP root device is registered as a UPnP Device service with
the Framework, as well as all its sub-devices. Most applications will
work with sub-devices, and, as a result, the children of the root device
are registered under the <code class="code">UPnPDevice</code> interface.
</p>
<p>UPnP device properties are defined per sub-device in the UPnP
specification. These properties must be registered with the OSGi
Framework service registry so they are searchable.
</p>
<p>Bundles that want to handle the UPnP device hierarchy can use the
registered service properties to find the parent of a device (which is
another registered <code class="code">UPnPDevice</code>).
</p>
<p>The following service registration properties can be used to
discover this hierarchy:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.PARENT_UDN" title="111.16.3.16 public static final String PARENT_UDN = "UPnP.device.parentUDN"">PARENT_UDN</a> - (<code class="code">String</code>) The Universal Device
Name (UDN) of the parent device. A root device most not have this
property registered. Type is a <code class="code">String</code> object.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.CHILDREN_UDN" title="111.16.3.1 public static final String CHILDREN_UDN = "UPnP.device.childrenUDN"">CHILDREN_UDN</a> - <code class="code">(String[])</code> An array of UDNs
of this device's children.
</p>
</li>
</ul>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e24971"></a><span xmlns="" class="number">111.3.2</span> Exported Versus Imported Devices
</h3>
</div>
</div>
</div>
<p>Both imported (from the network to the OSGi service registry) and
exported (from the service registry to the network)
<code class="code">UPnPDevice</code> services must have the same representation in
the OSGi Framework for identical devices. For example, if an OSGi UPnP
Device service is exported as a UPnP device from an OSGi Framework to
the network, and it is imported into another OSGi Framework, the object
representation should be equal. Application bundles should therefore be
able to interact with imported and exported forms of the UPnP device in
the same manner.
</p>
<p>Imported and exported UPnP devices differ only by two marker
properties that can be added to the service registration. One marker,
<code class="code">DEVICE_CATEGORY</code>, should typically be set only on imported
devices. By not setting <code class="code">DEVICE_CATEGORY</code> on internal UPnP
devices, the Device Manager does not try to refine these devices (See
the <a xmlns="" class="xref" href="service.device.html" title="103 Device Access Specification"><em xmlns="http://www.w3.org/1999/xhtml">Device Access Specification</em></a> for more information about the
Device Manager). If the device service does not implement the
<code class="code">Device</code> interface and does not have the
<code class="code">DEVICE_CATEGORY</code> property set, it is not considered a
<span class="emphasis"><em>device</em></span> according to the Device Access
Specification.
</p>
<p>The other marker, <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UPNP_EXPORT" title="111.16.3.22 public static final String UPNP_EXPORT = "UPnP.export"">UPNP_EXPORT</a>, should only be set on internally created
devices that the bundle developer wants to export. By not setting <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UPNP_EXPORT" title="111.16.3.22 public static final String UPNP_EXPORT = "UPnP.export"">UPNP_EXPORT</a> on registered UPnP Device services, the UPnP
Device service can be used by internally created devices that should not
be exported to the network. This allows UPnP devices to be simulated
within an OSGi Framework without announcing all of these devices to any
networks.
</p>
<p>The <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UPNP_EXPORT" title="111.16.3.22 public static final String UPNP_EXPORT = "UPnP.export"">UPNP_EXPORT</a> service property has no defined type, any value
is correct.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e25008"></a><span xmlns="" class="number">111.3.3</span> Icons
</h3>
</div>
</div>
</div>
<p>A UPnP device can optionally support an icon. The purpose of this
icon is to identify the device on a UPnP control point. UPnP control
points can be implemented in large computers like PC's or simple devices
like a remote control. However, the graphic requirements for these UPnP
devices differ tremendously. The device can, therefore, export a number
of icons of different size and depth.
</p>
<p>In the UPnP specifications, an icon is represented by a URL that
typically refers to the device itself. In this specification, a list of
icons is available from the UPnP Device service.
</p>
<p>In order to obtain localized icons, the method <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.getIcons-String-" title="111.16.3.24 public UPnPIcon[] getIcons(String locale)">getIcons(String)</a> can be used to obtain different versions. If the
locale specified is a <code class="code">null</code> argument, then the call returns
the icons of the default locale of the called device (not the default
locale of the UPnP control point).When a bundle wants to access the icon
of an imported UPnP device, the UPnP driver gets the data and presents
it to the application through an input stream.
</p>
<p>A bundle that needs to export a UPnP Device service with one or
more icons must provide an implementation of the <code class="code">UPnPIcon</code>
interface. This implementation must provide an <code class="code">InputStream</code>
object to the actual icon data. The UPnP driver bundle must then
register this icon with an HTTP server and include the URL to the icon
with the UPnP device data at the appropriate place.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25030"></a><span xmlns="" class="number">111.4</span> Device Category
</h2>
</div>
</div>
</div>
<p>UPnP Device services are devices in the context of the Device
Manager. This means that these services need to register with a number of
properties to participate in driver refinement. The value for UPnP devices
is defined in the <code class="code">UPnPDevice</code> constant <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.DEVICE_CATEGORY" title="111.16.3.2 public static final String DEVICE_CATEGORY = "UPnP"">DEVICE_CATEGORY</a>. The value is <code class="code">UPnP</code>. The
<code class="code">UPnPDevice</code> interface contains a number of constants for
matching values. Refer to <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.MATCH_GENERIC" title="111.16.3.7 public static final int MATCH_GENERIC = 1">MATCH_GENERIC</a> for further information.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="i1527770"></a><span xmlns="" class="number">111.5</span> UPnPService
</h2>
</div>
</div>
</div>
<p>A UPnP Device contains a number of <code class="code">UPnPService</code> objects.
<code class="code">UPnPService</code> objects combine zero or more actions and one or
more state variables.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1487511"></a><span xmlns="" class="number">111.5.1</span> State Variables
</h3>
</div>
</div>
</div>
<p>The <code class="code">UPnPStateVariable</code> interface encapsulates the
properties of a UPnP state variable. In addition to the properties
defined by the UPnP specification, a state variable is also mapped to a
Java data type. The Java data type is used when an event is generated
for this state variable and when an action is performed containing
arguments related to this state variable. There must be a strict
correspondence between the UPnP data type and the Java data type so that
bundles using a particular UPnP device profile can predict the precise
Java data type.
</p>
<p>The function <code class="code">QueryStateVariable</code> defined in the UPnP
specification has been deprecated and is therefore not implemented. It
is recommended to use the UPnP event mechanism to track UPnP state
variables.
</p>
<p>Additionally, a <code class="code">UPnPStateVariable</code> object can also
implement the <code class="code">UPnPLocalStateVariable</code> interface if the
device is implemented locally. That is, the device is not imported from
the network. The <code class="code">UPnPLocalStateVariable</code> interface provides
a <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPLocalStateVariable.getCurrentValue--" title="111.16.7.1 public Object getCurrentValue()">getCurrentValue()</a> method that provides direct access to the actual
value of the state variable.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25085"></a><span xmlns="" class="number">111.6</span> Working With a UPnP Device
</h2>
</div>
</div>
</div>
<p>The UPnP driver must register all discovered UPnP devices in the
local networks. These devices are registered under a
<code class="code">UPnPDevice</code> interface with the OSGi Framework.
</p>
<p>Using a remote UPnP device thus involves tracking UPnP Device
services in the OSGi service registry. The following code illustrates how
this can be done. The sample <code class="code">Controller</code> class extends the
<code class="code">ServiceTracker</code> class so that it can track all UPnP Device
services and add them to a user interface, such as a remote controller
application.
</p><pre xmlns="" class="programlisting"><code>class Controller extends ServiceTracker {
UI ui;
Controller( BundleContext context ) {
super( context, UPnPDevice.class.getName(), null );
}
public Object addingService( ServiceReference ref ) {
UPnPDevice dev = (UPnPDevice)super.addingService(ref);
ui.addDevice( dev );
return dev;
}
public void removedService( ServiceReference ref,
Object dev ) {
ui.removeDevice( (UPnPDevice) dev );
}
...
}</code></pre></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25103"></a><span xmlns="" class="number">111.7</span> Implementing a UPnP Device
</h2>
</div>
</div>
</div>
<p>OSGi services can also be exported as UPnP devices to the local
networks, in a way that is transparent to typical UPnP devices. This
allows developers to bridge legacy devices to UPnP networks. A bundle
should perform the following to export an OSGi service as a UPnP
device:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Register an UPnP Device service with the registration property
<a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UPNP_EXPORT" title="111.16.3.22 public static final String UPNP_EXPORT = "UPnP.export"">UPNP_EXPORT</a>.
</p>
</li>
<li class="listitem">
<p>Use the registration property <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.PRESENTATION_URL" title="111.16.3.17 public static final String PRESENTATION_URL = "UPnP.presentationURL"">PRESENTATION_URL</a> to provide the presentation page. The service
implementer must register its own servlet with the Http Service to
serve out this interface. This URL must point to that servlet.
</p>
</li>
</ul>
</div>
<p>There can be multiple UPnP root devices hosted by one OSGi platform.
The relationship between the UPnP devices and the OSGi platform is defined
by the <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.PARENT_UDN" title="111.16.3.16 public static final String PARENT_UDN = "UPnP.device.parentUDN"">PARENT_UDN</a> and <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.CHILDREN_UDN" title="111.16.3.1 public static final String CHILDREN_UDN = "UPnP.device.childrenUDN"">CHILDREN_UDN</a> service properties. The bundle registering those
device services must make sure these properties are set
accordingly.
</p>
<p>Devices that are implemented on the OSGi Framework (in contrast with
devices that are imported from the network) should use the <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPLocalStateVariable" title="111.16.7 public interface UPnPLocalStateVariable extends UPnPStateVariable">UPnPLocalStateVariable</a> interface for their state variables instead of the
<a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPStateVariable" title="111.16.9 public interface UPnPStateVariable">UPnPStateVariable</a> interface. This interface provides programmatic
access to the actual value of the state variable as maintained by the
device specific code.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="i1527771"></a><span xmlns="" class="number">111.8</span> Event API
</h2>
</div>
</div>
</div>
<p>There are two distinct event directions for the UPnP Service
specification.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>External events from the network must be dispatched to listeners
inside the OSGi Frameworks. The UPnP Base driver is responsible for
mapping the network events to internal listener events.
</p>
</li>
<li class="listitem">
<p>Implementations of UPnP devices must send out events to local
listeners as well as cause the transmission of the UPnP network
events.
</p>
</li>
</ul>
</div>
<p>UPnP events are sent using the whiteboard model, in which a bundle
interested in receiving the UPnP events registers an object implementing
the <code class="code">UPnPEventListener</code> interface. A filter can be set to limit
the events for which a bundle is notified. The UPnP Base driver must
register a UPnP Event Lister without filter that receives all
events.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e25148"></a><p class="title"><strong>Figure <span xmlns="" class="number">111</span>.3 Event Dispatching for Local and External Devices</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/111-event-dispatching.png" align="middle" width="369" height="153" alt="Event Dispatching for Local and External Devices" /></div>
</div>
</div><br class="figure-break" /><p>If a service is registered with a property named
<code class="code">upnp.filter</code> with the value of an instance of an
<code class="code">Filter</code> object, the listener is only notified for matching
events (This is a <code class="code">Filter</code> object and not a <code class="code">String</code>
object because it allows the <code class="code">InvalidSyntaxException</code> to be
thrown in the client and not the UPnP driver bundle).
</p>
<p>The filter might refer to any valid combination of the following
pseudo properties for event filtering:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="code">UPnPDevice.</code><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UDN" title="111.16.3.20 public static final String UDN = "UPnP.device.UDN"">UDN</a>
- (<code class="code">UPnP.device.UDN/String</code>) Only events generated by
services contained in the specific device are delivered. For example:
<code class="code">(UPnP.device.UDN=uuid:Upnp-TVEmulator-1_0-1234567890001)</code></p>
</li>
<li class="listitem">
<p><code class="code">UPnPDevice.</code><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.TYPE" title="111.16.3.19 public static final String TYPE = "UPnP.device.type"">TYPE</a> - (<code class="code">UPnP.device.type/String or
String[]</code>) Only events generated by services contained in a
device of the given type are delivered. For example:
<code class="code">(UPnP.device.type=urn:schemas-upnp-org:device:tvdevice:1)</code></p>
</li>
<li class="listitem">
<p><code class="code">UPnPService.</code><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPService.ID" title="111.16.8.1 public static final String ID = "UPnP.service.id"">ID</a>
- (<code class="code">UPnP.service.id/String</code>) Service identity. Only events
generated by services matching the given service ID are
delivered.
</p>
</li>
<li class="listitem">
<p><code class="code">UPnPService.</code><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPService.TYPE" title="111.16.8.2 public static final String TYPE = "UPnP.service.type"">TYPE</a> - (<code class="code">UPnP.service.type/String or
String[]</code>) Only events generated by services of the given type
are delivered.
</p>
</li>
</ul>
</div>
<p>If an event is generated by either a local device or via the base
driver for an external device, the <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPEventListener.notifyUPnPEvent-String-String-Dictionary-" title="111.16.4.2 public void notifyUPnPEvent(String deviceId, String serviceId, Dictionary<String, Object> events)">notifyUPnPEvent(String,String,Dictionary)</a> method is called on all registered <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPEventListener" title="111.16.4 public interface UPnPEventListener">UPnPEventListener</a>
services for which the optional filter matches for that event. If no
filter is specified, all events must be delivered. If the filter does not
match, the UPnP Driver must not call the UPnP Event Listener service. The
way events must be delivered is the same as described in
<span class="emphasis"><em>Delivering Events</em></span> of <a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a>.
</p>
<p>One or multiple events are passed as parameters to the <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPEventListener.notifyUPnPEvent-String-String-Dictionary-" title="111.16.4.2 public void notifyUPnPEvent(String deviceId, String serviceId, Dictionary<String, Object> events)">notifyUPnPEvent(String,String,Dictionary)</a> method. The <code class="code">Dictionary</code> object holds a
pair of <code class="code">UpnPStateVariable</code> objects that triggered the event
and an Object for the new value of the state variable.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1527773"></a><span xmlns="" class="number">111.8.1</span> Initial Event Delivery
</h3>
</div>
</div>
</div>
<p>Special care must be taken with the initial subscription to
events. According to the UPnP specification, when a client subscribes
for notification of events for the first time, the device sends out a
number of events for each state variable, indicating the current value
of each state variable. This behavior simplifies the synchronization of
a device and an event-driven client.
</p>
<p>The UPnP Base Driver must mimic this event distribution on behalf
of external devices. It must therefore remember the values of the state
variables of external devices. A UPnP Device implementation must send
out these initial events for each state variable they have a value
for.
</p>
<p>The UPnP Base Driver must have stored the last event from the
device and retransmit the value over the multicast network. The UPnP
Driver must register an event listener without any filter for this
purpose.
</p>
<p>The call to the listener's notification method must be done
asynchronously.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="i1527772"></a><span xmlns="" class="number">111.9</span> UPnP Events and Event Admin service
</h2>
</div>
</div>
</div>
<p>UPnP events must be delivered asynchronously to the Event Admin
service by the UPnP implementation, if present. UPnP events have the
following topic:
</p><pre xmlns="" class="programlisting"><code>org/osgi/service/upnp/UPnPEvent</code></pre><p>The properties of a UPnP event are the following:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="code">upnp.deviceId</code> - (<code class="code">String</code>) The identity
as defined by <code class="code">UPnPDevice.</code><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.UDN" title="111.16.3.20 public static final String UDN = "UPnP.device.UDN"">UDN</a>
of the device sending the event.
</p>
</li>
<li class="listitem">
<p><code class="code">upnp.serviceId</code> - (<code class="code">String)</code> The identity
of the service sending the events.
</p>
</li>
<li class="listitem">
<p><code class="code">upnp.events - (Dictionary)</code> A
<code class="code">Dictionary</code> object containing the new values for the state
variables that have changed.
</p>
</li>
</ul>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25284"></a><span xmlns="" class="number">111.10</span> Localization
</h2>
</div>
</div>
</div>
<p>All values of the UPnP properties are obtained from the device using
the device's default locale. If an application wants to query a set of
localized property values, it has to use the method <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.getDescriptions-String-" title="111.16.3.23 public Dictionary<String, Object> getDescriptions(String locale)">getDescriptions(String)</a>. For localized versions of the icons, the method
<a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPDevice.getIcons-String-" title="111.16.3.24 public UPnPIcon[] getIcons(String locale)">getIcons(String)</a> is to be used.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25293"></a><span xmlns="" class="number">111.11</span> Dates and Times
</h2>
</div>
</div>
</div>
<p>The UPnP specification uses different types for date and time
concepts. An overview of these types is given in the following
table.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e25298"></a><p class="title"><strong>Table <span xmlns="" class="number">111</span>.1 Mapping UPnP Date/Time types to Java</strong></p>
<div class="table-contents">
<table summary="Mapping UPnP Date/Time types to Java" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">UPnP Type</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Class</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Example</th>
<th style="border-bottom: 0.5pt solid ; ">Value (TZ=CEST=UTC+0200)</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">date</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">Date</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">1985-04-12</code></td>
<td style="border-bottom: 0.5pt solid ; "><code class="code">Sun April 12 00:00:00 CEST 1985</code></td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">dateTime</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">Date</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">1985-04-12T10:15:30</code></td>
<td style="border-bottom: 0.5pt solid ; "><code class="code">Sun April 12 10:15:30 CEST 1985</code></td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">dateTime.tz</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">Date</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">1985-04-12T10:15:30+0400</code></td>
<td style="border-bottom: 0.5pt solid ; "><code class="code">Sun April 12 08:15:30 CEST 1985</code></td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">time</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">Long</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">23:20:50</code></td>
<td style="border-bottom: 0.5pt solid ; "><code class="code">84.050.000 (ms)</code></td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">time.tz</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">Long</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">23:20:50+0100</code></td>
<td style=""><code class="code">1.250.000 (ms)</code></td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>The UPnP specification points to <a xmlns="" class="xref" href="service.upnp.html#i1325817" title="XML Schema">[2] <em>XML Schema</em></a>. In this
standard, <a xmlns="" class="xref" href="service.upnp.html#i1325829" title="ISO 8601 Date And Time formats">[3] <em>ISO 8601 Date And Time formats</em></a> are referenced. The mapping is not
completely defined which means that this OSGi UPnP specification defines a
complete mapping to Java classes. The UPnP types <code class="code">date</code>,
<code class="code">dateTime</code> and <code class="code">dateTime.tz</code> are represented as a
<code class="code">Date</code> object. For the <code class="code">date</code> type, the hours,
minutes and seconds must all be zero.
</p>
<p>The UPnP types <code class="code">time</code> and <code class="code">time.tz</code> are
represented as a <code class="code">Long</code> object that represents the number of ms
since midnight. If the time wraps to the next day due to a time zone
value, then the final value must be truncated modulo 86.400.000.
</p>
<p>See also <a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPStateVariable.TYPE_DATE" title="111.16.9.5 public static final String TYPE_DATE = "date"">TYPE_DATE</a>.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25418"></a><span xmlns="" class="number">111.12</span> UPnP Exception
</h2>
</div>
</div>
</div>
<p>The UPnP Exception can be thrown when a <code class="code">UPnPAction</code> is
invoked. This exception contains information about the different UPnP
layers. The following errors are defined:
</p>
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPException.INVALID_ACTION" title="111.16.5.2 public static final int INVALID_ACTION = 401">INVALID_ACTION</a> - (<code class="code">401</code>) No such action could be
found.
</p>
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPException.INVALID_ARGS" title="111.16.5.3 public static final int INVALID_ARGS = 402">INVALID_ARGS</a> - (<code class="code">402</code>) Invalid argument.
</p>
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPException.INVALID_SEQUENCE_NUMBER" title="111.16.5.4 public static final int INVALID_SEQUENCE_NUMBER = 403">INVALID_SEQUENCE_NUMBER</a> - (<code class="code">403</code>) Out of
synchronization.
</p>
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPException.INVALID_VARIABLE" title="111.16.5.5 public static final int INVALID_VARIABLE = 404">INVALID_VARIABLE</a> - (<code class="code">404</code>) State variable not
found.
</p>
<p><a xmlns="" class="xref" href="service.upnp.html#org.osgi.service.upnp.UPnPException.DEVICE_INTERNAL_ERROR" title="111.16.5.1 public static final int DEVICE_INTERNAL_ERROR = 501">DEVICE_INTERNAL_ERROR</a> - (<code class="code">501</code>) Internal error.
</p>
<p>Further errors are categorized as follows:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Common Action Errors</em></span> - In the range of
<code class="code">600-69</code>, defined by the UPnP Forum Technical
Committee.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Action Specific Errors</em></span> - In the range of
700-799, defined by the UPnP Forum Working Committee.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Non-Standard Action Specific Errors</em></span> - In
the range of 800-899. Defined by vendors.
</p>
</li>
</ul>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25477"></a><span xmlns="" class="number">111.13</span> Configuration
</h2>
</div>
</div>
</div>
<p>In order to provide a standardized way to configure a UPnP driver
bundle, the Configuration Admin property <code class="code">upnp.ssdp.address</code> is
defined.
</p>
<p>The value is a <code class="code">String[]</code> with a list of IP addresses,
optionally followed with a colon (<code class="code">':' \u003A</code>) and a port
number. For example:
</p><pre xmlns="" class="programlisting"><code>239.255.255.250:1900</code></pre><p>Those addresses define the interfaces which the UPnP driver is
operating on. If no SSDP address is specified, the default assumed will be
239.255.255.250:1900. If no port is specified, port 1900 is assumed as
default.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e25497"></a><span xmlns="" class="number">111.14</span> Networking considerations
</h2>
</div>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e25500"></a><span xmlns="" class="number">111.14.1</span> The UPnP Multicasts
</h3>