com.docomostar.io
インタフェース SocketConnection

すべてのスーパーインタフェース:

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

public interface SocketConnection

extends javax.microedition.io.StreamConnection

TCP プロトコルでのネットワークへの接続を定義します。この機能は、パーミッションとして TCP 通信（クライアント／サーバー型もしくはPeer-to-Peer型）が許可されたトラステッドStarアプリでのみ利用することができます。

TCP 通信では、端末に対してドコモ網から接続に必要な情報(IPアドレス、ポート番号等)を取得した後、TCP セッションを確立して通信を行います。

端末⇔コンテンツプロバイダ間で通信する「クライアント/サーバ型接続」、あるいは端末⇔端末間で通信する「Peer-to-Peer型接続」のいずれかの方式で通信を行うことができます。詳細は後述を参照してください。

本インタフェースには、以下の状態が存在します。

初期状態

Connector.open() を "socket" のスキームでコールすることで生成された直後の状態を指します。

ポートオープン状態

端末に対してドコモ網から接続に必要な情報(IPアドレス、ポート番号等)を取得した状態を指します。

初期状態で openRemotePort() メソッドを実行するとポートオープン状態に遷移します。

初期状態からのみ openRemotePort() メソッドは実行可能です。

TCP 通信可能状態

TCP 通信用のセッションが確立された状態を指します。

StreamConnection インタフェースから継承したストリームを利用する機能によりTCP通信を行うことができます。

ポートオープン状態で、 TCP のセッションが確立されると TCP 通信可能状態に遷移します。

セッション確立メソッド(connect()、connect(String, int))は、ポートオープン状態からのみ実行可能です。

TCP 通信可能状態において網から切断された場合は、close()、getAddress()、getLocalAddress()、getLocalPort()、getPort() をのぞくメソッドの呼び出しはIOExceptionが発生します。

この場合はTCP通信不可状態への状態遷移のみが可能となります。

接続待ち状態

他の端末からの接続を待ち受けている状態を指します。

ポートオープン状態において、 listen(String, int) メソッドを実行すると接続待ち状態になります。

listen(String, int) メソッドはセッションが確立されるまで処理をブロックします。

listen(String, int) メソッドはポートオープン状態からのみ実行可能です。

TCP通信不可状態

TCP のポートがクローズされ、通信ができない状態を指します。

この状態では、ネットワークのリソース、及び送受信バッファ等のリソースは全て破棄されます。

close() メソッドを実行すると TCP 通信不可状態に遷移します。

close() メソッドは、任意の状態で実行することが可能です。

TCP 通信は「クライアント/サーバ型接続」、もしくは「Peer-to-Peer型接続」のいずれかの方式で通信を行うことができます。 以下にそれぞれの方式についての詳細を述べます。

クライアント/サーバ型接続

端末と任意のサーバの通信を行う接続型です。

Connector.open() メソッドで、接続先 URL を以下の形式で指定するとTCP通信:クライアント/サーバ型接続となります。
"socket://<ホスト名>:<ポート番号>"

以下に TCP 通信においてクライアント/サーバ型接続を行う場合のコード例を示します。

   
       SocketConnection sc = (SocketConnection)Connector.open("socket://example.com:12345");
       sc.openRemotePort(); // ドコモサーバに対してグローバルIPアドレスとポート番号の払い出し要求を行う。
       sc.connect(); // 端末とサーバ間のセッションを確立します。

       InputStream in = sc.openInputStream();
       OutputStream out = sc.openOutputStream();
       // 読み込み、書き込み処理

       in.close();
       out.close();
       sc.close(); // 接続を閉じてリソースを解放します。 
   
 

Peer-to-Peer 型接続

端末間で直接通信を行う接続型です。

Connector.open() メソッドで、接続先 URL を以下の形式で指定するとTCP通信:Peer-to-Peer型接続となります。
"socket://<P-to-P用URL>"

<P-to-P用URL> 部分には通信がPeer-to-Peer型接続であることを示す固定文字列を設定します。

