-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.device.html
5996 lines (5938 loc) · 705 KB
/
service.device.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>103 Device Access Specification - OSGi Compendium 7</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
<link rel="home" href="toc.html" title="OSGi Compendium" />
<link rel="up" href="toc.html" title="OSGi Compendium" />
<link rel="prev" href="service.http.html" title="102 Http Service Specification" />
<link rel="next" href="service.cm.html" title="104 Configuration Admin Service Specification" />
<meta name="Section-title" content="103 Device Access Specification" />
<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/logo.svg" alt="OSGi Alliance Documentation" /><h1>OSGi Compendium Release 7</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.http.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.cm.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.device"></a><span xmlns="" class="number">103</span> Device Access Specification
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="service.device.html#org.osgi.service.device" title="103.9 org.osgi.service.device">Version 1.1</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="d0e8350"></a><span xmlns="" class="number">103.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>A Framework is a meeting point for services and devices from many
different vendors: a meeting point where users add and cancel service
subscriptions, newly installed services find their corresponding input and
output devices, and device drivers connect to their hardware.
</p>
<p>In an OSGi Framework, these activities will dynamically take place
while the Framework is running. Technologies such as USB and IEEE 1394
explicitly support plugging and unplugging devices at any time, and
wireless technologies are even more dynamic.
</p>
<p>This flexibility makes it hard to configure all aspects of an OSGi
Framework, particularly those relating to devices. When all of the
possible services and device requirements are factored in, each OSGi
Framework will be unique. Therefore, automated mechanisms are needed that
can be extended and customized, in order to minimize the configuration
needs of the OSGi environment.
</p>
<p>The Device Access specification supports the coordination of
automatic detection and attachment of existing devices on an OSGi
Framework, facilitates hot-plugging and -unplugging of new devices, and
downloads and installs device drivers on demand.
</p>
<p>This specification, however, deliberately does not prescribe any
particular device or network technology, and mentioned technologies are
used as examples only. Nor does it specify a particular device discovery
method. Rather, this specification focuses on the attachment of devices
supplied by different vendors. It emphasizes the development of
standardized device interfaces to be defined in device categories,
although no such device categories are defined in 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="d0e8363"></a><span xmlns="" class="number">103.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>Embedded Devices</em></span> - OSGi bundles will
likely run in embedded devices. This environment implies limited
possibility for user interaction, and low-end devices will probably
have resource limitations.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Remote Administration</em></span> - OSGi environments
must support administration by a remote service provider.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Vendor Neutrality</em></span> - OSGi-compliant driver
bundles will be supplied by different vendors; each driver bundle
must be well-defined, documented, and replaceable.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Continuous Operation</em></span> - OSGi environments
will be running for extended periods without being restarted,
possibly continuously, requiring stable operation and stable
resource consumption.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Dynamic Updates</em></span> - As much as possible,
driver bundles must be individually replaceable without affecting
unrelated bundles. In particular, the process of updating a bundle
should not require a restart of the whole OSGi Framework or disrupt
operation of connected devices.
</p>
</li>
</ul>
</div>
<p>A number of requirements must be satisfied by Device Access
implementations in order for them to be OSGi-compliant. Implementations
must support the following capabilities:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Hot-Plugging</em></span> - Plugging and unplugging of
devices at any time if the underlying hardware and drivers allow
it.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Legacy Systems</em></span> - Device technologies
which do not implement the automatic detection of plugged and
unplugged devices.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Dynamic Device Driver Loading</em></span> - Loading
new driver bundles on demand with no prior device-specific knowledge
of the Device service.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Multiple Device Representations</em></span> - Devices
to be accessed from multiple levels of abstraction.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Deep Trees</em></span> - Connections of devices in a
tree of mixed network technologies of arbitrary depth.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Topology Independence</em></span> - Separation of the
interfaces of a device from where and how it is attached.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Complex Devices</em></span> - Multifunction devices
and devices that have multiple configurations.
</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="d0e8430"></a><span xmlns="" class="number">103.1.2</span> Operation
</h3>
</div>
</div>
</div>
<p>This specification defines the behavior of a device manager (which
is <span class="emphasis"><em>not</em></span> a service as might be expected). This device
manager detects registration of Device services and is responsible for
associating these devices with an appropriate Driver service. These
tasks are done with the help of Driver Locator services and the Driver
Selector service that allow a device manager to find a Driver bundle and
install it.
</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="d0e8438"></a><span xmlns="" class="number">103.1.3</span> Entities
</h3>
</div>
</div>
</div>
<p>The main entities of the Device Access specification are:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Device Manager</em></span> - The bundle that controls
the initiation of the attachment process behind the scenes.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Device Category</em></span> - Defines how a Driver
service and a Device service can cooperate.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Driver</em></span> - Competes for attaching Device
services of its recognized device category. See <a xmlns="" class="xref" href="service.device.html#i1282334" title="103.4 Driver Services">Driver Services</a>.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Device</em></span> - A representation of a physical
device or other entity that can be attached by a Driver service. See
<a xmlns="" class="xref" href="service.device.html#i1292342" title="103.2 Device Services">Device Services</a>.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>DriverLocator</em></span> - Assists in locating
bundles that provide a Driver service. See <a xmlns="" class="xref" href="service.device.html#i1292350" title="103.5 Driver Locator Service">Driver Locator Service</a>.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>DriverSelector</em></span> - Assists in selecting
which Driver service is best suited to a Device service. See <a xmlns="" class="xref" href="service.device.html#i1286950" title="103.6 The Driver Selector Service">The Driver Selector Service</a>.
</p>
</li>
</ul>
</div>
<p><a xmlns="" class="xref" href="service.device.html#i1309251" title="Figure 103.1 Device Access Class Overview">Figure <span class="number">103</span>.1</a> show the classes and their
relationships.
</p>
<div class="figure"><a xmlns="" class="anchor" id="i1309251"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.1 Device Access Class Overview</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/103-device-classes.png" align="middle" width="630" height="400" alt="Device Access Class Overview" /></div>
</div>
</div><br class="figure-break" /></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="i1292342"></a><span xmlns="" class="number">103.2</span> Device Services
</h2>
</div>
</div>
</div>
<p>A Device service represents some form of a device. It can represent
a hardware device, but that is not a requirement. Device services differ
widely: some represent individual physical devices and others represent
complete networks. Several Device services can even simultaneously
represent the same physical device at different levels of abstraction. For
example:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>A USB network.</p>
</li>
<li class="listitem">
<p>A device attached on the USB network.</p>
</li>
<li class="listitem">
<p>The same device recognized as a USB to Ethernet bridge.</p>
</li>
<li class="listitem">
<p>A device discovered on the Ethernet using Salutation.</p>
</li>
<li class="listitem">
<p>The same device recognized as a simple printer.</p>
</li>
<li class="listitem">
<p>The same printer refined to a PostScript printer.</p>
</li>
</ul>
</div>
<p>A device can also be represented in different ways. For example, a
USB mouse can be considered as:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>A USB device which delivers information over the USB bus.</p>
</li>
<li class="listitem">
<p>A mouse device which delivers <code class="code">x</code> and <code class="code">y</code>
coordinates and information about the state of its buttons.
</p>
</li>
</ul>
</div>
<p>Each representation has specific implications:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>That a particular device is a mouse is irrelevant to an
application which provides management of USB devices.
</p>
</li>
<li class="listitem">
<p>That a mouse is attached to a USB bus or a serial port would be
inconsequential to applications that respond to mouse-like
input.
</p>
</li>
</ul>
</div>
<p>Device services must belong to a defined <span class="emphasis"><em>device
category</em></span>, or else they can implement a generic service which
models a particular device, independent of its underlying technology.
Examples of this type of implementation could be Sensor or Actuator
services.
</p>
<p>A device category specifies the methods for communicating with a
Device service, and enables interoperability between bundles that are
based on the same underlying technology. Generic Device services will
allow interoperability between bundles that are not coupled to specific
device technologies.
</p>
<p>For example, a device category is required for the USB, so that
Driver bundles can be written that communicate to the devices that are
attached to the USB. If a printer is attached, it should also be available
as a generic Printer service defined in a Printer service specification,
indistinguishable from a Printer service attached to a parallel port.
Generic categories, such as a Printer service, should also be described in
a Device Category.
</p>
<p>It is expected that most Device service objects will actually
represent a physical device in some form, but that is not a requirement of
this specification. A Device service is represented as a normal service in
the OSGi Framework and all coordination and activities are performed upon
Framework services. This specification does not limit a bundle developer
from using Framework mechanisms for services that are not related to
physical devices.
</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="service.device-device.service.registration"></a><span xmlns="" class="number">103.2.1</span> Device Service Registration
</h3>
</div>
</div>
</div>
<p>A Device service is defined as a normal service registered with
the Framework that either:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Registers a service object under the interface
<code class="code">org.osgi.service.Device</code> with the Framework, or
</p>
</li>
<li class="listitem">
<p>Sets the <a xmlns="" class="xref" href="service.device.html#org.osgi.service.device.Constants.DEVICE_CATEGORY" title="103.9.2.1 public static final String DEVICE_CATEGORY = "DEVICE_CATEGORY"">DEVICE_CATEGORY</a> property in the registration. The value of
<code class="code">DEVICE_CATEGORY</code> is an array of <code class="code">String</code>
objects of all the device categories that the device belongs to.
These strings are defined in the associated device category.
</p>
</li>
</ul>
</div>
<p>If this document mentions a Device service, it is meant to refer
to services registered with the name
<code class="code">org.osgi.service.device.Device</code> <span class="emphasis"><em>or</em></span>
services registered with the <code class="code">DEVICE_CATEGORY</code> property
set.
</p>
<p>When a Device service is registered, additional properties may be
set that describe the device to the device manager and potentially to
the end users. The following properties have their semantics defined in
this specification:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><a xmlns="" class="xref" href="service.device.html#org.osgi.service.device.Constants.DEVICE_CATEGORY" title="103.9.2.1 public static final String DEVICE_CATEGORY = "DEVICE_CATEGORY"">DEVICE_CATEGORY</a> - A marker property indicating that this
service must be regarded as a Device service by the device manager.
Its value is of type <code class="code">String[]</code>, and its meaning is
defined in the associated device category specification.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="service.device.html#org.osgi.service.device.Constants.DEVICE_DESCRIPTION" title="103.9.2.2 public static final String DEVICE_DESCRIPTION = "DEVICE_DESCRIPTION"">DEVICE_DESCRIPTION</a> - Describes the device to an end user. Its
value is of type <code class="code">String</code>.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="service.device.html#org.osgi.service.device.Constants.DEVICE_SERIAL" title="103.9.2.3 public static final String DEVICE_SERIAL = "DEVICE_SERIAL"">DEVICE_SERIAL</a> - A unique serial number for this device. If
the device hardware contains a serial number, the driver bundle is
encouraged to specify it as this property. Different Device services
representing the same physical hardware at different abstraction
levels should set the same <code class="code">DEVICE_SERIAL</code>, thus
simplifying identification. Its value is of type
<code class="code">String</code>.
</p>
</li>
<li class="listitem">
<p><code class="code">service.pid</code> - Service Persistent ID (PID),
defined in <code class="code">org.osgi.framework.Constants</code>. Device
services should set this property. It must be unique among all
registered services. Even different abstraction levels of the same
device must use different PIDs. The service PIDs must be
reproducible, so that every time the same hardware is plugged in,
the same PIDs are used.
</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="d0e8619"></a><span xmlns="" class="number">103.2.2</span> Device Service Attachment
</h3>
</div>
</div>
</div>
<p>When a Device service is registered with the Framework, the device
manager is responsible for finding a suitable Driver service and
instructing it to attach to the newly registered Device service. The
Device service itself is passive: it only registers a Device service
with the Framework and then waits until it is called.
</p>
<p>The actual communication with the underlying physical device is
not defined in the <code class="code">Device</code> interface because it differs
significantly between different types of devices. The Driver service is
responsible for attaching the device in a device type-specific manner.
The rules and interfaces for this process must be defined in the
appropriate device category.
</p>
<p>If the device manager is unable to find a suitable Driver service,
the Device service remains unattached. In that case, if the service
object implements the <code class="code">Device</code> interface, it must receive a
call to the <a xmlns="" class="xref" href="service.device.html#org.osgi.service.device.Device.noDriverFound--" title="103.9.3.2 public void noDriverFound()">noDriverFound()</a> method. The Device service can wait until a new
driver is installed, or it can unregister and attempt to register again
with different properties that describe a more generic device or try a
different configuration.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e8636"></a><span xmlns="" class="number">103.2.2.1</span> Idle Device Service
</h4>
</div>
</div>
</div>
<p>The main purpose of the device manager is to try to attach
drivers to idle devices. For this purpose, a Device service is
considered <span class="emphasis"><em>idle</em></span> if no bundle that itself has
registered a Driver service is using the Device service.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e8644"></a><span xmlns="" class="number">103.2.2.2</span> Device Service Unregistration
</h4>
</div>
</div>
</div>
<p>When a Device service is unregistered, no immediate action is
required by the device manager. The normal service of unregistering
events, provided by the Framework, takes care of propagating the
unregistration information to affected drivers. Drivers must take the
appropriate action to release this Device service and perform any
necessary cleanup, as described in their device category
specification.
</p>
<p>The device manager may, however, take a device unregistration as
an indication that driver bundles may have become idle and are thus
eligible for removal. It is therefore important for Device services to
unregister their service object when the underlying entity becomes
unavailable.
</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="service.device-device.category"></a><span xmlns="" class="number">103.3</span> Device Category Specifications
</h2>
</div>
</div>
</div>
<p>A device category specifies the rules and interfaces needed for the
communication between a Device service and a Driver service. Only Device
services and Driver services of the same device category can communicate
and cooperate.
</p>
<p>The Device Access service specification is limited to the attachment
of Device services by Driver services, and does <span class="emphasis"><em>not</em></span>
enumerate different device categories.
</p>
<p>Other specifications must specify a number of device categories
before this specification can be made operational. Without a set of
defined device categories, no interoperability can be achieved.
</p>
<p>Device categories are related to a specific device technology, such
as USB, IEEE 1394, JINI, UPnP, Salutation, CEBus, Lonworks, and others.
The purpose of a device category specification is to make all Device
services of that category conform to an agreed interface, so that, for
example, a USB Driver service of vendor A can control Device services from
vendor B attached to a USB bus.
</p>
<p>This specification is limited to defining the guidelines for device
category definitions only. Device categories may be defined by the OSGi
organization or by external specification bodies - for example, when these
bodies are associated with a specific device technology.
</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="d0e8667"></a><span xmlns="" class="number">103.3.1</span> Device Category Guidelines
</h3>
</div>
</div>
</div>
<p>A device category definition comprises the following
elements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>An interface that all devices belonging to this category must
implement. This interface should lay out the rules of how to
communicate with the underlying device. The specification body may
define its own device interfaces (or classes) or leverage existing
ones. For example, a serial port device category could use the
<code class="code">javax.comm.SerialPort</code> interface which is defined in
<a xmlns="" class="xref" href="service.device.html#i1424268" title="Java Communications API">[1] <em>Java Communications API</em></a>.
</p>
<p>When registering a device belonging to this category with the
Framework, the interface or class name for this category must be
included in the registration.
</p>
</li>
<li class="listitem">
<p>A set of service registration properties, their data types,
and semantics, each of which must be declared as either
<code class="code">MANDATORY</code> or <code class="code">OPTIONAL</code> for this device
category.
</p>
</li>
<li class="listitem">
<p>A range of match values specific to this device category.
Matching is explained later in <a xmlns="" class="xref" href="service.device.html#i1288442" title="103.7.2 The Device Attachment Algorithm">The Device Attachment Algorithm</a>.
</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="i1306027"></a><span xmlns="" class="number">103.3.2</span> Sample Device Category Specification
</h3>
</div>
</div>
</div>
<p>The following is a partial example of a fictitious device
category:
</p><pre xmlns="" class="programlisting"><code>public interface /* com.acme.widget.*/ WidgetDevice{
int MATCH_SERIAL = 10;
int MATCH_VERSION = 8;
int MATCH_MODEL = 6;
int MATCH_MAKE = 4;
int MATCH_CLASS = 2;
void sendPacket( byte [] data );
byte [] receivePacket( long timeout );
}</code></pre><p>Devices in this category must implement the interface
<code class="code">com.acme.widget.WidgetDevice</code> to receive attachments from
Driver services in this category.
</p>
<p>Device properties for this fictitious category are defined in the
following table.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e8711"></a><p class="title"><strong>Table <span xmlns="" class="number">103</span>.1 Example Device Category Properties, M=Mandatory,
O=Optional</strong></p>
<div class="table-contents">
<table summary="Example Device Category Properties, M=Mandatory,
 O=Optional" 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 ; ">Property name</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">M/O</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Type</th>
