Current proposed API:

/**
 * Obtain a NET_Address usable for broadcasting.
 *
 * **WARNING**: The function exists largely for compatibility with existing
 * software. In software that doesn't have to talk to legacy programs that
 * use broadcasting, you are encouraged to use NET_CreateMulticastAddress()
 * instead.
 *
 * Broadcast packets are (more or less) sent to every machine on the LAN,
 * unconditionally. It can be used to alert everyone of the availability of
 * a service (such as a game server) without a more formal discovery
 * mechanism.
 *
 * Addresses returned from this are usable with NET_CreateDatagramSocket()
 * to listen for broadcasts on the LAN, and can be used with
 * NET_SendDatagram() to send broadcast packets.
 *
 * A successfully-returned address does not need to resolve
 * (NET_WaitUntilResolved() would not block and NET_GetAddressStatus() will
 * always report NET_SUCCESS) and can be used immediately.
 *
 * **WARNING**: It is possible to build a game where everyone is playing on
 * the same LAN, and every player is simply sending packets to the broadcast
 * address. This is absolutely the wrong thing to do, however. Broadcast
 * packets go to every device on the LAN, whether they want them or not. The
 * game DOOM, in its heyday, was capable of [bringing entire networks to their
 * knees](https://doomwiki.org/wiki/Doom_in_workplaces),
 * as many players on the same network would all be broadcasting relentlessly.
 *
 * In practice, broadcasting sparingly can be useful for certain
 * functionality: a LAN-only server reporting that it exists by broadcasting
 * a single packet every few seconds is reasonable and safe. Once clients
 * see the broadcast packet, they can talk to the server directly without
 * broadcasting. For peer-to-peer games, once connection is established, it's
 * better to either send unique packets to each known player, or use a
 * multicast address (which works like broadcast, but only routes packets to
 * devices that are explicitly listening for it).
 *
 * The `interface` parameter is meant to be an interface address to use for
 * broadcast, as different interfaces may be talking to different subnets. You
 * can get a list of valid interfaces for the system from NET_GetLocalAddresses().
 * Passing a NULL for `interface` will select a reasonable default (and/or
 * every available interface together).
 *
 * In IPv4, the broadcast address is either 255.255.255.255 (broadcast to all
 * interfaces on the machine), or XXX.XXX.XXX.255 (broadcast to a specific
 * interface's subnet). In IPv6, this is actually faked with multicast to the
 * all-nodes link-local multicast group, ff02::1, either on a specific
 * interface or letting the OS choose the default. Other protocols might fake
 * broadcast operations in similar ways in the future.
 *
 * \param interface the interface to use for broadcasting. May be NULL.
 * \returns a address that can be used for multicast transmission.
 */
extern SDL_DECLSPEC NET_Address * SDLCALL NET_CreateBroadcastAddress(NET_Address *interface);

/**
 * Obtain a NET_Address usable for multicasting.
 *
 * Multicasting sends packets to every machine on the LAN that is interested
 * in a given service. This works by choosing an address from a magic range
 * that routers know to treat differently, and individual machines reporting
 * interest in that address to the routers so packets are sent to them.
 *
 * It can be used to alert everyone of the availability of a service (such as
 * a game server) in an ad-hoc manner without sending data to every device
 * on the LAN.
 *
 * Addresses returned from this are usable with NET_CreateDatagramSocket()
 * to listen for multicasts on the LAN, and can be used with
 * NET_SendDatagram() to send multicast packets.
 *
 * A successfully-returned address does not need to resolve
 * (NET_WaitUntilResolved() would not block and NET_GetAddressStatus() will
 * always report NET_SUCCESS) and can be used immediately.
 *
 * The `interface` parameter is meant to be an interface address to use for
 * broadcast, as different interfaces may be talking to different subnets. You
 * can get a list of valid interfaces for the system from NET_GetLocalAddresses().
 * Passing a NULL for `interface` will select a reasonable default (and/or
 * every available interface together).
 *
 * Actual multicast addresses are chosen based on the "group" this function
 * requests. This is used to pick the proper multicast address in a protocol
 * independent way. In practice, SDL_Net will mask the group number against
 * the available addresses and use it as an offset from a base address.
 * There are about 28 bits in IPv4 and 112 in IPv6. This function does not make
 * the entire IPv6 range available, and is slightly larger than what IPv4 can
 * offer; a safe group number that works with both is less than 268 million,
 * but this is plenty of space; unrelated things can join the same multicast
 * address and use a different port without collisions.
 *
 * \param group a group number to join, which will decide the actual address.
 * \param interface the interface to use for broadcasting. May be NULL.
 * \returns a address that can be used for multicast transmission.
 */
extern SDL_DECLSPEC NET_Address * SDLCALL NET_CreateMulticastAddress(Uint32 group, NET_Address *interface);

Allow UDP broadcasts #97

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions