1// Copyright 2012 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package ipv4 implements IP-level socket options for the Internet 6// Protocol version 4. 7// 8// The package provides IP-level socket options that allow 9// manipulation of IPv4 facilities. 10// 11// The IPv4 protocol and basic host requirements for IPv4 are defined 12// in RFC 791 and RFC 1122. 13// Host extensions for multicasting and socket interface extensions 14// for multicast source filters are defined in RFC 1112 and RFC 3678. 15// IGMPv1, IGMPv2 and IGMPv3 are defined in RFC 1112, RFC 2236 and RFC 16// 3376. 17// Source-specific multicast is defined in RFC 4607. 18// 19// 20// Unicasting 21// 22// The options for unicasting are available for net.TCPConn, 23// net.UDPConn and net.IPConn which are created as network connections 24// that use the IPv4 transport. When a single TCP connection carrying 25// a data flow of multiple packets needs to indicate the flow is 26// important, Conn is used to set the type-of-service field on the 27// IPv4 header for each packet. 28// 29// ln, err := net.Listen("tcp4", "0.0.0.0:1024") 30// if err != nil { 31// // error handling 32// } 33// defer ln.Close() 34// for { 35// c, err := ln.Accept() 36// if err != nil { 37// // error handling 38// } 39// go func(c net.Conn) { 40// defer c.Close() 41// 42// The outgoing packets will be labeled DiffServ assured forwarding 43// class 1 low drop precedence, known as AF11 packets. 44// 45// if err := ipv4.NewConn(c).SetTOS(0x28); err != nil { 46// // error handling 47// } 48// if _, err := c.Write(data); err != nil { 49// // error handling 50// } 51// }(c) 52// } 53// 54// 55// Multicasting 56// 57// The options for multicasting are available for net.UDPConn and 58// net.IPConn which are created as network connections that use the 59// IPv4 transport. A few network facilities must be prepared before 60// you begin multicasting, at a minimum joining network interfaces and 61// multicast groups. 62// 63// en0, err := net.InterfaceByName("en0") 64// if err != nil { 65// // error handling 66// } 67// en1, err := net.InterfaceByIndex(911) 68// if err != nil { 69// // error handling 70// } 71// group := net.IPv4(224, 0, 0, 250) 72// 73// First, an application listens to an appropriate address with an 74// appropriate service port. 75// 76// c, err := net.ListenPacket("udp4", "0.0.0.0:1024") 77// if err != nil { 78// // error handling 79// } 80// defer c.Close() 81// 82// Second, the application joins multicast groups, starts listening to 83// the groups on the specified network interfaces. Note that the 84// service port for transport layer protocol does not matter with this 85// operation as joining groups affects only network and link layer 86// protocols, such as IPv4 and Ethernet. 87// 88// p := ipv4.NewPacketConn(c) 89// if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil { 90// // error handling 91// } 92// if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil { 93// // error handling 94// } 95// 96// The application might set per packet control message transmissions 97// between the protocol stack within the kernel. When the application 98// needs a destination address on an incoming packet, 99// SetControlMessage of PacketConn is used to enable control message 100// transmissions. 101// 102// if err := p.SetControlMessage(ipv4.FlagDst, true); err != nil { 103// // error handling 104// } 105// 106// The application could identify whether the received packets are 107// of interest by using the control message that contains the 108// destination address of the received packet. 109// 110// b := make([]byte, 1500) 111// for { 112// n, cm, src, err := p.ReadFrom(b) 113// if err != nil { 114// // error handling 115// } 116// if cm.Dst.IsMulticast() { 117// if cm.Dst.Equal(group) { 118// // joined group, do something 119// } else { 120// // unknown group, discard 121// continue 122// } 123// } 124// 125// The application can also send both unicast and multicast packets. 126// 127// p.SetTOS(0x0) 128// p.SetTTL(16) 129// if _, err := p.WriteTo(data, nil, src); err != nil { 130// // error handling 131// } 132// dst := &net.UDPAddr{IP: group, Port: 1024} 133// for _, ifi := range []*net.Interface{en0, en1} { 134// if err := p.SetMulticastInterface(ifi); err != nil { 135// // error handling 136// } 137// p.SetMulticastTTL(2) 138// if _, err := p.WriteTo(data, nil, dst); err != nil { 139// // error handling 140// } 141// } 142// } 143// 144// 145// More multicasting 146// 147// An application that uses PacketConn or RawConn may join multiple 148// multicast groups. For example, a UDP listener with port 1024 might 149// join two different groups across over two different network 150// interfaces by using: 151// 152// c, err := net.ListenPacket("udp4", "0.0.0.0:1024") 153// if err != nil { 154// // error handling 155// } 156// defer c.Close() 157// p := ipv4.NewPacketConn(c) 158// if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 159// // error handling 160// } 161// if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil { 162// // error handling 163// } 164// if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil { 165// // error handling 166// } 167// 168// It is possible for multiple UDP listeners that listen on the same 169// UDP port to join the same multicast group. The net package will 170// provide a socket that listens to a wildcard address with reusable 171// UDP port when an appropriate multicast address prefix is passed to 172// the net.ListenPacket or net.ListenUDP. 173// 174// c1, err := net.ListenPacket("udp4", "224.0.0.0:1024") 175// if err != nil { 176// // error handling 177// } 178// defer c1.Close() 179// c2, err := net.ListenPacket("udp4", "224.0.0.0:1024") 180// if err != nil { 181// // error handling 182// } 183// defer c2.Close() 184// p1 := ipv4.NewPacketConn(c1) 185// if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 186// // error handling 187// } 188// p2 := ipv4.NewPacketConn(c2) 189// if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 190// // error handling 191// } 192// 193// Also it is possible for the application to leave or rejoin a 194// multicast group on the network interface. 195// 196// if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 197// // error handling 198// } 199// if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 250)}); err != nil { 200// // error handling 201// } 202// 203// 204// Source-specific multicasting 205// 206// An application that uses PacketConn or RawConn on IGMPv3 supported 207// platform is able to join source-specific multicast groups. 208// The application may use JoinSourceSpecificGroup and 209// LeaveSourceSpecificGroup for the operation known as "include" mode, 210// 211// ssmgroup := net.UDPAddr{IP: net.IPv4(232, 7, 8, 9)} 212// ssmsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)} 213// if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 214// // error handling 215// } 216// if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 217// // error handling 218// } 219// 220// or JoinGroup, ExcludeSourceSpecificGroup, 221// IncludeSourceSpecificGroup and LeaveGroup for the operation known 222// as "exclude" mode. 223// 224// exclsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 254)} 225// if err := p.JoinGroup(en0, &ssmgroup); err != nil { 226// // error handling 227// } 228// if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil { 229// // error handling 230// } 231// if err := p.LeaveGroup(en0, &ssmgroup); err != nil { 232// // error handling 233// } 234// 235// Note that it depends on each platform implementation what happens 236// when an application which runs on IGMPv3 unsupported platform uses 237// JoinSourceSpecificGroup and LeaveSourceSpecificGroup. 238// In general the platform tries to fall back to conversations using 239// IGMPv1 or IGMPv2 and starts to listen to multicast traffic. 240// In the fallback case, ExcludeSourceSpecificGroup and 241// IncludeSourceSpecificGroup may return an error. 242package ipv4 // import "golang.org/x/net/ipv4" 243 244// BUG(mikio): This package is not implemented on JS, NaCl and Plan 9. 245