Package com.nokia.nfc.llcp

See:
          Description

Package com.nokia.nfc.llcp Description

Provides an interface for communicating with remote devices using LLCP.

Logical Link Control Protocol API

The Logical Link Control Protocol API, LLCP API, provides MIDlets an interface to communicate with remote devices using LLCP.

Two LLCP transport types are supported: Type 1 and Type 2. Type 1 is a connection-less transport that is a unreliable, session-less data transport. Type 2 is a connection-oriented transport that is a reliable, session-based data transport. In this API communication using either of the transport types is done with the common LLCPConnection interface.

One can listen to LLCP link related events by using the LLCPLinkListener interface. The listener is notified when a link is established and when a link is lost. These listeners are added and removed using the LLCPManager class. For example:

    LLCPManager llcpMngr = LLCPManager.getInstance();
    llcpManager.addLinkListener(this);
    ...
    llcpManager.removeLinkListener(this);

This API supports listening to incoming connections and opening a connection with the remote device directly. The latter method of opening a connection is done using the Connector.open() method, but only if a LLCP link has been established. For example to open a Type 2 connection that uses the protocol identifier (PID) 5:

    public void linkEstablished(String uid) {
        // Time consuming operations should be done in a separate thread.
        new Thread() {
            public void run() {
                LLCPConnection conn = (LLCPConnection) Connector.open("nfc:llcp;type=2;pid=5;uid=" + uid);
                ...
            }
        }.start();
    }

    <llcp_connection_uri> ::== "nfc:llcp;type="<transport_type>";pid="<protocol_id>";uid="<uid>
         <transport_type> ::== "1" | "2"
            <protocol_id> ::== decimal integer (0-62)
                    <uid> ::== UID of the remote LLCP device as a hexadecimal string

In order to start listening for incoming connections use the LLCPManager.startListening method. When the remote LLCP device connects to the local device using same transport type and PID, the implementation creates the LLCPConnection object and calls the LLCPConnectionListener.connectionOpened method. To stop listening for incoming connections call the LLCPManager.stopListening method. Applications should start listening for incoming connections before a link has been established. Otherwise it is possible that connection attempts from a remote device will fail. When using Type 1 transport the connections are specific for a protocol identifier. The first incoming Type 1 data frame with the PID that the application is listening to, will open the LLCPConnection. When using Type 2 transport the connections have separate channels.

Once a connection is open data can be sent and received using the LLCPConnection.send and LLCPConnection.receive methods. For example:

    LLCPConnection conn = null;
    
    try {
        conn = ...;
        byte[] data = "Hello world!".getBytes();
        conn.send(data);
        data = conn.receive();
        ...
    } finally {
        if (conn != null) {
            conn.close();
        }
    }

The ErrorRecoveryListener can be used to get information about the LLCP link error recovery status. These listeners can be added and removed using the methods LLCPManager.addErrorRecoveryListener and LLCPManager.removeErrorRecoveryListener.

PushRegistry support

The implementation supports LLCP PushRegistry connections that enable launching a registered MIDlet when a remote device communicates with the local device using LLCP. When using a Type 1 PushRegistry connection sending a single packet of data to the correct PID will launch the MIDlet, and the MIDlet can acquire the received data by starting to listen for incoming connections using the same PID. When using a Type 2 PushRegistry connection the remote device needs to open a connection using the same PID. Once the registered MIDlet has been launched the MIDlet should start listening for incoming connections using the same PID in order to open the connection and to start receiving data.

LLCP push registration connection URI must conform to the BNF syntax specified below.

     <llcp_push_uri> ::== "llcp-type"<transport_type>":?pid="<protocol_id>
    <transport_type> ::== "1" | "2"
       <protocol_id> ::== decimal integer (0-62)

Received data will be buffered until the MIDlet has been launched and it has created a connection corresponding to the Push registration. The implementation can limit the amount of time the buffered data is available. So for example the buffered data might not be available after 30 seconds.

Implementation specifics

SNEP PID (5) is reserved for native applications. This means that applications cannot add PushRegistry connections using SNEP PID. When a MIDlet is running the application can use SNEP.

The implementation maintains an internal buffer for received data. The buffer size is fixed and shared between LLCPConnection objects. If the buffer gets full the device will stop acknowledging incoming data until the data is consumed by the MIDlet or once the connections are closed either by the MIDlet or if the link is lost.

For Type 1 PushRegistry connections only the first data packet will be buffered. The data packet can be acquired even if the link is already lost when starting to listen for incoming connections. When using Type 2 PushRegistry connections receiving the data will not be acknowledged to the remote device until the MIDlet has started and created the connection. This way the data the remote device has sent will not get lost.