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