以下に TCP 通信において 端末Aと端末BがサーバCより相互に通信相手に払い出されたIPアドレスとポート番号について通知を受け、 Peer-to-Peer 型接続を行う場合のコード例を示します。（この例ではサーバCとの通信でHTTPコネクションを使用し、通信相手アドレスを交換します。サーバはマッチングサーバ・ゲームサーバであることが想定されます）

   ※端末A※  
    // ① グローバルIPアドレスとポート番号をサーバーCに送信する。 //
    // ② サーバーCから端末BのグローバルIPアドレスとポート番号取得する。 //
    // ③ 端末Bに対してセッションの確立を行う。 //
    
       // ① //
       SocketConnection scA = (SocketConnection)Connector.open("socket://<P-to-P用URL>");
       scA.openRemotePort(); // グローバルIPアドレスとポート番号を払い出してもらう。
       String addressMobileA = scA.getLocalAddress(); // 端末Aに払い出されたIPアドレスを取得
       int portMobileA = scA.getLocalPort(); //端末Aに払い出されたポート番号を取得
       HttpConnection hcA = (HttpConnection)Connector.open("http://<サーバーCのホスト名>");
       //サーバCに対して端末Aに払い出されたIPアドレスとポート番号を送信
       
       // ② //
       hcA.connect(…);    
       //サーバCから、端末Bに払い出されたIPアドレスとポート番号を受信
       
       // ③ //
       scA.connect(addressMobileB, portMobileB); // 端末Bに対して Peer-to-Peer 接続要求を行う。
       
       InputStream in = scA.openInputStream();
       OutputStream out = scA.openOutputStream();
       // 読み込み、書き込み処理

       in.close();
       out.close();
       scA.close(); // 接続を閉じてリソースを解放します。 
       
  ※端末B※  
    // ① グローバルIPアドレスとポート番号をサーバーCに送信する。 
    // ② サーバCから端末AのグローバルIPアドレスとポート番号を取得する。 //
    // ③ 端末AのグローバルIPアドレスとポート番号からのセッション確立要求待ち状態に遷移する。 //
    
       // ① //
       SocketConnection scB = (SocketConnection)Connector.open("socket://<P-to-P用URL>");
       scB.openRemotePort(); // グローバルIPアドレスとポート番号を払い出してもらう。
       String addressMobileB = scB.getLocalAddress(); // 端末Bに払い出されたIPアドレスを取得
       int portMobileB = scB.getLocalPort(); //端末Bに払い出されたポート番号を取得
       HttpConnection hcB = (HttpConnection)Connector.open("http://<サーバーCのホスト名>");
       //サーバCに対して端末Bに払い出されたIPアドレスとポート番号を送信
       
       // ② //
       hcB.connect(…);
       //サーバCから、端末Aに払い出されたIPアドレスとポート番号を受信
       
       // ③ //
       scB.listen(addressMobileA, portMobileA); // 端末Aからの接続要求を待つ。
       
       InputStream in = scB.openInputStream();
       OutputStream out = scB.openOutputStream();
       // 読み込み、書き込み処理
       
       in.close();
       out.close();
       scB.close(); // 接続を閉じてリソースを解放します。 
       
 

導入されたバージョン:

Star-1.0

メソッドの概要

void	close() 接続を閉じてリソースを解放します。
void	connect() クライアント/サーバ型接続にて、接続先に対してセッションを確立します。
void	connect(String host, int port) Peer-to-Peer 型接続にて、指定した接続先に対してセッションを確立します。
String	getAddress() 接続先のアドレスを取得します。
String	getLocalAddress() 端末に払い出された IP アドレスを取得します。
int	getLocalPort() 端末に払い出されたポート番号を取得します。
int	getPort() 接続先ポート番号を取得します。
void	listen(String host, int port) Peer-to-Peer 型接続にて、指定した接続先からの接続を待ち受けます。
java.io.DataInputStream	openDataInputStream() データ入力ストリームを取得します。
java.io.DataOutputStream	openDataOutputStream() データ出力ストリームを取得します。
java.io.InputStream	openInputStream() 入力ストリームを取得します。
java.io.OutputStream	openOutputStream() 出力ストリームを取得します。
void	openRemotePort() グローバルIPアドレスとポート番号の払い出し要求を行います。

