summaryrefslogtreecommitdiffstats
path: root/PICA_media.h
diff options
context:
space:
mode:
authorAnton <anton@picapica.im>2026-11-22 18:43:34 +0400
committerAnton <anton@picapica.im>2026-11-22 18:43:34 +0400
commit05b82a33c145f768de9b3b3abca18630a798aabb (patch)
treedf4e709e70f8c67d691ad0264a2191f30cfb3715 /PICA_media.h
parentee5e6b4dac1d2cf0c2c5a29fe69efd7adf8d4bf6 (diff)
downloadpica-pica-audio_video_calls.tar.gz
pica-pica-audio_video_calls.zip
rework network settings, add multiple addresses, UDP hole punchingaudio_video_calls
Diffstat (limited to 'PICA_media.h')
-rw-r--r--PICA_media.h151
1 files changed, 136 insertions, 15 deletions
diff --git a/PICA_media.h b/PICA_media.h
index 971b918..9a71302 100644
--- a/PICA_media.h
+++ b/PICA_media.h
@@ -17,12 +17,19 @@
/* mediac2c connections - call media over UDP, protected by DTLS.
*
- * A mediac2c connection exists only while a call is in progress and only
- * between two clients that already have an established directc2c connection.
- * It reuses that connection's address and port number with UDP instead of
- * TCP, so nothing has to be announced or negotiated over the c2c connection:
- * the client that made the outgoing directc2c connection is the DTLS client,
- * the one that accepted it is the DTLS server.
+ * A mediac2c connection exists only while a call is in progress. When the
+ * call becomes active, up to two attempts are made, one after another - see
+ * "Establishing the media connection" in doc/proto-doc-latest.txt:
+ *
+ * 1. Over the directc2c connection's address and port number, with UDP
+ * instead of TCP, if the call's c2c connection has an established directc2c
+ * one: the client that made the outgoing directc2c connection is the DTLS
+ * client, the one that accepted it is the DTLS server, listening on its
+ * PICA_media_listener.
+ *
+ * 2. By UDP hole punching between the media sockets the two clients opened
+ * for the call (PICA_media_call), over the addresses exchanged in 0x70 and
+ * 0x71. The caller is the DTLS client.
*
* Media packets are sent over this connection whenever it is established and
* over the c2c/directc2c connection otherwise; the receiving side accepts
@@ -53,11 +60,23 @@
*/
#define PICA_MEDIA_SAFE_PAYLOAD (PICA_MEDIA_LINK_MTU - 100)
-/* How long a call keeps trying to bring the media connection up before
- * giving up and carrying the media over the c2c connection for the rest of
- * the call, in seconds.
+/* The time limits of the two attempts, in milliseconds. A failed attempt 1
+ * is followed by attempt 2; once that fails too, the media stays on the c2c
+ * connection for the rest of the call.
+ */
+/* attempt 1, from the call becoming active to the handshake completing */
+#define PICA_MEDIA_DIRECT_TIMEOUT 5000
+/* attempt 2: probes are sent this often... */
+#define PICA_MEDIA_PROBE_INTERVAL 200
+/* ...for at most this long, until an address is selected */
+#define PICA_MEDIA_PUNCH_TIMEOUT 10000
+/* and the handshake has this long to complete once it is */
+#define PICA_MEDIA_PUNCH_HANDSHAKE_TIMEOUT 10000
+
+/* How long 0x70 and 0x71 wait for the node to report the address of the
+ * media socket before they are sent without it, in milliseconds.
*/
-#define PICA_MEDIA_HANDSHAKE_TIMEOUT 10
+#define PICA_MEDIA_LEARN_TIMEOUT 2000
/* An established media connection with no datagram received for this many
* seconds is considered broken; media falls back to the c2c connection.
@@ -71,6 +90,11 @@
#define PICA_MEDIA_READBUFSIZE 4096
+/* largest tail of 0x70/0x71 after the length field: the token and the
+ * addresses, IPv4 ones being the only kind sent
+ */
+#define PICA_MEDIA_CALL_INFO_MAXSIZE (PICA_PROTO_CALL_TOKENSIZE + PICA_PROTO_CALL_MAXADDRS * PICA_PROTO_DIRECTC2C_ADDRLIST_ITEM_IPV4_SIZE)
+
/* transport of the media packets of a call, reported by call_media_transport_cb */
#define PICA_CALL_TRANSPORT_C2C 0
#define PICA_CALL_TRANSPORT_MEDIAC2C 1
@@ -78,8 +102,15 @@
enum PICA_media_state
{
PICA_MEDIA_STATE_NEW = 0,
- /* DTLS server role, socket bound, waiting for the first datagram */
+ /* attempt 1, DTLS server role, socket bound, waiting for the first
+ * datagram */
PICA_MEDIA_STATE_LISTENING,
+ /* attempt 2, sending probes to every address of the peer, waiting for
+ * one of its probes to arrive */
+ PICA_MEDIA_STATE_PUNCHING,
+ /* attempt 2, DTLS server role, address selected, waiting for the first
+ * datagram of the handshake from it */
+ PICA_MEDIA_STATE_SELECTED,
PICA_MEDIA_STATE_HANDSHAKE,
PICA_MEDIA_STATE_ACTIVE,
PICA_MEDIA_STATE_FAILED
@@ -98,9 +129,53 @@ struct PICA_media_listener
struct PICA_media_channel *channel;
};
+/* Everything a call needs for hole punching, from the moment it starts to
+ * ring until it ends. Created by PICA_media_call_prepare(), freed by
+ * PICA_media_call_free().
+ */
+struct PICA_media_call
+{
+ /* the call socket, -1 if this side does not take part in hole punching */
+ SOCKET sck;
+ /* its port number, host byte order */
+ int local_port;
+ int is_caller;
+
+ unsigned char token[PICA_PROTO_CALL_TOKENSIZE];
+
+ /* the node is being asked for the address of sck */
+ int learning;
+ uint64_t learn_started;
+ /* what it answered, valid when learned is set */
+ int learned;
+ struct sockaddr_in learned_addr;
+
+ /* PICA_PROTO_CALLREQ or PICA_PROTO_CALLANS while that message waits for
+ * the address, 0 otherwise */
+ int pending_msg;
+ uint64_t pending_deadline;
+
+ /* from the peer's 0x70 or 0x71 */
+ int peer_info_received;
+ unsigned char peer_token[PICA_PROTO_CALL_TOKENSIZE];
+ struct sockaddr_in peer_addrs[PICA_PROTO_CALL_MAXADDRS];
+ int peer_addrs_count;
+
+ /* call parameters set while the call was PICA_CALL_STATE_ANSWERING */
+ int audio_params_pending;
+ char audio_codec[PICA_PROTO_CALL_CODECNAMESIZE + 1];
+ uint16_t audio_sample_rate;
+ int video_params_pending;
+ char video_codec[PICA_PROTO_CALL_CODECNAMESIZE + 1];
+ uint16_t video_width;
+ uint16_t video_height;
+};
+
struct PICA_media_channel
{
struct PICA_c2c *c2c;
+ /* 1 - over the directc2c address, 2 - by hole punching */
+ int attempt;
/* set when this side has the DTLS server role */
struct PICA_media_listener *listener;
@@ -117,6 +192,15 @@ struct PICA_media_channel
enum PICA_media_state state;
time_t started;
+ /* when the current stage of setting the connection up has to be
+ * complete, PICA_media_now() milliseconds */
+ uint64_t deadline;
+
+ /* attempt 2 */
+ uint64_t last_probe;
+ /* the first DTLS datagram has arrived from the selected address, the
+ * peer no longer needs probes */
+ int dtls_seen;
time_t last_rx;
time_t last_tx;
@@ -136,11 +220,48 @@ int PICA_media_listener_new(const struct PICA_acc *acc, int public_port, int loc
struct PICA_media_listener **ml);
void PICA_media_listener_close(struct PICA_media_listener *ml);
+/** Milliseconds from an arbitrary point, never going backwards. */
+uint64_t PICA_media_now(void);
+
+/**
+ * Starts preparing for hole punching: opens the call socket and asks the
+ * node for its address - for the caller before it sends 0x70, for the
+ * callee when 0x70 arrives. Without hole punching, e.g. with direct
+ * connections disabled, only creates c2c->media_call, whose address list is
+ * then empty.
+ * \param peer_info for the callee, the tail of the caller's 0x70 after the
+ * length field, see PICA_media_call_read_info(); NULL for the caller
+ */
+int PICA_media_call_prepare(struct PICA_c2c *c2c, int is_caller,
+ const unsigned char *peer_info, unsigned int peer_info_len);
+
+/** The node's answer about the call socket's address; status as in
+ * udp_address_cb. */
+void PICA_media_call_learned(struct PICA_c2c *c2c, int status, const unsigned char *addr_bin, int type, uint16_t port);
+
+/** Whether 0x70/0x71 can be sent now: the address is known, or will not be. */
+int PICA_media_call_ready(struct PICA_c2c *c2c);
+
+/**
+ * Writes the probe token and the address list of 0x70/0x71 to buf.
+ * \return number of octets written, at most PICA_MEDIA_CALL_INFO_MAXSIZE
+ */
+unsigned int PICA_media_call_write_info(struct PICA_c2c *c2c, unsigned char *buf);
+
+/**
+ * Takes the probe token and the address list from the tail of the peer's
+ * 0x70/0x71, after the length field.
+ * \return 0 if it is malformed
+ */
+int PICA_media_call_read_info(struct PICA_c2c *c2c, const unsigned char *buf, unsigned int len);
+
+/** Releases everything PICA_media_call_prepare() made. */
+void PICA_media_call_free(struct PICA_c2c *c2c);
+
/**
- * Brings up a media connection for a call that has just become active.
- * Does nothing if the preconditions (an established directc2c connection,
- * and a media listener on the accepting side) are not met - the media then
- * stays on the c2c connection.
+ * Brings up a media connection for a call that has just become active, see
+ * the two attempts above. Does nothing if neither of them can be made - the
+ * media then stays on the c2c connection.
*/
void PICA_media_start(struct PICA_c2c *c2c);
void PICA_media_close(struct PICA_c2c *c2c);