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