BDatagramSocket Class Reference

BAbstractSocket implementation for datagram connections. More...

Inherits BAbstractSocket.

Public Member Functions
	BDatagramSocket ()
	Default constructor.
	BDatagramSocket (const BDatagramSocket &other)
	Copy constructor.
	BDatagramSocket (const BNetworkAddress &peer, bigtime_t timeout=-1)
	Create and connect a datagram socket.
virtual	~BDatagramSocket ()
	Destructor.
virtual size_t	MaxTransmissionSize () const
virtual ssize_t	Read (void *buffer, size_t size)
	Receive a datagram from any sender.
virtual ssize_t	ReceiveFrom (void *buffer, size_t bufferSize, BNetworkAddress &from)
	receive a single datagram from a given host
virtual ssize_t	SendTo (const BNetworkAddress &address, const void *buffer, size_t size)
	Send a single datagram to the given address.
status_t	SetBroadcast (bool broadcast)
	enables or disable broadcast mode
void	SetPeer (const BNetworkAddress &peer)
	Change the remote host for this connections.
virtual ssize_t	Write (const void *buffer, size_t size)
	Send a datagram to the default target.
Public Member Functions inherited from BAbstractSocket
	BAbstractSocket ()
	Default constructor.
	BAbstractSocket (const BAbstractSocket &other)
	Copy constructor.
virtual	~BAbstractSocket ()
	Destructor.
virtual void	Disconnect ()
	Close the connection.
status_t	InitCheck () const
	Check connection status.
virtual bool	IsBound () const
virtual bool	IsConnected () const
virtual const BNetworkAddress &	Local () const
	gets the local address for this socket
virtual size_t	MaxTransmissionSize () const
	Return the maximal size of a transmission on this socket.
virtual const BNetworkAddress &	Peer () const
	gets the peer address
virtual status_t	SetTimeout (bigtime_t timeout)
	sets the read and write timeout
int	Socket () const
	get the underlying socket descriptor
virtual bigtime_t	Timeout () const
	gets the socket timeout
virtual status_t	WaitForReadable (bigtime_t timeout=B_INFINITE_TIMEOUT) const
	wait for incoming data
virtual status_t	WaitForWritable (bigtime_t timeout=B_INFINITE_TIMEOUT) const
	wait until writing is possible
Public Member Functions inherited from BDataIO
	BDataIO ()
	This constructor does nothing.
virtual	~BDataIO ()
	This destructor does nothing.
virtual status_t	Flush ()
	Writes pending data to underlying storage.
virtual ssize_t	Read (void *buffer, size_t size)
	Reads data from the object into a buffer.
status_t	ReadExactly (void *buffer, size_t size, size_t *_bytesRead=NULL)
	Reads an exact amount of data from the object into a buffer.
virtual ssize_t	Write (const void *buffer, size_t size)
	Writes data from a buffer to the object.
status_t	WriteExactly (const void *buffer, size_t size, size_t *_bytesWritten=NULL)
	Writes an exact amount of data from a buffer to the object.

Additional Inherited Members
Protected Member Functions inherited from BAbstractSocket
status_t	Bind (const BNetworkAddress &local, bool reuseAddr, int type)
	binds the socket to the given address
status_t	Connect (const BNetworkAddress &peer, int type, bigtime_t timeout=B_INFINITE_TIMEOUT)
	Connect the socket to the given peer.

Detailed Description

BAbstractSocket implementation for datagram connections.

Datagrams are atomic messages. There is no notion of sequence and the data sent in a sequence of write calls may not get to the other end of the connections in the same order. There is no flow control, so some of them may not even make it to the peer. The most well known datagram protocol is UDP, which also happens to be the only one that Haiku currently supports.

The main uses for datagram sockets are when performance is more important than safety (the lack of acknowledge mechanism allows to send a lot of datagram packets at once, whereas TCP is limited by its sliding window mechanism), when the application wants to manage flow control and acknowledges itself (ie. when you want to implement your own protocol on top of UDP), and when lost packets don't matter (for example, in a video stream, there is no use for receiving late video frames if they were already skipped to play the following ones).