メソッドの詳細

close

public void close()
           throws java.io.IOException

接続を閉じてリソースを解放します。

ネットワークのリソース、及び送受信バッファ等のリソースは全て破棄されます。

定義:

インタフェース javax.microedition.io.Connection 内の close

例外:

ConnectionException -
(OUT_OF_SERVICE)
圏外(音声不可/パケット不可)になったことを検知した場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
現在の実装では発生することは有りません。

connect

public void connect()
             throws java.io.IOException

クライアント/サーバ型接続にて、接続先に対してセッションを確立します。

Connector.open() メソッドの引数 name に指定した接続先 URL に対してセッションを確立します。

メソッドを呼び出した場合、Star アプリはサスペンドせずに接続処理を行います。 このメソッドはブロッキングメソッドとして動作します。

本メソッドはクライアント/サーバ型接続時に使用します。 Peer-to-Peer型接続時に本メソッドが呼ばれた場合は例外が発生します。

本メソッドはポートオープン状態で実行してください。 その他の状態で実行された場合は例外が発生します。

例外:

ConnectionException -
(OUT_OF_SERVICE)
圏外(音声不可/パケット不可)になったことを検知した場合に発生します。

IllegalStateException -
ポートオープン状態以外で実行された場合に発生します。

ConnectionException -
(SERVICE_UNAVAILABLE)
接続時や通信時に、 キッズ制限が適用されている、等の理由でTCP通信がサービスとして利用できない場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

ConnectionException -
(TIMEOUT)
接続時や通信時にタイムアウトした場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
別スレッドにて同一インスタンスの connect() を呼び出し中に、このメソッドを呼び出した場合に発生します。

IllegalStateException -
コネクションオブジェクトが クライアント/サーバ型接続 のためのオブジェクトではなく、Peer-to-Peer 型接続 のためのものであった場合に発生します。 別スレッドにて同一インスタンスの connect(String, int) を呼び出し中に、このメソッドを呼び出した場合も含みます。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
I/Oエラーの場合に発生します。

connect

public void connect(String host,
                    int port)
             throws java.io.IOException

Peer-to-Peer 型接続にて、指定した接続先に対してセッションを確立します。

引数に指定した接続先に対して TCP セッションの確立を行います。 引数の接続先には、ドコモ網から払い出された接続先の IP アドレス、及びポート番号を指定してください。 クライアント/サーバ型接続時に本メソッドが呼ばれた場合は例外が発生します。

メソッドを呼び出した場合、Star アプリはサスペンドせずに接続処理を行います。 このメソッドはブロッキングメソッドとして動作します。

本メソッドはポートオープン状態で実行してください。 その他の状態で実行された場合は例外が発生します。

パラメータ:

host - 接続先の IP アドレスを指定します。

port - 接続先ポート番号を指定します。

例外:

IllegalArgumentException -
引数の host が不正な場合に発生します。

IllegalArgumentException -
引数の port が不正な場合（ポート番号が1〜65535の範囲にない）に発生します。

ConnectionException -
(OUT_OF_SERVICE)
圏外(音声不可/パケット不可)になったことを検知した場合に発生します。

IllegalStateException -
ポートオープン状態以外で実行された場合に発生します。

ConnectionException -
(SERVICE_UNAVAILABLE)
接続時や通信時に、 キッズ制限が適用されている、等の理由でTCP通信/UDP通信がサービスとして利用できない場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

ConnectionException -
(TIMEOUT)
接続時や通信時にタイムアウトした場合に発生します。

ConnectionException -
(P2P_NOT_LISTENING)
peer-to-peer接続時に相手先端末がListenしていない場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
別スレッドにて同一インスタンスの connect(String, int) を呼び出し中に、このメソッドを呼び出した場合に発生します。

