Darwin Streaming Server Source Code Description

This document provides detailed information on the internals of the Darwin Streaming Server. The server implements four standard IETF protocols, RTSP (Real-time streaming protocol, RFC 2326), RTP (Real-time Transport Protocol, RFC 1889), RTCP (Real-time transport control protocol, RFC 1889), and SDP (Session description protocol, RFC 2327). Before making modifications to the server code is may help to be familiar with those RFCs.

Introduction

The Darwin Streaming Server source code is written entirely in C++, and pervasively uses object-oriented concepts such as inheritance and polymorphism. Almost exclusively, there is one C++ class per .h / .cpp file pair, and those file names match the class name.

The Server code has three major subsystems, the RTP server, the RTSP server, and common utilities. Each source code file belonging to the RTP subsystem has the prefix "RTP". Similarly, each file belonging to the RTSP subsystem has the prefix "RTSP". Any other source code file belongs to the Common Utilities subsystem.

Common Utilities

Common Utilities is a toolkit of thread management, data structure, networking, and text parsing utilities. The RTP and RTSP servers uses these classes to accomplish the following three goals: 1) reduce repeated code by abstracting similar or identical tasks, 2) make the higher level code simpler through encapsulation, 3) separate out any and all platform-specific code.

Here is a short description of all the classes in the Common Utilities subsystem by group:

OS Classes: Platform-specific code abstractions for timing, condition variables, mutexes, and threads: OS, OSCond, OSMutex, OSThread, OSFileSource. Data structures: OSQueue, OSHashTable, OSHeap, OSRef.

Sockets: Platform-specific code abstractions for TCP and UDP networking. Socket classes are generally asynchronous (or non-blocking), and can send events to "Task objects". For a complete description on how this works, see "What are task objects?" in the FAQ section. Classes are: Socket, UDPSocket, UDPDemuxer, UDPSocketPool, TCPSocket, TCPListenerSocket.

Parsing Utilities: These classes serve as a toolkit for parsing and formatting text. Classes are: StringParser, StringFormatter, StrPtrLen, StringTranslator.

Tasks: These classes implement the asynchronous event mechanism the server uses. For a complete description of how tasks work, see "What are task objects?" in the FAQ section. Classes include: Task, TimeoutTask, IdleTask.

RTSP & RTP Servers

The two server subsystems have nearly identical class structures, so it is possible to discuss them together. Both servers implement a module API. Each server feature is implemented as a separate module. The following modules are currently provided:

RTSP Modules:

RTSPWebStatsModule: Allows an administrator to view server statistics from a web browser.
RTSPWebDebugModule: Provides debugging information to a web browser
RTSPValidationModule: Does a complete validation test on the RTSP server.
RTSPLoggingModule: Writes error and status messages out to a log.
RTSPSvrControlModule: Specific to the MacOS X platform. Allows the server to be controlled from the MacOS X Streaming Server Admin console.
RTPInterfaceModule: The linkage between the RTSP server and the RTP server. Acts as a pass-through for RTSP requests.

RTP Modules:

RTPAccessLogModule: Logs all client accesses to a file.
RTPFileModule: Serves hinted QuickTime files.
RTPReflectorModule: Reflects live broadcasts.
RTCPFlowControlModule: Interprets RTCP quality feedback messages from the clients, and determines whether bandwidth should be raised or lowered.

Notes on Porting to other Platforms:

The following files contain platform specific code:

OSThread, OSCond, OSMutex: Implements threads, mutexes, and condition variables. The implementations provided work on MacOS X as well as any platform that supports pthreads.

OS: Includes some platform-specific code for getting the current time. Implementations provided work on MacOS X as well as any platform that supports gettimeofday.

Socket: This class is C++ wrapper for the sockets API. On MacOS X, this class uses a set of APIs collectively called the Event Queue for receiving events from sockets in non-blocking mode. For other platforms, an implementation of the Event Queue APIs using select() has been provided in ev.cpp. For more details on the Event Queue, see  "What is the Event Queue?" in the FAQ section.

