ewe.io
Class RemoteConnection

java.lang.Object
  ewe.util.Errorable
      ewe.io.RemoteConnection

public class RemoteConnection

extends Errorable

This class provides services to allow ewe applications on a desktop to communicate with ewe applications on a mobile pc when they are connected. On a Windows PC this connection is provided by the ActiveSync service.

When such a connection is made native applications on the desktop and mobile PC are run and this provides a constant streaming connection between the two devices. The RemoteConnection class then provides an API to access the services provided by the underlying connection.

Field Summary

static int	AUTO_START_EMULATOR
static int	AUTO_START_IS_EWE_APPLICATION This registers an auto-start entry which will start when ewesync begins.
static int	AUTO_START_SERVICE
int	connectTimeOut This is a time in milliseconds for timing out a connection between the ewe application and the underlying RemoteConnection.
static int	IS_DESKTOP This is returned by getStatus().
static int	IS_MOBILE This is returned by getStatus().
static int	MANUAL_MOBILE_START_ON_EMULATOR
static int	MOBILE_GET_COMMAND_FROM_REGISTRY
static int	MOBILE_IS_EWE_APPLICATION

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

protected

RemoteConnection()

Method Summary

Socket	connectToHost(String hostName, int port) This is used by an application to connect to a host and port which is accessible from the remote machine (including the remote machine itself).
Socket	connectToService(String service) This is used by an application to connect to a service on the remote machine.
static ServerSocket	createService(String serviceName) This creates a ServerSocket on a new port and then posts the service to the RemoteConnecion.
void	execRemote(String[] commandLines, int execOptions) Run command lines on the remote.
void	execRemote(String commandLine, int execOptions) Run a command line on the remote.
static RemoteConnection	getConnection() Use this to get an instance of a RemoteConnection.
static RemoteConnection	getInstance() Deprecated. use getConnection() instead.
static RemoteConnection	getNewConnection() Use this to get a new instance of a RemoteConnection.
String	getRegistryValue(String keyName)
int	getStatus() This is used to check the RemoteConnection status.
Socket	getSyncConnection(String serviceName, String remoteCommandLine, boolean remoteIsEweApp, TimeOut howLong)
boolean	isEmulated() This returns true if the RemoteConnection is running on an EweSync Emulator.
static void	main(String[] args)
Socket	makeSyncConnection(String serviceName, String[] commandLines, TimeOut howLong, int makeOptions) This is a convenience method for doing standard application synchronization that can be be run on both the desktop and mobile device.
Socket	makeSyncConnection(String serviceName, String commandLine, TimeOut howLong, int makeOptions) This is a convenience method for doing standard application synchronization that can be be run on both the desktop and mobile device.
boolean	postService(String service, ServerSocket serverSocket) This is used by an application to notify the connection that it has created and is listening to a TCP/IP server port on the specified hostName and port number.
boolean	postService(String service, String hostName, int port) This is used by an application to notify the connection that it has created and is listening to a TCP/IP server port on the specified hostName and port number.
static void	registerAutoStart(String entryName, String commandLine, int typeAndOptions) Use this to register an AutoStart entry.
static void	registerAutoStartEweApp(String entryName, String eweCommandLine) This registers a normal autostart entry specifying the entry name and a command line that is taken to be a Ewe application.
boolean	runRemoteApp(String commandLine) Deprecated. use execRemote() instead.
boolean	runRemoteEwe(String eweCommandLine) Deprecated. use execRemote() instead.

Methods inherited from class ewe.util.Errorable

returnError, returnError, returnError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

connectTimeOut

public int connectTimeOut

This is a time in milliseconds for timing out a connection between the ewe application and the underlying RemoteConnection.

IS_DESKTOP

public static final int IS_DESKTOP

This is returned by getStatus().

See Also:

Constant Field Values

IS_MOBILE

public static final int IS_MOBILE

This is returned by getStatus().

See Also:

Constant Field Values

AUTO_START_IS_EWE_APPLICATION

public static final int AUTO_START_IS_EWE_APPLICATION

This registers an auto-start entry which will start when ewesync begins. The name parameter must be unique and non-null. If register is false it will de-register the auto-start. If you are de-registering the application (i.e. register is false) then path may be null.

See Also:

Constant Field Values

AUTO_START_EMULATOR

public static final int AUTO_START_EMULATOR

See Also:

Constant Field Values

AUTO_START_SERVICE

public static final int AUTO_START_SERVICE

See Also:

Constant Field Values

MOBILE_IS_EWE_APPLICATION

public static final int MOBILE_IS_EWE_APPLICATION

See Also:

Constant Field Values

MANUAL_MOBILE_START_ON_EMULATOR

public static final int MANUAL_MOBILE_START_ON_EMULATOR

See Also:

Constant Field Values

