/*
 * Copyright 2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.tk
 *
 * Corresponds to:
 *		headers/os/net/DatagramSocket.h rev 43302
 *		src/kits/network/libnetapi/DatagramSocket.cpp rev 43302
 */

/*!
	\file DatagramSocket.h
	\ingroup network
	\brief BAbstractSocket implementation for UDP datagram connections.
*/

/*!
	\class BDatagramSocket
	\ingroup network
	\brief BAbstractSocket implementation for UDP 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 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, 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).

	To better match the atomic behavior of datagrams, this class provides
	SendTo and ReceiveFrom methods. These allow to send datagrams to different
	peers, and receive datagrams only from a single one at a time. This allows
	the use of a single datagram connection to communicate with multiple peers
	at the same time.
*/

/*!
	\fn BDatagramSocket::BDatagramSocket()
	\brief Default constructor.

	Does nothing. Call Bind or Connect to actually start network communications.
	
	\see BAbstractSocket::BAbstractSocket().
*/

/*!
	\fn BDatagramSocket::BDatagramSocket(const BNetworkAddress& peer,
		bigtime_t timeout)
	\brief Create and connect a datagram socket.

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

	\param peer host to connect to
	\param timeout connection timeout, in microsecond.
*/

/*!
	\fn BDatagramSocket::BDatagramSocket(const BDatagramSocket& other)
	\brief Copy constructor.
*/

/*!
	\fn BDatagramSocket::~BDatagramSocket()
	\brief Destructor.

	The socket is disconnected.
*/

/*!
	\fn BDatagramSocket::SetBroadcast(bool broadcast)
	\brief 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.

	\param broadcast the requested state for broadcast permissions.
	\return B_OK on success, or other error codes on failure.
*/

/*!
	\fn void BDatagramSocket::SetPeer(const BNetworkAddress& peer)
	\brief 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.

	\param peer the address to which following Write calls will send datagrams
*/

/*!
	\fn size_t BDatagramSocket::MaxTransmissionSize() const

	The maximum size for datagram sockets is 32768 bytes.

	\returns 32768
*/

/*!
	\fn ssize_t BDatagramSocket::SendTo(const BNetworkAddress& address,
		const void* buffer, size_t size)
	\brief 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.

	\param address the host to send the datagram to
	\param buffer datagram contents
	\param size size of the buffer
	\returns the number of bytes sent, which may be less than requested, or a
		negative error code.
*/

/*!
	\fn ssize_t BDatagramSocket::ReceiveFrom(void* buffer, size_t bufferSize,
		BNetworkAddress& from)
	\brief receive a single datagram from a given host

	Wait for a message to come from the given host and fill the buffer with it.
	If the buffer is too small, extra bytes from the datagram will be lost.

	\param buffer the buffer to store the datagram in
	\param bufferSize size of the buffer
	\param from the datagram sneder address
*/

/*!
	\fn ssize_t BDatagramSocket::Read(void* buffer, size_t size)
	\brief Receive a datagram from any sender

	This is similar to ReceiveFrom, but does not allow filtering which host the
	datagram comes from. The first message that comes in will be accepted.

	There is no way to know who sent the message.

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

	\param buffer memory to store the datagram in
	\param size the size of the buffer
	\return the number of bytes actually written, or a negative error code.
*/

/*!
	\fn ssize_t BDatagramSocket::Write(const void* buffer, size_t size)
	\brief 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 givento the SetPeer function.

	\param buffer the datagram to send
	\param size the size of the message
	\return the number of bytes written, which may be less than requested, or
		a negative error code.
*/