javax.microedition.io
Interface IMCConnection

All Superinterfaces:

javax.microedition.io.Connection, javax.microedition.io.InputConnection, javax.microedition.io.OutputConnection, javax.microedition.io.StreamConnection

public interface IMCConnection
extends javax.microedition.io.StreamConnection

This interface defines a low-level asynchronous bi-directional stream connection for the Inter-MIDlet Communication protocol (IMC).

An instance of this interface is returned from Connector.open() when it is called with an IMC client URI string. An IMCConnection instance is also returned from IMCServerConnection.acceptAndOpen() for incoming client connection.

An IMC server MIDlet can register a server connection with push registry and be automatically launched upon client connection request. An implementation MUST support registration of IMC server MIDlets for application launch on incoming IMC connection. If the AMS fails to launch the IMC server MIDlet due to the system limit of maximum number of concurrent MIDlets has been reached or the user denies such auto-launch request or any other reasons, a ConnectionNotFoundException MUST be thrown from Connector.open() to the IMC client MIDlet.

BNF Format for Connector.open() string

The IMC client connection URIs must conform to the BNF syntax defined below. If a client URI passed into Connector.open() does not conform to this syntax, an IllegalArgumentException is thrown.

<client_conn_string>	::= "imc://" (<MIDlet UID>|"*") ":" <server name> ":" <server version> ";" [<authmode>]
<MIDlet UID>	::= <MIDlet suite vendor>":" <MIDlet suite name>":" <MIDlet suite version>
<MIDlet suite vendor>	::= MIDlet suite vendor
<MIDlet suite name>	::= MIDlet suite name
<MIDlet suite version>	::= MIDlet suite version or wildcard character "*"
<server name>	::= IMC server name following the class naming syntax
<server version>	::= version of the IMC server. Version backward compatibility is assumed.Versioning follows the format defined for the MIDlet-Version attribute.
<authmode>	::= authmode=true|false

The BNF syntax allows the wildcard "*" to be used instead of a specific MIDlet UID when opening an IMC client connection. When the wildcard character is used, it allows the client to connect to any of the MIDlets from different vendors if they all provide the same IMC service and meet the authorization requirements. However, which MIDlet's IMC server the client will be connected is implementation specific.

An IMC server may restrict access to a authorized clients only using Application level access authorization. See IMCServerConnection for further details. If the client connection is not authorized to connect to the server, the Connector.open(..) call MUST throw a SecurityException. Similarly, an IMC Client connection can specify that it connect only to authorized servers. Authorized servers are identified using the Application level access authorization mechanisms. The MIDlet that is making the client connection declares it authorization attributes that identify the server as authorized. Only authorized servers will cause a Connector.open(..) call from a client to succeed.

Examples

      // Create a connection to any MIDlet providing the com.foo.services.barServer
      IMCConnection conn = (IMCConnection)Connector.open(
              "imc://*:com.foo.services.barServer:1.0;authmode=false");

      try {
          DataOutputStream request = conn.openDataOutputStream();

          // writes request data
          ...

          // flush the request input stream
          request.flush();

          DataInputStream response = conn.openDataInputStream();

          // retrieve response data
          ...
      } finally {
          conn.close();
      }
 

Since:

MIDP 3.0

Method Summary

MIDletIdentity	getRemoteIdentity() Get the identity of the MIDlet on the remote end of this connection
java.lang.String	getRequestedServerVersion() Get the server version the IMC client requested to connect to in the client connection URI
java.lang.String	getServerName() Get the name of the IMC server of this connection.

Methods inherited from interface javax.microedition.io.InputConnection

openDataInputStream, openInputStream

Methods inherited from interface javax.microedition.io.Connection

close

Methods inherited from interface javax.microedition.io.OutputConnection

openDataOutputStream, openOutputStream

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

getServerName

java.lang.String getServerName()

Get the name of the IMC server of this connection. The name is the server name specified in the connection URI.

Returns:

Server name of the IMC connection

getRequestedServerVersion

java.lang.String getRequestedServerVersion()

Get the server version the IMC client requested to connect to in the client connection URI

Returns:

The requested server version

getRemoteIdentity

MIDletIdentity getRemoteIdentity()

Get the identity of the MIDlet on the remote end of this connection

Returns:

MIDlet identity of the other end of the connection