org.opennfc.p2p
Interface P2PManager

public interface P2PManager

This interface exposes the methods for the Peer to Peer communication (P2P). Use NfcManager.getP2PManager() to create an new instance of P2P manager. Both connection-oriented and connectionless transports defined in the LLCP specification are supported.

The local P2P stack is configurable. The stack configuration is common to all applications, meaning that only the last parameters set are taken into account. A change of the P2P stack configuration does not impact the currently established P2P link (if any), but only the future link establishments.

Default configuration values should suit most application requirements, meaning the configuration of the stack is optional.

The P2P link establishment is requested by calling the establishLink() API. Once P2P link establishment has been requested, the NFC controller starts hunting for the presence of a peer P2P device. When a P2P device is found, the establishment P2PLinkEventHandler.onLinkDetected() method is called.

Both connection-oriented and connectionless object retrieved by a call to createP2PConnection() or createP2PConnectionLess() functions are not related to one P2P link session P2PLink, meaning the same connection object can be used over several P2P link establishments. The connection object are destroyed only when the corresponding handles are closed.

Since:

Open NFC 4.1

establishLink

void establishLink(P2PLinkEventHandler listener)
                   throws NfcException

Requests establishment of the P2P RF link.

Parameters:

listener - a P2PLinkEventHandler whose onLinkDetected() method will be called when a new P2P link is established or onLinkError() method will be called when an error occurs or onLinkReleased() method will be called when the link is broken.

Throws:

IllegalArgumentException - if listener is null.

IllegalStateException - if a link operation is ongoing.

NfcException - a NFC error occurred.

Since:

Open NFC 4.1

cancelLink

void cancelLink()

Cancels the pending establishment link procedure.

If cancel is called when the link establishment is not yet completed, the onLinkDetected() function is called.

Since:

Open NFC 4.1

createP2PConnection

P2PConnection createP2PConnection(P2PManager.Mode mode,
                                  String serviceUri,
                                  byte sap)
                                  throws NfcException

Creates a new P2P connection-oriented object.

Prior being able to send/receive data through a connection-oriented transport, a connection must be established, using OpenNfcP2PConnection.connect() function call. We distinguish 3 types of connection-oriented transports : client, server and client/server transports.

When called with parameter type set to P2PManager.Mode.SERVER, a connection-oriented server transport will be created.

If non-zero, the parameter SAP contains the SAP value on which the server will listen (valid range is 2 - 63). SAP is typically only set to a non-zero value when implementing a "well-known service" that must listen on a specific SAP value.

If parameter SAP is set to zero, a free SAP will be allocated by the stack.

If non null, the parameter sericeUri contains the service name associated to the connection. This service name will be registered into the SDP (Service Discovery Protocol) implemented in the P2P stack, allowing a remote device to connect to this server using its name.

The combination of SAP set to null and sericeUri set to null is not a valid configuration for server transports.

When called with type set to P2PManager.Mode.CLIENT, a connection-oriented client transport will be created.

If non-zero, the parameter SAP contains the SAP value on which the client will try to connect (2-63). In this case, the parameter sericeUri must be null.

If the parameter serviceUri is non null, it contains the service name on which the client will try to connect. In this case, the parameter SAP value must be zero.

The combination of SAP set to a value different from zero and sericeUri set to a non-null value is not a valid configuration for connection oriented client transport.

When called with type set to P2PManager.Mode.CLIENT_SERVER, a connection-oriented client/server will be created.

If non-zero, the parameter SAP contains the SAP value on which the client/server will listen. If SAP is set to zero, a free SAP will be allocated to the connection by the P2P stack. If the parameter sericeUri is null, the parameter SAP value is also be used to establish a connection with the peer. Otherwise, the sericeUri parameter will be used to perform the connection.

If not null, the sericeUri contains the service name associated to the socket. This service name will be registered into the SDP implemented in the P2P stack. This service name will also be used to connect to the remote service.

Parameters:

mode - the requested mode for the connection:

• Mode.CLIENT for a client connection,
• Mode.SERVER for a server connection, or
• Mode.CLIENT_SERVER for aclient or server connection.

.

serviceUri - the service URI to connect to.

sap - The Service Access Point. Valid values are 0, and any value in the range 2-63.

Returns:

A new P2P connection instance.

Throws:

IllegalStateException - if the specified sap or sericeUri value is already in use.

NullPointerException - if mode is null.

IllegalArgumentException - if the combination of SAP and sericeUri is not a valid configuration.

NfcException - if NFC error occurred.

Since:

Open NFC 4.1

createP2PConnectionLess

P2PConnectionLess createP2PConnectionLess(String serviceUri,
                                          byte sap)
                                          throws NfcException

Creates a new P2P connectionless object.

Connectionless transport do not require any connect operation prior being able to send/receive data.

If non-zero, the SAP parameter contains the SAP value on which the connectionless will be bound. If set to zero, a free SAP will be allocated to the connectionless by the P2P stack.

If non null, sericeUri contains the service the service name associated to the connectionless object. This service name will be registered into the SDP implemented into the stack, allowing peer device to perform a name lookup (LLCP 1.1 specific feature)

The combination of SAP set to zero and sericeUri set to null is not a valid configuration for connectionless transports.

Parameters:

serviceUri - the service URI to connect to.

sap - The Service Access Point. Valid values are 0, and any value in the range 2-63.

Returns:

A new P2P connectionless instance.

Throws:

IllegalStateException - if the specified SAP or sericeUri value is already in use.

IllegalArgumentException - if the combination of SAP and sericeUri is not a valid configuration.

NfcException - if NFC error occurred.

Since:

Open NFC 4.1