Driver
Date: 2016-06-25

org.osgi.service.device

## Interface Driver

-     public interface Driver

  A `Driver` service object must be registered by each Driver bundle wishing to attach to Device services provided by other drivers. For each newly discovered `Device` object, the device manager enters a bidding phase. The `Driver` object whose `match(ServiceReference)` method bids the highest for a particular `Device` object will be instructed by the device manager to attach to the `Device` object.
  See Also:
    `Device`, `DriverLocator`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `attach(org.osgi.framework.ServiceReference reference)` Attaches this Driver service to the Device service represented by the given `ServiceReference` object.
    `int` | `match(org.osgi.framework.ServiceReference reference)` Checks whether this Driver service can be attached to the Device service.

- - ### Method Detail

    - #### match

          int match(org.osgi.framework.ServiceReference reference)
                    throws java.lang.Exception

      Checks whether this Driver service can be attached to the Device service. The Device service is represented by the given `ServiceReference` and returns a value indicating how well this driver can support the given Device service, or `Device.MATCH_NONE` if it cannot support the given Device service at all.

      The return value must be one of the possible match values defined in the device category definition for the given Device service, or `Device.MATCH_NONE` if the category of the Device service is not recognized.

      In order to make its decision, this Driver service may examine the properties associated with the given Device service, or may get the referenced service object (representing the actual physical device) to talk to it, as long as it ungets the service and returns the physical device to a normal state before this method returns.

      A Driver service must always return the same match code whenever it is presented with the same Device service.

      The match function is called by the device manager during the matching process.

      Parameters:
        `reference` - the `ServiceReference` object of the device to match
      Returns:
        value indicating how well this driver can support the given Device service, or `Device.MATCH_NONE` if it cannot support the Device service at all
      Throws:
        `java.lang.Exception` - if this Driver service cannot examine the Device service

    - #### attach

          java.lang.String attach(org.osgi.framework.ServiceReference reference)
                                  throws java.lang.Exception

      Attaches this Driver service to the Device service represented by the given `ServiceReference` object.

      A return value of `null` indicates that this Driver service has successfully attached to the given Device service. If this Driver service is unable to attach to the given Device service, but knows of a more suitable Driver service, it must return the `DRIVER_ID` of that Driver service. This allows for the implementation of referring drivers whose only purpose is to refer to other drivers capable of handling a given Device service.

      After having attached to the Device service, this driver may register the underlying device as a new service exposing driver-specific functionality.

      This method is called by the device manager.

      Parameters:
        `reference` - the `ServiceReference` object of the device to attach to
      Returns:
        `null` if this Driver service has successfully attached to the given Device service, or the `DRIVER_ID` of a more suitable driver
      Throws:
        `java.lang.Exception` - if the driver cannot attach to the given device and does not know of a more suitable driver