RTSP Server toolkit

Created: 26.6.97
Modified: 10.9.97
Contents:

Features
Version history
Dowloading and using
API
Real Time Scheduler

1. Features

Server

Runs standalone or under inetd.
Logs requests and errors.
Generic parsing of methods and URIs.
Validation of version and method parameters. Table.
Includes Real Time Scheduler to schedule play/pause events.
Basic proxy support, non-caching.
Highly customizable - protocol layer is written entirely in ksh.
Convenient for networking and protocol research.
Generic application interface -
- command line control of backend.
- request parameters exported through shell variables.
- supports applications with or without Real Time capability.

Unimplemented / To do

Session timeout and reclamation.
UDP and persistent TCP connections.
Basic and Digest authentication.
Caching proxy service.
Sample applications for Real Time Scheduler.
Push methods.

2. Version history

0.1	26.6.97	Basic server, incl both dummy and video.
0.2	20.6.97	Beautified code, platform for further dev.
0.3	23.7.97	Formalized server application interface.
0.4	26.8.97	Added proxy service and inetd support.

3. Downloading and using

Download the sources.
Edit the file conf to reflect your needs. The important variables to set are:
- UID - This controls what privileges the server runs under. Since this is a shell level implementation, there is no effective way of setting this to a non-existent user, as in many web servers. As RTSP involves session management, it is important to create a special user account for the application anyway.
- SERVER - This should be set to the absolute pathname of the file that supplies the do_method functions for your application.
Especially while debugging the backend application interface, it is convenient to run the server under inetd. To do this, make entries in /etc/inetd.conf and /etc/services as illustrated in etc/inetd/inetd.conf and etc/inetd/services files, respectively, and issue kill -1 to the inetd process.
Running standalone can help avoid load-up time for serving successive requests. For this, you need to be on an AIX 4.1+ platform and to install the TCP device driver in the etc/ipdev directory. Use the following commands (# being the shell prompt for root):
```
	# cd etc/ipdev
	# cfgdd -l
	IPDEV loaded
	# chmod a+rw /dev/tcp
	# cd -
	# cd server/rtspd
	# rtspd			# foreground
	# (rtspd &)		# background
	
```
When running this way in the foreground, the server can be made to enter an interactive debug mode by hitting Ctrl-C (SIGINT). The mode is handled by the debug function in the server/rtspd/misc file, and can be easily extended. As coded, the server puts out a ? prompt, and evals any command or shell function typed before resuming operation. The function stat prints out tail portions of the log and error log files.
Even if you're not on an AIX 4.1+ platform, there are situations where you cannot, or do not want to, use inetd. The C-based tool decaf is provided for precisely this purpose. Run the server by entering one of the following commands:
```
	# (decaf 554 rtspd <options> &)
		or
	$ (decaf 8554 rtspd <options> &)
	
```
($ being the usual shell prompt for the unprivileged user). Note that this is identical to usage under inetd and will not save on load time.
The server "main", rtspd, understands command line options that can be listed by typing:
```
	$ rtspd -help
	
```

4. Application Programming Interface

Basic interface

The server calls application-defined commands or shell functions named do_method, ex. do_setup, do_play etc., to service RTSP requests. The request parameters are exported as environment variables listed below. The do_ functions are called with stdin and stdout redirected from and to the client socket connection. If the server is run under inetd, stderr also gets redirected.

A shell function finish is provided to generate the RTSP response, and must be called on error with one of the error codes defined in the C header file rtsperr.h, minus the RTSP_ prefix. See the dummy server for example. Finish does not return to the caller. The server calls finish OK by default. Also useful for logging purposes is the built-in function perror, which behaves like its C equivalent. Another built-in function, redirect, may be called instead of finish.

Real time control

An application may utilize the Real Time Scheduler by invoking the RTS commands from the do_ functions. The RTS commands understand SMPTE, NPT and UTC formats.

List of environment variables

Name	Value
Out	As stated above, the RTSP response header is generated by the built-in functions finish or redirect. Any additional text to the returned to the client, including response parameters, should be written to $Out. The server automatically appends this file to the reply. Any text accidentally output to stdout, or also to stderr when running under inetd, will end up in the response.
protocol, server, content	These are set by interpreting the URI as: protocol://server/content Protocol can be only one of rtsp, rtsps and rtspu. Also note that there is no allowance for HTTP's CGI arguments following the content. The backend application may allow pathname content references, ex. action_movies/bond/diamonds_are_forever.
client_*	The following environment variables are set only when the corresponding parameters are present in the client request. The parameters are validated by the method context, but their values are not checked except for range and transport parameters. Client_rangetype is set to smpte, npt, or clock, and client_range is set to the range itself, ie. to a string of the form xxx-yyy. The server does not itself translate the parameter strings to binary values, but tools are provided to aid in the translation. client_accept client_accept_encoding client_accept_language client_authorization client_bandwidth client_blocksize client_cache_control client_conference client_connection client_content_encoding client_content_language client_content_length client_content_type client_date client_expires client_from client_if_modified_since client_last_modified client_public client_range client_rangetype client_referer client_retry_after client_scale client_session client_server client_speed client_transport client_user_agent client_via client_www_authenticate

Name

Value

Out

As stated above, the RTSP response header is generated by the built-in functions finish or redirect. Any additional text to the returned to the client, including response parameters, should be written to $Out. The server automatically appends this file to the reply. Any text accidentally output to stdout, or also to stderr when running under inetd, will end up in the response.

protocol, server, content

These are set by interpreting the URI as:

	protocol://server/content

Protocol can be only one of rtsp, rtsps and rtspu. Also note that there is no allowance for HTTP's CGI arguments following the content. The backend application may allow pathname content references, ex. action_movies/bond/diamonds_are_forever.

client_*

The following environment variables are set only when the corresponding parameters are present in the client request. The parameters are validated by the method context, but their values are not checked except for range and transport parameters. Client_rangetype is set to smpte, npt, or clock, and client_range is set to the range itself, ie. to a string of the form xxx-yyy. The server does not itself translate the parameter strings to binary values, but tools are provided to aid in the translation.

	client_accept
	client_accept_encoding
	client_accept_language
	client_authorization
	client_bandwidth
	client_blocksize
	client_cache_control
	client_conference
	client_connection
	client_content_encoding
	client_content_language
	client_content_length
	client_content_type
	client_date
	client_expires
	client_from
	client_if_modified_since
	client_last_modified
	client_public
	*client_range
	*client_rangetype
	client_referer
	client_retry_after
	client_scale
	client_session
	client_server
	client_speed
	client_transport
	client_user_agent
	client_via
	client_www_authenticate