ot::net
class DatagramPacket
#include "ot/net/DatagramPacket.h"
Class to represent a datagram packet.
Datagram packets are packets of data which are transmitted from one host to another via connectionless UDP sockets.
UDP datagram sockets are not connected to another host (they are connectionless) and for this reason, information about the address and port of the peer host is contained within the DatagramPacket class itself.
The DatagramPacket also contains a pointer to a buffer where data can be sent from or received into. The data buffer can either be provided by the application or automatically allocated by the DatagramPacket constructor. When the data buffer is provided by the application, ownership of the buffer (and the corresponding responsibility to delete it) can be assigned to the DatagramPacket object or retained by the application.
The data buffer and the function signatures used to access it refer to non-const Bytes. This is due to the fact that DatagramPackets can be used to both send and receive data, therefore the contained buffer must be modifiable. However, if the application will only use the DatagramPacket to send data, then it is safe to use a const_cast<> when constructing the DatagramPacket from a constant buffer, as in the example below:-
RefPtr<DatagramSocket> rpSocket(new DatagramSocket);
RefPtr<InetAddress> rpDest = InetAddress::GetByName("udp.destination.net");
const int port = 1234;
const Byte* msg = "THIS IS A UDP MESSAGE";
//send a UDP packet to the remote host
rpSocket->send(DatagramPacket(const_cast<Byte*>(msg), strlen(msg), rpDest.get(), port));
- Since:
-
1.3
Constructor/Destructor Summary |
DatagramPacket(size_t bufSize)
Creates a DatagramPacket and automatically allocates a data buffer of a given size. |
DatagramPacket(Byte* pBuffer, size_t bufSize, bool bAssignBuffer)
Creates a DatagramPacket, providing an application-supplied data buffer. |
DatagramPacket(Byte* pBuffer, size_t bufSize, InetAddress* pAddress, int port, bool bAssignBuffer)
Creates a DatagramPacket, providing an application-supplied data buffer and pre-defined destination details. |
~DatagramPacket()
DatagramPacket destructor. |
Method Summary
|
RefPtr< InetAddress > |
getAddress() const
Returns an InetAddress which represents the IP address of the host from which this DatagramPacket was received or to which it will be sent. |
size_t |
getBufferSize() const
Returns the size of the data buffer as specified in the constructor or one of the overloaded setData methods. |
Byte* |
getData() const
Returns a pointer to the data buffer referenced by this DatagramPacket. |
size_t |
getLength() const
Returns the length (in bytes) of the data to be sent or, following a receive operation, the length of the data received. |
int |
getPort() const
Returns the port number on the remote host to which this datagram packet will be sent or from which it was received. |
void |
setAddress(InetAddress* pAddress)
Sets the IP address of the host to which this datagram packet will be sent. |
void |
setData(size_t bufSize)
Replaces the existing data buffer for this DatagramPacket with a new buffer of a different size. |
void |
setData(Byte* pBuffer, size_t bufSize, bool bAssignBuffer)
Replaces the existing data buffer for this DatagramPacket with the supplied data buffer. |
void |
setLength(size_t length)
Sets the length (in bytes) of the datagram packet to send or the maximum length to receive. |
void |
setPort(int port)
Sets the port number on the remote host(s) to which this datagram packet will be sent. |
Constructor/Destructor Detail |
DatagramPacket
DatagramPacket(size_t bufSize)
-
Creates a DatagramPacket and automatically allocates a data buffer of a given size.
- Parameters:
bufSize
-
the size of the buffer to automatically allocate. The value of bufSize may be zero, in which case no data will be sent from or received into this datagram packet.
DatagramPacket
DatagramPacket(Byte* pBuffer,
size_t bufSize,
bool bAssignBuffer)
-
Creates a DatagramPacket, providing an application-supplied data buffer.
The supplied data buffer may be created on the stack or dynamically allocated from the free store. Ownership of dynamically allocated buffers may be transferred from the application to the DatagramPacket object by setting the bAssignBuffer parameter to true. When the application retains ownership of the data buffer (which must always be the case when the buffer is created on the stack), it is responsible for ensuring that the buffer's lifetime exceeds the lifetime of the DatagramPacket which references it.
- Parameters:
pBuffer
-
a pointer to an array of Bytes to use as a data buffer. The buffer is non constant so that the DatagramPacket can be used for both send and receive operations. If bufSize is zero then pBuffer may be null.
bufSize
-
the size of the supplied buffer, which may be zero.
bAssignBuffer
-
if set to true, the data buffer is automatically deleted by the DatagramPacket's destructor.
- Exceptions:
NullPointerException
-
if both pBuffer is null and bufSize is non-zero.
DatagramPacket
DatagramPacket(Byte* pBuffer,
size_t bufSize,
InetAddress* pAddress,
int port,
bool bAssignBuffer)
-
Creates a DatagramPacket, providing an application-supplied data buffer and pre-defined destination details.
This constructor provides tha ability to set the address and port number to which data in this datagram may be sent or, in the case of received datagrams, from which it may be received.
The supplied data buffer may be created on the stack or dynamically allocated from the free store. Ownership of dynamically allocated buffers may be transferred from the application to the DatagramPacket object by setting the bAssignBuffer parameter to true. When the application retains ownership of the data buffer (which must always be the case when the buffer is created on the stack), it is responsible for ensuring that the buffer's lifetime exceeds the lifetime of the DatagramPacket which references it.
- Parameters:
pBuffer
-
a pointer to an array of Bytes to use as a data buffer. The buffer is non constant so that the DatagramPacket can be used for both send and receive operations. If bufSize is zero then pBuffer may be null.
bufSize
-
the size of the supplied buffer, which may be zero.
pAddress
-
the destination IP address to which data will be sent or from which data may be received.
port
-
the destination port number or -1 if this datagram may be used to receive messages from any port.
bAssignBuffer
-
if set to true, the data buffer is automatically deleted by the DatagramPacket's destructor.
- Exceptions:
NullPointerException
-
if both pBuffer is null and bufSize is non-zero.
~DatagramPacket
~DatagramPacket()
-
DatagramPacket destructor.
This will automatically delete the referenced data buffer when it is marked as being owned by this DatagramPacket object.
getAddress
RefPtr< InetAddress > getAddress() const
-
Returns an InetAddress which represents the IP address of the host from which this DatagramPacket was received or to which it will be sent.
- Returns:
-
an InetAddress representing the IP address from which this datagram packet was received, or the address to which it will be sent. A null value indicates that the address has not yet been set for send operations.
- See also:
-
setAddress
getBufferSize
size_t getBufferSize() const
-
Returns the size of the data buffer as specified in the constructor or one of the overloaded setData methods.
- Returns:
-
the size of the referenced data buffer.
- See also:
-
getData , setData
getData
Byte* getData() const
-
Returns a pointer to the data buffer referenced by this DatagramPacket.
getLength
size_t getLength() const
-
Returns the length (in bytes) of the data to be sent or, following a receive operation, the length of the data received.
The length field is initially set equal to the size of the data buffer, but is modified by calls to setLength() or DatagramSocket::receive().
- Returns:
-
the length (in bytes) of the data to be sent or received.
- See also:
-
setLength , setData
getPort
int getPort() const
-
Returns the port number on the remote host to which this datagram packet will be sent or from which it was received.
A return value of -1 indicates that this datagram packet has not yet had a port number specified.
- Returns:
-
the port number on the remote host to which this datagram packet will be sent or from which it was received.
- See also:
-
setPort
setAddress
void setAddress(InetAddress* pAddress)
-
Sets the IP address of the host to which this datagram packet will be sent.
Setting the address value has no affect on receive operations. To specify the host from which data can be received, use the DatagramSocket::connect() function.
- Parameters:
pAddress
-
a pointer to an InetAddress representing the IP address to which this datagram packet will be sent. It is permissible for this to be a null pointer, in which case the DatagramSocket used to send this datagram packet must be connected to a specific host/port.
- See also:
-
getAddress , DatagramSocket::connect
setData
void setData(size_t bufSize)
-
Replaces the existing data buffer for this DatagramPacket with a new buffer of a different size.
If the existing buffer is 'owned' by this DatagramPacket then it is first deleted before allocating a new buffer. Any data in the existing buffer is discarded.
If the new size is less than the length field, the length field is reduced to be equal to the new buffer size. Otherwise it is left unchanged.
- Parameters:
bufSize
-
the size of the buffer to automatically allocate. The value of bufSize may be zero, in which case no data will be sent from or received into this datagram packet.
setData
void setData(Byte* pBuffer,
size_t bufSize,
bool bAssignBuffer)
-
Replaces the existing data buffer for this DatagramPacket with the supplied data buffer.
If the existing buffer is 'owned' by this DatagramPacket then it is first deleted before allocating a new buffer.
The supplied data buffer may be created on the stack or dynamically allocated from the free store. Ownership of dynamically allocated buffers may be transferred from the application to the DatagramPacket object by setting the bAssignBuffer parameter to true. When the application retains ownership of the data buffer (which must always be the case when the buffer is created on the stack), it is responsible for ensuring that the buffer's lifetime exceeds the lifetime of the DatagramPacket which references it.
- Parameters:
pBuffer
-
a pointer to an array of Bytes to use as a data buffer. The buffer is non constant so that the DatagramPacket can be used for both send and receive operations. If bufSize is zero then pBuffer may be null.
bufSize
-
the size of the supplied buffer, which may be zero.
bAssignBuffer
-
if set to true, the data buffer is automatically deleted by the DatagramPacket's destructor.
- Exceptions:
NullPointerException
-
if both pBuffer is null and bufSize is non-zero.
setLength
void setLength(size_t length)
-
Sets the length (in bytes) of the datagram packet to send or the maximum length to receive.
The specified length must not exceed the size of the referenced data buffer.
When receiving a datagram packet, if the received packet is larger than the value of length, then it will be silently truncated to the specified length.
- Parameters:
length
-
the length (in bytes) to send or receive.
- Exceptions:
IllegalArgumentException
-
if length is less than the size of the data buffer.
- Note:
-
When a DatagramPacket is received via a DatagramSocket, its length field is set equal to the size of the datagram packet received. Unless this value is changed by a subsequent call to setLength(), this new length value will be used to control further send and receive operations.
- See also:
-
getLength
setPort
void setPort(int port)
-
Sets the port number on the remote host(s) to which this datagram packet will be sent.
Setting the port number has no affect on receive operations. To specify the host and port from which data can be received, use the DatagramSocket::connect() function.
- Parameters:
port
-
the number of the port or -1 to unset the port, in which case the DatagramSocket used to send this datagram packet. must be connected to a specific host/port.
- See also:
-
getAddress , DatagramSocket::connect
Found a bug or missing feature? Please email us at support@elcel.com