1 /** 2 Interface to a WebRTC peer connection. 3 4 Copyright: 5 Copyright (c) 2007-2018 Juan Linietsky, Ariel Manzur. 6 Copyright (c) 2014-2018 Godot Engine contributors (cf. AUTHORS.md) 7 Copyright (c) 2017-2018 Godot-D contributors 8 9 License: $(LINK2 https://opensource.org/licenses/MIT, MIT License) 10 11 12 */ 13 module godot.webrtcpeerconnection; 14 import std.meta : AliasSeq, staticIndexOf; 15 import std.traits : Unqual; 16 import godot.d.traits; 17 import godot.core; 18 import godot.c; 19 import godot.d.bind; 20 import godot.d.reference; 21 import godot.globalenums; 22 import godot.object; 23 import godot.classdb; 24 import godot.reference; 25 import godot.webrtcdatachannel; 26 /** 27 Interface to a WebRTC peer connection. 28 29 A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain and monitor the connection. 30 Setting up a WebRTC connection between two peers from now on) may not seem a trivial task, but it can be broken down into 3 main steps: 31 - The peer that wants to initiate the connection (`A` from now on) creates an offer and send it to the other peer (`B` from now on). 32 - `B` receives the offer, generate and answer, and sends it to `A`). 33 - `A` and `B` then generates and exchange ICE candidates with each other. 34 After these steps, the connection should become connected. Keep on reading or look into the tutorial for more information. 35 */ 36 @GodotBaseClass struct WebRTCPeerConnection 37 { 38 package(godot) enum string _GODOT_internal_name = "WebRTCPeerConnection"; 39 public: 40 @nogc nothrow: 41 union { /** */ godot_object _godot_object; /** */ Reference _GODOT_base; } 42 alias _GODOT_base this; 43 alias BaseClasses = AliasSeq!(typeof(_GODOT_base), typeof(_GODOT_base).BaseClasses); 44 package(godot) __gshared bool _classBindingInitialized = false; 45 package(godot) static struct GDNativeClassBinding 46 { 47 __gshared: 48 @GodotName("add_ice_candidate") GodotMethod!(GodotError, String, long, String) addIceCandidate; 49 @GodotName("close") GodotMethod!(void) close; 50 @GodotName("create_data_channel") GodotMethod!(WebRTCDataChannel, String, Dictionary) createDataChannel; 51 @GodotName("create_offer") GodotMethod!(GodotError) createOffer; 52 @GodotName("get_connection_state") GodotMethod!(WebRTCPeerConnection.ConnectionState) getConnectionState; 53 @GodotName("initialize") GodotMethod!(GodotError, Dictionary) initialize; 54 @GodotName("poll") GodotMethod!(GodotError) poll; 55 @GodotName("set_local_description") GodotMethod!(GodotError, String, String) setLocalDescription; 56 @GodotName("set_remote_description") GodotMethod!(GodotError, String, String) setRemoteDescription; 57 } 58 /// 59 pragma(inline, true) bool opEquals(in WebRTCPeerConnection other) const 60 { return _godot_object.ptr is other._godot_object.ptr; } 61 /// 62 pragma(inline, true) typeof(null) opAssign(typeof(null) n) 63 { _godot_object.ptr = n; return null; } 64 /// 65 pragma(inline, true) bool opEquals(typeof(null) n) const 66 { return _godot_object.ptr is n; } 67 /// 68 size_t toHash() const @trusted { return cast(size_t)_godot_object.ptr; } 69 mixin baseCasts; 70 /// Construct a new instance of WebRTCPeerConnection. 71 /// Note: use `memnew!WebRTCPeerConnection` instead. 72 static WebRTCPeerConnection _new() 73 { 74 static godot_class_constructor constructor; 75 if(constructor is null) constructor = _godot_api.godot_get_class_constructor("WebRTCPeerConnection"); 76 if(constructor is null) return typeof(this).init; 77 return cast(WebRTCPeerConnection)(constructor()); 78 } 79 @disable new(size_t s); 80 /// 81 enum ConnectionState : int 82 { 83 /** 84 The connection is new, data channels and an offer can be created in this state. 85 */ 86 stateNew = 0, 87 /** 88 The peer is connecting, ICE is in progress, none of the transports has failed. 89 */ 90 stateConnecting = 1, 91 /** 92 The peer is connected, all ICE transports are connected. 93 */ 94 stateConnected = 2, 95 /** 96 At least one ICE transport is disconnected. 97 */ 98 stateDisconnected = 3, 99 /** 100 One or more of the ICE transports failed. 101 */ 102 stateFailed = 4, 103 /** 104 The peer connection is closed (after calling $(D close) for example). 105 */ 106 stateClosed = 5, 107 } 108 /// 109 enum Constants : int 110 { 111 stateNew = 0, 112 stateConnecting = 1, 113 stateConnected = 2, 114 stateDisconnected = 3, 115 stateFailed = 4, 116 stateClosed = 5, 117 } 118 /** 119 Add an ice candidate generated by a remote peer (and received over the signaling server). See $(D iceCandidateCreated). 120 */ 121 GodotError addIceCandidate(in String media, in long index, in String name) 122 { 123 checkClassBinding!(typeof(this))(); 124 return ptrcall!(GodotError)(GDNativeClassBinding.addIceCandidate, _godot_object, media, index, name); 125 } 126 /** 127 Close the peer connection and all data channels associated with it. Note, you cannot reuse this object for a new connection unless you call $(D initialize). 128 */ 129 void close() 130 { 131 checkClassBinding!(typeof(this))(); 132 ptrcall!(void)(GDNativeClassBinding.close, _godot_object); 133 } 134 /** 135 Returns a new $(D WebRTCDataChannel) (or `null` on failure) with given `label` and optionally configured via the `options` dictionary. This method can only be called when the connection is in state $(D constant STATE_NEW). 136 There are two ways to create a working data channel: either call $(D createDataChannel) on only one of the peer and listen to $(D dataChannelReceived) on the other, or call $(D createDataChannel) on both peers, with the same values, and the `negotiated` option set to `true`. 137 Valid `options` are: 138 139 140 { 141 "negotiated": true, # When set to true (default off), means the channel is negotiated out of band. "id" must be set too. "data_channel_received" will not be called. 142 "id": 1, # When "negotiated" is true this value must also be set to the same value on both peer. 143 144 # Only one of maxRetransmits and maxPacketLifeTime can be specified, not both. They make the channel unreliable (but also better at real time). 145 "maxRetransmits": 1, # Specify the maximum number of attempt the peer will make to retransmits packets if they are not acknowledged. 146 "maxPacketLifeTime": 100, # Specify the maximum amount of time before giving up retransmitions of unacknowledged packets (in milliseconds). 147 "ordered": true, # When in unreliable mode (i.e. either "maxRetransmits" or "maxPacketLifetime" is set), "ordered" (true by default) specify if packet ordering is to be enforced. 148 149 "protocol": "my-custom-protocol", # A custom sub-protocol string for this channel. 150 } 151 152 153 $(B Note:) You must keep a reference to channels created this way, or it will be closed. 154 */ 155 Ref!WebRTCDataChannel createDataChannel(in String label, in Dictionary options = Dictionary.make()) 156 { 157 checkClassBinding!(typeof(this))(); 158 return ptrcall!(WebRTCDataChannel)(GDNativeClassBinding.createDataChannel, _godot_object, label, options); 159 } 160 /** 161 Creates a new SDP offer to start a WebRTC connection with a remote peer. At least one $(D WebRTCDataChannel) must have been created before calling this method. 162 If this functions returns $(D constant OK), $(D sessionDescriptionCreated) will be called when the session is ready to be sent. 163 */ 164 GodotError createOffer() 165 { 166 checkClassBinding!(typeof(this))(); 167 return ptrcall!(GodotError)(GDNativeClassBinding.createOffer, _godot_object); 168 } 169 /** 170 Returns the connection state. See $(D connectionstate). 171 */ 172 WebRTCPeerConnection.ConnectionState getConnectionState() const 173 { 174 checkClassBinding!(typeof(this))(); 175 return ptrcall!(WebRTCPeerConnection.ConnectionState)(GDNativeClassBinding.getConnectionState, _godot_object); 176 } 177 /** 178 Re-initialize this peer connection, closing any previously active connection, and going back to state $(D constant STATE_NEW). A dictionary of `options` can be passed to configure the peer connection. 179 Valid `options` are: 180 181 182 { 183 "iceServers": [ 184 { 185 "urls": $(D "stun:stun.example.com:3478" ), # One or more STUN servers. 186 }, 187 { 188 "urls": $(D "turn:turn.example.com:3478" ), # One or more TURN servers. 189 "username": "a_username", # Optional username for the TURN server. 190 "credential": "a_password", # Optional password for the TURN server. 191 } 192 ] 193 } 194 195 196 */ 197 GodotError initialize(in Dictionary configuration = Dictionary.make()) 198 { 199 checkClassBinding!(typeof(this))(); 200 return ptrcall!(GodotError)(GDNativeClassBinding.initialize, _godot_object, configuration); 201 } 202 /** 203 Call this method frequently (e.g. in $(D Node._process) or $(D Node._physicsProcess)) to properly receive signals. 204 */ 205 GodotError poll() 206 { 207 checkClassBinding!(typeof(this))(); 208 return ptrcall!(GodotError)(GDNativeClassBinding.poll, _godot_object); 209 } 210 /** 211 Sets the SDP description of the local peer. This should be called in response to $(D sessionDescriptionCreated). 212 After calling this function the peer will start emitting $(D iceCandidateCreated) (unless an $(D error) different from $(D constant OK) is returned). 213 */ 214 GodotError setLocalDescription(in String type, in String sdp) 215 { 216 checkClassBinding!(typeof(this))(); 217 return ptrcall!(GodotError)(GDNativeClassBinding.setLocalDescription, _godot_object, type, sdp); 218 } 219 /** 220 Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server. 221 If `type` is `offer` the peer will emit $(D sessionDescriptionCreated) with the appropriate answer. 222 If `type` is `answer` the peer will start emitting $(D iceCandidateCreated). 223 */ 224 GodotError setRemoteDescription(in String type, in String sdp) 225 { 226 checkClassBinding!(typeof(this))(); 227 return ptrcall!(GodotError)(GDNativeClassBinding.setRemoteDescription, _godot_object, type, sdp); 228 } 229 }