All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | List of all members
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
peerhost to connect to
timeoutconnection 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
buffermemory to store the datagram in
sizethe 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
bufferthe buffer to store the datagram in
bufferSizesize of the buffer
fromthe 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
addressthe host to send the datagram to
bufferdatagram contents
sizesize 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
broadcastthe 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
peerthe 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
bufferthe datagram to send
sizethe size of the message
Returns
the number of bytes written, which may be less than requested, or a negative error code.

Reimplemented from BDataIO.