<th style="border-bottom: 0.5pt solid ; ">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">DEVICE_CATEGORY</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">M</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String[]</code></td>
<td style="border-bottom: 0.5pt solid ; "><code class="code">{"Widget"}</code></td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">com.acme.class</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">M</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>A class description of this device. For example
"<code class="code">audio</code>", "<code class="code">video</code>",
"<code class="code">serial</code>", etc. An actual device category
specification should contain an exhaustive list and define a
process to add new classes.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">com.acme.model</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">M</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>A definition of the model. This is usually vendor
specific. For example "<code class="code">Mouse</code>".
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">com.acme.manufacturer</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">M</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Manufacturer of this device, for example "ACME
Widget Division".
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">com.acme.revision</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">O</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Revision number. For example, "42".</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">com.acme.serial</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">O</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">String</code></td>
<td style="">
<p>A serial number. For example
"<code class="code">SN6751293-12-2112/A</code>".
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-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="d0e8823"></a><span xmlns="" class="number">103.3.3</span> Match Example
</h3>
</div>
</div>
</div>
<p>Driver services and Device services are connected via a matching
process that is explained in <a xmlns="" class="xref" href="service.device.html#i1288442" title="103.7.2 The Device Attachment Algorithm">The Device Attachment Algorithm</a>. The Driver
service plays a pivotal role in this matching process. It must inspect
the Device service (from its <code class="code">ServiceReference</code> object) that
has just been registered and decide if it potentially could cooperate
with this Device service.
</p>
<p>It must be able to answer a value indicating the quality of the
match. The scale of this match value must be defined in the device
category so as to allow Driver services to match on a fair basis. The
scale must start at least at 1 and go upwards.
</p>
<p>Driver services for this sample device category must return one of
the match codes defined in the <code class="code">com.acme.widget.WidgetDevice</code>
interface or <code class="code">Device.MATCH_NONE</code> if the Device service is not
recognized. The device category must define the exact rules for the
match codes in the device category specification. In this example, a
small range from 2 to 10 (<code class="code">MATCH_NONE</code> is 0) is defined for
<code class="code">WidgetDevice</code> devices. They are named in the
<code class="code">WidgetDevice</code> interface for convenience and have the
following semantics.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e8852"></a><p class="title"><strong>Table <span xmlns="" class="number">103</span>.2 Sample Device Category Match Scale</strong></p>
<div class="table-contents">
<table summary="Sample Device Category Match Scale" 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 />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Match name</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Value</th>
<th style="border-bottom: 0.5pt solid ; ">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">MATCH_SERIAL</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">10</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>An exact match, including the serial
number.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">MATCH_VERSION</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">8</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Matches the right class, make model, and
version.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">MATCH_MODEL</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">6</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Matches the right class and make
model.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">MATCH_MAKE</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">4</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Matches the make.</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">MATCH_CLASS</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">2</code></td>
<td style="">
<p>Only matches the class.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>A Driver service should use the constants to return when it
decides how closely the Device service matches its suitability. For
example, if it matches the exact serial number, it should return
<code class="code">MATCH_SERIAL</code>.
</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="i1282334"></a><span xmlns="" class="number">103.4</span> Driver Services
</h2>
</div>
</div>
</div>
<p>A Driver service is responsible for attaching to suitable Device
services under control of the device manager. Before it can attach a
Device service, however, it must compete with other Driver services for
control.
</p>
<p>If a Driver service wins the competition, it must attach the device
in a device category-specific way. After that, it can perform its intended
functionality. This functionality is not defined here nor in the device
category; this specification only describes the behavior of the Device
service, not how the Driver service uses it to implement its intended
functionality. A Driver service may register one or more new Device
services of another device category or a generic service which models a
more refined form of the device.
</p>
<p>Both refined Device services as well as generic services should be
defined in a Device Category. See <a xmlns="" class="xref" href="service.device.html#service.device-device.category" title="103.3 Device Category Specifications">Device Category Specifications</a>.
</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="d0e8934"></a><span xmlns="" class="number">103.4.1</span> Driver Bundles
</h3>
</div>
</div>
</div>
<p>A Driver service is, like <span class="emphasis"><em>all</em></span> services,
implemented in a bundle, and is recognized by the device manager by
registering one or more <code class="code">Driver</code> service objects with the
Framework.
</p>
<p>Such bundles containing one or more Driver services are called
<span class="emphasis"><em>driver bundles</em></span>. The device manager must be aware of
the fact that the cardinality of the relationship between bundles and
Driver services is 1:1...*.
</p>
<p>A driver bundle must register <span class="emphasis"><em>at least</em></span> one
Driver service in its <code class="code">BundleActivator.start</code>
implementation.
</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="d0e8958"></a><span xmlns="" class="number">103.4.2</span> Driver Taxonomy
</h3>
</div>
</div>
</div>
<p>Device Drivers may belong to one of the following
categories:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Base Drivers (Discovery, Pure Discovery and Normal)</p>
</li>
<li class="listitem">
<p>Refining Drivers</p>
</li>
<li class="listitem">
<p>Network Drivers</p>
</li>
<li class="listitem">
<p>Composite Drivers</p>
</li>
<li class="listitem">
<p>Referring Drivers</p>
</li>
<li class="listitem">
<p>Bridging Drivers</p>
</li>
<li class="listitem">
<p>Multiplexing Drivers</p>
</li>
<li class="listitem">
<p>Pure Consuming Drivers</p>
</li>
</ul>
</div>
<p>This list is not definitive, and a Driver service is not required
to fit into one of these categories. The purpose of this taxonomy is to
show the different topologies that have been considered for the Device
Access service specification.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e8990"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.2 Legend for Device Driver Services Taxonomy</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/103-driver-services-taxonomy.png" align="middle" width="585" height="120" alt="Legend for Device Driver Services Taxonomy" /></div>
</div>
</div><br class="figure-break" /><div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e8996"></a><span xmlns="" class="number">103.4.2.1</span> Base Drivers
</h4>
</div>
</div>
</div>
<p>The first category of device drivers are called <span class="emphasis"><em>base
drivers</em></span> because they provide the lowest-level
representation of a physical device. The distinguishing factor is that
they are not registered as Driver services because they do not have to
compete for access to their underlying technology.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e9004"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.3 Base Driver Types</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/103-base-driver-types.png" align="middle" width="585" height="132" alt="Base Driver Types" /></div>
</div>
</div><br class="figure-break" /><p>Base drivers discover physical devices using code not specified
here (for example, through notifications from a device driver in
native code) and then register corresponding Device services.
</p>
<p>When the hardware supports a discovery mechanism and reports a
physical device, a Device service is then registered. Drivers
supporting a discovery mechanism are called <span class="emphasis"><em>discovery base
drivers</em></span>.
</p>
<p>An example of a discovery base driver is a USB driver.
Discovered USB devices are registered with the Framework as a generic
USB Device service. The USB specification (see <a xmlns="" class="xref" href="service.device.html#i1270819" title="USB Specification">[2] <em>USB Specification</em></a> ) defines a tightly integrated discovery method.
Further, devices are individually addressed; no provision exists for
broadcasting a message to all devices attached to the USB bus.
Therefore, there is no reason to expose the USB network itself;
instead, a discovery base driver can register the individual devices
as they are discovered.
</p>
<p>Not all technologies support a discovery mechanism. For example,
most serial ports do not support detection, and it is often not even
possible to detect whether a device is attached to a serial
port.
</p>
<p>Although each driver bundle should perform discovery on its own,
a driver for a non-discoverable serial port requires external help -
either through a user interface or by allowing the Configuration Admin
service to configure it.
</p>
<p>It is possible for the driver bundle to combine automatic
discovery of Plug and Play-compliant devices with manual configuration
when non-compliant devices are plugged in.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e9027"></a><span xmlns="" class="number">103.4.2.2</span> Refining Drivers
</h4>
</div>
</div>
</div>
<p>The second category of device drivers are called
<span class="emphasis"><em>refining drivers</em></span>. Refining drivers provide a
refined view of a physical device that is already represented by
another Device service registered with the Framework. Refining drivers
register a Driver service with the Framework. This Driver service is
used by the device manager to attach the refining driver to a less
refined Device service that is registered as a result of events within
the Framework itself.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e9035"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.4 Refining Driver Diagram</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/103-refining-driver.png" align="middle" width="585" height="123" alt="Refining Driver Diagram" /></div>
</div>
</div><br class="figure-break" /><p>An example of a refining driver is a mouse driver, which is
attached to the generic USB Device service representing a physical
mouse. It then registers a new Device service which represents it as a
Mouse service, defined elsewhere.
</p>
<p>The majority of drivers fall into the refining driver
type.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e9045"></a><span xmlns="" class="number">103.4.2.3</span> Network Drivers
</h4>
</div>
</div>
</div>
<p>An Internet Protocol (IP) capable network such as Ethernet
supports individually addressable devices and allows broadcasts, but
does not define an intrinsic discovery protocol. In this case, the
entire network should be exposed as a single Device service.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e9050"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.5 Network Driver diagram</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/103-network-driver.png" align="middle" width="585" height="172" alt="Network Driver diagram" /></div>
</div>
</div><br class="figure-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1271466"></a><span xmlns="" class="number">103.4.2.4</span> Composite Drivers
</h4>
</div>
</div>
</div>
<p>Complex devices can often be broken down into several parts.
Drivers that attach to a single service and then register multiple
Device services are called <span class="emphasis"><em>composite drivers</em></span>. For
example, a USB speaker containing software-accessible buttons can be
registered by its driver as two separate Device services: an Audio
Device service and a Button Device service.
</p>
<div class="figure"><a xmlns="" class="anchor" id="d0e9064"></a><p class="title"><strong>Figure <span xmlns="" class="number">103</span>.6 Composite Driver structure</strong></p>