TFTP
Date: 2016-06-23

org.apache.commons.net.tftp

## Class TFTP

- java.lang.Object
- - org.apache.commons.net.DatagramSocketClient
  - - org.apache.commons.net.tftp.TFTP

- Direct Known Subclasses:
    TFTPClient

      public class TFTP
      extends DatagramSocketClient

  The TFTP class exposes a set of methods to allow you to deal with the TFTP protocol directly, in case you want to write your own TFTP client or server. However, almost every user should only be concerend with the `open()` , and `close()` , methods. Additionally,the a `setDefaultTimeout()` method may be of importance for performance tuning.

  Details regarding the TFTP protocol and the format of TFTP packets can be found in RFC 783. But the point of these classes is to keep you from having to worry about the internals.

  See Also:
    `DatagramSocketClient`, `TFTPPacket`, `TFTPPacketException`, `TFTPClient`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ASCII_MODE` The ascii transfer mode.
    `static int` | `BINARY_MODE` The binary transfer mode.
    `static int` | `DEFAULT_PORT` The default TFTP port according to RFC 783 is 69.
    `static int` | `DEFAULT_TIMEOUT` The default number of milliseconds to wait to receive a datagram before timing out.
    `static int` | `IMAGE_MODE` The image transfer mode.
    `static int` | `NETASCII_MODE` The netascii transfer mode.
    `static int` | `OCTET_MODE` The octet transfer mode.

    - ### Fields inherited from class org.apache.commons.net.DatagramSocketClient

      `_isOpen_, _socket_, _socketFactory_, _timeout_`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TFTP()` Creates a TFTP instance with a default timeout of DEFAULT_TIMEOUT, a null socket, and buffered operations disabled.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beginBufferedOps()` Initializes the internal buffers.
    `TFTPPacket` | `bufferedReceive()` This is a special method to perform a more efficient packet receive.
    `void` | `bufferedSend(TFTPPacket packet)` This is a special method to perform a more efficient packet send.
    `void` | `discardPackets()` This method synchronizes a connection by discarding all packets that may be in the local socket buffer.
    `void` | `endBufferedOps()` Releases the resources used to perform buffered sends and receives.
    `static java.lang.String` | `getModeName(int mode)` Returns the TFTP string representation of a TFTP transfer mode.
    `TFTPPacket` | `receive()` Receives a TFTPPacket.
    `void` | `send(TFTPPacket packet)` Sends a TFTP packet to its destination.

    - ### Methods inherited from class org.apache.commons.net.DatagramSocketClient

      `close, getCharset, getCharsetName, getDefaultTimeout, getLocalAddress, getLocalPort, getSoTimeout, isOpen, open, open, open, setCharset, setDatagramSocketFactory, setDefaultTimeout, setSoTimeout`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ASCII_MODE

          public static final int ASCII_MODE

      The ascii transfer mode. Its value is 0 and equivalent to NETASCII_MODE
      See Also:
        Constant Field Values

    - #### NETASCII_MODE

          public static final int NETASCII_MODE

      The netascii transfer mode. Its value is 0.
      See Also:
        Constant Field Values

    - #### BINARY_MODE

          public static final int BINARY_MODE

      The binary transfer mode. Its value is 1 and equivalent to OCTET_MODE.
      See Also:
        Constant Field Values

    - #### IMAGE_MODE

          public static final int IMAGE_MODE

      The image transfer mode. Its value is 1 and equivalent to OCTET_MODE.
      See Also:
        Constant Field Values

    - #### OCTET_MODE

          public static final int OCTET_MODE

      The octet transfer mode. Its value is 1.
      See Also:
        Constant Field Values

    - #### DEFAULT_TIMEOUT

          public static final int DEFAULT_TIMEOUT

      The default number of milliseconds to wait to receive a datagram before timing out. The default is 5000 milliseconds (5 seconds).
      See Also:
        Constant Field Values

    - #### DEFAULT_PORT

          public static final int DEFAULT_PORT

      The default TFTP port according to RFC 783 is 69.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TFTP

          public TFTP()

      Creates a TFTP instance with a default timeout of DEFAULT_TIMEOUT, a null socket, and buffered operations disabled.

  - ### Method Detail

    - #### getModeName

          public static final java.lang.String getModeName(int mode)

      Returns the TFTP string representation of a TFTP transfer mode. Will throw an ArrayIndexOutOfBoundsException if an invalid transfer mode is specified.
      Parameters:
        `mode` - The TFTP transfer mode. One of the MODE constants.
      Returns:
        The TFTP string representation of the TFTP transfer mode.

    - #### discardPackets

          public final void discardPackets()
                                    throws java.io.IOException

      This method synchronizes a connection by discarding all packets that may be in the local socket buffer. This method need only be called when you implement your own TFTP client or server.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### bufferedReceive

          public final TFTPPacket bufferedReceive()
                                           throws java.io.IOException,
                                                  java.io.InterruptedIOException,
                                                  java.net.SocketException,
                                                  TFTPPacketException

      This is a special method to perform a more efficient packet receive. It should only be used after calling `beginBufferedOps()` . beginBufferedOps() initializes a set of buffers used internally that prevent the new allocation of a DatagramPacket and byte array for each send and receive. To use these buffers you must call the bufferedReceive() and bufferedSend() methods instead of send() and receive(). You must also be certain that you don't manipulate the resulting packet in such a way that it interferes with future buffered operations. For example, a TFTPDataPacket received with bufferedReceive() will have a reference to the internal byte buffer. You must finish using this data before calling bufferedReceive() again, or else the data will be overwritten by the the call.
      Returns:
        The TFTPPacket received.
      Throws:
        `java.io.InterruptedIOException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
        `java.net.SocketException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
        `java.io.IOException` - If some other I/O error occurs.
        `TFTPPacketException` - If an invalid TFTP packet is received.

    - #### bufferedSend

          public final void bufferedSend(TFTPPacket packet)
                                  throws java.io.IOException

      This is a special method to perform a more efficient packet send. It should only be used after calling `beginBufferedOps()` . beginBufferedOps() initializes a set of buffers used internally that prevent the new allocation of a DatagramPacket and byte array for each send and receive. To use these buffers you must call the bufferedReceive() and bufferedSend() methods instead of send() and receive(). You must also be certain that you don't manipulate the resulting packet in such a way that it interferes with future buffered operations. For example, a TFTPDataPacket received with bufferedReceive() will have a reference to the internal byte buffer. You must finish using this data before calling bufferedReceive() again, or else the data will be overwritten by the the call.
      Parameters:
        `packet` - The TFTP packet to send.
      Throws:
        `java.io.IOException` - If some I/O error occurs.

    - #### beginBufferedOps

          public final void beginBufferedOps()

      Initializes the internal buffers. Buffers are used by `bufferedSend()` and `bufferedReceive()` . This method must be called before calling either one of those two methods. When you finish using buffered operations, you must call `endBufferedOps()` .

    - #### endBufferedOps

          public final void endBufferedOps()

      Releases the resources used to perform buffered sends and receives.

    - #### send

          public final void send(TFTPPacket packet)
                          throws java.io.IOException

      Sends a TFTP packet to its destination.
      Parameters:
        `packet` - The TFTP packet to send.
      Throws:
        `java.io.IOException` - If some I/O error occurs.

    - #### receive

          public final TFTPPacket receive()
                                   throws java.io.IOException,
                                          java.io.InterruptedIOException,
                                          java.net.SocketException,
                                          TFTPPacketException

      Receives a TFTPPacket.
      Returns:
        The TFTPPacket received.
      Throws:
        `java.io.InterruptedIOException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
        `java.net.SocketException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
        `java.io.IOException` - If some other I/O error occurs.
        `TFTPPacketException` - If an invalid TFTP packet is received.