com.veraxsystems.icmp.jni
Class IcmpJniBridge

java.lang.Object
  extended by com.veraxsystems.icmp.jni.IcmpJniBridge

public class IcmpJniBridge
extends java.lang.Object

The Java/DLL interface class. It offers set of Java methods that may execute set of function implemented in IcmpJniBridge.DLL module. Class covers ICMP socket handling in the way that each instance of IcmpJniBridge object has its own ICMP socket handle. This way it is possible to create and handle many ICMP sockets in application.

Underneath, the ICMP socket creates RAW socket. In Windows such operation requires program being run on Administrator privileges.

Including this class in application causes loading of IcmpJniBridge.DLL file that must be available in any directory specified in java java.library.path property.

The IcmpJniBridge object is allocating system resources when successful call to openSocket() is performed. In order to release those resources the closeSocket() method must be executed.


Field Summary
static int MAX_DATA_LENGTH
          The maximum size of ICMP data that may be sent via IP packet
 
Constructor Summary
IcmpJniBridge()
           
 
Method Summary
 void closeSocket()
          Close ICMP socket.
 int getId()
          Get identifier unique for computer starting from 0 up to 2147483647.
static void loadNativeLibrary()
          Load DLL module.
 void openSocket()
          Open ICMP socket.
 IcmpEchoResponse receive()
          Receive ICMP response.
 void selectSocket(int timeout)
          Wait for ICMP socket data.
 int send(java.net.InetAddress address, int messageId, byte[] data, int dataLength)
          Send ICMP EchoRequest.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_DATA_LENGTH

public static final int MAX_DATA_LENGTH
The maximum size of ICMP data that may be sent via IP packet

See Also:
Constant Field Values
Constructor Detail

IcmpJniBridge

public IcmpJniBridge()
Method Detail

loadNativeLibrary

public static void loadNativeLibrary()
Load DLL module.


getId

public int getId()
Get identifier unique for computer starting from 0 up to 2147483647. The identifier value is increased on every call. When maximum value is reached counting is restarted from 0.

The counter value is common for all applications using IcmpJniBridge.DLL module so they never get the same value at the same time.

Returns:
unique integer value

openSocket

public void openSocket()
                throws IcmpSystemException
Open ICMP socket. If socket is already opened operation is ignored.

Throws:
IcmpSystemException - exception is thrown when any system error occurs

closeSocket

public void closeSocket()
                 throws IcmpSystemException
Close ICMP socket. If socket was not opened operation is ignored. Due to release resources this method must be called after successful socket creation via openSocket()

Throws:
IcmpSystemException - exception is thrown when any system error occurs

selectSocket

public void selectSocket(int timeout)
                  throws IcmpSystemException,
                         IcmpTimeoutException
Wait for ICMP socket data. Method waits until data is available for reading or given timeout is reached.

Closing socket (closeSocket()) terminates operation and causes method to throw exception.

Parameters:
timeout - expressed in milliseconds time to wait for data
Throws:
IcmpSystemException - exception is thrown when any system error occurs
IcmpTimeoutException

send

public int send(java.net.InetAddress address,
                int messageId,
                byte[] data,
                int dataLength)
         throws IcmpSystemException
Send ICMP EchoRequest. Before this method is used the ICMP socket must be created using openSocket(). ICMP message is sent to host specified by address parameter.

The ISMP message is built using provided parameters. The messageId is split into ICMP message identifier and sequenceNumber (see RFC 792). The data is sent as ICMP optional data field.

The messageId should be unique value because it is used to recognize response message.

In case illegal parameter is provided or socket error occurs the IcmpSystemException is thrown.

Parameters:
address - host address the request is sent to
messageId - identifier of request message
data - data to be sent
dataLength - length of data to be send
Returns:
number of bytes sent
Throws:
IcmpSystemException - exception is thrown when any system error occurs

receive

public IcmpEchoResponse receive()
                         throws IcmpSystemException,
                                IcmpFatalErrorException
Receive ICMP response. Before this method is used the ICMP socket must be created using openSocket(). The received response is mapped to IcmpEchoResponse object. The response object content depends an type of received ICMP response, thus, before accessing IcmpEchoResponse values the status of response should be verified using IcmpEchoResponse.getStatus() method.

Method is a blocking operation. To introduce timeout functionality into receiving data, the selectSocket(int) must be called before receive.

Method either returns object or exception - never null.

Returns:
received ICMP response message
Throws:
IcmpSystemException - exception is thrown when any system error occurs
IcmpFatalErrorException - exception is thrown when DLL module is not able to create IcmpEchoResponse object.