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