net.kano.joscar.rvcmd
Class RvConnectionInfo

java.lang.Object
  extended byRvConnectionInfo
All Implemented Interfaces:
LiveWritable

public class RvConnectionInfo
extends java.lang.Object
implements LiveWritable

A data structure containing information about a destination address for a client-to-client rendezvous TCP connection.

Briefly, RvConnectionInfo represents a set of RV TLV's common to all TCP-connection-based rendezvous requests (and redirects). When a user sends a Direct IM invitation, for example, TLV's containing his ("internal") IP address and a port on which the recipient can connect for a Direct IM connection. Between the user and the recipient, the server adds another field to the command: the user's "external" IP address, or his or her address from its perspective. Finally, the recipient attempts to connect to either address (if they are different). (If he or she cannot connect, he sends a "redirect" request with his own RvConnectionInfo.)

New to the rendezvous client-to-client system is the AOL Proxy Server, a proxy hosted by AOL (at ars.oscar.aol.com) to allow two firewalled users to send files and hold Direct IM sessions even though neither can accept incoming TCP connections. This class accommodates for this with the fields proxyIP and proxied. For details on AOL Proxy Server support, see net.kano.joscar.rvproto.rvproxy.

The protocol for initiating such connection-based rendezvouses provides the concept of an "internal" and an "external" IP address. The need for such a distinction comes from the fact that when one is behind a firewall one may have a "LAN IP address" and a "WAN IP address," the LAN IP address being a computer's IP address on the internal network and the WAN IP address being the IP address of that same computer to users from outside the internal network.

When attempting to initiate a direct TCP connection, a client normally provides its "internal" or "LAN" IP address to the server. (In most cases, when not behind a firewall, this address is also the "external" IP address.) During the request's transmission from the source client to the recipient of the request, the server adds a field to the request containing the IP address of the source client from its perspective outside the user's internal network (unless, of course, one is connecting from inside an internal network at AOL :).


Constructor Summary
RvConnectionInfo(java.net.InetAddress internalIP, java.net.Inet4Address externalIP, java.net.Inet4Address proxyIP, int port, boolean proxied, boolean encrypted)
          Creates a new connection information block with the given properties.
 
Method Summary
static RvConnectionInfo createForOutgoingProxiedRequest(java.net.Inet4Address proxyIP, int port)
          Creates a new connection information block describing a connection via the AOL Proxy Server with the given proxy server IP address and "port number."
static RvConnectionInfo createForOutgoingRequest(java.net.InetAddress internalIP, int port)
          Creates a new connection information block with the given "internal IP address" and port.
static RvConnectionInfo createForOutgoingSecureRequest(java.net.InetAddress internalIP, int port)
          Creates a new connection information block with the given "internal IP address" and port for a secure (SSL) connection to the given host.
 java.net.InetAddress getExternalIP()
          Returns the "external IP address" contained in this connection information block.
 java.net.InetAddress getInternalIP()
          Returns the "internal IP address" contained in this connection information block.
 int getPort()
          Returns the TCP port specified in this connection information block.
 java.net.InetAddress getProxyIP()
          Returns the IP address of an AOL Proxy Server over which a connection should be made.
 boolean isEncrypted()
          Returns whether or not the associated connection is to be encrypted via SSL.
 boolean isProxied()
          Returns whether this connection block describes a connection over an AOL Proxy Server.
static RvConnectionInfo readConnectionInfo(TlvChain chain)
          Reads a connection information block from the given RV TLV chain.
 java.lang.String toString()
           
 void write(java.io.OutputStream out)
          Writes a representation of this object to the given stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RvConnectionInfo

public RvConnectionInfo(java.net.InetAddress internalIP,
                        java.net.Inet4Address externalIP,
                        java.net.Inet4Address proxyIP,
                        int port,
                        boolean proxied,
                        boolean encrypted)
Creates a new connection information block with the given properties.

Note that normally a client does not define the externalIP value (that is, the externalIP value should normally be null). This value is normally inserted by the OSCAR server.

Also note that there are two normal "formats" for an outgoing RvConnectionInfo, as described below. Note that in the table below "set" means "non-null" for objects and "nonnegative" for integers (the value of port).
internalIPexternalIP proxyIPport proxiedencrypted
setnot setnot set setfalsetrue or false
not setnot setset settruetrue or false