MOBILE_GET_COMMAND_FROM_REGISTRY

public static final int MOBILE_GET_COMMAND_FROM_REGISTRY

See Also:

Constant Field Values

Constructor Detail

RemoteConnection

protected RemoteConnection()

Method Detail

getConnection

public static RemoteConnection getConnection()
                                      throws IOException

Use this to get an instance of a RemoteConnection. This will re-use the previous one.

Returns:

A RemoteConnection instance.

Throws:

IOException - if there is an error getting the connection.

getNewConnection

public static RemoteConnection getNewConnection()
                                         throws IOException

Use this to get a new instance of a RemoteConnection.

Returns:

A new RemoteConnection instance.

Throws:

IOException - if there is an error getting the connection.

getInstance

public static RemoteConnection getInstance()

Deprecated. use getConnection() instead.

runRemoteApp

public boolean runRemoteApp(String commandLine)

Deprecated. use execRemote() instead.

This executes a command line on the remote machine - it works on the desktop or mobile pc. If there are any spaces in the path to the executable file, then that path should be enclosed in double quotation marks. e.g.:

 runRemoteApp("\"\\Program Files\\Calculator.exe\"");
 

Parameters:

commandLine - The command line to run, including program arguments.

Returns:

true if the request was successfully sent across, false if not. A return value of true does not indicate that the remote executable was sucessfully run.

runRemoteEwe

public boolean runRemoteEwe(String eweCommandLine)

Deprecated. use execRemote() instead.

This executes the ewe vm on the remote machine with the provided program arugments. You should pass at least one ewe file as a program argument. If the path for that ewe file contains spaces, then you should enclose it in double quotation marks.

 runRemoteEwe("\"\\Program Files\\MyApp.ewe\"");
 

Returns:

true if the request was successfully sent across, false if not. A return value of true does not indicate that the remote executable was sucessfully run.

execRemote

public void execRemote(String[] commandLines,
                       int execOptions)
                throws IOException

Run command lines on the remote.

Parameters:

commandLines - The line to run or remote Registry value that stores the command to be run.

execOptions - This can be any of MOBILE_GET_COMMAND_FROM_REGISTRY, MOBILE_IS_EWE_APPLICATION, OR'ed together.

Throws:

IOException - If the command could not be executed.

execRemote

public void execRemote(String commandLine,
                       int execOptions)
                throws IOException

Run a command line on the remote.

Parameters:

commandLine - The line to run or remote Registry value that stores the command to be run.

execOptions - This can be any of MOBILE_GET_COMMAND_FROM_REGISTRY, MOBILE_IS_EWE_APPLICATION, OR'ed together.

Throws:

IOException - If the command could not be executed.

postService

public boolean postService(String service,
                           String hostName,
                           int port)

This is used by an application to notify the connection that it has created and is listening to a TCP/IP server port on the specified hostName and port number. The server port is then associated with the provided service name. A remote ewe application could then connect to the named service by using connectToService().

Parameters:

service - The service name to post. Note that this IS case sensitive.

hostName - The name of the host used for the connection.

port - The port number of the connection.

Returns:

true if successful, false if not.

postService

public boolean postService(String service,
                           ServerSocket serverSocket)

This is used by an application to notify the connection that it has created and is listening to a TCP/IP server port on the specified hostName and port number. The server port is then associated with the provided service name. A remote ewe application could then connect to the named service by using connectToService().

Parameters:

service - The service name to post. Note that this IS case sensitive.

serverSocket - The socket being listened to.

Returns:

true if successful, false if not.

createService

public static ServerSocket createService(String serviceName)
                                  throws IOException

This creates a ServerSocket on a new port and then posts the service to the RemoteConnecion.

Parameters:

serviceName - The name of the service to be posted.

Returns:

The ServerSocket created.

Throws:

IOException - If ther ServerSocket could not be created or if the service could not be posted.

connectToHost

public Socket connectToHost(String hostName,
                            int port)

This is used by an application to connect to a host and port which is accessible from the remote machine (including the remote machine itself).

Returns:

A socket which can be used to communicate with the specified port if successful, null if not.

connectToService

public Socket connectToService(String service)

This is used by an application to connect to a service on the remote machine. If the service has not been posted or is not running, the underlying service on the remote machine will look up in the registry (or equivalent) under the AutoStart, EmulatorAutoStart and Services keys to see if the service has been registered (the EweConfig app is used to register services) and if it has it will attempt to start the service.

Returns:

A socket which can be used to communicate with the specified port if successful, null if not.

getRegistryValue

public String getRegistryValue(String keyName)

getStatus

public int getStatus()

This is used to check the RemoteConnection status.

Returns:

-1 = Remote Connection server is not running.
0 = Remote Connection is running but there is an internal error.
IS_DESKTOP = Remote Connection is running and OK and this process is running on the Desktop.
IS_MOBILE = Remote Connection is running and OK and this process is running on a Mobile PC.

