44 |
*/ |
*/ |
45 |
|
|
46 |
/** |
/** |
47 |
* This class models a packet of data that is to be sent across the network |
* This class models a packet of data that is to be sent across the network |
48 |
* using a connectionless protocol such as UDP. It contains the data |
* using a connectionless protocol such as UDP. It contains the data |
49 |
* to be send, as well as the destination address and port. Note that |
* to be send, as well as the destination address and port. Note that |
50 |
* datagram packets can arrive in any order and are not guaranteed to be |
* datagram packets can arrive in any order and are not guaranteed to be |
51 |
* delivered at all. |
* delivered at all. |
52 |
* <p> |
* <p> |
53 |
* This class can also be used for receiving data from the network. |
* This class can also be used for receiving data from the network. |
54 |
* <p> |
* <p> |
55 |
* Note that for all method below where the buffer length passed by the |
* Note that for all method below where the buffer length passed by the |
56 |
* caller cannot exceed the actually length of the byte array passed as |
* caller cannot exceed the actually length of the byte array passed as |
57 |
* the buffer, if this condition is not true, then the method silently |
* the buffer, if this condition is not true, then the method silently |
58 |
* reduces the length value to maximum allowable value. |
* reduces the length value to maximum allowable value. |
59 |
* |
* |
60 |
* Written using on-line Java Platform 1.2 API Specification, as well |
* Written using on-line Java Platform 1.2 API Specification, as well |
61 |
* as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998). |
* as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998). |
62 |
* Status: Believed complete and correct. |
* Status: Believed complete and correct. |
63 |
* |
* |
64 |
* @author Warren Levy <warrenl@cygnus.com> |
* @author Warren Levy <warrenl@cygnus.com> |
65 |
* @author Aarom M. Renn (arenn@urbanophile.com) (Documentation comments) |
* @author Aarom M. Renn (arenn@urbanophile.com) (Documentation comments) |
66 |
* @date April 28, 1999. |
* @date April 28, 1999. |
67 |
*/ |
*/ |
|
|
|
68 |
public final class DatagramPacket |
public final class DatagramPacket |
69 |
{ |
{ |
70 |
/** |
/** |
71 |
* The data buffer to send |
* The data buffer to send |
72 |
*/ |
*/ |
73 |
private byte[] buffer; |
private byte[] buffer; |
74 |
|
|
75 |
/** |
/** |
76 |
* This is the offset into the buffer to start sending from or receiving to. |
* This is the offset into the buffer to start sending from or receiving to. |
77 |
*/ |
*/ |
78 |
private int offset; |
private int offset; |
79 |
|
|
80 |
/** |
/** |
81 |
* The length of the data buffer to send |
* The length of the data buffer to send |
82 |
*/ |
*/ |
83 |
private int length; |
private int length; |
84 |
|
|
85 |
/** |
/** |
86 |
* The address to which the packet should be sent or from which it |
* The address to which the packet should be sent or from which it |
87 |
* was received |
* was received |
88 |
*/ |
*/ |
89 |
private InetAddress address; |
private InetAddress address; |
90 |
|
|
91 |
/** |
/** |
92 |
* The port to which the packet should be sent or from which it was |
* The port to which the packet should be sent or from which it was |
93 |
* was received. |
* was received. |
94 |
*/ |
*/ |
95 |
private int port; |
private int port; |
96 |
|
|
97 |
/** |
/** |
98 |
* This method initializes a new instance of <code>DatagramPacket</code> |
* This method initializes a new instance of <code>DatagramPacket</code> |
99 |
* which has the specified buffer, offset, and length. |
* which has the specified buffer, offset, and length. |
100 |
* |
* |
101 |
* @param buf The buffer for holding the incoming datagram. |
* @param buf The buffer for holding the incoming datagram. |
102 |
* @param offset The offset into the buffer to start writing. |
* @param offset The offset into the buffer to start writing. |
103 |
* @param length The maximum number of bytes to read. |
* @param length The maximum number of bytes to read. |
104 |
* |
* |
105 |
* @since 1.2 |
* @since 1.2 |
106 |
*/ |
*/ |
107 |
public DatagramPacket(byte[] buf, int offset, int length) |
public DatagramPacket(byte[] buf, int offset, int length) |
108 |
{ |
{ |
109 |
if (buf == null) |
if (buf == null) |
123 |
this.port = -1; |
this.port = -1; |
124 |
} |
} |
125 |
|
|
126 |
/** |
/** |
127 |
* Initializes a new instance of <code>DatagramPacket</code> for |
* Initializes a new instance of <code>DatagramPacket</code> for |
128 |
* receiving packets from the network. |
* receiving packets from the network. |
129 |
* |
* |
130 |
* @param buf A buffer for storing the returned packet data |
* @param buf A buffer for storing the returned packet data |
131 |
* @param length The length of the buffer (must be <= buf.length) |
* @param length The length of the buffer (must be <= buf.length) |
132 |
*/ |
*/ |
133 |
public DatagramPacket(byte[] buf, int length) |
public DatagramPacket(byte[] buf, int length) |
134 |
{ |
{ |
135 |
this(buf, 0, length); |
this(buf, 0, length); |
136 |
} |
} |
137 |
|
|
138 |
/** |
/** |
139 |
* Initializes a new instance of <code>DatagramPacket</code> for |
* Initializes a new instance of <code>DatagramPacket</code> for |
140 |
* transmitting packets across the network. |
* transmitting packets across the network. |
141 |
* |
* |
142 |
* @param buf A buffer containing the data to send |
* @param buf A buffer containing the data to send |
143 |
* @param offset The offset into the buffer to start writing from. |
* @param offset The offset into the buffer to start writing from. |
144 |
* @param len The length of the buffer (must be <= buf.length) |
* @param len The length of the buffer (must be <= buf.length) |
145 |
* @param addr The address to send to |
* @param addr The address to send to |
146 |
* @param port The port to send to |
* @param port The port to send to |
147 |
* |
* |
148 |
* @since 1.2 |
* @since 1.2 |
149 |
*/ |
*/ |
150 |
public DatagramPacket(byte[] buf, int offset, int length, |
public DatagramPacket(byte[] buf, int offset, int length, |
151 |
InetAddress address, int port) |
InetAddress address, int port) |
152 |
{ |
{ |
171 |
this.port = port; |
this.port = port; |
172 |
} |
} |
173 |
|
|
174 |
/** |
/** |
175 |
* Initializes a new instance of <code>DatagramPacket</code> for |
* Initializes a new instance of <code>DatagramPacket</code> for |
176 |
* transmitting packets across the network. |
* transmitting packets across the network. |
177 |
* |
* |
178 |
* @param buf A buffer containing the data to send |
* @param buf A buffer containing the data to send |
179 |
* @param length The length of the buffer (must be <= buf.length) |
* @param length The length of the buffer (must be <= buf.length) |
180 |
* @param address The address to send to |
* @param address The address to send to |
181 |
* @param port The port to send to |
* @param port The port to send to |
182 |
*/ |
*/ |
183 |
public DatagramPacket(byte[] buf, int length, InetAddress address, int port) |
public DatagramPacket(byte[] buf, int length, InetAddress address, int port) |
184 |
{ |
{ |
185 |
this(buf, 0, length, address, port); |
this(buf, 0, length, address, port); |
195 |
* @param address The socket address to send to |
* @param address The socket address to send to |
196 |
* |
* |
197 |
* @exception SocketException If an error occurs |
* @exception SocketException If an error occurs |
198 |
|
* @exception IllegalArgumentException If address type is not supported |
199 |
* |
* |
200 |
* @since 1.4 |
* @since 1.4 |
201 |
*/ |
*/ |
202 |
public DatagramPacket(byte[] buf, int offset, int length, SocketAddress address) |
public DatagramPacket(byte[] buf, int offset, int length, |
203 |
|
SocketAddress address) |
204 |
throws SocketException |
throws SocketException |
205 |
{ |
{ |
206 |
this(buf, offset, length, ((InetSocketAddress)address).getAddress(), |
this(buf, offset, length, ((InetSocketAddress)address).getAddress(), |
216 |
* @param address The socket address to send to |
* @param address The socket address to send to |
217 |
* |
* |
218 |
* @exception SocketException If an error occurs |
* @exception SocketException If an error occurs |
219 |
|
* @exception IllegalArgumentException If address type is not supported |
220 |
* |
* |
221 |
* @since 1.4 |
* @since 1.4 |
222 |
*/ |
*/ |
227 |
((InetSocketAddress)address).getPort()); |
((InetSocketAddress)address).getPort()); |
228 |
} |
} |
229 |
|
|
230 |
/** |
/** |
231 |
* Returns the address that this packet is being sent to or, if it was used |
* Returns the address that this packet is being sent to or, if it was used |
232 |
* to receive a packet, the address that is was received from. If the |
* to receive a packet, the address that is was received from. If the |
233 |
* constructor that doesn not take an address was used to create this object |
* constructor that doesn not take an address was used to create this object |
234 |
* and no packet was actually read into this object, then this method |
* and no packet was actually read into this object, then this method |
235 |
* returns <code>null</code>. |
* returns <code>null</code>. |
236 |
* |
* |
237 |
* @return The address for this packet. |
* @return The address for this packet. |
238 |
*/ |
*/ |
239 |
public synchronized InetAddress getAddress() |
public synchronized InetAddress getAddress() |
240 |
{ |
{ |
241 |
return address; |
return address; |
242 |
} |
} |
243 |
|
|
244 |
/** |
/** |
245 |
* Returns the port number this packet is being sent to or, if it was used |
* Returns the port number this packet is being sent to or, if it was used |
246 |
* to receive a packet, the port that it was received from. If the |
* to receive a packet, the port that it was received from. If the |
247 |
* constructor that doesn not take an address was used to create this object |
* constructor that doesn not take an address was used to create this object |
248 |
* and no packet was actually read into this object, then this method |
* and no packet was actually read into this object, then this method |
249 |
* will return 0. |
* will return 0. |
250 |
* |
* |
251 |
* @return The port number for this packet |
* @return The port number for this packet |
252 |
*/ |
*/ |
253 |
public synchronized int getPort() |
public synchronized int getPort() |
254 |
{ |
{ |
255 |
return port; |
return port; |
256 |
} |
} |
257 |
|
|
258 |
/** |
/** |
259 |
* Returns the data buffer for this packet |
* Returns the data buffer for this packet |
260 |
* |
* |
261 |
* @return This packet's data buffer |
* @return This packet's data buffer |
262 |
*/ |
*/ |
263 |
public synchronized byte[] getData() |
public synchronized byte[] getData() |
264 |
{ |
{ |
265 |
return buffer; |
return buffer; |
266 |
} |
} |
267 |
|
|
268 |
/** |
/** |
269 |
* This method returns the current offset value into the data buffer |
* This method returns the current offset value into the data buffer |
270 |
* where data will be sent from. |
* where data will be sent from. |
271 |
* |
* |
272 |
* @return The buffer offset. |
* @return The buffer offset. |
273 |
* |
* |
274 |
* @since 1.2 |
* @since 1.2 |
275 |
*/ |
*/ |
276 |
public synchronized int getOffset() |
public synchronized int getOffset() |
277 |
{ |
{ |
278 |
return offset; |
return offset; |
279 |
} |
} |
280 |
|
|
281 |
/** |
/** |
282 |
* Returns the length of the data in the buffer |
* Returns the length of the data in the buffer |
283 |
* |
* |
284 |
* @return The length of the data |
* @return The length of the data |
285 |
*/ |
*/ |
286 |
public synchronized int getLength() |
public synchronized int getLength() |
287 |
{ |
{ |
288 |
return length; |
return length; |
289 |
} |
} |
290 |
|
|
291 |
/** |
/** |
292 |
* This sets the address to which the data packet will be transmitted. |
* This sets the address to which the data packet will be transmitted. |
293 |
* |
* |
294 |
* @param addr The destination address |
* @param addr The destination address |
295 |
* |
* |
296 |
* @since 1.1 |
* @since 1.1 |
297 |
*/ |
*/ |
298 |
public synchronized void setAddress(InetAddress iaddr) |
public synchronized void setAddress(InetAddress iaddr) |
299 |
{ |
{ |
300 |
if (iaddr == null) |
if (iaddr == null) |
303 |
address = iaddr; |
address = iaddr; |
304 |
} |
} |
305 |
|
|
306 |
/** |
/** |
307 |
* This sets the port to which the data packet will be transmitted. |
* This sets the port to which the data packet will be transmitted. |
308 |
* |
* |
309 |
* @param port The destination port |
* @param port The destination port |
310 |
* |
* |
311 |
* @since 1.1 |
* @since 1.1 |
312 |
*/ |
*/ |
313 |
public synchronized void setPort(int iport) |
public synchronized void setPort(int iport) |
314 |
{ |
{ |
315 |
if (iport < 0 || iport > 65535) |
if (iport < 0 || iport > 65535) |
323 |
* |
* |
324 |
* @param address The socket address of the remove host |
* @param address The socket address of the remove host |
325 |
* |
* |
326 |
* @exception IllegalArgumentException If an error occurs |
* @exception IllegalArgumentException If address type is not supported |
327 |
* |
* |
328 |
* @since 1.4 |
* @since 1.4 |
329 |
*/ |
*/ |
350 |
return new InetSocketAddress (address, port); |
return new InetSocketAddress (address, port); |
351 |
} |
} |
352 |
|
|
353 |
/** |
/** |
354 |
* Sets the data buffer for this packet. |
* Sets the data buffer for this packet. |
355 |
* |
* |
356 |
* @param buf The new buffer for this packet |
* @param buf The new buffer for this packet |
357 |
* |
* |
358 |
* @since 1.1 |
* @exception NullPointerException If the argument is null |
359 |
*/ |
* |
360 |
|
* @since 1.1 |
361 |
|
*/ |
362 |
public synchronized void setData(byte[] buf) |
public synchronized void setData(byte[] buf) |
363 |
{ |
{ |
364 |
// This form of setData requires setLength to be called separately |
// This form of setData requires setLength to be called separately |
369 |
buffer = buf; |
buffer = buf; |
370 |
} |
} |
371 |
|
|
372 |
/** |
/** |
373 |
* This method sets the data buffer for the packet. |
* This method sets the data buffer for the packet. |
374 |
* |
* |
375 |
* @param buf The byte array containing the data for this packet. |
* @param buf The byte array containing the data for this packet. |
376 |
* @param offset The offset into the buffer to start reading data from. |
* @param offset The offset into the buffer to start reading data from. |
377 |
* @param length The number of bytes of data in the buffer. |
* @param length The number of bytes of data in the buffer. |
378 |
* |
* |
379 |
* @since 1.2 |
* @exception NullPointerException If the argument is null |
380 |
*/ |
* |
381 |
|
* @since 1.2 |
382 |
|
*/ |
383 |
public synchronized void setData(byte[] buf, int offset, int length) |
public synchronized void setData(byte[] buf, int offset, int length) |
384 |
{ |
{ |
385 |
// This form of setData must be used if offset is to be changed. |
// This form of setData must be used if offset is to be changed. |
399 |
this.length = length; |
this.length = length; |
400 |
} |
} |
401 |
|
|
402 |
/** |
/** |
403 |
* Sets the length of the data in the buffer. |
* Sets the length of the data in the buffer. |
404 |
* |
* |
405 |
* @param length The new length. (Where len <= buf.length) |
* @param length The new length. (Where len <= buf.length) |
406 |
* |
* |
407 |
* @since 1.1 |
* @exception IllegalArgumentException If the length is negative or |
408 |
*/ |
* if the length is greater than the packet's data buffer length |
409 |
|
* |
410 |
|
* @since 1.1 |
411 |
|
*/ |
412 |
public synchronized void setLength(int length) |
public synchronized void setLength(int length) |
413 |
{ |
{ |
414 |
if (length < 0) |
if (length < 0) |