1 /* 2 * Copyright 2015 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #import <Foundation/Foundation.h> 12 13 #import "RTCMacros.h" 14 15 @class RTC_OBJC_TYPE(RTCConfiguration); 16 @class RTC_OBJC_TYPE(RTCDataChannel); 17 @class RTC_OBJC_TYPE(RTCDataChannelConfiguration); 18 @class RTC_OBJC_TYPE(RTCIceCandidate); 19 @class RTC_OBJC_TYPE(RTCIceCandidateErrorEvent); 20 @class RTC_OBJC_TYPE(RTCMediaConstraints); 21 @class RTC_OBJC_TYPE(RTCMediaStream); 22 @class RTC_OBJC_TYPE(RTCMediaStreamTrack); 23 @class RTC_OBJC_TYPE(RTCPeerConnectionFactory); 24 @class RTC_OBJC_TYPE(RTCRtpReceiver); 25 @class RTC_OBJC_TYPE(RTCRtpSender); 26 @class RTC_OBJC_TYPE(RTCRtpTransceiver); 27 @class RTC_OBJC_TYPE(RTCRtpTransceiverInit); 28 @class RTC_OBJC_TYPE(RTCSessionDescription); 29 @class RTC_OBJC_TYPE(RTCStatisticsReport); 30 @class RTC_OBJC_TYPE(RTCLegacyStatsReport); 31 32 typedef NS_ENUM(NSInteger, RTCRtpMediaType); 33 34 NS_ASSUME_NONNULL_BEGIN 35 36 extern NSString *const kRTCPeerConnectionErrorDomain; 37 extern int const kRTCSessionDescriptionErrorCode; 38 39 /** Represents the signaling state of the peer connection. */ 40 typedef NS_ENUM(NSInteger, RTCSignalingState) { 41 RTCSignalingStateStable, 42 RTCSignalingStateHaveLocalOffer, 43 RTCSignalingStateHaveLocalPrAnswer, 44 RTCSignalingStateHaveRemoteOffer, 45 RTCSignalingStateHaveRemotePrAnswer, 46 // Not an actual state, represents the total number of states. 47 RTCSignalingStateClosed, 48 }; 49 50 /** Represents the ice connection state of the peer connection. */ 51 typedef NS_ENUM(NSInteger, RTCIceConnectionState) { 52 RTCIceConnectionStateNew, 53 RTCIceConnectionStateChecking, 54 RTCIceConnectionStateConnected, 55 RTCIceConnectionStateCompleted, 56 RTCIceConnectionStateFailed, 57 RTCIceConnectionStateDisconnected, 58 RTCIceConnectionStateClosed, 59 RTCIceConnectionStateCount, 60 }; 61 62 /** Represents the combined ice+dtls connection state of the peer connection. */ 63 typedef NS_ENUM(NSInteger, RTCPeerConnectionState) { 64 RTCPeerConnectionStateNew, 65 RTCPeerConnectionStateConnecting, 66 RTCPeerConnectionStateConnected, 67 RTCPeerConnectionStateDisconnected, 68 RTCPeerConnectionStateFailed, 69 RTCPeerConnectionStateClosed, 70 }; 71 72 /** Represents the ice gathering state of the peer connection. */ 73 typedef NS_ENUM(NSInteger, RTCIceGatheringState) { 74 RTCIceGatheringStateNew, 75 RTCIceGatheringStateGathering, 76 RTCIceGatheringStateComplete, 77 }; 78 79 /** Represents the stats output level. */ 80 typedef NS_ENUM(NSInteger, RTCStatsOutputLevel) { 81 RTCStatsOutputLevelStandard, 82 RTCStatsOutputLevelDebug, 83 }; 84 85 typedef void (^RTCCreateSessionDescriptionCompletionHandler)(RTC_OBJC_TYPE(RTCSessionDescription) * 86 _Nullable sdp, 87 NSError *_Nullable error); 88 89 typedef void (^RTCSetSessionDescriptionCompletionHandler)(NSError *_Nullable error); 90 91 @class RTC_OBJC_TYPE(RTCPeerConnection); 92 93 RTC_OBJC_EXPORT 94 @protocol RTC_OBJC_TYPE 95 (RTCPeerConnectionDelegate)<NSObject> 96 97 /** Called when the SignalingState changed. */ 98 - (void)peerConnection 99 : (RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection didChangeSignalingState 100 : (RTCSignalingState)stateChanged; 101 102 /** Called when media is received on a new stream from remote peer. */ 103 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 104 didAddStream:(RTC_OBJC_TYPE(RTCMediaStream) *)stream; 105 106 /** Called when a remote peer closes a stream. 107 * This is not called when RTCSdpSemanticsUnifiedPlan is specified. 108 */ 109 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 110 didRemoveStream:(RTC_OBJC_TYPE(RTCMediaStream) *)stream; 111 112 /** Called when negotiation is needed, for example ICE has restarted. */ 113 - (void)peerConnectionShouldNegotiate:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection; 114 115 /** Called any time the IceConnectionState changes. */ 116 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 117 didChangeIceConnectionState:(RTCIceConnectionState)newState; 118 119 /** Called any time the IceGatheringState changes. */ 120 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 121 didChangeIceGatheringState:(RTCIceGatheringState)newState; 122 123 /** New ice candidate has been found. */ 124 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 125 didGenerateIceCandidate:(RTC_OBJC_TYPE(RTCIceCandidate) *)candidate; 126 127 /** Called when a group of local Ice candidates have been removed. */ 128 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 129 didRemoveIceCandidates:(NSArray<RTC_OBJC_TYPE(RTCIceCandidate) *> *)candidates; 130 131 /** New data channel has been opened. */ 132 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 133 didOpenDataChannel:(RTC_OBJC_TYPE(RTCDataChannel) *)dataChannel; 134 135 /** Called when signaling indicates a transceiver will be receiving media from 136 * the remote endpoint. 137 * This is only called with RTCSdpSemanticsUnifiedPlan specified. 138 */ 139 @optional 140 /** Called any time the IceConnectionState changes following standardized 141 * transition. */ 142 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 143 didChangeStandardizedIceConnectionState:(RTCIceConnectionState)newState; 144 145 /** Called any time the PeerConnectionState changes. */ 146 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 147 didChangeConnectionState:(RTCPeerConnectionState)newState; 148 149 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 150 didStartReceivingOnTransceiver:(RTC_OBJC_TYPE(RTCRtpTransceiver) *)transceiver; 151 152 /** Called when a receiver and its track are created. */ 153 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 154 didAddReceiver:(RTC_OBJC_TYPE(RTCRtpReceiver) *)rtpReceiver 155 streams:(NSArray<RTC_OBJC_TYPE(RTCMediaStream) *> *)mediaStreams; 156 157 /** Called when the receiver and its track are removed. */ 158 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 159 didRemoveReceiver:(RTC_OBJC_TYPE(RTCRtpReceiver) *)rtpReceiver; 160 161 /** Called when the selected ICE candidate pair is changed. */ 162 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 163 didChangeLocalCandidate:(RTC_OBJC_TYPE(RTCIceCandidate) *)local 164 remoteCandidate:(RTC_OBJC_TYPE(RTCIceCandidate) *)remote 165 lastReceivedMs:(int)lastDataReceivedMs 166 changeReason:(NSString *)reason; 167 168 /** Called when gathering of an ICE candidate failed. */ 169 - (void)peerConnection:(RTC_OBJC_TYPE(RTCPeerConnection) *)peerConnection 170 didFailToGatherIceCandidate:(RTC_OBJC_TYPE(RTCIceCandidateErrorEvent) *)event; 171 172 @end 173 174 RTC_OBJC_EXPORT 175 @interface RTC_OBJC_TYPE (RTCPeerConnection) : NSObject 176 177 /** The object that will be notifed about events such as state changes and 178 * streams being added or removed. 179 */ 180 @property(nonatomic, weak, nullable) id<RTC_OBJC_TYPE(RTCPeerConnectionDelegate)> delegate; 181 /** This property is not available with RTCSdpSemanticsUnifiedPlan. Please use 182 * `senders` instead. 183 */ 184 @property(nonatomic, readonly) NSArray<RTC_OBJC_TYPE(RTCMediaStream) *> *localStreams; 185 @property(nonatomic, readonly, nullable) RTC_OBJC_TYPE(RTCSessionDescription) * localDescription; 186 @property(nonatomic, readonly, nullable) RTC_OBJC_TYPE(RTCSessionDescription) * remoteDescription; 187 @property(nonatomic, readonly) RTCSignalingState signalingState; 188 @property(nonatomic, readonly) RTCIceConnectionState iceConnectionState; 189 @property(nonatomic, readonly) RTCPeerConnectionState connectionState; 190 @property(nonatomic, readonly) RTCIceGatheringState iceGatheringState; 191 @property(nonatomic, readonly, copy) RTC_OBJC_TYPE(RTCConfiguration) * configuration; 192 193 /** Gets all RTCRtpSenders associated with this peer connection. 194 * Note: reading this property returns different instances of RTCRtpSender. 195 * Use isEqual: instead of == to compare RTCRtpSender instances. 196 */ 197 @property(nonatomic, readonly) NSArray<RTC_OBJC_TYPE(RTCRtpSender) *> *senders; 198 199 /** Gets all RTCRtpReceivers associated with this peer connection. 200 * Note: reading this property returns different instances of RTCRtpReceiver. 201 * Use isEqual: instead of == to compare RTCRtpReceiver instances. 202 */ 203 @property(nonatomic, readonly) NSArray<RTC_OBJC_TYPE(RTCRtpReceiver) *> *receivers; 204 205 /** Gets all RTCRtpTransceivers associated with this peer connection. 206 * Note: reading this property returns different instances of 207 * RTCRtpTransceiver. Use isEqual: instead of == to compare 208 * RTCRtpTransceiver instances. This is only available with 209 * RTCSdpSemanticsUnifiedPlan specified. 210 */ 211 @property(nonatomic, readonly) NSArray<RTC_OBJC_TYPE(RTCRtpTransceiver) *> *transceivers; 212 213 - (instancetype)init NS_UNAVAILABLE; 214 215 /** Sets the PeerConnection's global configuration to `configuration`. 216 * Any changes to STUN/TURN servers or ICE candidate policy will affect the 217 * next gathering phase, and cause the next call to createOffer to generate 218 * new ICE credentials. Note that the BUNDLE and RTCP-multiplexing policies 219 * cannot be changed with this method. 220 */ 221 - (BOOL)setConfiguration:(RTC_OBJC_TYPE(RTCConfiguration) *)configuration; 222 223 /** Terminate all media and close the transport. */ 224 - (void)close; 225 226 /** Provide a remote candidate to the ICE Agent. */ 227 - (void)addIceCandidate:(RTC_OBJC_TYPE(RTCIceCandidate) *)candidate 228 DEPRECATED_MSG_ATTRIBUTE("Please use addIceCandidate:completionHandler: instead"); 229 230 /** Provide a remote candidate to the ICE Agent. */ 231 - (void)addIceCandidate:(RTC_OBJC_TYPE(RTCIceCandidate) *)candidate 232 completionHandler:(void (^)(NSError *_Nullable error))completionHandler; 233 234 /** Remove a group of remote candidates from the ICE Agent. */ 235 - (void)removeIceCandidates:(NSArray<RTC_OBJC_TYPE(RTCIceCandidate) *> *)candidates; 236 237 /** Add a new media stream to be sent on this peer connection. 238 * This method is not supported with RTCSdpSemanticsUnifiedPlan. Please use 239 * addTrack instead. 240 */ 241 - (void)addStream:(RTC_OBJC_TYPE(RTCMediaStream) *)stream; 242 243 /** Remove the given media stream from this peer connection. 244 * This method is not supported with RTCSdpSemanticsUnifiedPlan. Please use 245 * removeTrack instead. 246 */ 247 - (void)removeStream:(RTC_OBJC_TYPE(RTCMediaStream) *)stream; 248 249 /** Add a new media stream track to be sent on this peer connection, and return 250 * the newly created RTCRtpSender. The RTCRtpSender will be 251 * associated with the streams specified in the `streamIds` list. 252 * 253 * Errors: If an error occurs, returns nil. An error can occur if: 254 * - A sender already exists for the track. 255 * - The peer connection is closed. 256 */ 257 - (nullable RTC_OBJC_TYPE(RTCRtpSender) *)addTrack:(RTC_OBJC_TYPE(RTCMediaStreamTrack) *)track 258 streamIds:(NSArray<NSString *> *)streamIds; 259 260 /** With PlanB semantics, removes an RTCRtpSender from this peer connection. 261 * 262 * With UnifiedPlan semantics, sets sender's track to null and removes the 263 * send component from the associated RTCRtpTransceiver's direction. 264 * 265 * Returns YES on success. 266 */ 267 - (BOOL)removeTrack:(RTC_OBJC_TYPE(RTCRtpSender) *)sender; 268 269 /** addTransceiver creates a new RTCRtpTransceiver and adds it to the set of 270 * transceivers. Adding a transceiver will cause future calls to CreateOffer 271 * to add a media description for the corresponding transceiver. 272 * 273 * The initial value of `mid` in the returned transceiver is nil. Setting a 274 * new session description may change it to a non-nil value. 275 * 276 * https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver 277 * 278 * Optionally, an RtpTransceiverInit structure can be specified to configure 279 * the transceiver from construction. If not specified, the transceiver will 280 * default to having a direction of kSendRecv and not be part of any streams. 281 * 282 * These methods are only available when Unified Plan is enabled (see 283 * RTCConfiguration). 284 */ 285 286 /** Adds a transceiver with a sender set to transmit the given track. The kind 287 * of the transceiver (and sender/receiver) will be derived from the kind of 288 * the track. 289 */ 290 - (nullable RTC_OBJC_TYPE(RTCRtpTransceiver) *)addTransceiverWithTrack: 291 (RTC_OBJC_TYPE(RTCMediaStreamTrack) *)track; 292 - (nullable RTC_OBJC_TYPE(RTCRtpTransceiver) *) 293 addTransceiverWithTrack:(RTC_OBJC_TYPE(RTCMediaStreamTrack) *)track 294 init:(RTC_OBJC_TYPE(RTCRtpTransceiverInit) *)init; 295 296 /** Adds a transceiver with the given kind. Can either be RTCRtpMediaTypeAudio 297 * or RTCRtpMediaTypeVideo. 298 */ 299 - (nullable RTC_OBJC_TYPE(RTCRtpTransceiver) *)addTransceiverOfType:(RTCRtpMediaType)mediaType; 300 - (nullable RTC_OBJC_TYPE(RTCRtpTransceiver) *) 301 addTransceiverOfType:(RTCRtpMediaType)mediaType 302 init:(RTC_OBJC_TYPE(RTCRtpTransceiverInit) *)init; 303 304 /** Tells the PeerConnection that ICE should be restarted. This triggers a need 305 * for negotiation and subsequent offerForConstraints:completionHandler call will act as if 306 * RTCOfferAnswerOptions::ice_restart is true. 307 */ 308 - (void)restartIce; 309 310 /** Generate an SDP offer. */ 311 - (void)offerForConstraints:(RTC_OBJC_TYPE(RTCMediaConstraints) *)constraints 312 completionHandler:(RTCCreateSessionDescriptionCompletionHandler)completionHandler; 313 314 /** Generate an SDP answer. */ 315 - (void)answerForConstraints:(RTC_OBJC_TYPE(RTCMediaConstraints) *)constraints 316 completionHandler:(RTCCreateSessionDescriptionCompletionHandler)completionHandler; 317 318 /** Apply the supplied RTCSessionDescription as the local description. */ 319 - (void)setLocalDescription:(RTC_OBJC_TYPE(RTCSessionDescription) *)sdp 320 completionHandler:(RTCSetSessionDescriptionCompletionHandler)completionHandler; 321 322 /** Creates an offer or answer (depending on current signaling state) and sets 323 * it as the local session description. */ 324 - (void)setLocalDescriptionWithCompletionHandler: 325 (RTCSetSessionDescriptionCompletionHandler)completionHandler; 326 327 /** Apply the supplied RTCSessionDescription as the remote description. */ 328 - (void)setRemoteDescription:(RTC_OBJC_TYPE(RTCSessionDescription) *)sdp 329 completionHandler:(RTCSetSessionDescriptionCompletionHandler)completionHandler; 330 331 /** Limits the bandwidth allocated for all RTP streams sent by this 332 * PeerConnection. Nil parameters will be unchanged. Setting 333 * `currentBitrateBps` will force the available bitrate estimate to the given 334 * value. Returns YES if the parameters were successfully updated. 335 */ 336 - (BOOL)setBweMinBitrateBps:(nullable NSNumber *)minBitrateBps 337 currentBitrateBps:(nullable NSNumber *)currentBitrateBps 338 maxBitrateBps:(nullable NSNumber *)maxBitrateBps; 339 340 /** Start or stop recording an Rtc EventLog. */ 341 - (BOOL)startRtcEventLogWithFilePath:(NSString *)filePath maxSizeInBytes:(int64_t)maxSizeInBytes; 342 - (void)stopRtcEventLog; 343 344 @end 345 346 @interface RTC_OBJC_TYPE (RTCPeerConnection) 347 (Media) 348 349 /** Create an RTCRtpSender with the specified kind and media stream ID. 350 * See RTCMediaStreamTrack.h for available kinds. 351 * This method is not supported with RTCSdpSemanticsUnifiedPlan. Please use 352 * addTransceiver instead. 353 */ 354 - (RTC_OBJC_TYPE(RTCRtpSender) *)senderWithKind : (NSString *)kind streamId 355 : (NSString *)streamId; 356 357 @end 358 359 @interface RTC_OBJC_TYPE (RTCPeerConnection) 360 (DataChannel) 361 362 /** Create a new data channel with the given label and configuration. */ 363 - (nullable RTC_OBJC_TYPE(RTCDataChannel) *)dataChannelForLabel 364 : (NSString *)label configuration : (RTC_OBJC_TYPE(RTCDataChannelConfiguration) *)configuration; 365 366 @end 367 368 typedef void (^RTCStatisticsCompletionHandler)(RTC_OBJC_TYPE(RTCStatisticsReport) *); 369 370 @interface RTC_OBJC_TYPE (RTCPeerConnection) 371 (Stats) 372 373 /** Gather stats for the given RTCMediaStreamTrack. If `mediaStreamTrack` is nil 374 * statistics are gathered for all tracks. 375 */ 376 - (void)statsForTrack 377 : (nullable RTC_OBJC_TYPE(RTCMediaStreamTrack) *)mediaStreamTrack statsOutputLevel 378 : (RTCStatsOutputLevel)statsOutputLevel completionHandler 379 : (nullable void (^)(NSArray<RTC_OBJC_TYPE(RTCLegacyStatsReport) *> *stats))completionHandler; 380 381 /** Gather statistic through the v2 statistics API. */ 382 - (void)statisticsWithCompletionHandler:(RTCStatisticsCompletionHandler)completionHandler; 383 384 /** Spec-compliant getStats() performing the stats selection algorithm with the 385 * sender. 386 */ 387 - (void)statisticsForSender:(RTC_OBJC_TYPE(RTCRtpSender) *)sender 388 completionHandler:(RTCStatisticsCompletionHandler)completionHandler; 389 390 /** Spec-compliant getStats() performing the stats selection algorithm with the 391 * receiver. 392 */ 393 - (void)statisticsForReceiver:(RTC_OBJC_TYPE(RTCRtpReceiver) *)receiver 394 completionHandler:(RTCStatisticsCompletionHandler)completionHandler; 395 396 @end 397 398 NS_ASSUME_NONNULL_END 399