|
|
|
|
|
This chapter discusses in brief the API components defined by OSGi UPnP Device Specification.
UPnP Device
Every UPnP-enabled device - imported or exported, root or embedded - is available under the org.osgi.service.upnp.UPnPDevice interface. The UPnPDevice provides as service properties the basic device attributes specified in the "UPnP Device Architecture 1.1" and some specific properties provided for all imported UPnP devices. Some of these attributes are type, device UDN and UPC, UDNs of embedded devices, and so on.
Retrieving Descriptive Parameters
The getDescriptions method returns a dictionary which contains the localised attributes of the UPnP device if it supports the desired locale, such as presentation URL, manufacturer information, etc. The attribute keys are provided as static fields of UPnPDevice. This method should be invoked with a non-null argument only in case the caller needs the localised values of the properties. Otherwise, for the default locale call the getDescriptions method passing null for locale argument.
In addition, the descriptions of imported devices contain the properties com.prosyst.mbs.services.upnp.UPnPConstants.DEVICE_IP and com.prosyst.mbs.services.upnp.UPnPConstants.DEVICE_PORT showing respectively the IP address and port for communication with the announced device.
If the UPnP device cannot support the specified locale, you will receive the properties for the device's default locale.
To retrieve the localized icons – org.osgi.service.upnp.UPnPIcon instances, that represent the UPnP device, the getIcons method should be used with a non-null argument.
Retrieving UPnP Services
The UPnP services – org.osgi.service.upnp.UPnPService objects, can be obtained through the getServices and getService(String serviceId) methods.
Getting Device Relations
In case the root UPnP device encloses another UPnP device(s), the UPnPDevice.PARENT_UDN and UPnPDevice.CHILDREN_UDN properties of the UPnP Device services manifest the relation between the devices.
UPnP Device Icon
The UPnP device icon for a particular locale is an implementation of the org.osgi.service.upnp.UPnPIcon interface. The implemented methods should provide: an input stream to read the icon data from and optionally its byte size; the icon's MIME type, width, height and depth.
UPnP Service
A UPnP service of a device is represented by the org.osgi.service.upnp.UPnPService interface and is obtained from the appropriate UPnPDevice.
UPnPService has methods to access the attributes of the service - ID, type and version. It also provides access to the service actions (org.osgi.service.upnp.UPnPAction objects) through the getActions and getAction(String name) methods, and to the service state variables (org.osgi.service.upnp.UPnPStateVariable objects) through the getStateVariable and getStateVariable(String name) methods.
UPnP State Variable
The org.osgi.service.upnp.UPnPStateVariable represents the state variables of UPnP services as well as the arguments (input or output) of UPnP service actions. UPnPStateVariable contains methods for the state variable's properties - name, data type, default value, allowed values and the value range.
Data Type Specifics
The data type of a state variable has two formats - UPnP data type, specified in the "UPnP Device Architecture 1.1", and Java data type, which is the Java analog to the UPnP variable type. These types are tightly bound to each other so that applications can invoke actions passing arguments as Java types as well as process received events through an event listener.
The getJavaDataType and getUPnPDataType methods return the data format of the concrete variable. Further cast to one of the two data types can be done with the help of the UPnPStateVariable's static fields.
This table shows the mapping between UPnP data types and related Java data types.
UPnP Data Type |
Java Data Type |
Description |
|---|---|---|
ui1 |
java.lang.Integer |
Unsigned 1 Byte int |
ui2 |
java.lang.Integer |
Unsigned 2 Byte int |
ui4 |
java.lang.Long |
Unsigned 4 Byte int |
i1 |
java.lang.Integer |
1 Byte int |
i2 |
java.lang.Integer |
2 Byte int |
i4 |
java.lang.Integer |
4 Byte int. Must be between -2147483648 and 2147483647. |
int |
java.lang.Integer |
Integer number |
r4 |
java.lang.Float |
4 Byte float. Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38. |
r8 |
java.lang.Double |
8 Byte float. Same format as float. Must be between -1.79769313486232E308 and -4.94065645841247E-324 for negative values, and between 4.94065645841247E-324 and 1.79769313486232E308 for positive values, that is IEEE 64-bit (8-Byte) double. |
number |
java.lang.Double |
Same as r8 |
fixed.14.4 |
java.lang.Double |
Same as r8 but no more than 14 digits to the left of the decimal point and no more than 4 to the right |
float |
java.lang.Float |
Floating point number. Mantissa (left of the decimal) and/or exponent may have a leading sign. Mantissa and/or exponent may have leading zeros. Decimal character in mantissa is a period, that is whole digits in mantissa separated from fractional digits by period. Mantissa separated from exponent by E. (No currency symbol.) (No grouping of digits in the mantissa, e.g., no commas.) |
char |
java.lang.Character |
Unicode string. One character long. |
string |
java.lang.String |
Unicode string. No limit on length. |
date |
java.util.Date (always 00:00 hours) |
Date in a subset of ISO 8601 format without time data. |
dateTime |
java.util.Date (default time zone) |
Date in ISO 8601 format with optional time but no time zone. |
dateTime.tz |
java.util.Date (adjusted to default time zone) |
Date in ISO 8601 format with optional time and optional time zone. |
time |
java.lang.Long (ms since midnight) |
Time in a subset of ISO 8601 format with no date and no time zone. |
time.tz |
java.lang.Long (ms since midnight, adjusted to default time zone, wrapping at 0 and 24*60*60*1000) |
Time in a subset of ISO 8601 format with optional time zone but no date. |
boolean |
java.lang.Boolean |
for false - 0, false, or no; for true - 1, true, or yes. |
bin.base64 |
byte[] |
MIME-style Base64 encoded binary BLOB. Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an octet. (3 octets are encoded as 4.) No limit on size. The Java byte array will hold the decoded content of the BLOB. |
bin.hex |
byte[] |
Hexadecimal digits representing octets. Treats each nibble as a hex digit and encodes as a separate Byte. (1 octet is encoded as 2.) No limit on size. The Java byte array will hold the decoded content of the BLOB. |
uri |
java.lang.String |
Universal Resource Identifier |
uuid |
java.lang.String |
Universally Unique ID. Hexadecimal digits representing octets. Optional embedded hyphens are ignored. |
Eventing Issue
The sendsEvents method indicates if the state variable will serve as source of events when its value changes.
UPnP Action
Actions of UPnP service are wrapped by the org.osgi.service.upnp.UPnPAction interface. Each UPnPAction contains information about its arguments (input and output). UPnPAction provides the following essential operations:
Viewing the Names and Data Types of Action Arguments
The names of the input and output arguments of the action are fetched by the getInputArgumentNames and getOutputArgumentNames methods. Then, the getStateVariable method returns the UPnPStateVariable related to the argument.
Invoking the Action
The invoke method loads the execution of the action.
This method takes as input argument a dictionary whose keys are the argument names provided through the getInputArgumentNames method; and whose values are objects of the Java classes returned by the getJavaDataType method of the related to the arguments UPnPStateVariable instances.
The results from an action are also placed in a dictionary with the same format as the one for input arguments. The property keys are the argument names returned by the getOutputArgumentNames method.