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:

Type

Name

Description

long

SessionCount

Read-only property indicating how many sessions are active in this Media object.

IUnknown

SessionItem(long index)

Read-only property which retrieves a ILMRTSPServerSession interface from the active session list.

Interface Methods:

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

Parameters

pServer

Pointer to the ILMRTSPServer interface that has received this command.

pCommandParser

Pointer to the ILMRTSPCommandParser interface containing the command.

pResponseBuilder

Pointer to the ILMRTSPResponseBuilder interface that will contain the response.

serverSocket

Pointer to the socket object that received the command. The same socket object will be used to send the response.

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

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

When you receive a PLAY command, you need to

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

sessionID

A string containing the session ID to find.

ppServerSession

Pointer to a variable that should be filled with the ILMRTSPServerSession interface identifying the server session.

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

notification

Indicates the notification type

pSession

Pointer to a ILMRTSPServerSession interface identifying the server session. It can be NULL if there is no server session associated with the notification.

serverSocket

The socket on which commands for this session are received or sent. It can be NULL if there is no server socket associated with the notification.

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:

Notification type

What it means and what you should do

RTSPServerSessionNotification_Timeout

[1] The session has been inactive for a period longer than the amount specified with the ILMRTSPServerSession::Timeout property. Note that it is the Media object that sets the value of this property.

pSession indicates which ILMRTSPServerSession session has timed out and serverSocket indicates which server socket receives the RTSP commands and sends the RTSP responses for this connection.

The recommended action is to close the connection and close the server socket by calling ILMRTSPServer::CloseServerSocket(serverSocket). The RTSP client can reconnect if it wishes to issue more RTSP commands. You should close inactive connections to reclaim memory and resources used by connections that might never be used again. If you don't do so, inactive connections can use up all available memory and you won't able to serve any new clients.

RTSPServerSessionNotification_Removed

[2] Your media object has been removed from the server.

pSession and serverSocket will be NULL and should be ignored.

This is sent by the server when ILMRTSPServer::RemoveMedia method has been called.

It is recommended you free up any active connections.

RTSPServerSessionNotification_ServerStopped

[3] The server has been stopped.

pSession and serverSocket will be NULL and should be ignored.

This is sent by the server in when ILMRTSPServer::StopServer method has been called.

It is recommended you free up any active connections.

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_INVALIDARG

pSession is not NULL and is not valid.

Help Version 21.0.2021.7.2
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2021 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2021 LEAD Technologies, Inc. All Rights Reserved.