repo/core/curl/files/CURLOPT_RTSP_REQUEST.3

.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_REQUEST.md
.TH CURLOPT_RTSP_REQUEST 3 "2024-06-01" libcurl
.SH NAME
CURLOPT_RTSP_REQUEST \- RTSP request
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request);
.fi
.SH DESCRIPTION
Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP
enum values as a long in the \fIrequest\fP argument. Unless noted otherwise,
commands require the Session ID to be initialized.
.IP CURL_RTSPREQ_OPTIONS
Used to retrieve the available methods of the server. The application is
responsible for parsing and obeying the response. The session ID is not needed
for this method.
.IP CURL_RTSPREQ_DESCRIBE
Used to get the low level description of a stream. The application should note
what formats it understands in the \fI\(aqAccept:\(aq\fP header. Unless set manually,
libcurl automatically adds in \fI\(aqAccept: application/sdp\(aq\fP. Time\-condition
headers are added to Describe requests if the \fICURLOPT_TIMECONDITION(3)\fP
option is used. (The session ID is not needed for this method)
.IP CURL_RTSPREQ_ANNOUNCE
When sent by a client, this method changes the description of the session. For
example, if a client is using the server to record a meeting, the client can
use Announce to inform the server of all the meta\-information about the
session. ANNOUNCE acts like an HTTP PUT or POST just like
\fICURL_RTSPREQ_SET_PARAMETER\fP
.IP CURL_RTSPREQ_SETUP
Setup is used to initialize the transport layer for the session. The
application must set the desired Transport options for a session by using the
\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session
ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts
and uses the session ID in the response to this request. The session ID is not
needed for this method.
.IP CURL_RTSPREQ_PLAY
Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to
modify the playback time (e.g. \fInpt=10\-15\fP).
.IP CURL_RTSPREQ_PAUSE
Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with
a single value to indicate when the stream should be
halted. (e.g. \fInpt=25\fP)
.IP CURL_RTSPREQ_TEARDOWN
This command terminates an RTSP session. Simply closing a connection does not
terminate the RTSP session since it is valid to control an RTSP session over
different connections.
.IP CURL_RTSPREQ_GET_PARAMETER
Retrieve a parameter from the server. By default, libcurl adds a
\fIContent\-Type: text/parameters\fP header on all non\-empty requests unless a
custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see
\fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat
message (e.g. in the presence of a server\-specified timeout) should send use
an empty GET_PARAMETER request.
.IP CURL_RTSPREQ_SET_PARAMETER
Set a parameter on the server. By default, libcurl uses a *Content\-Type:
text/parameters* header unless a custom one is set. The interaction with
SET_PARAMETER is much like an HTTP PUT or POST. An application may either use
\fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like an HTTP PUT, or it may use
\fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are allowed, so
the application must set the \fICURLOPT_INFILESIZE(3)\fP in the former and
\fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use of multi\-part
POSTs within RTSP.
.IP CURL_RTSPREQ_RECORD
Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP
option to modify the record time.
.IP CURL_RTSPREQ_RECEIVE
This is a special request because it does not send any data to the server. The
application may call this function in order to receive interleaved RTP
data. It returns after processing one read buffer of data in order to give the
application a chance to run.
.SH DEFAULT
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode res;
    curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
    /* ask for options! */
    curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS);
    res = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_RTSP_SESSION_ID (3),
.BR CURLOPT_RTSP_STREAM_URI (3)