Purpose

The DVR Engine API provides access to DVR Engine which is responsible handling RTSP streaming and playback of RTP recordings.

Constraints

This API is valid for all platforms running on Symbian OS 9.4 or later.

Classification and release information

This API is an Domain API and was first published in S60 release 5.1.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

API description

The DVR Engine API (also known as CCRDvrApi) is a Library API that provides a Client-Server interface to DVR Engine. DVR Engine is an engine that handles RTP packets from various sources and passes them to video player utility for rendering. For historical reasons most of the classes in the engine are named after letters CR that stands for Common Recording. As this component is now called DVR Engine, the naming has not yet made its way to names of classes or variables inside component.

As said above, CCRDvrApi/Engine, is tightly tied to video player functionality. Sequences what to do and when can be hard to understand if one is not familiar with the MMF framework. The idea is that through MMF framework the video player opens a local host address (internal connection). After opening is completed, the player uses CCRDvrApi to connect a remote server to start streaming. After this point, DVR Engine forwards all data and RTSP messages it receives from remote server (external connection) to the MMF framework through this internal socket where it is connected (internal connection). All communication with DVR Engine during streaming is done through an internal socket (internal connection) via MMF framework. Example: making a PauseL() call to CVideoPlayerUtility causes the MMF framework to send a RTSP PAUSE command to internal socket (internal connection). DVR Engine gets this RTSP PAUSE command and forwards it to the remote server.

Communication and data flow of DVR Engin...


Communication and data flow of DVR Engine while streaming

DVR Engine can also be used to play proprietary RTP clips (DVBH recordings). In local playback, DVR Engine pushes recorded packets to the MMF framework through its interface below, XPS. In this case all control of playback is done through DVR Engine instead of MMF framework and RTSP commands of internal connection.

Note that API for DVR Engine does not provide any means to adjust the quality of the stream or the speed of the playback.

Use cases

Most important use cases for the DVR Engine API are starting and stopping the streaming of an RTSP clip.

Starting the streaming happens by first creating a client. After that the client needs an Access Point usable for streaming. This is done by calling the SetIap method. Now DVR Engine is ready for streaming. Streaming starts by making a PlayRtspUrl call to API. This function requires two parameters: aSessionChk and aRtspParams. The first one, aSessionCheck, is a reference to an unsigned integer. This value is a checksum that is used to identify the correct server session. When performing the PlayRtspUrl method, the user leaves this value empty. When the call is finished, it contains a value that can be used to access the same streaming session again. The second one, aRtspParams, is a dataholder for RTSP-related information (URL, user name, password, message queue name, possible RTSP proxy server and proxy server port).

Stopping the streaming happens by calling the CloseSession method. The only parameter, aSessionChk, is an unsigned integer used to identify the correct server session. This is the same value as the one contained in the aSessionChk parameter after the PlayRtspUrl method call has finished.

Further access to streaming session (pause, seek, etc.) goes through the MMF framework.

Other use cases are:

  • Setting IAP: As implied above, this is done by calling SetIap. Later if the IAP needs to be changed, the current one can be removed by calling CancelSetIap.

  • Local file playback: DVR Engine can be used to play locally stored RTP clips. It uses the following commands:

    • PlayRtpFile: Starts playback of the given file. After the call returns, the session identifier can be found from the aSessionChk parameter.

    • PlayCommand: Starts playback from the given playback position. The correct playback session is identified by the aSessionChk parameter.

    • PauseCommand: Pauses playback from a playback session identified by the aSessionChk parameter.

    • StopCommand: Stops playback from a playback session identifier by the aSessionChk parameter.

  • Recording: Currently no recording services are available. Method calls still exist to keep binary compatibility.

Related APIs
  • CancelSetIap
  • CloseSession
  • PauseCommand
  • PlayCommand
  • PlayRtpFile
  • PlayRtspUrl
  • SetIap
  • StopCommand
  • aRtspParams
  • aSessionCheck
  • aSessionChk

API class structure

The application using the DVR Engine API needs to implement the MCREngineObserver interface. The DVR Engine API uses this to inform of changes in streaming. Other than that, there are no additional requirements. Connecting to server happens by creating a new instance of CCRDvrApi by calling CCRDvrApi::NewL.

Class structure of


Class structure of

Related APIs
  • CCRDvrApi
  • CCRDvrApi::NewL
Related APIs
  • CCRDvrApi
  • CVideoPlayerUtility
  • PauseL()

Using the DVR Engine API

RTSP streaming:

  • Create CCRDvrApi (by calling NewL).

  • Set an Access Point by calling SetIap.

  • Begin streaming by calling PlayRtspUrl.

  • Stop streaming by calling CloseSession.

  • Delete CCRDvrApi.

Playing RTSP streaming clip

The first application using CCRDvrApi must create one:

CCRDvrApi* dvrApi = CCRDvrApi::NewL( this );

The next step is to add Internet Access Point to dvrApi:

dvrApi->SetIap( iap );

This call starts the procedure of DVR Engine attaching to existing IAP. When the function returns, it is NOT ready to be used. After the attachment is ready, the client gets a notification through MCREngineObserver by receiving "ECRAttachCompleted".

Now, after IAP is set, DVR Engine is ready to start playing RTSP clip. At this point, the video player should perform OpenUrlL to local address (127.0.0.1). When the opening is completed, notified by MMF framework through MVideoPlayerUtilityObserver, by calling MvpuoOpenComplete, the application can start streaming:

dvrApi->PlayRtspUrl( sessionChk, serviceParams );

At this point DVR Engine starts RTSP negotiation with the remote RTSP server. After this if the user wants to communicate with DVR Engine about possible playback issues (such as pausing) it needs to be performed through the MMF framework

Finally, when the user wants to close the RTSP streaming, it calls close session and deletes it.

dvrApi->CloseSession( sessionChk );
delete dvrApi; 
dvrApi = NULL;
Related APIs
  • CCRDvrApi
  • ECRAttachCompleted
  • MCREngineObserver
  • MVideoPlayerUtilityObserver
  • MvpuoOpenComplete
  • OpenUrlL
  • dvrApi

Error handling

In case of error, CCRDvrApi returns generic error codes.

Streaming/playback errors and problems are informed through the MCREngineObserver interface.

Related APIs
  • CCRDvrApi
  • MCREngineObserver

Memory overhead

Memory/build:

  • WINSCW UDeb: Code: 109 kB, Data: 58 kB

  • ARMV5 URel: Code: 56 kB, Data: 23kB

Run-time memory allocation for this component is huge while the clip is playing. Several hundred kilobytes of memory is allocated for the RTP packet buffers sitting between source and sinks. There is no measurement of that available.

Extensions to the API

There are no extensions.

Limitations of the API

There are no limitations.

Related APIs
  • CCRDvrApi
  • CloseSession
  • NewL
  • PlayRtspUrl
  • SetIap