1. /*

  2.  * Copyright 2001-2004 The Apache Software Foundation

  3.  *

  4.  * Licensed under the Apache License, Version 2.0 (the "License");

  5.  * you may not use this file except in compliance with the License.

  6.  * You may obtain a copy of the License at

  7.  *

  8.  *     http://www.apache.org/licenses/LICENSE-2.0

  9.  *

  10.  * Unless required by applicable law or agreed to in writing, software

  11.  * distributed under the License is distributed on an "AS IS" BASIS,

  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  13.  * See the License for the specific language governing permissions and

  14.  * limitations under the License.

  15.  */

  16. package org.apache.commons.net.tftp;

  17. import java.net.DatagramPacket;

  18. import java.net.InetAddress;

  19. 

  20. /***

  21.  * TFTPPacket is an abstract class encapsulating the functionality common

  22.  * to the 5 types of TFTP packets.  It also provides a static factory

  23.  * method that will create the correct TFTP packet instance from a

  24.  * datagram.  This relieves the programmer from having to figure out what

  25.  * kind of TFTP packet is contained in a datagram and create it himself.

  26.  * <p>

  27.  * Details regarding the TFTP protocol and the format of TFTP packets can

  28.  * be found in RFC 783.  But the point of these classes is to keep you

  29.  * from having to worry about the internals.  Additionally, only very

  30.  * few people should have to care about any of the TFTPPacket classes

  31.  * or derived classes.  Almost all users should only be concerned with the

  32.  * <a href="org.apache.commons.net.tftp.TFTPClient.html#_top_">TFTPClient</a> class

  33.  * <a href="org.apache.commons.net.tftp.TFTPClient.html#receiveFile">receiveFile()</a>

  34.  * and

  35.  * <a href="org.apache.commons.net.tftp.TFTPClient.html#sendFile">sendFile()</a>

  36.  * methods.

  37.  * <p>

  38.  * <p>

  39.  * @author Daniel F. Savarese

  40.  * @see TFTPPacketException

  41.  * @see TFTP

  42.  ***/

  43. 

  44. public abstract class TFTPPacket

  45. {

  46.     /***

  47.      * The minimum size of a packet.  This is 4 bytes.  It is enough

  48.      * to store the opcode and blocknumber or other required data

  49.      * depending on the packet type.

  50.      ***/

  51.     static final int MIN_PACKET_SIZE = 4;

  52. 

  53.     /***

  54.      * This is the actual TFTP spec

  55.      * identifier and is equal to 1.

  56.      * Identifier returned by <a href="#getType">getType()</a>

  57.      * indicating a read request packet.

  58.      ***/

  59.     public static final int READ_REQUEST = 1;

  60. 

  61.     /***

  62.      * This is the actual TFTP spec

  63.      * identifier and is equal to 2.

  64.      * Identifier returned by <a href="#getType">getType()</a>

  65.      * indicating a write request packet.

  66.      ***/

  67.     public static final int WRITE_REQUEST = 2;

  68. 

  69.     /***

  70.      * This is the actual TFTP spec

  71.      * identifier and is equal to 3.

  72.      * Identifier returned by <a href="#getType">getType()</a>

  73.      * indicating a data packet.

  74.      ***/

  75.     public static final int DATA = 3;

  76. 

  77.     /***

  78.      * This is the actual TFTP spec

  79.      * identifier and is equal to 4.

  80.      * Identifier returned by <a href="#getType">getType()</a>

  81.      * indicating an acknowledgement packet.

  82.      ***/

  83.     public static final int ACKNOWLEDGEMENT = 4;

  84. 

  85.     /***

  86.      * This is the actual TFTP spec

  87.      * identifier and is equal to 5.

  88.      * Identifier returned by <a href="#getType">getType()</a>

  89.      * indicating an error packet.

  90.      ***/

  91.     public static final int ERROR = 5;

  92. 

  93.     /***

  94.      * The TFTP data packet maximum segment size in bytes.  This is 512

  95.      * and is useful for those familiar with the TFTP protocol who want

  96.      * to use the <a href="org.apache.commons.net.tftp.TFTP.html#_top_">TFTP</a>

  97.      * class methods to implement their own TFTP servers or clients.

  98.      ***/

  99.     public static final int SEGMENT_SIZE = 512;

  100. 

  101.     /*** The type of packet. ***/

  102.     int _type;

  103. 

  104.     /*** The port the packet came from or is going to. ***/

  105.     int _port;

  106. 

  107.     /*** The host the packet is going to be sent or where it came from. ***/

  108.     InetAddress _address;

  109. 

  110.     /***

  111.      * When you receive a datagram that you expect to be a TFTP packet, you use

  112.      * this factory method to create the proper TFTPPacket object

  113.      * encapsulating the data contained in that datagram.  This method is the

  114.      * only way you can instantiate a TFTPPacket derived class from a

  115.      * datagram.

  116.      * <p>

  117.      * @param datagram  The datagram containing a TFTP packet.

  118.      * @return The TFTPPacket object corresponding to the datagram.

  119.      * @exception TFTPPacketException  If the datagram does not contain a valid

  120.      *             TFTP packet.

  121.      ***/

  122.     public final static TFTPPacket newTFTPPacket(DatagramPacket datagram)

  123.     throws TFTPPacketException

  124.     {

  125.         byte[] data;

  126.         TFTPPacket packet = null;

  127. 

  128.         if (datagram.getLength() < MIN_PACKET_SIZE)

  129.             throw new TFTPPacketException(

  130.                 "Bad packet. Datagram data length is too short.");

  131. 

  132.         data = datagram.getData();

  133. 

  134.         switch (data[1])

  135.         {

  136.         case READ_REQUEST:

  137.             packet = new TFTPReadRequestPacket(datagram);

  138.             break;

  139.         case WRITE_REQUEST:

  140.             packet = new TFTPWriteRequestPacket(datagram);

  141.             break;

  142.         case DATA:

  143.             packet = new TFTPDataPacket(datagram);

  144.             break;

  145.         case ACKNOWLEDGEMENT:

  146.             packet = new TFTPAckPacket(datagram);

  147.             break;

  148.         case ERROR:

  149.             packet = new TFTPErrorPacket(datagram);

  150.             break;

  151.         default:

  152.             throw new TFTPPacketException(

  153.                 "Bad packet.  Invalid TFTP operator code.");

  154.         }

  155. 

  156.         return packet;

  157.     }

  158. 

  159.     /***

  160.      * This constructor is not visible outside of the package.  It is used

  161.      * by subclasses within the package to initialize base data.

  162.      * <p>

  163.      * @param type The type of the packet.

  164.      * @param address The host the packet came from or is going to be sent.

  165.      * @param port The port the packet came from or is going to be sent.

  166.      **/

  167.     TFTPPacket(int type, InetAddress address, int port)

  168.     {

  169.         _type = type;

  170.         _address = address;

  171.         _port = port;

  172.     }

  173. 

  174.     /***

  175.      * This is an abstract method only available within the package for

  176.      * implementing efficient datagram transport by elminating buffering.

  177.      * It takes a datagram as an argument, and a byte buffer in which

  178.      * to store the raw datagram data.  Inside the method, the data

  179.      * should be set as the datagram's data and the datagram returned.

  180.      * <p>

  181.      * @param datagram  The datagram to create.

  182.      * @param data The buffer to store the packet and to use in the datagram.

  183.      * @return The datagram argument.

  184.      ***/

  185.     abstract DatagramPacket _newDatagram(DatagramPacket datagram, byte[] data);

  186. 

  187.     /***

  188.      * Creates a UDP datagram containing all the TFTP packet

  189.      * data in the proper format.

  190.      * This is an abstract method, exposed to the programmer in case he

  191.      * wants to implement his own TFTP client instead of using

  192.      * the <a href="org.apache.commons.net.tftp.TFTPClient.html#_top_">TFTPClient</a>

  193.      * class.

  194.      * Under normal circumstances, you should not have a need to call this

  195.      * method.

  196.      * <p>

  197.      * @return A UDP datagram containing the TFTP packet.

  198.      ***/

  199.     public abstract DatagramPacket newDatagram();

  200. 

  201.     /***

  202.      * Returns the type of the packet.

  203.      * <p>

  204.      * @return The type of the packet.

  205.      ***/

  206.     public final int getType()

  207.     {

  208.         return _type;

  209.     }

  210. 

  211.     /***

  212.      * Returns the address of the host where the packet is going to be sent

  213.      * or where it came from.

  214.      * <p>

  215.      * @return The type of the packet.

  216.      ***/

  217.     public final InetAddress getAddress()

  218.     {

  219.         return _address;

  220.     }

  221. 

  222.     /***

  223.      * Returns the port where the packet is going to be sent

  224.      * or where it came from.

  225.      * <p>

  226.      * @return The port where the packet came from or where it is going.

  227.      ***/

  228.     public final int getPort()

  229.     {

  230.         return _port;

  231.     }

  232. 

  233.     /*** Sets the port where the packet is going to be sent. ***/

  234.     public final void setPort(int port)

  235.     {

  236.         _port = port;

  237.     }

  238. 

  239.     /*** Sets the host address where the packet is going to be sent. ***/

  240.     public final void setAddress(InetAddress address)

  241.     {

  242.         _address = address;

  243.     }

  244. }