ILMRTSPServerMedia Interface

This is the interface for handling a certain Media for the RTSP Server functionality exposed by the LEAD RTSP Sink filter. See the Creating an RTSP Server using the RTSP Sink topic for a general overview of how to use this interface.

You have to implement this interface for a low level implementation of the RTSP Server. You add this interface to the list of ILMRTSPServerMedia interfaces supported by a server by calling ILMRTSPServer::AddMedia.

When an RTSP command is received, the RTSP Server will enumerate all the ILMRTSPServerMedia interfaces and call its HandleCommand method until it finds the ILMRTSPServerMedia interface that can handle the command.

This interface is responsible for handling the RTSP commands for all the files or media streams. You are responsible for

1. Giving information regarding a media (file, capture) you are capable of supporting in response to an RTSP DESCRIBE command

2. keeping a list of active sessions

3. creating new sessions in response to an RTSP SETUP command

4. starting to stream data in response to an RTSP PLAY command

5. pausing streaming in response to an RTSP PAUSE command

6. destroying sessions in response to an RTSP TEARDOWN or when a session is inactive for too long

A session is typically a capture or convert graph, with the media in question as the source and the LEAD RTSP Sink filter as the sink. The ILMRTSPServerSession interface is exported by the LEAD RTSP Sink filter. You will need to devise a way to find which capture or convert graph corresponds to a certain ILMRTSPServerSession interface. Look below at the notes for the HandleCommand method for ideas of how an implementation might look like.

Data Types:

LMRTSPServerSessionNotificationType

typedef enum 
{ 
   RTSPServerSessionNotification_Timeout = 1, 
   RTSPServerSessionNotification_Removed, 
   RTSPServerSessionNotification_ServerStopped, 
} LMRTSPServerSessionNotificationType; 

Lists the valid values for the notification parameter that can be passed to the OnNotification method. See the OnNotification method description for more details.

Interface Properties:

Interface Methods:

HRESULT HandleCommand(IUnknown *pServer, IUnknown *pCommandParser, IUnknown *pResponseBuilder, DWORD_PTR serverSocket)

Parameters

Description

The RTSP server will call this method when it receives an RTSP command from the client. You need to examine the command URL and determine if your Media object can handle this command. For example, if you were to implement an object that plays files from a folder, you would look at the URL and find out whether it identifies a file in your folder.

If you return an error code, the next ILMRTSPServerMedia object will be given a chance to handle the command.

If you return S_OK, a response will be sent automatically by the server using the response data present in the pResponseBuilder parameter.

If you return LTMM_S_RESPONSE_PENDING [0x00050048], the server will assume that your media can handle the command and that the response will be sent separately using the ILMRTSPServer::SendCommandResponse method.

A possible implementation of this interface might keep one convert/capture object for handling the DESCRIBE commands.

When you receive a SETUP command without a session ID, you can

• create a capture/convert graph

• set LEAD RTSP Sink filter as the sink

• render the requested video or audio stream as specified in the SETUP command.

• add capture/convert graph to the list of active sessions.

• Get the ILMRTSPServerSession interface from the LEAD RTSP Sink filter from the graph.

• Generate a unique session ID and associate it with the ILMRTSPServerSession interface using the ILMRTSPServerSession::SessionID property. You can generate the string yourself or have the server to generate one for you using the ILMRTSPServer::GenerateNewSessionID method.

• Pass the SETUP command to ILMRTSPServerSession::HandleCommand for further processing.

When you receive a SETUP command with a session ID, you need to

• Find the capture/convert graph with that session ID. If you don't find it, return an error and let other ILMRTSPServerMedia object handle it.

• render the additional audio/video stream specified in the SETUP command

• Pass the SETUP command to ILMRTSPServerSession::HandleCommand for further processing.

When you receive a PLAY command, you need to

• Find the capture/convert graph with that session ID (the session ID must be present in the command, otherwise you can return an error). If you don't find the session with the same session ID in your list of active sessions, return an error and let other ILMRTSPServerMedia object handle it.

• Pass the command to the LEAD RTSP Sink filter for further processing by calling ILMRTSPServerSession::HandleCommand.

• Call the ILMRTSPServer::SendCommandResponse to send the response back to the client

• Start streaming the data by starting the conversion/capture process.

When you receive a PAUSE command, you need to pause the capture/conversion graph with the corresponding session ID.

When you receive a TEARDOWN command, you need to destroy the capture/conversion graph with the corresponding session ID.

In general, the LEAD RTSP Sink filter exports the ILMRTSPServerSession interface, which assists through ILMRTSPServerSession::HandleCommand in building the RTSP response.

But you still need to be familiar with the RTSP commands and responses. So you should read the "RFC 2326 - Real Time Streaming Protocol (RTSP)" specification.

See the Creating an RTSP Server using RTSP Sink topic for more information.

Returns

S_OK if successful and this Media can handle the command and the response should be sent automatically by the server

LTMM_S_RESPONSE_PENDING (0x00050048) to indicate your Media object can handle the command and that the response will be sent using the ILMRTSPServer::SendCommandResponse method.

LTMM_E_AUTHENTICATION_REQUIRED (0x8005004A) to indicate your Media object can handle the command but that authentication is required to access this stream.

Return an error code < 0 to indicate this Media object cannot handle the command. In this case, other Media objects will be given a chance to handle the command.

HRESULT FindSession(BSTR sessionID, IUnknown **ppServerSession)

Parameters

Description

The RTSP server calls this method to find a server session. You should look in your list of active sessions to find out which matches the requested session ID.

If you find it, you should store its ILMRTSPServerSession interface in ppServerSession and return S_OK.

If none of your server sessions matches the session ID, return an error and the RTSP server will look for the session ID in the next ILMRTSPServerMedia interfaces from its list.

Returns

S_OK if successful, < 0 if an error occurred.

HRESULT OnNotification(LMRTSPServerSessionNotificationType notification, IUnknown *pSession, DWORD_PTR serverSocket)

Parameters

Description

The Media object will receive notifications other than commands through the OnNotification method. The action to be taken depends on the notification, which can be as follows:

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes