/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.net.tftp;

import java.io.IOException;
import java.io.InterruptedIOException;
import java.net.DatagramPacket;
import java.net.SocketException;

import org.apache.commons.net.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/***
 * 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 {@link org.apache.commons.net.DatagramSocketClient#open  open() },
 * and {@link org.apache.commons.net.DatagramSocketClient#close  close() },
 * methods. Additionally,the a
 * {@link org.apache.commons.net.DatagramSocketClient#setDefaultTimeout setDefaultTimeout() }
 *  method may be of importance for performance tuning.
 * <p>
 * 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 org.apache.commons.net.DatagramSocketClient
 * @see TFTPPacket
 * @see TFTPPacketException
 * @see TFTPClient
 ***/

public class TFTP extends DatagramSocketClient
{
    
The ascii transfer mode.  Its value is 0 and equivalent to NETASCII_MODE
/***
     * The ascii transfer mode.  Its value is 0 and equivalent to NETASCII_MODE
     ***/
    public static final int ASCII_MODE = 0;

    
The netascii transfer mode.  Its value is 0.
/***
     * The netascii transfer mode.  Its value is 0.
     ***/
    public static final int NETASCII_MODE = 0;

    
The binary transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
/***
     * The binary transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
     ***/
    public static final int BINARY_MODE = 1;

    
The image transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
/***
     * The image transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
     ***/
    public static final int IMAGE_MODE = 1;

    
The octet transfer mode.  Its value is 1.
/***
     * The octet transfer mode.  Its value is 1.
     ***/
    public static final int OCTET_MODE = 1;

    
The default number of milliseconds to wait to receive a datagram
before timing out.  The default is 5000 milliseconds (5 seconds).
/***
     * The default number of milliseconds to wait to receive a datagram
     * before timing out.  The default is 5000 milliseconds (5 seconds).
     ***/
    public static final int DEFAULT_TIMEOUT = 5000;

    
The default TFTP port according to RFC 783 is 69.
/***
     * The default TFTP port according to RFC 783 is 69.
     ***/
    public static final int DEFAULT_PORT = 69;

    
The size to use for TFTP packet buffers.  Its 4 plus the
TFTPPacket.SEGMENT_SIZE, i.e. 516.
/***
     * The size to use for TFTP packet buffers.  Its 4 plus the
     * TFTPPacket.SEGMENT_SIZE, i.e. 516.
     ***/
    static final int PACKET_SIZE = TFTPPacket.SEGMENT_SIZE + 4;

    
A buffer used to accelerate receives in bufferedReceive() /*** A buffer used to accelerate receives in bufferedReceive() ***/
    private byte[] __receiveBuffer;

    
A datagram used to minimize memory allocation in bufferedReceive() /*** A datagram used to minimize memory allocation in bufferedReceive() ***/
    private DatagramPacket __receiveDatagram;

    
A datagram used to minimize memory allocation in bufferedSend() /*** A datagram used to minimize memory allocation in bufferedSend() ***/
    private DatagramPacket __sendDatagram;

    
A buffer used to accelerate sends in bufferedSend().
It is left package visible so that TFTPClient may be slightly more
efficient during file sends.  It saves the creation of an
additional buffer and prevents a buffer copy in _newDataPcket().
/***
     * A buffer used to accelerate sends in bufferedSend().
     * It is left package visible so that TFTPClient may be slightly more
     * efficient during file sends.  It saves the creation of an
     * additional buffer and prevents a buffer copy in _newDataPcket().
     ***/
    byte[] _sendBuffer;


    
Returns the TFTP string representation of a TFTP transfer mode.
Will throw an ArrayIndexOutOfBoundsException if an invalid transfer
mode is specified.
Params:
mode –  The TFTP transfer mode.  One of the MODE constants.
Returns:
 The TFTP string representation of the TFTP transfer mode./***
     * Returns the TFTP string representation of a TFTP transfer mode.
     * Will throw an ArrayIndexOutOfBoundsException if an invalid transfer
     * mode is specified.
     *
     * @param mode  The TFTP transfer mode.  One of the MODE constants.
     * @return  The TFTP string representation of the TFTP transfer mode.
     ***/
    public static final String getModeName(int mode)
    {
        return TFTPRequestPacket._modeStrings[mode];
    }

    
Creates a TFTP instance with a default timeout of DEFAULT_TIMEOUT,
a null socket, and buffered operations disabled.
/***
     * Creates a TFTP instance with a default timeout of DEFAULT_TIMEOUT,
     * a null socket, and buffered operations disabled.
     ***/
    public TFTP()
    {
        setDefaultTimeout(DEFAULT_TIMEOUT);
        __receiveBuffer = null;
        __receiveDatagram = null;
    }

    
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:
IOException – if an I/O error occurs./***
     * 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 IOException if an I/O error occurs.
     ***/
    public final void discardPackets() throws IOException
    {
        int to;
        DatagramPacket datagram;

        datagram = new DatagramPacket(new byte[PACKET_SIZE], PACKET_SIZE);

        to = getSoTimeout();
        setSoTimeout(1);

        try
        {
            while (true) {
                _socket_.receive(datagram);
            }
        }
        catch (SocketException e)
        {
            // Do nothing.  We timed out so we hope we're caught up.
        }
        catch (InterruptedIOException e)
        {
            // Do nothing.  We timed out so we hope we're caught up.
        }

        setSoTimeout(to);
    }


    
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. 
Throws:
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.
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.
IOException –  If some other I/O error occurs.
TFTPPacketException – If an invalid TFTP packet is received.
Returns:
The TFTPPacket received./***
     * This is a special method to perform a more efficient packet receive.
     * It should only be used after calling
     * {@link #beginBufferedOps  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.
     *
     * @return The TFTPPacket received.
     * @throws 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.
     * @throws 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.
     * @throws IOException  If some other I/O error occurs.
     * @throws TFTPPacketException If an invalid TFTP packet is received.
     ***/
    public final TFTPPacket bufferedReceive() throws IOException,
                InterruptedIOException, SocketException, TFTPPacketException
    {
        __receiveDatagram.setData(__receiveBuffer);
        __receiveDatagram.setLength(__receiveBuffer.length);
        _socket_.receive(__receiveDatagram);

        TFTPPacket newTFTPPacket = TFTPPacket.newTFTPPacket(__receiveDatagram);
        trace("<", newTFTPPacket);
        return newTFTPPacket;
    }

    
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. 
Params:
packet –  The TFTP packet to send.
Throws:
IOException –  If some  I/O error occurs./***
     * This is a special method to perform a more efficient packet send.
     * It should only be used after calling
     * {@link #beginBufferedOps  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.
     *
     * @param packet  The TFTP packet to send.
     * @throws IOException  If some  I/O error occurs.
     ***/
    public final void bufferedSend(TFTPPacket packet) throws IOException
    {
        trace(">", packet);
        _socket_.send(packet._newDatagram(__sendDatagram, _sendBuffer));
    }


    
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(). /***
     * Initializes the internal buffers. Buffers are used by
     * {@link #bufferedSend  bufferedSend() } and
     * {@link #bufferedReceive  bufferedReceive() }.  This
     * method must be called before calling either one of those two
     * methods.  When you finish using buffered operations, you must
     * call {@link #endBufferedOps  endBufferedOps() }.
     ***/
    public final void beginBufferedOps()
    {
        __receiveBuffer = new byte[PACKET_SIZE];
        __receiveDatagram =
            new DatagramPacket(__receiveBuffer, __receiveBuffer.length);
        _sendBuffer = new byte[PACKET_SIZE];
        __sendDatagram =
            new DatagramPacket(_sendBuffer, _sendBuffer.length);
    }

    
Releases the resources used to perform buffered sends and receives.
/***
     * Releases the resources used to perform buffered sends and receives.
     ***/
    public final void endBufferedOps()
    {
        __receiveBuffer = null;
        __receiveDatagram = null;
        _sendBuffer = null;
        __sendDatagram = null;
    }


    
Sends a TFTP packet to its destination.
Params:
packet –  The TFTP packet to send.
Throws:
IOException –  If some  I/O error occurs./***
     * Sends a TFTP packet to its destination.
     *
     * @param packet  The TFTP packet to send.
     * @throws IOException  If some  I/O error occurs.
     ***/
    public final void send(TFTPPacket packet) throws IOException
    {
        trace(">", packet);
        _socket_.send(packet.newDatagram());
    }


    
Receives a TFTPPacket.
Throws:
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.
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.
IOException –  If some other I/O error occurs.
TFTPPacketException – If an invalid TFTP packet is received.
Returns:
The TFTPPacket received./***
     * Receives a TFTPPacket.
     *
     * @return The TFTPPacket received.
     * @throws 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.
     * @throws 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.
     * @throws IOException  If some other I/O error occurs.
     * @throws TFTPPacketException If an invalid TFTP packet is received.
     ***/
    public final TFTPPacket receive() throws IOException, InterruptedIOException,
                SocketException, TFTPPacketException
    {
        DatagramPacket packet;

        packet = new DatagramPacket(new byte[PACKET_SIZE], PACKET_SIZE);

        _socket_.receive(packet);

        TFTPPacket newTFTPPacket = TFTPPacket.newTFTPPacket(packet);
        trace("<", newTFTPPacket);
        return newTFTPPacket;
    }

    
Trace facility; this implementation does nothing.

Override it to trace the data, for example:
 System.out.println(direction + " " + packet.toString()); 
Params:
direction – ">" or "<"
packet – the packet to be sent or that has been received
Since:
3.6/**
     * Trace facility; this implementation does nothing.
     * <p>
     * Override it to trace the data, for example:<br>
     * {@code System.out.println(direction + " " + packet.toString());}
     * @param direction ">" or "<"
     * @param packet the packet to be sent or that has been received
     * @since 3.6
     */
    protected void trace(String direction, TFTPPacket packet) {
    }

}