TAMZ. JavaME. Optional APIs. Department of Computer Science VŠB-Technical University of Ostrava

Transcription

1 Optional APIs 1

2 Detecting API Presence (1) Optional APIs may be present in your phone, but then again, they may be missing (remember the SAX parser). We need a mechanism to detect presence of a given API and behave accordingly. We can detect presence of specific classes by calling Class.forName(). public class MyXmlParserFactory { public static MyXmlParser getparser() throws ClassNotFoundException { try { Class.forName("org.xml.sax.helpers.DefaultHandler"); Class.forName("javax.xml.parsers.SAXParserFactory"); return (MyXmlParser)(Class.forName("XML.MySAXParser").newInstance()); } catch (Exception e) { System.err.println("SAX parser unavailable"); } try { Class.forName("org.kxml2.io.KXmlParser"); return (MyXmlParser)(Class.forName("XML.MykXmlParser").newInstance()); } catch (Exception e) { System.err.println("kXML parser unavailable"); } throw new ClassNotFoundException("No XML parser package found"); } } 2

3 Detecting API Presence (2) However, there is still a catch when you create your MIDlet, you must have the libraries present to compile the bytecode (most APIs are either in WTK or supplied by vendor's SDK e.g. Nokia UI, Mascot Capsule). Also, we must sometimes solve a problem with different revisions of the same API. We can usually obtain version information from a system property: System.getProperty("microedition.location.version"); System.getProperty("microedition.io.file.FileConnection.version"); (null API is not supported) Also, the API usually defines more properties, connected with its functionality, for example the music folder URL for filesystem access: System.getProperty("filecon.dir.music"); 3

4 File Connection API (part of JSR-75) 4

5 Accessing Files (1) The FileConnection API uses GFC to open files and directories. There are only two classes, one interface and two exceptions. Availability of FC can be tested by: if (System.getProperty("microedition.io.file.FileConnection.version")!= null) { // FC available, we can use it. } FileSystemRegistry allows to obtain filesystem roots for both built-in and external memory by FileSystemRegistry.listRoots(). An implementation of FileSystemListener can be added (and removed) to detect insertion and removal of external memory cards. IllegalModeException and ConnectionClosedException can be thrown to detect incorrect file access mode or closed connection. 5

6 Accessing Files (2) FileConnection interface is based on StreamConnection and is used to read/write files and directories. try { FileConnection fconn = (FileConnection) Connector.open("file:///e:/out.txt",Connector.READ_WRITE); // URI is valid, but streams may still throw IOExceptions if (!fconn.exists()) { fconn.create(); } // create file OutputStream os = fcon.openoutputstream(); fconn.close(); } catch (IOException ioe) { } And inside of the try-catch block we can extract directory contents: if( conn.isdirectory() ){ Enumeration names = conn.list(); //Directory contents while( names.hasmoreelements() ){ String name = (String) e.nextelement(); } // do something }

7 PIM API (part of JSR-75) 7

8 Accessing PIM Data The PIM API can be used to obtain Lists of Contacts, Events and ToDos Several exceptions exist, identifying empty, full and unsupported fields. Changes in fields must be commited. import javax.microedition.pim.*; if (System.getProperty("microedition.pim.version")!= null) { // FC available, we can use it. } Obtaining PIM instance: PIM pim = PIM.getInstance(); Contact PIM ContactList RepeatRule Event PIMItem 0..* 0..* PIMList EventList ToDo ToDoList 8

9 PIM PIM lists The PIM class can be used to open local PIM lists, list names of PIM lists and convert data from/to serial format (VCARD). Supported formats are obtained by calling supportedserialformats(type). More info can be found in API doc. PIM pim = PIM.getInstance(); ContactList cl; Vector mobn = new Vector(); try { cl = (ContactList) pim.openpimlist(pim.contact_list, PIM.READ_WRITE); } catch (Exception e) { /* security or unsupported exception */ } Contact c; for (Enumeration contacts = cl.items(); contacts.hasmoreelements();) { c = (Contact) contacts.nextelement(); int phonenumbercount = c.countvalues(contact.tel); for(int i = 0; i < phonenumbercount; i++) { if((c.getattributes(contact.tel,i) & Contact.ATTR_MOBILE)!= 0) { mobn.addelement(c.getstring(contact.tel, i)); } }}

10 PIM vcard example BEGIN:VCARD VERSION:2.1 N:Moravec;Pavel FN:Pavel Moravec ORG:VSB-TU Ostrava TITLE:Assistant professor NOTE:Know your lecturer! TEL;WORK;VOICE: TEL;CELL: ****** X-IRMC-LUID: ADR;WORK;ENCODING=QUOTED-PRINTABLE:;;FEECS, VSB-TUO =0D=0A 17.listopadu 15;Ostrava-Poruba;MSK;708 33;Czech Republic URL;WORK: REV: T194140Z END:VCARD

11 Bluetooth API (JSR-82) 11

12 Bluetooth The Bluetooth wireless connectivity technology was originally envisioned in 1994 by the Swedish phone equipment maker Ericsson as a way for mobile devices to communicate with each other at short ranges, up to 10 meters. In 1998, Ericsson, IBM, Intel, Nokia, and Toshiba formed the Bluetooth Special Interest Group consortium to develop a royalty-free, open specification for short-range wireless connectivity. Since then, more than 2000 companies have joined the Bluetooth SIG, including virtually all manufacturers of phone, computer, and PDA equipment. Source: 12

13 Bluetooth Network Topology Bluetooth-enabled devices are organized in groups called piconets. A piconet consists of a master and up to seven active slaves. A master and a single slave use point-to-point communication; if there are multiple slaves, point-to-multipoint communication is used. A master unit is the device that initiates the communication. A device in one piconet can communicate to another device in another piconet, forming a scatternet. s m s&m s s Source: 13

14 Bluetooth Profiles Bluetooth profiles are intended to ensure interoperability among different devices and applications. A profile defines the roles and capabilities for specific types of applications. Generic Access Profile Defines connection procedures, device discovery, and link management. At a minimum all Bluetooth devices must support this profile. Service Discovery Application and Profile Defines the features and procedures for an application to discover services registered in other devices. Serial Port Profile Defines the requirements for Bluetooth devices that need to set up connections that emulate serial cables.... Source: 14

15 Java APIs for Bluetooth Wireless Technology While Bluetooth hardware has advanced, there has been no standardized way to develop Bluetooth applications, until JSR 82 came into play. It hides the complexity of the Bluetooth protocol stack behind a set of Java APIs that allow you to focus on application development rather than the low-level details of Bluetooth. Like all JSRs, the Java APIs for Bluetooth are being developed through the Java Community Process. Its expert group has members representing 20 companies. The final specification is available for download. JSR 82 consists of two optional packages: the core Bluetooth API and the Object Exchange (OBEX) API. The latter is transport-independent and can be used without the former. Source: 15

16 Device Management The Java Bluetooth APIs contain the classes LocalDevice and RemoteDevice, which provide the device-management capabilities defined in the Generic Access Profile. The LocalDevice class retrieves the device's type and the kinds of services it offers. The RemoteDevice class represents a remote device and provides methods to retrieve information about the device, including its Bluetooth address and name. LocalDevice local = LocalDevice.getLocalDevice(); String address = local.getbluetoothaddress(); String name = local.getfriendlyname(); RemoteDevice remote = RemoteDevice.getRemoteDevice(...) String address = remote.getbluetoothaddress(); String name = remote.getfriendlyname(); 16

17 Discovering a Remote Device Each Bluetooth device has a specific code (CoD class of device), which consists of service class of each device (e.g. Telephony, networking, ) device class consisting of two parts major (computer, audio,...) minor (PDA for computer, headset for audio), which identify the type of the device. This code identifies, what is the function and role of given device. Each Bluetooth device has also an unique 6-byte MAC address, through which it can be addressed. Some devices can be discovered, while others are not Generally discoverable devices (GIAC) can be discovered at all times Limited Discoverable devices (LIAC) can be discovered for short time periods (e.g. 30 seconds after a button on BT handsfree is pressed) Non-discoverable devices (NOT_DISCOVERABLE) are invisible. 17

18 Offering a Bluetooth Service The steps involved in registering a service are defined in the Service Discovery Protocol (SDP), which is part of the Bluetooth Specification, and are as follows: create a service record, add the service record to the Service Discovery Database, set security measures associated with connections to clients, accept connections from clients Each Bluetooth service offered by a host is represented by a Service Record in the Service Discovery Database (SDDB). To connect to a service a client obtains a Service Record from the server and uses the information therein to connect to the service. 18

19 Requesting a Connection Bluetooth services are uniquely identified by a 128-bit Universally Unique Identifier (UUID). Every service has a UUID including generic low-level protocols and profiles. LocalDevice local = LocalDevice.getLocalDevice(); UUID uuid = new UUID(" AABBCCDDEEFF", true); DiscoveryAgent agent = local.getdiscoveryagent(); String url = agent.selectservice(uuid, ServiceRecord.NOAUTHENTICATE_NOENCRYPT, false); if (url == null) { throw new IOException("Device not found"); } StreamConnection connection = (StreamConnection)Connector.open(url); InputStream input = connection.openinputstream(); Note: For convenience the Service Discovery Protocol allows the use of 16-bit or 32-bit alias ( short ) UUIDs. UUIDs must be generated (e.g. by uuidgen) or obtained from 19

20 Offering a Connection The acceptandopen() method makes the server ready to accept client connections. It blocks until the server accepts the client connection. LocalDevice local = LocalDevice.getLocalDevice(); local.setdiscoverable(discoveryagent.giac); UUID uuid = new UUID(" AABBCCDDEEFF", true); String url = "btspp://localhost:" + uuid.tostring(); StreamConnectionNotifier notifier = Connector.open(url.toString()); StreamConnection connection = notifier.acceptandopen(); InputStream input = connection.openinputstream(); OutputStream output = connection.openoutputstream(); 20

21 Well-known UUIDs SDP 0x bit RFCOMM 0x bit OBEX 0x bit HTTP 0x000C 16-bit L2CAP 0x bit BNEP 0x000F 16-bit Serial Port 0x bit ServiceDiscoveryServerServiceClassID 0x bit BrowseGroupDescriptorServiceClassID 0x bit PublicBrowseGroup 0x bit OBEX Object Push Profile 0x bit OBEX File Transfer Profile 0x bit Personal Area Networking User 0x bit Network Access Point 0x bit Group Network 0x bit Base UUID Value (used in promoting 16-bit and 32-bit UUIDs to 128-bit UUIDs) 0x F9B34FB

22 Device Discovery Because wireless devices are mobile they need a mechanism that allows them to find other devices and gain access to their capabilities. The DiscoveryAgent class and DiscoveryListener interface provide the necessary discovery services. The DiscoveryAgent class provides methods to perform device and service discovery. A local device must have only one DiscoveryAgent object. LocalDevice local = LocalDevice.getLocalDevice(); DiscoveryAgent agent = local.getdiscoveryagent(); 22

23 Discovery Listener The DiscoveryListener interface allows an application to receive device discovery and service discovery events. DiscoveryAgent startinquiry() cancelinquiry() searchservice() 1 DiscoveryListener devicediscovered() inquirycompleted() servicediscovered() servicesearchcompleted() public class Discoverer implements DiscoveryListener {... public void startdiscovery() { agent = local.getdiscoveryagent(); agent.startinquiry(discoveryagent.giac, this); } 23

24 Discovery Listener (1) When a device is discovered the devicediscovered() method is called by an implementation. It may be called many times. public void devicediscovered(remotedevice device, DeviceClass type) { try{ remotedevices.addelement(remotedevice); } catch(exception e){ } } The inquirycompleted() method is called by the implementation when the device inquiry has completed. public void inquirycompleted(int status) { if (status == INQUIRY_COMPLETED) { } else if (status == INQUIRY_TERMINATED){ } else if (status == INQUIRY_ERROR) { } } 24

25 Discovery Listener (2) Once we obtain a remote device, we can search for offered services by searchservices(attrset, uuidset, remotedevice, this) and servicesdiscovered method is called on the Listener each time a service is found. It can be used to list the services and select an usable one, or for other purposes. public void servicesdiscovered(int transid, ServiceRecord[] servrecord) { for(int i = 0; i < servrecord.length; i++) { DataElement servicenameelement = servrecord[i].getattributevalue(0x0100); String servicename = ((String)serviceNameElement.getValue()).trim(); } } 25

26 Connection Protocols JSR 82 specifies support for three communication protocols: L2CAP The Logical Link Control and Adaption Protocol (L2CAP) is the lowest level data transmission protocol in the Bluetooth stack. Data is sent and received in packets, whose maximum size is defined by the Maximum Transmission Unit (MTU). RFCOMM The RFCOMM layer provides a stream based connection protocol analogous to serial port communication and is the basis of the Serial Port Profile (SPP). OBEX OBEX is the highest level communication protocol available in JSR 82, sitting on top of RFCOMMM and L2CAP. OBEX, the Object Exchange protocol, can be used to send and receive complete objects (e.g. files, images etc). 26

27 Connection Examples The addresses can be either constructed (see above), or stored (e.g. in record store). String UUID = new UUID(0xABCD1234).toString(); L2CAP String url="btl2cap://001a2b3c4d5e:" + UUID + ";ReceiveMTU=500;TransmitMTU=500"; RFCOMM String url="btspp://001a2b3c4d5e:" + UUID //e.g. 0x1101 for serial port + ";authenticate=false;encrypt=false;master=true"; String srvurl ="btspp://localhost:" + UUID + ";name=sserver" OBEX String url="btgoep://00a3920b2c22:" + channel; String srvurl="btgoep://localhost:" + UUID; StreamConnection conn = (StreamConnection)Connector.open(url); 27

28 OBEX remarks OBEX defines several commands, which can processed by OBEX server. Once a client session is established, they are processed by your class extending ServerRequestHandler. The commands are: CONNECT SET PATH PUT GET DELETE connection from client change current directory send an object from client receive an object by client remove the object on server An authenticator is used to verify the client 28