// SPDX-FileCopyrightText: 2023 The Pion community <https://pion.ly>// SPDX-License-Identifier: MIT//go:build !js// +build !jspackage webrtcimport (dtlsElliptic)// SettingEngine allows influencing behavior in ways that are not// supported by the WebRTC API. This allows us to support additional// use-cases without deviating from the WebRTC API elsewhere.typeSettingEnginestruct { ephemeralUDP struct { PortMin uint16 PortMax uint16 } detach struct { DataChannels bool } timeout struct { ICEDisconnectedTimeout *time.Duration ICEFailedTimeout *time.Duration ICEKeepaliveInterval *time.Duration ICEHostAcceptanceMinWait *time.Duration ICESrflxAcceptanceMinWait *time.Duration ICEPrflxAcceptanceMinWait *time.Duration ICERelayAcceptanceMinWait *time.Duration ICESTUNGatherTimeout *time.Duration } candidates struct { ICELite bool ICENetworkTypes []NetworkType InterfaceFilter func(string) (keep bool) IPFilter func(net.IP) (keep bool) NAT1To1IPs []string NAT1To1IPCandidateType ICECandidateType MulticastDNSMode ice.MulticastDNSMode MulticastDNSHostName string UsernameFragment string Password string IncludeLoopbackCandidate bool } replayProtection struct { DTLS *uint SRTP *uint SRTCP *uint } dtls struct { insecureSkipHelloVerify bool disableInsecureSkipVerify bool retransmissionInterval time.Duration ellipticCurves []dtlsElliptic.Curve connectContextMaker func() (context.Context, func()) extendedMasterSecret dtls.ExtendedMasterSecretType clientAuth *dtls.ClientAuthType clientCAs *x509.CertPool rootCAs *x509.CertPool keyLogWriter io.Writer customCipherSuites func() []dtls.CipherSuite clientHelloMessageHook func(handshake.MessageClientHello) handshake.Message serverHelloMessageHook func(handshake.MessageServerHello) handshake.Message certificateRequestMessageHook func(handshake.MessageCertificateRequest) handshake.Message } sctp struct { maxReceiveBufferSize uint32 enableZeroChecksum bool rtoMax time.Duration maxMessageSize uint32 minCwnd uint32 fastRtxWnd uint32 cwndCAStep uint32 } sdpMediaLevelFingerprints bool answeringDTLSRole DTLSRole disableCertificateFingerprintVerification bool disableSRTPReplayProtection bool disableSRTCPReplayProtection bool net transport.Net BufferFactory func(packetType packetio.BufferPacketType, ssrc uint32) io.ReadWriteCloser LoggerFactory logging.LoggerFactory iceTCPMux ice.TCPMux iceUDPMux ice.UDPMux iceProxyDialer proxy.Dialer iceDisableActiveTCP bool iceBindingRequestHandler func(m *stun.Message, local, remote ice.Candidate, pair *ice.CandidatePair) bool//nolint:lll disableMediaEngineCopy bool disableMediaEngineMultipleCodecs bool srtpProtectionProfiles []dtls.SRTPProtectionProfile receiveMTU uint iceMaxBindingRequests *uint16 fireOnTrackBeforeFirstRTP bool disableCloseByDTLS bool dataChannelBlockWrite bool}func ( *SettingEngine) () uint32 {if .sctp.maxMessageSize != 0 {return .sctp.maxMessageSize }returndefaultMaxSCTPMessageSize}// getReceiveMTU returns the configured MTU. If SettingEngine's MTU is configured to 0 it returns the default.func ( *SettingEngine) () uint {if .receiveMTU != 0 {return .receiveMTU }returnreceiveMTU}// DetachDataChannels enables detaching data channels. When enabled// data channels have to be detached in the OnOpen callback using the// DataChannel.Detach method.func ( *SettingEngine) () { .detach.DataChannels = true}// EnableDataChannelBlockWrite allows data channels to block on write,// it only works if DetachDataChannels is enabled.func ( *SettingEngine) ( bool) { .dataChannelBlockWrite = }// SetSRTPProtectionProfiles allows the user to override the default SRTP Protection Profiles// The default srtp protection profiles are provided by the function `defaultSrtpProtectionProfiles`.func ( *SettingEngine) ( ...dtls.SRTPProtectionProfile) { .srtpProtectionProfiles = }// SetICETimeouts sets the behavior around ICE Timeouts//// disconnectedTimeout://// Duration without network activity before an Agent is considered disconnected. Default is 5 Seconds//// failedTimeout://// Duration without network activity before an Agent is considered failed after disconnected. Default is 25 Seconds//// keepAliveInterval://// How often the ICE Agent sends extra traffic if there is no activity, if media is flowing no traffic will be sent.//// Default is 2 seconds.func ( *SettingEngine) (, , time.Duration) { .timeout.ICEDisconnectedTimeout = & .timeout.ICEFailedTimeout = & .timeout.ICEKeepaliveInterval = &}// SetHostAcceptanceMinWait sets the ICEHostAcceptanceMinWait.func ( *SettingEngine) ( time.Duration) { .timeout.ICEHostAcceptanceMinWait = &}// SetSrflxAcceptanceMinWait sets the ICESrflxAcceptanceMinWait.func ( *SettingEngine) ( time.Duration) { .timeout.ICESrflxAcceptanceMinWait = &}// SetPrflxAcceptanceMinWait sets the ICEPrflxAcceptanceMinWait.func ( *SettingEngine) ( time.Duration) { .timeout.ICEPrflxAcceptanceMinWait = &}// SetRelayAcceptanceMinWait sets the ICERelayAcceptanceMinWait.func ( *SettingEngine) ( time.Duration) { .timeout.ICERelayAcceptanceMinWait = &}// SetSTUNGatherTimeout sets the ICESTUNGatherTimeout.func ( *SettingEngine) ( time.Duration) { .timeout.ICESTUNGatherTimeout = &}// SetEphemeralUDPPortRange limits the pool of ephemeral ports that// ICE UDP connections can allocate from. This affects both host candidates,// and the local address of server reflexive candidates.//// When portMin and portMax are left to the 0 default value, pion/ice candidate// gatherer replaces them and uses 1 for portMin and 65535 for portMax.func ( *SettingEngine) (, uint16) error {if < {returnice.ErrPort } .ephemeralUDP.PortMin = .ephemeralUDP.PortMax = returnnil}// SetLite configures whether or not the ice agent should be a lite agent.func ( *SettingEngine) ( bool) { .candidates.ICELite = }// SetNetworkTypes configures what types of candidate networks are supported// during local and server reflexive gathering.func ( *SettingEngine) ( []NetworkType) { .candidates.ICENetworkTypes = }// SetInterfaceFilter sets the filtering functions when gathering ICE candidates// This can be used to exclude certain network interfaces from ICE. Which may be// useful if you know a certain interface will never succeed, or if you wish to reduce// the amount of information you wish to expose to the remote peer.func ( *SettingEngine) ( func(string) ( bool)) { .candidates.InterfaceFilter = }// SetIPFilter sets the filtering functions when gathering ICE candidates// This can be used to exclude certain ip from ICE. Which may be// useful if you know a certain ip will never succeed, or if you wish to reduce// the amount of information you wish to expose to the remote peer.func ( *SettingEngine) ( func(net.IP) ( bool)) { .candidates.IPFilter = }// SetNAT1To1IPs sets a list of external IP addresses of 1:1 (D)NAT// and a candidate type for which the external IP address is used.// This is useful when you host a server using Pion on an AWS EC2 instance// which has a private address, behind a 1:1 DNAT with a public IP (e.g.// Elastic IP). In this case, you can give the public IP address so that// Pion will use the public IP address in its candidate instead of the private// IP address. The second argument, candidateType, is used to tell Pion which// type of candidate should use the given public IP address.// Two types of candidates are supported://// ICECandidateTypeHost://// The public IP address will be used for the host candidate in the SDP.//// ICECandidateTypeSrflx://// A server reflexive candidate with the given public IP address will be added to the SDP.//// Please note that if you choose ICECandidateTypeHost, then the private IP address// won't be advertised with the peer. Also, this option cannot be used along with mDNS.//// If you choose ICECandidateTypeSrflx, it simply adds a server reflexive candidate// with the public IP. The host candidate is still available along with mDNS// capabilities unaffected. Also, you cannot give STUN server URL at the same time.// It will result in an error otherwise.func ( *SettingEngine) ( []string, ICECandidateType) { .candidates.NAT1To1IPs = .candidates.NAT1To1IPCandidateType = }// SetIncludeLoopbackCandidate enable pion to gather loopback candidates, it is useful// for some VM have public IP mapped to loopback interface.func ( *SettingEngine) ( bool) { .candidates.IncludeLoopbackCandidate = }// SetAnsweringDTLSRole sets the DTLS role that is selected when offering// The DTLS role controls if the WebRTC Client as a client or server. This// may be useful when interacting with non-compliant clients or debugging issues.//// DTLSRoleActive://// Act as DTLS Client, send the ClientHello and starts the handshake//// DTLSRolePassive://// Act as DTLS Server, wait for ClientHellofunc ( *SettingEngine) ( DTLSRole) error {if != DTLSRoleClient && != DTLSRoleServer {returnerrSettingEngineSetAnsweringDTLSRole } .answeringDTLSRole = returnnil}// SetNet sets the Net instance that is passed to pion/ice//// Net is an network interface layer for Pion, allowing users to replace// Pions network stack with a custom implementation.func ( *SettingEngine) ( transport.Net) { .net = }// SetICEMulticastDNSMode controls if pion/ice queries and generates mDNS ICE Candidates.func ( *SettingEngine) ( ice.MulticastDNSMode) { .candidates.MulticastDNSMode = }// SetMulticastDNSHostName sets a static HostName to be used by pion/ice instead of generating one on startup//// This should only be used for a single PeerConnection.// Having multiple PeerConnections with the same HostName will cause undefined behavior.func ( *SettingEngine) ( string) { .candidates.MulticastDNSHostName = }// SetICECredentials sets a staic uFrag/uPwd to be used by pion/ice//// This is useful if you want to do signalless WebRTC session,// or having a reproducible environment with static credentials.func ( *SettingEngine) (, string) { .candidates.UsernameFragment = .candidates.Password = }// DisableCertificateFingerprintVerification disables fingerprint verification after DTLS Handshake has finished.func ( *SettingEngine) ( bool) { .disableCertificateFingerprintVerification = }// SetDTLSReplayProtectionWindow sets a replay attack protection window size of DTLS connection.func ( *SettingEngine) ( uint) { .replayProtection.DTLS = &}// SetSRTPReplayProtectionWindow sets a replay attack protection window size of SRTP session.func ( *SettingEngine) ( uint) { .disableSRTPReplayProtection = false .replayProtection.SRTP = &}// SetSRTCPReplayProtectionWindow sets a replay attack protection window size of SRTCP session.func ( *SettingEngine) ( uint) { .disableSRTCPReplayProtection = false .replayProtection.SRTCP = &}// DisableSRTPReplayProtection disables SRTP replay protection.func ( *SettingEngine) ( bool) { .disableSRTPReplayProtection = }// DisableSRTCPReplayProtection disables SRTCP replay protection.func ( *SettingEngine) ( bool) { .disableSRTCPReplayProtection = }// SetSDPMediaLevelFingerprints configures the logic for DTLS Fingerprint insertion// If true, fingerprints will be inserted in the sdp at the fingerprint// level, instead of the session level. This helps with compatibility with// some webrtc implementations.func ( *SettingEngine) ( bool) { .sdpMediaLevelFingerprints = }// SetICETCPMux enables ICE-TCP when set to a non-nil value. Make sure that// NetworkTypeTCP4 or NetworkTypeTCP6 is enabled as well.func ( *SettingEngine) ( ice.TCPMux) { .iceTCPMux = }// SetICEUDPMux allows ICE traffic to come through a single UDP port, drastically// simplifying deployments where ports will need to be opened/forwarded.// UDPMux should be started prior to creating PeerConnections.func ( *SettingEngine) ( ice.UDPMux) { .iceUDPMux = }// SetICEProxyDialer sets the proxy dialer interface based on golang.org/x/net/proxy.func ( *SettingEngine) ( proxy.Dialer) { .iceProxyDialer = }// SetICEMaxBindingRequests sets the maximum amount of binding requests// that can be sent on a candidate before it is considered invalid.func ( *SettingEngine) ( uint16) { .iceMaxBindingRequests = &}// DisableActiveTCP disables using active TCP for ICE. Active TCP is enabled by default.func ( *SettingEngine) ( bool) { .iceDisableActiveTCP = }// DisableMediaEngineCopy stops the MediaEngine from being copied. This allows a user to modify// the MediaEngine after the PeerConnection has been constructed. This is useful if you wish to// modify codecs after signaling. Make sure not to share MediaEngines between PeerConnections.func ( *SettingEngine) ( bool) { .disableMediaEngineCopy = }// DisableMediaEngineMultipleCodecs disables the MediaEngine negotiating different codecs.// With the default value multiple media sections in the SDP can each negotiate different// codecs. This is the new default behvior, because it makes Pion more spec compliant.// The value of this setting will get copied to every copy of the MediaEngine generated// for new PeerConnections (assuming DisableMediaEngineCopy is set to false).// Note: this setting is targeted to be removed in release 4.2.0 (or later).func ( *SettingEngine) ( bool) { .disableMediaEngineMultipleCodecs = }// SetReceiveMTU sets the size of read buffer that copies incoming packets. This is optional.// Leave this 0 for the default receiveMTU.func ( *SettingEngine) ( uint) { .receiveMTU = }// SetDTLSRetransmissionInterval sets the retranmission interval for DTLS.func ( *SettingEngine) ( time.Duration) { .dtls.retransmissionInterval = }// SetDTLSInsecureSkipHelloVerify sets the skip HelloVerify flag for DTLS.// If true and when acting as DTLS server, will allow client to skip hello verify phase and// receive ServerHello after initial ClientHello. This will mean faster connect times,// but will have lower DoS attack resistance.func ( *SettingEngine) ( bool) { .dtls.insecureSkipHelloVerify = }// SetDTLSDisableInsecureSkipVerify sets the disable skip insecure verify flag for DTLS.// This controls whether a client verifies the server's certificate chain and host name.func ( *SettingEngine) ( bool) { .dtls.disableInsecureSkipVerify = }// SetDTLSEllipticCurves sets the elliptic curves for DTLS.func ( *SettingEngine) ( ...dtlsElliptic.Curve) { .dtls.ellipticCurves = }// SetDTLSConnectContextMaker sets the context used during the DTLS Handshake.// It can be used to extend or reduce the timeout on the DTLS Handshake.// If nil, the default dtls.ConnectContextMaker is used. It can be implemented as following.//// func ConnectContextMaker() (context.Context, func()) {// return context.WithTimeout(context.Background(), 30*time.Second)// }func ( *SettingEngine) ( func() (context.Context, func())) { .dtls.connectContextMaker = }// SetDTLSExtendedMasterSecret sets the extended master secret type for DTLS.func ( *SettingEngine) ( dtls.ExtendedMasterSecretType) { .dtls.extendedMasterSecret = }// SetDTLSClientAuth sets the client auth type for DTLS.func ( *SettingEngine) ( dtls.ClientAuthType) { .dtls.clientAuth = &}// SetDTLSClientCAs sets the client CA certificate pool for DTLS certificate verification.func ( *SettingEngine) ( *x509.CertPool) { .dtls.clientCAs = }// SetDTLSRootCAs sets the root CA certificate pool for DTLS certificate verification.func ( *SettingEngine) ( *x509.CertPool) { .dtls.rootCAs = }// SetDTLSKeyLogWriter sets the destination of the TLS key material for debugging.// Logging key material compromises security and should only be use for debugging.func ( *SettingEngine) ( io.Writer) { .dtls.keyLogWriter = }// SetSCTPMaxReceiveBufferSize sets the maximum receive buffer size.// Leave this 0 for the default maxReceiveBufferSize.func ( *SettingEngine) ( uint32) { .sctp.maxReceiveBufferSize = }// EnableSCTPZeroChecksum controls the zero checksum feature in SCTP.// This removes the need to checksum every incoming/outgoing packet and will reduce// latency and CPU usage. This feature is not backwards compatible so is disabled by default.func ( *SettingEngine) ( bool) { .sctp.enableZeroChecksum = }// SetSCTPMaxMessageSize sets the largest message we are willing to accept.// Leave this 0 for the default max message size.func ( *SettingEngine) ( uint32) { .sctp.maxMessageSize = }// SetDTLSCustomerCipherSuites allows the user to specify a list of DTLS CipherSuites.// This allow usage of Ciphers that are reserved for private usage.func ( *SettingEngine) ( func() []dtls.CipherSuite) { .dtls.customCipherSuites = }// SetDTLSClientHelloMessageHook if not nil, is called when a DTLS Client Hello message is sent// from a client. The returned handshake message replaces the original message.func ( *SettingEngine) ( func(handshake.MessageClientHello) handshake.Message) { .dtls.clientHelloMessageHook = }// SetDTLSServerHelloMessageHook if not nil, is called when a DTLS Server Hello message is sent// from a client. The returned handshake message replaces the original message.func ( *SettingEngine) ( func(handshake.MessageServerHello) handshake.Message) { .dtls.serverHelloMessageHook = }// SetDTLSCertificateRequestMessageHook if not nil, is called when a DTLS Certificate Request message is sent// from a client. The returned handshake message replaces the original message.func ( *SettingEngine) (func(handshake.MessageCertificateRequest) handshake.Message,) { .dtls.certificateRequestMessageHook = }// SetSCTPRTOMax sets the maximum retransmission timeout.// Leave this 0 for the default timeout.func ( *SettingEngine) ( time.Duration) { .sctp.rtoMax = }// SetSCTPMinCwnd sets the minimum congestion window size. The congestion window// will not be smaller than this value during congestion control.func ( *SettingEngine) ( uint32) { .sctp.minCwnd = }// SetSCTPFastRtxWnd sets the fast retransmission window size.func ( *SettingEngine) ( uint32) { .sctp.fastRtxWnd = }// SetSCTPCwndCAStep sets congestion window adjustment step size during congestion avoidance.func ( *SettingEngine) ( uint32) { .sctp.cwndCAStep = }// SetICEBindingRequestHandler sets a callback that is fired on a STUN BindingRequest// This allows users to do things like// - Log incoming Binding Requests for debugging// - Implement draft-thatcher-ice-renomination// - Implement custom CandidatePair switching logic.func ( *SettingEngine) (func( *stun.Message, , ice.Candidate, *ice.CandidatePair) bool,) { .iceBindingRequestHandler = }// SetFireOnTrackBeforeFirstRTP sets if firing the OnTrack event should happen// before any RTP packets are received. Setting this to true will// have the Track's Codec and PayloadTypes be initially set to their// zero values in the OnTrack handler.// Note: This does not yet affect simulcast tracks.func ( *SettingEngine) ( bool) { .fireOnTrackBeforeFirstRTP = }// DisableCloseByDTLS sets if the connection should be closed when dtls transport is closed.// Setting this to true will keep the connection open when dtls transport is closed// and relies on the ice failed state to detect the connection is interrupted.func ( *SettingEngine) ( bool) { .disableCloseByDTLS = }
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.