1 // Copyright 2018 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef PLATFORM_API_UDP_SOCKET_H_ 6 #define PLATFORM_API_UDP_SOCKET_H_ 7 8 #include <stddef.h> // size_t 9 #include <stdint.h> // uint8_t 10 11 #include <memory> 12 13 #include "platform/api/network_interface.h" 14 #include "platform/base/error.h" 15 #include "platform/base/ip_address.h" 16 #include "platform/base/udp_packet.h" 17 18 namespace openscreen { 19 20 class TaskRunner; 21 22 // An open UDP socket for sending/receiving datagrams to/from either specific 23 // endpoints or over IP multicast. 24 // 25 // Usage: The socket is created and opened by calling the Create() method. This 26 // returns a unique pointer that auto-closes/destroys the socket when it goes 27 // out-of-scope. 28 class UdpSocket { 29 public: 30 // Client for the UdpSocket class. 31 class Client { 32 public: 33 virtual ~Client() = default; 34 35 // Method called when the UDP socket is bound. Default implementation 36 // does nothing, as clients may not care about the socket bind state. OnBound(UdpSocket * socket)37 virtual void OnBound(UdpSocket* socket) {} 38 39 // Method called on socket configuration operations when an error occurs. 40 // These specific APIs are: 41 // UdpSocket::Bind() 42 // UdpSocket::SetMulticastOutboundInterface(...) 43 // UdpSocket::JoinMulticastGroup(...) 44 // UdpSocket::SetDscp(...) 45 virtual void OnError(UdpSocket* socket, Error error) = 0; 46 47 // Method called when an error occurs during a SendMessage call. 48 virtual void OnSendError(UdpSocket* socket, Error error) = 0; 49 50 // Method called when a packet is read. 51 virtual void OnRead(UdpSocket* socket, ErrorOr<UdpPacket> packet) = 0; 52 }; 53 54 // Constants used to specify how we want packets sent from this socket. 55 enum class DscpMode : uint8_t { 56 // Default value set by the system on creation of a new socket. 57 kUnspecified = 0x0, 58 59 // Mode for Audio only. 60 kAudioOnly = 0xb8, 61 62 // Mode for Audio + Video. 63 kAudioVideo = 0x88, 64 65 // Mode for low priority operations such as trace log data. 66 kLowPriority = 0x20 67 }; 68 69 using Version = IPAddress::Version; 70 71 // Creates a new, scoped UdpSocket within the IPv4 or IPv6 family. 72 // |local_endpoint| may be zero (see comments for Bind()). This method must be 73 // defined in the platform-level implementation. All |client| methods called 74 // will be queued on the provided |task_runner|. For this reason, the provided 75 // TaskRunner and Client must exist for the duration of the created socket's 76 // lifetime. 77 static ErrorOr<std::unique_ptr<UdpSocket>> Create( 78 TaskRunner* task_runner, 79 Client* client, 80 const IPEndpoint& local_endpoint); 81 82 virtual ~UdpSocket(); 83 84 // Returns true if |socket| belongs to the IPv4/IPv6 address family. 85 virtual bool IsIPv4() const = 0; 86 virtual bool IsIPv6() const = 0; 87 88 // Returns the current local endpoint's address and port. Initially, this will 89 // be the same as the value that was passed into Create(). However, it can 90 // later change after certain operations, such as Bind(), are executed. 91 virtual IPEndpoint GetLocalEndpoint() const = 0; 92 93 // Binds to the address specified in the constructor. If the local endpoint's 94 // address is zero, the operating system will bind to all interfaces. If the 95 // local endpoint's port is zero, the operating system will automatically find 96 // a free local port and bind to it. Future calls to GetLocalEndpoint() will 97 // reflect the resolved port. 98 virtual void Bind() = 0; 99 100 // Sets the device to use for outgoing multicast packets on the socket. 101 virtual void SetMulticastOutboundInterface(NetworkInterfaceIndex ifindex) = 0; 102 103 // Joins to the multicast group at the given address, using the specified 104 // interface. 105 virtual void JoinMulticastGroup(const IPAddress& address, 106 NetworkInterfaceIndex ifindex) = 0; 107 108 // Sends a message. If the message is not sent, Client::OnSendError() will be 109 // called to indicate this. Error::Code::kAgain indicates the operation would 110 // block, which can be expected during normal operation. 111 virtual void SendMessage(const void* data, 112 size_t length, 113 const IPEndpoint& dest) = 0; 114 115 // Sets the DSCP value to use for all messages sent from this socket. 116 virtual void SetDscp(DscpMode state) = 0; 117 118 protected: 119 UdpSocket(); 120 }; 121 122 } // namespace openscreen 123 124 #endif // PLATFORM_API_UDP_SOCKET_H_ 125