SocketOptionProvider

public protocol SocketOptionProvider

This protocol defines an object, most commonly a Channel, that supports setting and getting socket options (via setsockopt/getsockopt or similar). It provides a strongly typed API that makes working with larger, less-common socket options easier than the ChannelOption API allows.

The API is divided into two portions. For socket options that NIO has prior knowledge about, the API has strongly and safely typed APIs that only allow users to use the exact correct type for the socket option. This will ensure that the API is safe to use, and these are encouraged where possible.

These safe APIs are built on top of an unsafe API that is also exposed to users as part of this protocol. The unsafe API is unsafe in the same way that UnsafePointer is: incorrect use of the API allows all kinds of memory-unsafe behaviour. This API is necessary for socket options that NIO does not have prior knowledge of, but wherever possible users are discouraged from using it.

Relationship to SocketOption

All Channel objects that implement this protocol should also support the SocketOption ChannelOption for simple socket options (those with C int values). These are the most common socket option types, and so this ChannelOption represents a convenient shorthand for using this protocol where the type allows, as well as avoiding the need to cast to this protocol.

Note

Like the Channel protocol, all methods in this protocol are thread-safe.
  • The EventLoop which is used by this SocketOptionProvider for execution.

    Declaration

    Swift

    var eventLoop: EventLoop { get }
  • Set a socket option for a given level and name to the specified value.

    This function is not memory-safe: if you set the generic type parameter incorrectly, this function will still execute, and this can cause you to incorrectly interpret memory and thereby read uninitialized or invalid memory. If at all possible, please use one of the safe functions defined by this protocol.

    Declaration

    Swift

    func unsafeSetSocketOption<Value>(level: SocketOptionLevel, name: SocketOptionName, value: Value) -> EventLoopFuture<Void>

    Parameters

    level

    The socket option level, e.g. SOL_SOCKET or IPPROTO_IP.

    name

    The name of the socket option, e.g. SO_REUSEADDR.

    value

    The value to set the socket option to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • Obtain the value of the socket option for the given level and name.

    This function is not memory-safe: if you set the generic type parameter incorrectly, this function will still execute, and this can cause you to incorrectly interpret memory and thereby read uninitialized or invalid memory. If at all possible, please use one of the safe functions defined by this protocol.

    Declaration

    Swift

    func unsafeGetSocketOption<Value>(level: SocketOptionLevel, name: SocketOptionName) -> EventLoopFuture<Value>

    Parameters

    level

    The socket option level, e.g. SOL_SOCKET or IPPROTO_IP.

    name

    The name of the socket option, e.g. SO_REUSEADDR.

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setSoLinger(_:) Extension method

    Sets the socket option SO_LINGER to value.

    Declaration

    Swift

    func setSoLinger(_ value: linger) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set SO_LINGER to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getSoLinger() Extension method

    Gets the value of the socket option SO_LINGER.

    Declaration

    Swift

    func getSoLinger() -> EventLoopFuture<linger>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPMulticastIF(_:) Extension method

    Sets the socket option IP_MULTICAST_IF to value.

    Declaration

    Swift

    func setIPMulticastIF(_ value: in_addr) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IP_MULTICAST_IF to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPMulticastIF() Extension method

    Gets the value of the socket option IP_MULTICAST_IF.

    Declaration

    Swift

    func getIPMulticastIF() -> EventLoopFuture<in_addr>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPMulticastTTL(_:) Extension method

    Sets the socket option IP_MULTICAST_TTL to value.

    Declaration

    Swift

    func setIPMulticastTTL(_ value: CUnsignedChar) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IP_MULTICAST_TTL to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPMulticastTTL() Extension method

    Gets the value of the socket option IP_MULTICAST_TTL.

    Declaration

    Swift

    func getIPMulticastTTL() -> EventLoopFuture<CUnsignedChar>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPMulticastLoop(_:) Extension method

    Sets the socket option IP_MULTICAST_LOOP to value.

    Declaration

    Swift

    func setIPMulticastLoop(_ value: CUnsignedChar) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IP_MULTICAST_LOOP to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPMulticastLoop() Extension method

    Gets the value of the socket option IP_MULTICAST_LOOP.

    Declaration

    Swift

    func getIPMulticastLoop() -> EventLoopFuture<CUnsignedChar>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPv6MulticastIF(_:) Extension method

    Sets the socket option IPV6_MULTICAST_IF to value.

    Declaration

    Swift

    func setIPv6MulticastIF(_ value: CUnsignedInt) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IPV6_MULTICAST_IF to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPv6MulticastIF() Extension method

    Gets the value of the socket option IPV6_MULTICAST_IF.

    Declaration

    Swift

    func getIPv6MulticastIF() -> EventLoopFuture<CUnsignedInt>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPv6MulticastHops(_:) Extension method

    Sets the socket option IPV6_MULTICAST_HOPS to value.

    Declaration

    Swift

    func setIPv6MulticastHops(_ value: CInt) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IPV6_MULTICAST_HOPS to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPv6MulticastHops() Extension method

    Gets the value of the socket option IPV6_MULTICAST_HOPS.

    Declaration

    Swift

    func getIPv6MulticastHops() -> EventLoopFuture<CInt>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.

  • setIPv6MulticastLoop(_:) Extension method

    Sets the socket option IPV6_MULTICAST_LOOP to value.

    Declaration

    Swift

    func setIPv6MulticastLoop(_ value: CUnsignedInt) -> EventLoopFuture<Void>

    Parameters

    value

    The value to set IPV6_MULTICAST_LOOP to.

    Return Value

    An EventLoopFuture that fires when the option has been set, or if an error has occurred.

  • getIPv6MulticastLoop() Extension method

    Gets the value of the socket option IPV6_MULTICAST_LOOP.

    Declaration

    Swift

    func getIPv6MulticastLoop() -> EventLoopFuture<CUnsignedInt>

    Return Value

    An EventLoopFuture containing the value of the socket option, or any error that occurred while retrieving the socket option.