IllegalStateException -
コネクションオブジェクトが Peer-to-Peer 型接続 のためのオブジェクトではなく、クライアント/サーバ型接続 のためのものであった場合に発生します。 別スレッドにて同一インスタンスの connect() を呼び出し中に、このメソッドを呼び出した場合も含みます。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

NullPointerException -
引数 host に null が指定された場合に発生します。

java.io.IOException -
I/Oエラーの場合に発生します。

listen

public void listen(String host,
                   int port)
            throws java.io.IOException

Peer-to-Peer 型接続にて、指定した接続先からの接続を待ち受けます。

引数に指定した接続先に対して TCP セッションの確立を行います。 引数の接続先には、ドコモ網から払い出された接続先の IP アドレス、及びポート番号を指定してください。 クライアント/サーバ型接続時に本メソッドが呼ばれた場合は例外が発生します。

メソッドを呼び出した場合、Star アプリはサスペンドせずに接続処理を行います。 このメソッドはブロッキングメソッドとして動作します。

本メソッドはポートオープン状態で実行してください。 その他の状態で実行された場合は例外が発生します。

パラメータ:

host - 接続先のIPアドレスを指定します。

port - 接続先ポート番号を指定します。

例外:

IllegalArgumentException -
引数の host が不正な場合に発生します。

IllegalArgumentException -
引数の port が不正な場合（ポート番号が1〜65535の範囲にない）に発生します。

ConnectionException -
(OUT_OF_SERVICE)
圏外(音声不可/パケット不可)になったことを検知した場合に発生します。

IllegalStateException -
ポートオープン状態以外で実行された場合に発生します。

ConnectionException -
(SERVICE_UNAVAILABLE)
接続時や通信時に、 キッズ制限が適用されている、等の理由でTCP通信/UDP通信がサービスとして利用できない場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

ConnectionException -
(TIMEOUT)
接続時や通信時にタイムアウトした場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
別スレッドにて同一インスタンスの listen(String, int) を呼び出し中に、このメソッドを呼び出した場合に発生します。

IllegalStateException -
コネクションオブジェクトが Peer-to-Peer型接続 のためのオブジェクトではなく、クライアント/サーバ型接続 のためのものであった場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

NullPointerException -
引数 host に null が指定された場合に発生します。

java.io.IOException -
I/Oエラーの場合に発生します。

openRemotePort

public void openRemotePort()
                    throws java.io.IOException

グローバルIPアドレスとポート番号の払い出し要求を行います。

払い出されたアドレスはgetLocalAddress()、getLocalPort() メソッドで取得できます。

メソッドを呼び出した場合、Star アプリはサスペンドせずに接続処理を行います。 このメソッドはブロッキングメソッドとして動作します。

本メソッドは初期状態で実行してください。 その他の状態で実行された場合は例外が発生します。

例外:

ConnectionException -
(OUT_OF_SERVICE)
通信開始時に、 iモード未契約、圏外(音声不可/パケット不可)、 規制(パケット規制ON) 、または、定額制ユーザのデータ通信規制中であった場合や、 通信中に圏外になった場合に発生します。

IllegalStateException -
初期状態以外で実行された場合に発生します。

ConnectionException -
(SELF_MODE)
端末がセルフモードの場合に発生します。

ConnectionException -
(SERVICE_UNAVAILABLE)
接続時や通信時に、 キッズ制限が適用されている、等の理由でTCP通信/UDP通信がサービスとして利用できない場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

ConnectionException -
(TIMEOUT)
接続時や通信時にタイムアウトした場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
テレビ電話通話中に呼び出された場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
PTT呼通信中、PTT設定中に呼び出された場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
ミュージックチャネルダウンローダ起動中に呼び出された場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
ソフトウェア更新実行中に呼び出された場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
サポートしている以上の接続をオープンしようとした場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
別スレッドにて同一インスタンスの openRemotePort() を呼び出し中に、このメソッドを呼び出した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
I/Oエラーの場合に発生します。

openInputStream

public java.io.InputStream openInputStream()
                                    throws java.io.IOException