isEmulated

public boolean isEmulated()

This returns true if the RemoteConnection is running on an EweSync Emulator.

registerAutoStart

public static void registerAutoStart(String entryName,
                                     String commandLine,
                                     int typeAndOptions)
                              throws IOException

Use this to register an AutoStart entry. When an successful EweSync connection from the desktop to the mobile device is made, then this will cause registered AutoStart entries to run.

Parameters:

entryName - A unique name for the entry. You can use spaces or special characters, but not the backslash (\) character.

commandLine - The command line to run. This should be a full command line, or it can be a command line to the EweVM if the AUTO_START_IS_EWE_APPLICATION option is chosen.

typeAndOptions - This can be a combination of AUTO_START_IS_EWE_APPLICATION with AUTO_START_EMULATOR or AUTO_START_SERVICE. If neither AUTO_START_EMULATOR nor AUTO_START_SERVICE is selected, then it is assumed that the entry is in the normal (default) auto start section.

Throws:

IOException - If the information could not be registerd.

registerAutoStartEweApp

public static void registerAutoStartEweApp(String entryName,
                                           String eweCommandLine)
                                    throws IOException

This registers a normal autostart entry specifying the entry name and a command line that is taken to be a Ewe application.

Parameters:

entryName - A unique name for the entry. You can use spaces or special characters, but not the backslash (\) character.

Throws:

IOException - If the information could not be registerd.

makeSyncConnection

public Socket makeSyncConnection(String serviceName,
                                 String commandLine,
                                 TimeOut howLong,
                                 int makeOptions)
                          throws TimedOutException,
                                 IOException,
                                 InterruptedException

This is a convenience method for doing standard application synchronization that can be be run on both the desktop and mobile device.

If it is running on the desktop it will do the following:

1. Create a server socket on an arbitrary port.
2. Post the service name and the socket port.
3. Execute the remote command line, unless the MANUAL_MOBILE_START_ON_EMULATOR 
                option is selected in which case a MessageBox is shown if the connection
                is running on the Ewesync Emulator and you must start the mobile app yourself.

                If the MOBILE_GET_COMMAND_FROM_REGISTRY option is used, then the command line supplied should
                be the name of a value in the registry key - this value will be retrieved and then run.
                If MOBILE_IS_EWE_APPLICATION option is used then the value retrieved from the registry
                should be the location of a .ewe file.

4. Wait for a connection.

If it is running on the mobile this method will:

1.  Attempt to connect to the serviceName on the remote host.

Parameters:

serviceName - The unique service name to be used.

commandLine - A command line to pass to the Ewe VM on the remote device.

howLong - The length of time to wait for a connection.

makeOptions - This can be any of MANUAL_MOBILE_START_ON_EMULATOR, MOBILE_IS_EWE_APPLICATION OR'ed together.

Returns:

The connected Socket.

Throws:

TimedOutException - If no connection was made during the Timeout period.

IOException - If there was an error making the connection.

InterruptedException

makeSyncConnection

public Socket makeSyncConnection(String serviceName,
                                 String[] commandLines,
                                 TimeOut howLong,
                                 int makeOptions)
                          throws TimedOutException,
                                 IOException,
                                 InterruptedException

This is a convenience method for doing standard application synchronization that can be be run on both the desktop and mobile device.

If it is running on the desktop it will do the following:

1. Create a server socket on an arbitrary port.
2. Post the service name and the socket port.
3. Execute the remote command lines, unless the MANUAL_MOBILE_START_ON_EMULATOR 
                option is selected in which case a MessageBox is shown if the connection
                is running on the Ewesync Emulator and you must start the mobile app yourself.

                If the MOBILE_GET_COMMAND_FROM_REGISTRY option is used, then the command lines supplied should
                be the name of a value in the registry key - this value will be retrieved and then run.
                If MOBILE_IS_EWE_APPLICATION option is used then the value retrieved from the registry
                should be the location of a .ewe file.

4. Wait for a connection.

If it is running on the mobile this method will:

1.  Attempt to connect to the serviceName on the remote host.

Parameters:

serviceName - The unique service name to be used.

commandLines - An array of command lines to pass to the Ewe VM on the remote device.

howLong - The length of time to wait for a connection.

makeOptions - This can be any of MANUAL_MOBILE_START_ON_EMULATOR, MOBILE_IS_EWE_APPLICATION OR'ed together.

Returns:

The connected Socket.

Throws:

TimedOutException - If no connection was made during the Timeout period.

IOException - If there was an error making the connection.

InterruptedException

getSyncConnection

public Socket getSyncConnection(String serviceName,
                                String remoteCommandLine,
                                boolean remoteIsEweApp,
                                TimeOut howLong)

main

public static void main(String[] args)