1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_INTERLEAVEFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_INTERLEAVEDATA (3)
9  - CURLOPT_RTSP_REQUEST (3)
10Protocol:
11  - RTSP
12Added-in: 7.20.0
13---
14
15# NAME
16
17CURLOPT_INTERLEAVEFUNCTION - callback for RTSP interleaved data
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24size_t interleave_callback(void *ptr, size_t size, size_t nmemb,
25                           void *userdata);
26
27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEFUNCTION,
28                          interleave_callback);
29~~~
30
31# DESCRIPTION
32
33Pass a pointer to your callback function, which should match the prototype
34shown above.
35
36This callback function gets called by libcurl as soon as it has received
37interleaved RTP data. This function gets called for each $ block and therefore
38contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl
39writes the interleaved header as well as the included data for each call. The
40first byte is always an ASCII dollar sign. The dollar sign is followed by a
41one byte channel identifier and then a 2 byte integer length in network byte
42order. See RFC 2326 Section 10.12 for more information on how RTP interleaving
43behaves. If unset or set to NULL, curl uses the default write function.
44
45Interleaved RTP poses some challenges for the client application. Since the
46stream data is sharing the RTSP control connection, it is critical to service
47the RTP in a timely fashion. If the RTP data is not handled quickly,
48subsequent response processing may become unreasonably delayed and the
49connection may close. The application may use *CURL_RTSPREQ_RECEIVE* to
50service RTP data when no requests are desired. If the application makes a
51request, (e.g. *CURL_RTSPREQ_PAUSE*) then the response handler processes
52any pending RTP data before marking the request as finished.
53
54The CURLOPT_INTERLEAVEDATA(3) is passed in the *userdata* argument in
55the callback.
56
57Your callback should return the number of bytes actually taken care of. If
58that amount differs from the amount passed to your callback function, it
59signals an error condition to the library. This causes the transfer to abort
60and the libcurl function used returns *CURLE_WRITE_ERROR*.
61
62You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
63
64# DEFAULT
65
66NULL, the interleave data is then passed to the regular write function:
67CURLOPT_WRITEFUNCTION(3).
68
69# %PROTOCOLS%
70
71# EXAMPLE
72
73~~~c
74struct local {
75  void *custom;
76};
77
78static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp)
79{
80  struct local *l = userp;
81  printf("our ptr: %p\n", l->custom);
82  /* take care of the packet in 'ptr', then return... */
83  return size * nmemb;
84}
85
86int main(void)
87{
88  struct local rtp_data;
89  CURL *curl = curl_easy_init();
90  if(curl) {
91    curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write);
92    curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data);
93  }
94}
95~~~
96
97# %AVAILABILITY%
98
99# RETURN VALUE
100
101Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
102