入力ストリームを取得します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。 また、入力ストリーム、あるいはデータ入力ストリームが既に開かれている状態で 本メソッドを実行した場合には例外が発生します。

定義:

インタフェース javax.microedition.io.InputConnection 内の openInputStream

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
既にInputStream、またはDataInputStreamがオープンされている場合に発生します。

java.io.IOException -
TCP 通信可能状態、かつ、網から切断された状態で呼び出された場合に発生します。

openDataInputStream

public java.io.DataInputStream openDataInputStream()
                                            throws java.io.IOException

データ入力ストリームを取得します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。 また、入力ストリーム、あるいはデータ入力ストリームが既に開かれている状態で 本メソッドを実行した場合には例外が発生します。

定義:

インタフェース javax.microedition.io.InputConnection 内の openDataInputStream

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
既にInputStream、またはDataInputStreamがオープンされている場合に発生します。

java.io.IOException -
TCP 通信可能状態、かつ、網から切断された状態で呼び出された場合に発生します。

openOutputStream

public java.io.OutputStream openOutputStream()
                                      throws java.io.IOException

出力ストリームを取得します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。 また出力ストリーム、あるいはデータ出力ストリームが既に開かれている状態で 本メソッドを実行した場合には例外が発生します。

定義:

インタフェース javax.microedition.io.OutputConnection 内の openOutputStream

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
既にOutputStream、またはDataOutputStreamがオープンされている場合に発生します。

java.io.IOException -
TCP 通信可能状態、かつ、網から切断された状態で呼び出された場合に発生します。

openDataOutputStream

public java.io.DataOutputStream openDataOutputStream()
                                              throws java.io.IOException

データ出力ストリームを取得します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。 また、出力ストリーム、あるいはデータ出力ストリームが既に開かれている状態で 本メソッドを実行した場合には例外が発生します。

定義:

インタフェース javax.microedition.io.OutputConnection 内の openDataOutputStream

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

ConnectionException -
(USER_ABORT)
ユーザ操作による Suspended 状態から復帰したことを検知した場合に発生します。

java.io.InterruptedIOException -
Suspended 状態から復帰したことを検知した場合や、 中断要求が発生したことを検知した場合に発生します。

java.io.IOException -
既にOutputStream、またはDataOutputStreamがオープンされている場合に発生します。

java.io.IOException -
TCP 通信可能状態、かつ、網から切断された状態で呼び出された場合に発生します。

getAddress

public String getAddress()

接続先のアドレスを取得します。

クライアント/サーバ型接続の場合は接続先ホスト名を返します。 Peer-to-Peer型接続の場合は接続先IPアドレスを返します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。

戻り値:

クライアント/サーバ型通信の場合は Connector.open() 時に指定したホスト名を返します。 Peer-to-Peer型接続の場合は connect()/listen() 時に指定したIPアドレスを返します。

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

getPort

public int getPort()

接続先ポート番号を取得します。

本メソッドは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。

戻り値:

クライアント/サーバ型通信の場合は Connector.open() 時に指定したポート番号を返します。 Peer-to-Peer型接続の場合は connect()/listen() 時に指定したポート番号を返します。

例外:

IllegalStateException -
TCP通信可能状態以外で実行された場合に発生します。

getLocalAddress

public String getLocalAddress()

端末に払い出された IP アドレスを取得します。

本メソッドは ポートオープン状態、接続待ち状態もしくは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。

戻り値:

自端末の IP アドレスを取得します。

例外:

IllegalStateException -
ポートオープン状態、接続待ち状態もしくは TCP 通信可能状態 以外の状態で実行された場合に発生します。

getLocalPort

public int getLocalPort()

端末に払い出されたポート番号を取得します。

本メソッドは ポートオープン状態、接続待ち状態もしくは TCP 通信可能状態で実行してください。 その他の状態で実行された場合は例外が発生します。

戻り値:

自端末のポート番号を取得します。

例外:

IllegalStateException -
ポートオープン状態、接続待ち状態もしくは TCP 通信可能状態 以外の状態で実行された場合に発生します。