LEADTOOLS Filters Help
| LEADTOOLS Filters Help > Filters, Codecs and Interfaces > Streaming Filters > 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 a 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 a 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
Giving information regarding a media (file, capture) you are capable of supporting in response to a RTSP DESCRIBE command
keeping a list of active sessions
creating new sessions in response to a RTSP SETUP command
starting to stream data in response to a RTSP PLAY command
pausing streaming in response to a RTSP PAUSE command
destroying sessions in response to a 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.
|
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. |
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. |
|
socket |
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 a 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 a 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 a 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 a 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.
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.
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. |
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.
