search

paullouisageneau / libdatachannel

C/C++ WebRTC network library featuring Data Channels, Media Transport, and WebSockets
https://libdatachannel.org/
Mozilla Public License 2.0
1.77k stars 358 forks source link

C++ API documentation #935

Open dhopsonlb opened 1 year ago

dhopsonlb commented 1 year ago

Hi, I see that you have C API documentation, but you haven't implemented any media handling in the C API. I'd prefer to use the C++ API anyways, but it appears there is no documentation for it at all.

I've been trying to use a mixture of the two APIs to get something functional, but I'm hitting barriers there as well.

I've been having to literally read the source code to figure out how to use the C++ API, and I see you have getChannel internally to convert the integer handles back and forth from the C API and C++ API, but there's no such public-facing method for tracks or connections.

What this means is that I either have to use an API with no documentation at all, or mix them, but I can't really mix them effectively because they don't return the same object types, or even provide a method to convert between them.

Thanks.

paullouisageneau commented 1 year ago

Hi, I see that you have C API documentation, but you haven't implemented any media handling in the C API.

There is media handling it the C API, only it's not documented in the API reference for now.

I'd prefer to use the C++ API anyways, but it appears there is no documentation for it at all.

Indeed, it needs to be documented.

I've been having to literally read the source code to figure out how to use the C++ API

Most examples use the C++ API, you should start from there rather than reading the library source code. Also, the API is quite similar to the JavaScript WebRTC API, which should help.

I see you have getChannel internally to convert the integer handles back and forth from the C API and C++ API, but there's no such public-facing method for tracks or connections.

This is by design as mixing the two would be very error-prone and lead to memory leaks. You should use either one or the other.

dhopsonlb commented 1 year ago

There is media handling it the C API, only it's not documented in the API reference for now.

Okay, that's good to know. Wish I had found it sooner. Thanks.

Indeed, it needs to be documented.

I see a few machine-friendly annotations in the comments, but I'd imagine the easiest way would be something like Doxygen, after adding additional machine-friendly annotations of course.

Most examples use the C++ API, you should start from there rather than reading the library source code. Also, the API is quite similar to the JavaScript WebRTC API, which should help.

Those parts of the API were indeed quite easy to figure out. Media handling and whatnot was quite difficult to uncover, I had to search for "RTP" in the source to find the function RtpHeader::getBody(). Even the examples don't seem to use it. The examples don't seem to be exhaustive. I checked them extensively throughout development, but usually left with remaining questions.

This is by design as mixing the two would be very error-prone and lead to memory leaks. You should use either one or the other.

My plan was to strongly prefer the C API and only use C++ alternatives when there are no C equivalents. I'm quite good at memory management as well as thread-safety, so I wouldn't be too worried about that. Still, there was most definitely an "ick" factor in having to mix the two APIs.

In the end, I ended up writing to the C++ API, after studying it extensively.

Thanks.