Since UDP is a connectionless protocol, in order to specify the target, or to be able to know from where you got a packet, this class provides you with the extra methods SendTo() and ReceiveFrom().

Constructor & Destructor Documentation

BDatagramSocket() [1/2]

BDatagramSocket::BDatagramSocket

(

)

Default constructor.

Does nothing. Call Bind() or Connect() to actually start network communications.

See also

BAbstractSocket::BAbstractSocket().

BDatagramSocket() [2/2]

BDatagramSocket::BDatagramSocket	(	const BNetworkAddress &	peer,
		bigtime_t	timeout = -1
	)

Create and connect a datagram socket.

The socket is immediately connected to the given peer. Use InitCheck() to make sure the connection was successful.

Parameters

peer	host to connect to
timeout	connection timeout, in microsecond.

~BDatagramSocket()

BDatagramSocket::~BDatagramSocket ( )

virtual

Destructor.

The socket is disconnected.

Member Function Documentation

MaxTransmissionSize()

size_t BDatagramSocket::MaxTransmissionSize ( ) const

virtual

The maximum size for datagram sockets is 32768 bytes.

Returns

32768

Reimplemented from BAbstractSocket.

Read()

ssize_t BDatagramSocket::Read ( void *  buffer, size_t  size  )

virtual

Receive a datagram from any sender.

This is similar to ReceiveFrom(), but there is no way to know who sent the message.

If the buffer is too small, the remaining part of the datagram is lost.

Parameters

buffer	memory to store the datagram in
size	the size of the buffer

Returns

the number of bytes actually written, or a negative error code.

Reimplemented from BDataIO.

ReceiveFrom()

ssize_t BDatagramSocket::ReceiveFrom ( void *  buffer, size_t  bufferSize, BNetworkAddress &  from  )

virtual

receive a single datagram from a given host

Receives a datagram, and fills the from address with the host that sent it. If the buffer is too small, extra bytes from the datagram will be lost.

Parameters

buffer	the buffer to store the datagram in
bufferSize	size of the buffer
from	the datagram sender address

SendTo()

ssize_t BDatagramSocket::SendTo ( const BNetworkAddress &  address, const void *  buffer, size_t  size  )

virtual

Send a single datagram to the given address.

Unlike the Write() method, which always sends to the same peer, this method can be used to send messages to different destinations.

Parameters

address	the host to send the datagram to
buffer	datagram contents
size	size of the buffer

Returns

the number of bytes sent, which may be less than requested, or a negative error code.

SetBroadcast()

BDatagramSocket::SetBroadcast

(

bool

broadcast

)

enables or disable broadcast mode

In broadcast mode, datagrams can be sent to multiple peers at once. Calling this method is not enough, you must also set your peer address to be INADDR_BROADCAST to effectively send a broadcast message.

Note that broadcast messages usually don't propagate on Internet as they would generate too much traffic. Their use is thus restricted to local networks.

Parameters

broadcast

the requested state for broadcast permissions.

Returns

B_OK on success, or other error codes on failure.

SetPeer()

void BDatagramSocket::SetPeer

(

const BNetworkAddress &

peer

)

Change the remote host for this connections.

Datagram connections are not statically bound to a remote address, so it is possible to change the destination of packets at runtime.

Note that packets coming to the right local address, no matter where they come from, will always be accepted.

Parameters

peer	the address to which following Write calls will send datagrams

Write()

ssize_t BDatagramSocket::Write ( const void *  buffer, size_t  size  )

virtual

Send a datagram to the default target.

If the socket is connected, send a datagram to the connected host. If it's not, send to the peer given to the SetPeer() function.

Parameters

buffer	the datagram to send
size	the size of the message

Returns

the number of bytes written, which may be less than requested, or a negative error code.

Reimplemented from BDataIO.