Parameters:
internalIP - the client's "internal IP address," the local IP address from the perspective of the client
externalIP - the client's "external IP address," the IP address from the perspective of the OSCAR server
proxyIP - the IP address of an AOL Proxy Server through which a connection should be made
port - a TCP port on which the recipient of this block should connect to the given IP address, or -1 for none
proxied - whether or not the described connection is "proxied"
encrypted - whether or not the described connection is to be made via SSL
See Also:
createForOutgoingRequest(java.net.InetAddress, int), createForOutgoingProxiedRequest(java.net.Inet4Address, int)
Method Detail

readConnectionInfo

public static RvConnectionInfo readConnectionInfo(TlvChain chain)
Reads a connection information block from the given RV TLV chain. Note that this method will never return null even if the given TLV chain contains no connection information TLV's.

Parameters:
chain - a TLV chain containing a rendezvous connection information block
Returns:
a RvConnectionInfo read from the given TLV's

createForOutgoingRequest

public static RvConnectionInfo createForOutgoingRequest(java.net.InetAddress internalIP,
                                                        int port)
Creates a new connection information block with the given "internal IP address" and port.

Parameters:
internalIP - the client's IP address
port - a TCP port on which the recipient should connect, or -1 to not specify this field
Returns:
a RvConnectionInfo containing the given internal IP address and TCP port

createForOutgoingSecureRequest

public static RvConnectionInfo createForOutgoingSecureRequest(java.net.InetAddress internalIP,
                                                              int port)
Creates a new connection information block with the given "internal IP address" and port for a secure (SSL) connection to the given host.

Parameters:
internalIP - the client's IP address
port - a TCP port on which the recipient should connect, or -1 to not specify this field
Returns:
a RvConnectionInfo containing the given internal IP address and TCP port

createForOutgoingProxiedRequest

public static RvConnectionInfo createForOutgoingProxiedRequest(java.net.Inet4Address proxyIP,
                                                               int port)
Creates a new connection information block describing a connection via the AOL Proxy Server with the given proxy server IP address and "port number." Note that this port number is not used as a TCP port but rather is simply a value sent in the AOL Proxy Server protocol. As of this writing, it seems that one should always connect to the AOL proxy server on port 5190.

Parameters:
proxyIP - the IP address of the AOL Proxy Server over which the connection should be made
port - a "port" value used in the AOL Proxy Server protocol
Returns:
a RvConnectionInfo containing the given proxy IP and port value (and, of course, the proxied flag set to true)

getInternalIP

public final java.net.InetAddress getInternalIP()
Returns the "internal IP address" contained in this connection information block. See above for details.

Returns:
this connection information block's internal IP address value, or null if none is present

getExternalIP

public final java.net.InetAddress getExternalIP()
Returns the "external IP address" contained in this connection information block. See above for details.

Returns:
this connection information block's external IP address value or null if none is present

isProxied

public final boolean isProxied()
Returns whether this connection block describes a connection over an AOL Proxy Server. Normally a proxy IP address is specified if this value is true. See above for details.

Returns:
whether or not this connection information block represents a connection over an AOL Proxy Server

getProxyIP

public final java.net.InetAddress getProxyIP()
Returns the IP address of an AOL Proxy Server over which a connection should be made. This value is normally null unless the value of isProxied() is true. See above for details.

Returns:
the AOL Proxy Server IP address specified in this connection information block, or null if none was sent

getPort

public final int getPort()
Returns the TCP port specified in this connection information block. Note that this value is not the port to which the client could connect to the AOL proxy server. See createForOutgoingProxiedRequest(java.net.Inet4Address, int) for details. Note that this method will return -1 if no port is present in this block.

Returns:
the TCP port the TCP port specified in this connection information block, or -1 of none is present

isEncrypted

public final boolean isEncrypted()
Returns whether or not the associated connection is to be encrypted via SSL.

Returns:
whether the associated connection is to be encrypted over SSL

write

public void write(java.io.OutputStream out)
           throws java.io.IOException
Description copied from interface: LiveWritable
Writes a representation of this object to the given stream.

Specified by:
write in interface LiveWritable
Parameters:
out - the stream to which to write
Throws:
java.io.IOException - if an I/O error occurs

toString

public java.lang.String toString()