org.opennfc.p2p
Interface P2PConnection

public interface P2PConnection

This interface exposes the methods for the Peer to Peer communication (P2P). Use P2PManager.createP2PConnection(org.opennfc.p2p.P2PManager.Mode, java.lang.String, byte) to create an new instance of P2P connection.

Since:

Open NFC 4.1

getParameter

int getParameter(P2PConnection.P2PConnectionParameter parameter)
                 throws IOException,
                        NfcException

Retrieves the value of a connection parameter.

Parameters:

parameter - The parameter to be retrieved.

Returns:

The parameter value.

Throws:

IOException - if the connection is not established.

NfcException - if other error occurred.

setParameter

void setParameter(P2PConnection.P2PConnectionParameter parameter,
                  int value)
                  throws IOException,
                         NfcException

Sets the value of a connection parameter.

Parameters:

value - The value of the parameter to be set.

parameter - The value of the parameter to be set must be one of the following values:

• P2PConnection.P2PConnectionParameter.LOCAL_MIU is sent during the connection establishment,
• P2PConnection.P2PConnectionParameter.LOCAL_RW is sent during the connection establishment.

Throws:

IOException - if the connection is not established.

IllegalArgumentException - If the parameter is not valid.

NfcException - if a NFC error occurred.

connect

void connect(P2PLink link)
             throws IOException,
                    NfcException

Requests a connection establishment.

This method must be called prior to be able to send/receive data on the established P2P connection.

A P2P connection remains established as long as the specified P2P link remains active. When the P2P link is destroyed, the connection is automatically closed. A new call to connect() must be done once the P2P link has been reestablished.

Shutdown of an established connection can be done using the shutdown() method. Once the connection has been closed, it can be reestablished using connect(). Several connection/disconnection cycles can be performed during the same P2P link establishment.

This method is blocking until the connection has been established or in case of error. If needed, the connect operation can be canceled using shutdown() method.

Parameters:

link - The established link.

Throws:

IllegalArgumentException - if link is null.

IOException - if connection to the target is lost or it has been closed.

IllegalStateException - if the connection is already established or the P2P link is no longer established.

NfcException - if a NFC error occurred.

Since:

Open NFC 4.1

write

void write(byte[] data)
           throws IOException

Sends data to the peer device. If data is of length 0, an empty frame will be sent. The method block until the full buffer content is sent. The general contract for write(data) is that it should have exactly the same effect as the call write(data, 0, data.length).

Parameters:

data - the buffer containing the data to be sent.

Throws:

IllegalStateException - if the connection is not open or if another write operation is pending.

IllegalArgumentException - if the data buffer is null.

IOException - if an error occurs during the communication with the peer device, or if shutdown() is called before the write operation is completed, or if the peer device closed the connection before receiving the data.

Since:

Open NFC 4.1

write

void write(byte[] data,
           int off,
           int len)
           throws IOException

Sends data to the peer device. If data is of length 0, an empty I frame will be sent. The method block until the full buffer content is sent.

Parameters:

data - the buffer containing the data to be sent.

off - the start offset in byte of the data in the buffer.

len - the number of bytes to write.

Throws:

IllegalStateException - if the connection is not open or if another write operation is pending.

IllegalArgumentException - if the data buffer is null or if offset or length are negative.

IndexOutOfBoundsException - if the offset or length are outside of the data buffer.

IOException - if an error occurs during the communication with the peer device, or if shutdown() is called before the write operation is completed, or if the peer device closed the connection before receiving the data.

Since:

Open NFC 4.1

read

int read(byte[] data)
         throws IOException

Reads some number of bytes from the P2P connection and stores them into the buffer array data. The amount of data received in this operation is related to the value of the LocalMIU. The number of bytes actually read is returned as an integer.

This method block until input data is available, or an exception is thrown.

Parameters:

data - the buffer to store the received data.

Returns:

the actual number of bytes read; 0 if data length is zero.

Throws:

IllegalStateException - if the connection is not open or if another read operation is pending.

IllegalArgumentException - if the data buffer is null.

IOException - if an error occurs during the communication with the peer device or if shutdown() or cancel() is called before the read operation is completed.

Since:

Open NFC 4.1

read

int read(byte[] data,
         int off,
         int len)
         throws IOException

Reads up to len bytes of data from the P2P connection into an array of bytes. The amount of data received in this operation is related to the value of the LocalMIU. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer.

This method block until input data is available, or an exception is thrown.

If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available , the value -1 is returned; otherwise, at least one byte is read and stored into data.

Parameters:

data - the buffer to store the received data.

off - the start offset in byte of the data in the buffer.

len - the number of bytes to read.

Returns:

the actual number of bytes read; 0 if a zero length frame is received; 0 if data length is zero.

Throws:

IllegalStateException - if the connection is not open or if another read operation is pending.

IllegalArgumentException - if the data buffer is null or if off or len are negative.

IndexOutOfBoundsException - if the offset or length are outside of the data buffer.

IOException - if an error occurs during the communication with the peer device or if shutdown() or cancel() is called before the read operation is completed.

Since:

Open NFC 4.1

cancel

void cancel()

Cancels every pending operation.

Since:

Open NFC 4.1

shutdown

void shutdown()
              throws IOException,
                     NfcException

Shutdowns the connection. shutdown() tries to perform a graceful shutdown, meaning it ensures all pending data have been sent before closing the connection.

If the peer does not acknowledge pending data in a timely manner, the connection will be closed even if there is remaining data to send.

This is the safe manner to request termination of a P2P connection.

Throws:

IOException - if the connection is not established.

NfcException - if a NFC error occurred.

Since:

Open NFC 4.1

close

void close()
           throws IOException

Closes a pending connection.

Throws:

IOException - if the connection is broken.

Since:

Open NFC 4.1