rtc.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431
  1. /**
  2. * Copyright (c) 2019-2021 Paul-Louis Ageneau
  3. *
  4. * This library is free software; you can redistribute it and/or
  5. * modify it under the terms of the GNU Lesser General Public
  6. * License as published by the Free Software Foundation; either
  7. * version 2.1 of the License, or (at your option) any later version.
  8. *
  9. * This library is distributed in the hope that it will be useful,
  10. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12. * Lesser General Public License for more details.
  13. *
  14. * You should have received a copy of the GNU Lesser General Public
  15. * License along with this library; if not, write to the Free Software
  16. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17. */
  18. #ifndef RTC_C_API
  19. #define RTC_C_API
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23. #ifdef _WIN32
  24. #define RTC_EXPORT __declspec(dllexport)
  25. #ifdef CAPI_STDCALL
  26. #define RTC_API __stdcall
  27. #else
  28. #define RTC_API
  29. #endif
  30. #else // not WIN32
  31. #define RTC_EXPORT
  32. #define RTC_API
  33. #endif
  34. #ifndef RTC_ENABLE_WEBSOCKET
  35. #define RTC_ENABLE_WEBSOCKET 1
  36. #endif
  37. #ifndef RTC_ENABLE_MEDIA
  38. #define RTC_ENABLE_MEDIA 1
  39. #endif
  40. #define RTC_DEFAULT_MTU 1280 // IPv6 minimum guaranteed MTU
  41. #if RTC_ENABLE_MEDIA
  42. #define RTC_DEFAULT_MAXIMUM_FRAGMENT_SIZE \
  43. ((uint16_t)(RTC_DEFAULT_MTU - 12 - 8 - 40)) // SRTP/UDP/IPv6
  44. #define RTC_DEFAULT_MAXIMUM_PACKET_COUNT_FOR_NACK_CACHE ((unsigned)512)
  45. #endif
  46. #include <stdbool.h>
  47. #include <stdint.h>
  48. // libdatachannel C API
  49. typedef enum {
  50. RTC_NEW = 0,
  51. RTC_CONNECTING = 1,
  52. RTC_CONNECTED = 2,
  53. RTC_DISCONNECTED = 3,
  54. RTC_FAILED = 4,
  55. RTC_CLOSED = 5
  56. } rtcState;
  57. typedef enum {
  58. RTC_GATHERING_NEW = 0,
  59. RTC_GATHERING_INPROGRESS = 1,
  60. RTC_GATHERING_COMPLETE = 2
  61. } rtcGatheringState;
  62. typedef enum {
  63. RTC_SIGNALING_STABLE = 0,
  64. RTC_SIGNALING_HAVE_LOCAL_OFFER = 1,
  65. RTC_SIGNALING_HAVE_REMOTE_OFFER = 2,
  66. RTC_SIGNALING_HAVE_LOCAL_PRANSWER = 3,
  67. RTC_SIGNALING_HAVE_REMOTE_PRANSWER = 4,
  68. } rtcSignalingState;
  69. typedef enum { // Don't change, it must match plog severity
  70. RTC_LOG_NONE = 0,
  71. RTC_LOG_FATAL = 1,
  72. RTC_LOG_ERROR = 2,
  73. RTC_LOG_WARNING = 3,
  74. RTC_LOG_INFO = 4,
  75. RTC_LOG_DEBUG = 5,
  76. RTC_LOG_VERBOSE = 6
  77. } rtcLogLevel;
  78. typedef enum {
  79. RTC_CERTIFICATE_DEFAULT = 0, // ECDSA
  80. RTC_CERTIFICATE_ECDSA = 1,
  81. RTC_CERTIFICATE_RSA = 2,
  82. } rtcCertificateType;
  83. typedef enum {
  84. // video
  85. RTC_CODEC_H264 = 0,
  86. RTC_CODEC_VP8 = 1,
  87. RTC_CODEC_VP9 = 2,
  88. // audio
  89. RTC_CODEC_OPUS = 128
  90. } rtcCodec;
  91. typedef enum {
  92. RTC_DIRECTION_UNKNOWN = 0,
  93. RTC_DIRECTION_SENDONLY = 1,
  94. RTC_DIRECTION_RECVONLY = 2,
  95. RTC_DIRECTION_SENDRECV = 3,
  96. RTC_DIRECTION_INACTIVE = 4
  97. } rtcDirection;
  98. typedef enum { RTC_TRANSPORT_POLICY_ALL = 0, RTC_TRANSPORT_POLICY_RELAY = 1 } rtcTransportPolicy;
  99. #define RTC_ERR_SUCCESS 0
  100. #define RTC_ERR_INVALID -1 // invalid argument
  101. #define RTC_ERR_FAILURE -2 // runtime error
  102. #define RTC_ERR_NOT_AVAIL -3 // element not available
  103. #define RTC_ERR_TOO_SMALL -4 // buffer too small
  104. typedef void(RTC_API *rtcLogCallbackFunc)(rtcLogLevel level, const char *message);
  105. typedef void(RTC_API *rtcDescriptionCallbackFunc)(int pc, const char *sdp, const char *type,
  106. void *ptr);
  107. typedef void(RTC_API *rtcCandidateCallbackFunc)(int pc, const char *cand, const char *mid,
  108. void *ptr);
  109. typedef void(RTC_API *rtcStateChangeCallbackFunc)(int pc, rtcState state, void *ptr);
  110. typedef void(RTC_API *rtcGatheringStateCallbackFunc)(int pc, rtcGatheringState state, void *ptr);
  111. typedef void(RTC_API *rtcSignalingStateCallbackFunc)(int pc, rtcSignalingState state, void *ptr);
  112. typedef void(RTC_API *rtcDataChannelCallbackFunc)(int pc, int dc, void *ptr);
  113. typedef void(RTC_API *rtcTrackCallbackFunc)(int pc, int tr, void *ptr);
  114. typedef void(RTC_API *rtcOpenCallbackFunc)(int id, void *ptr);
  115. typedef void(RTC_API *rtcClosedCallbackFunc)(int id, void *ptr);
  116. typedef void(RTC_API *rtcErrorCallbackFunc)(int id, const char *error, void *ptr);
  117. typedef void(RTC_API *rtcMessageCallbackFunc)(int id, const char *message, int size, void *ptr);
  118. typedef void(RTC_API *rtcBufferedAmountLowCallbackFunc)(int id, void *ptr);
  119. typedef void(RTC_API *rtcAvailableCallbackFunc)(int id, void *ptr);
  120. // Log
  121. // NULL cb on the first call will log to stdout
  122. RTC_EXPORT void rtcInitLogger(rtcLogLevel level, rtcLogCallbackFunc cb);
  123. // User pointer
  124. RTC_EXPORT void rtcSetUserPointer(int id, void *ptr);
  125. RTC_EXPORT void *rtcGetUserPointer(int i);
  126. // PeerConnection
  127. typedef struct {
  128. const char **iceServers;
  129. int iceServersCount;
  130. const char *proxyServer; // libnice only
  131. const char *bindAddress; // libjuice only, NULL means any
  132. rtcCertificateType certificateType;
  133. rtcTransportPolicy iceTransportPolicy;
  134. bool enableIceTcp; // libnice only
  135. bool enableIceUdpMux; // libjuice only
  136. bool disableAutoNegotiation;
  137. uint16_t portRangeBegin; // 0 means automatic
  138. uint16_t portRangeEnd; // 0 means automatic
  139. int mtu; // <= 0 means automatic
  140. int maxMessageSize; // <= 0 means default
  141. } rtcConfiguration;
  142. RTC_EXPORT int rtcCreatePeerConnection(const rtcConfiguration *config); // returns pc id
  143. RTC_EXPORT int rtcDeletePeerConnection(int pc);
  144. RTC_EXPORT int rtcSetLocalDescriptionCallback(int pc, rtcDescriptionCallbackFunc cb);
  145. RTC_EXPORT int rtcSetLocalCandidateCallback(int pc, rtcCandidateCallbackFunc cb);
  146. RTC_EXPORT int rtcSetStateChangeCallback(int pc, rtcStateChangeCallbackFunc cb);
  147. RTC_EXPORT int rtcSetGatheringStateChangeCallback(int pc, rtcGatheringStateCallbackFunc cb);
  148. RTC_EXPORT int rtcSetSignalingStateChangeCallback(int pc, rtcSignalingStateCallbackFunc cb);
  149. RTC_EXPORT int rtcSetLocalDescription(int pc, const char *type);
  150. RTC_EXPORT int rtcSetRemoteDescription(int pc, const char *sdp, const char *type);
  151. RTC_EXPORT int rtcAddRemoteCandidate(int pc, const char *cand, const char *mid);
  152. RTC_EXPORT int rtcGetLocalDescription(int pc, char *buffer, int size);
  153. RTC_EXPORT int rtcGetRemoteDescription(int pc, char *buffer, int size);
  154. RTC_EXPORT int rtcGetLocalDescriptionType(int pc, char *buffer, int size);
  155. RTC_EXPORT int rtcGetRemoteDescriptionType(int pc, char *buffer, int size);
  156. RTC_EXPORT int rtcGetLocalAddress(int pc, char *buffer, int size);
  157. RTC_EXPORT int rtcGetRemoteAddress(int pc, char *buffer, int size);
  158. RTC_EXPORT int rtcGetSelectedCandidatePair(int pc, char *local, int localSize, char *remote,
  159. int remoteSize);
  160. RTC_EXPORT int rtcGetMaxDataChannelStream(int pc);
  161. // DataChannel, Track, and WebSocket common API
  162. RTC_EXPORT int rtcSetOpenCallback(int id, rtcOpenCallbackFunc cb);
  163. RTC_EXPORT int rtcSetClosedCallback(int id, rtcClosedCallbackFunc cb);
  164. RTC_EXPORT int rtcSetErrorCallback(int id, rtcErrorCallbackFunc cb);
  165. RTC_EXPORT int rtcSetMessageCallback(int id, rtcMessageCallbackFunc cb);
  166. RTC_EXPORT int rtcSendMessage(int id, const char *data, int size);
  167. RTC_EXPORT int rtcClose(int id);
  168. RTC_EXPORT bool rtcIsOpen(int id);
  169. RTC_EXPORT bool rtcIsClosed(int id);
  170. RTC_EXPORT int rtcGetBufferedAmount(int id); // total size buffered to send
  171. RTC_EXPORT int rtcSetBufferedAmountLowThreshold(int id, int amount);
  172. RTC_EXPORT int rtcSetBufferedAmountLowCallback(int id, rtcBufferedAmountLowCallbackFunc cb);
  173. // DataChannel, Track, and WebSocket common extended API
  174. RTC_EXPORT int rtcGetAvailableAmount(int id); // total size available to receive
  175. RTC_EXPORT int rtcSetAvailableCallback(int id, rtcAvailableCallbackFunc cb);
  176. RTC_EXPORT int rtcReceiveMessage(int id, char *buffer, int *size);
  177. // DataChannel
  178. typedef struct {
  179. bool unordered;
  180. bool unreliable;
  181. int maxPacketLifeTime; // ignored if reliable
  182. int maxRetransmits; // ignored if reliable
  183. } rtcReliability;
  184. typedef struct {
  185. rtcReliability reliability;
  186. const char *protocol; // empty string if NULL
  187. bool negotiated;
  188. bool manualStream;
  189. uint16_t stream; // numeric ID 0-65534, ignored if manualStream is false
  190. } rtcDataChannelInit;
  191. RTC_EXPORT int rtcSetDataChannelCallback(int pc, rtcDataChannelCallbackFunc cb);
  192. RTC_EXPORT int rtcCreateDataChannel(int pc, const char *label); // returns dc id
  193. RTC_EXPORT int rtcCreateDataChannelEx(int pc, const char *label,
  194. const rtcDataChannelInit *init); // returns dc id
  195. RTC_EXPORT int rtcDeleteDataChannel(int dc);
  196. RTC_EXPORT int rtcGetDataChannelStream(int dc);
  197. RTC_EXPORT int rtcGetDataChannelLabel(int dc, char *buffer, int size);
  198. RTC_EXPORT int rtcGetDataChannelProtocol(int dc, char *buffer, int size);
  199. RTC_EXPORT int rtcGetDataChannelReliability(int dc, rtcReliability *reliability);
  200. // Track
  201. typedef struct {
  202. rtcDirection direction;
  203. rtcCodec codec;
  204. int payloadType;
  205. uint32_t ssrc;
  206. const char *mid;
  207. const char *name; // optional
  208. const char *msid; // optional
  209. const char *trackId; // optional, track ID used in MSID
  210. } rtcTrackInit;
  211. RTC_EXPORT int rtcSetTrackCallback(int pc, rtcTrackCallbackFunc cb);
  212. RTC_EXPORT int rtcAddTrack(int pc, const char *mediaDescriptionSdp); // returns tr id
  213. RTC_EXPORT int rtcAddTrackEx(int pc, const rtcTrackInit *init); // returns tr id
  214. RTC_EXPORT int rtcDeleteTrack(int tr);
  215. RTC_EXPORT int rtcGetTrackDescription(int tr, char *buffer, int size);
  216. RTC_EXPORT int rtcGetTrackMid(int tr, char *buffer, int size);
  217. RTC_EXPORT int rtcGetTrackDirection(int tr, rtcDirection *direction);
  218. #if RTC_ENABLE_MEDIA
  219. // Media
  220. // Define how NAL units are separated in a H264 sample
  221. typedef enum {
  222. RTC_NAL_SEPARATOR_LENGTH = 0, // first 4 bytes are NAL unit length
  223. RTC_NAL_SEPARATOR_LONG_START_SEQUENCE = 1, // 0x00, 0x00, 0x00, 0x01
  224. RTC_NAL_SEPARATOR_SHORT_START_SEQUENCE = 2, // 0x00, 0x00, 0x01
  225. RTC_NAL_SEPARATOR_START_SEQUENCE = 3, // long or short start sequence
  226. } rtcNalUnitSeparator;
  227. typedef struct {
  228. uint32_t ssrc;
  229. const char *cname;
  230. uint8_t payloadType;
  231. uint32_t clockRate;
  232. uint16_t sequenceNumber;
  233. uint32_t timestamp;
  234. // H264
  235. rtcNalUnitSeparator nalSeparator; // NAL unit separator
  236. uint16_t maxFragmentSize; // Maximum NAL unit fragment size
  237. } rtcPacketizationHandlerInit;
  238. typedef struct {
  239. double seconds; // Start time in seconds
  240. bool since1970; // true if seconds since 1970
  241. // false if seconds since 1900
  242. uint32_t timestamp; // Start timestamp
  243. } rtcStartTime;
  244. typedef struct {
  245. uint32_t ssrc;
  246. const char *name; // optional
  247. const char *msid; // optional
  248. const char *trackId; // optional, track ID used in MSID
  249. } rtcSsrcForTypeInit;
  250. // Set H264PacketizationHandler for track
  251. RTC_EXPORT int rtcSetH264PacketizationHandler(int tr, const rtcPacketizationHandlerInit *init);
  252. // Set OpusPacketizationHandler for track
  253. RTC_EXPORT int rtcSetOpusPacketizationHandler(int tr, const rtcPacketizationHandlerInit *init);
  254. // Chain RtcpSrReporter to handler chain for given track
  255. RTC_EXPORT int rtcChainRtcpSrReporter(int tr);
  256. // Chain RtcpNackResponder to handler chain for given track
  257. RTC_EXPORT int rtcChainRtcpNackResponder(int tr, unsigned int maxStoredPacketsCount);
  258. /// Set start time for RTP stream
  259. RTC_EXPORT int rtcSetRtpConfigurationStartTime(int id, const rtcStartTime *startTime);
  260. // Start stats recording for RTCP Sender Reporter
  261. RTC_EXPORT int rtcStartRtcpSenderReporterRecording(int id);
  262. // Transform seconds to timestamp using track's clock rate, result is written to timestamp
  263. RTC_EXPORT int rtcTransformSecondsToTimestamp(int id, double seconds, uint32_t *timestamp);
  264. // Transform timestamp to seconds using track's clock rate, result is written to seconds
  265. RTC_EXPORT int rtcTransformTimestampToSeconds(int id, uint32_t timestamp, double *seconds);
  266. // Get current timestamp, result is written to timestamp
  267. RTC_EXPORT int rtcGetCurrentTrackTimestamp(int id, uint32_t *timestamp);
  268. // Get start timestamp for track identified by given id, result is written to timestamp
  269. RTC_EXPORT int rtcGetTrackStartTimestamp(int id, uint32_t *timestamp);
  270. // Set RTP timestamp for track identified by given id
  271. RTC_EXPORT int rtcSetTrackRtpTimestamp(int id, uint32_t timestamp);
  272. // Get timestamp of previous RTCP SR, result is written to timestamp
  273. RTC_EXPORT int rtcGetPreviousTrackSenderReportTimestamp(int id, uint32_t *timestamp);
  274. // Set NeedsToReport flag in RtcpSrReporter handler identified by given track id
  275. RTC_EXPORT int rtcSetNeedsToSendRtcpSr(int id);
  276. // Get all available payload types for given codec and stores them in buffer, does nothing if
  277. // buffer is NULL
  278. int rtcGetTrackPayloadTypesForCodec(int tr, const char *ccodec, int *buffer, int size);
  279. // Get all SSRCs for given track
  280. int rtcGetSsrcsForTrack(int tr, uint32_t *buffer, int count);
  281. // Get CName for SSRC
  282. int rtcGetCNameForSsrc(int tr, uint32_t ssrc, char *cname, int cnameSize);
  283. // Get all SSRCs for given media type in given SDP
  284. int rtcGetSsrcsForType(const char *mediaType, const char *sdp, uint32_t *buffer, int bufferSize);
  285. // Set SSRC for given media type in given SDP
  286. int rtcSetSsrcForType(const char *mediaType, const char *sdp, char *buffer, const int bufferSize,
  287. rtcSsrcForTypeInit *init);
  288. #endif // RTC_ENABLE_MEDIA
  289. #if RTC_ENABLE_WEBSOCKET
  290. // WebSocket
  291. typedef struct {
  292. bool disableTlsVerification; // if true, don't verify the TLS certificate
  293. const char *proxyServer; // unsupported for now
  294. const char **protocols;
  295. int protocolsCount;
  296. } rtcWsConfiguration;
  297. RTC_EXPORT int rtcCreateWebSocket(const char *url); // returns ws id
  298. RTC_EXPORT int rtcCreateWebSocketEx(const char *url, const rtcWsConfiguration *config);
  299. RTC_EXPORT int rtcDeleteWebSocket(int ws);
  300. RTC_EXPORT int rtcGetWebSocketRemoteAddress(int ws, char *buffer, int size);
  301. RTC_EXPORT int rtcGetWebSocketPath(int ws, char *buffer, int size);
  302. // WebSocketServer
  303. typedef void(RTC_API *rtcWebSocketClientCallbackFunc)(int wsserver, int ws, void *ptr);
  304. typedef struct {
  305. uint16_t port; // 0 means automatic selection
  306. bool enableTls; // if true, enable TLS (WSS)
  307. const char *certificatePemFile; // NULL for autogenerated certificate
  308. const char *keyPemFile; // NULL for autogenerated certificate
  309. const char *keyPemPass; // NULL if no pass
  310. } rtcWsServerConfiguration;
  311. RTC_EXPORT int rtcCreateWebSocketServer(const rtcWsServerConfiguration *config,
  312. rtcWebSocketClientCallbackFunc cb); // returns wsserver id
  313. RTC_EXPORT int rtcDeleteWebSocketServer(int wsserver);
  314. RTC_EXPORT int rtcGetWebSocketServerPort(int wsserver);
  315. #endif
  316. // Optional global preload and cleanup
  317. RTC_EXPORT void rtcPreload(void);
  318. RTC_EXPORT void rtcCleanup(void);
  319. // SCTP global settings
  320. typedef struct {
  321. int recvBufferSize; // in bytes, <= 0 means optimized default
  322. int sendBufferSize; // in bytes, <= 0 means optimized default
  323. int maxChunksOnQueue; // in chunks, <= 0 means optimized default
  324. int initialCongestionWindow; // in MTUs, <= 0 means optimized default
  325. int maxBurst; // in MTUs, 0 means optimized default, < 0 means disabled
  326. int congestionControlModule; // 0: RFC2581 (default), 1: HSTCP, 2: H-TCP, 3: RTCC
  327. int delayedSackTimeMs; // in msecs, 0 means optimized default, < 0 means disabled
  328. int minRetransmitTimeoutMs; // in msecs, <= 0 means optimized default
  329. int maxRetransmitTimeoutMs; // in msecs, <= 0 means optimized default
  330. int initialRetransmitTimeoutMs; // in msecs, <= 0 means optimized default
  331. int maxRetransmitAttempts; // number of retransmissions, <= 0 means optimized default
  332. int heartbeatIntervalMs; // in msecs, <= 0 means optimized default
  333. } rtcSctpSettings;
  334. // Note: SCTP settings apply to newly-created PeerConnections only
  335. RTC_EXPORT int rtcSetSctpSettings(const rtcSctpSettings *settings);
  336. #ifdef __cplusplus
  337. } // extern "C"
  338. #endif
  339. #endif