1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_RTSP_REQUEST
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_RTSP_SESSION_ID (3)
9  - CURLOPT_RTSP_STREAM_URI (3)
10---
11
12# NAME
13
14CURLOPT_RTSP_REQUEST - RTSP request
15
16# SYNOPSIS
17
18~~~c
19#include <curl/curl.h>
20
21CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request);
22~~~
23
24# DESCRIPTION
25
26Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP
27enum values as a long in the *request* argument. Unless noted otherwise,
28commands require the Session ID to be initialized.
29
30## CURL_RTSPREQ_OPTIONS
31
32Used to retrieve the available methods of the server. The application is
33responsible for parsing and obeying the response. The session ID is not needed
34for this method.
35
36## CURL_RTSPREQ_DESCRIBE
37
38Used to get the low level description of a stream. The application should note
39what formats it understands in the *'Accept:'* header. Unless set manually,
40libcurl automatically adds in *'Accept: application/sdp'*. Time-condition
41headers are added to Describe requests if the CURLOPT_TIMECONDITION(3)
42option is used. (The session ID is not needed for this method)
43
44## CURL_RTSPREQ_ANNOUNCE
45
46When sent by a client, this method changes the description of the session. For
47example, if a client is using the server to record a meeting, the client can
48use Announce to inform the server of all the meta-information about the
49session. ANNOUNCE acts like an HTTP PUT or POST just like
50*CURL_RTSPREQ_SET_PARAMETER*
51
52## CURL_RTSPREQ_SETUP
53
54Setup is used to initialize the transport layer for the session. The
55application must set the desired Transport options for a session by using the
56CURLOPT_RTSP_TRANSPORT(3) option prior to calling setup. If no session
57ID is currently set with CURLOPT_RTSP_SESSION_ID(3), libcurl extracts
58and uses the session ID in the response to this request. The session ID is not
59needed for this method.
60
61## CURL_RTSPREQ_PLAY
62
63Send a Play command to the server. Use the CURLOPT_RANGE(3) option to
64modify the playback time (e.g. *npt=10-15*).
65
66## CURL_RTSPREQ_PAUSE
67
68Send a Pause command to the server. Use the CURLOPT_RANGE(3) option with
69a single value to indicate when the stream should be
70halted. (e.g. *npt=25*)
71
72## CURL_RTSPREQ_TEARDOWN
73
74This command terminates an RTSP session. Simply closing a connection does not
75terminate the RTSP session since it is valid to control an RTSP session over
76different connections.
77
78## CURL_RTSPREQ_GET_PARAMETER
79
80Retrieve a parameter from the server. By default, libcurl adds a
81*Content-Type: text/parameters* header on all non-empty requests unless a
82custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see
83*CURL_RTSPREQ_SET_PARAMETER*). Applications wishing to send a heartbeat
84message (e.g. in the presence of a server-specified timeout) should send use
85an empty GET_PARAMETER request.
86
87## CURL_RTSPREQ_SET_PARAMETER
88
89Set a parameter on the server. By default, libcurl uses a *Content-Type:
90text/parameters* header unless a custom one is set. The interaction with
91SET_PARAMETER is much like an HTTP PUT or POST. An application may either use
92CURLOPT_UPLOAD(3) with CURLOPT_READDATA(3) like an HTTP PUT, or it may use
93CURLOPT_POSTFIELDS(3) like an HTTP POST. No chunked transfers are allowed, so
94the application must set the CURLOPT_INFILESIZE(3) in the former and
95CURLOPT_POSTFIELDSIZE(3) in the latter. Also, there is no use of multi-part
96POSTs within RTSP.
97
98## CURL_RTSPREQ_RECORD
99
100Used to tell the server to record a session. Use the CURLOPT_RANGE(3)
101option to modify the record time.
102
103## CURL_RTSPREQ_RECEIVE
104
105This is a special request because it does not send any data to the server. The
106application may call this function in order to receive interleaved RTP
107data. It returns after processing one read buffer of data in order to give the
108application a chance to run.
109
110# DEFAULT
111
112# PROTOCOLS
113
114RTSP
115
116# EXAMPLE
117
118~~~c
119int main(void)
120{
121  CURL *curl = curl_easy_init();
122  if(curl) {
123    CURLcode res;
124    curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
125    /* ask for options! */
126    curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS);
127    res = curl_easy_perform(curl);
128    curl_easy_cleanup(curl);
129  }
130}
131~~~
132
133# AVAILABILITY
134
135Added in 7.20.0
136
137# RETURN VALUE
138
139Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
140