1/* 2 * Copyright 2013-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Adrien Destugues, pulkomandy@pulkomandy.tk 7 * Axel Dörfler, axeld@pinc-software.de 8 * 9 * Corresponds to: 10 * headers/os/net/DatagramSocket.h rev 43302 11 * src/kits/network/libnetapi/DatagramSocket.cpp rev 43302 12 */ 13 14/*! 15 \file DatagramSocket.h 16 \ingroup network 17 \brief BAbstractSocket implementation for datagram connections. 18*/ 19 20/*! 21 \class BDatagramSocket 22 \ingroup network 23 \brief BAbstractSocket implementation for datagram connections. 24 25 Datagrams are atomic messages. There is no notion of sequence and the data 26 sent in a sequence of write calls may not get to the other end of the 27 connections in the same order. There is no flow control, so some of them 28 may not even make it to the peer. The most well known datagram protocol 29 is UDP, which also happens to be the only one that Haiku currently supports. 30 31 The main uses for datagram sockets are when performance is more important 32 than safety (the lack of acknowledge mechanism allows to send a lot of 33 datagram packets at once, whereas TCP is limited by its sliding window 34 mechanism), when the application wants to manage flow control and 35 acknowledges itself (ie. when you want to implement your own protocol on 36 top of UDP), and when lost packets don't matter (for example, in 37 a video stream, there is no use for receiving late video frames if they 38 were already skipped to play the following ones). 39 40 Since UDP is a connectionless protocol, in order to specify the target, 41 or to be able to know from where you got a packet, this class provides 42 you with the extra methods SendTo() and ReceiveFrom(). 43*/ 44 45/*! 46 \fn BDatagramSocket::BDatagramSocket() 47 \brief Default constructor. 48 49 Does nothing. Call Bind() or Connect() to actually start network 50 communications. 51 52 \see BAbstractSocket::BAbstractSocket(). 53*/ 54 55/*! 56 \fn BDatagramSocket::BDatagramSocket(const BNetworkAddress& peer, 57 bigtime_t timeout) 58 \brief Create and connect a datagram socket. 59 60 The socket is immediately connected to the given peer. Use InitCheck() to 61 make sure the connection was successful. 62 63 \param peer host to connect to 64 \param timeout connection timeout, in microsecond. 65*/ 66 67/*! 68 \fn BDatagramSocket::BDatagramSocket(const BDatagramSocket& other) 69 \brief Copy constructor. 70*/ 71 72/*! 73 \fn BDatagramSocket::~BDatagramSocket() 74 \brief Destructor. 75 76 The socket is disconnected. 77*/ 78 79/*! 80 \fn BDatagramSocket::SetBroadcast(bool broadcast) 81 \brief enables or disable broadcast mode 82 83 In broadcast mode, datagrams can be sent to multiple peers at once. 84 Calling this method is not enough, you must also set your peer address to 85 be \c INADDR_BROADCAST to effectively send a broadcast message. 86 87 Note that broadcast messages usually don't propagate on Internet as they 88 would generate too much traffic. Their use is thus restricted to local 89 networks. 90 91 \param broadcast the requested state for broadcast permissions. 92 \return \c B_OK on success, or other error codes on failure. 93*/ 94 95/*! 96 \fn void BDatagramSocket::SetPeer(const BNetworkAddress& peer) 97 \brief Change the remote host for this connections. 98 99 Datagram connections are not statically bound to a remote address, so it is 100 possible to change the destination of packets at runtime. 101 102 Note that packets coming to the right local address, no matter where they 103 come from, will always be accepted. 104 105 \param peer the address to which following Write calls will send datagrams 106*/ 107 108/*! 109 \fn size_t BDatagramSocket::MaxTransmissionSize() const 110 111 The maximum size for datagram sockets is 32768 bytes. 112 113 \returns 32768 114*/ 115 116/*! 117 \fn ssize_t BDatagramSocket::SendTo(const BNetworkAddress& address, 118 const void* buffer, size_t size) 119 \brief Send a single datagram to the given address 120 121 Unlike the Write() method, which always sends to the same peer, this method 122 can be used to send messages to different destinations. 123 124 \param address the host to send the datagram to 125 \param buffer datagram contents 126 \param size size of the buffer 127 \returns the number of bytes sent, which may be less than requested, or a 128 negative error code. 129*/ 130 131/*! 132 \fn ssize_t BDatagramSocket::ReceiveFrom(void* buffer, size_t bufferSize, 133 BNetworkAddress& from) 134 \brief receive a single datagram from a given host 135 136 Receives a datagram, and fills the \a from address with the host that 137 sent it. 138 If the buffer is too small, extra bytes from the datagram will be lost. 139 140 \param buffer the buffer to store the datagram in 141 \param bufferSize size of the buffer 142 \param from the datagram sender address 143*/ 144 145/*! 146 \fn ssize_t BDatagramSocket::Read(void* buffer, size_t size) 147 \brief Receive a datagram from any sender 148 149 This is similar to ReceiveFrom(), but there is no way to know who sent 150 the message. 151 152 If the buffer is too small, the remaining part of the datagram is lost. 153 154 \param buffer memory to store the datagram in 155 \param size the size of the buffer 156 \return the number of bytes actually written, or a negative error code. 157*/ 158 159/*! 160 \fn ssize_t BDatagramSocket::Write(const void* buffer, size_t size) 161 \brief Send a datagram to the default target 162 163 If the socket is connected, send a datagram to the connected host. 164 If it's not, send to the peer given to the SetPeer() function. 165 166 \param buffer the datagram to send 167 \param size the size of the message 168 \return the number of bytes written, which may be less than requested, or 169 a negative error code. 170*/ 171