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