ILMRTSPServer Interface

This is the interface controlling 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.

Data Types

LMRTSPServer_APILEVEL

Summary

Lists the valid values for the ApiLevel parameter that can be passed to the ResetToDefaultsEx method.

Syntax

typedef enum 
{ 
   LMRTSPServer_APILEVEL_1 = 0,  // current version 
} LMRTSPServer_APILEVEL; 

Properties

Type Name Description
BSTR ServerURL [read-only] This read-only property can be used to retrieve the server URL. It will return a string containing the server address and a "rtsp://" prefix. You can use this string to set it as a target filename when you use the LEAD RTSP Sink filter as a sink.
long MediaCount [read-only] The number indicates the number of ILMRTSPServerMedia interfaces that were added using the AddMedia method.
IUnknown MediaItem(long index) [read-only] Get an item from the list of ILMRTSPServerMedia interfaces that were added with the AddMedia method.The index parameter is 0-based and should be <= MediaCount - 1 and indicates which item should be retrieved.The property will fail with DISP_E_BADINDEX error if index < 0 or index >= MediaCount.

Methods

HRESULT ResetToDefaultsEx(LMRTSPServer_APILEVEL ApiLevel)

Description

Resets the filter to default values.

Parameters

ApiLevel

Specifies which defaults should be used by the filter. Current applications should set ApiLevel to LMRTSPServer_APILEVEL_1 = 0.

Comments

The filter might change in the future and have different properties or default behavior. Calling this method ensures future versions of the filter will behave the same way as when the application was developed.

It is best to call ResetToDefaultsEx(LMRTSPServer_APILEVEL_1) before you start setting properties and start calling other methods for this interface.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_INVALIDARG The ApiLevel parameter is invalid.

HRESULT AddMedia(IUnknown *pMedia)

Description

Adds an ILMRTSPServerMedia interface to the list of Media objects supported by the RTSP server.

Parameters

pMedia

The ILMRTSPServerMedia interface to be added to the list of Media objects supported by the server.

Comments

The RTSP server maintains internally a list of Media interfaces. When a command is received, the RTSP server asks all the Media interfaces whether they can process the command. Each command is passed to all the Media interfaces until it finds the first interface that can handle the command. If no Media interface can handle the command, an error response is sent to the RTSP client.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_INVALIDARG The pMedia parameter is not a valid ILMRTSPServerMedia interface.
E_OUTOFMEMORY There is not enough memory to reallocate the array of interface pointers. (Very unlikely)

HRESULT RemoveMedia(IUnknown *pMedia)

Description

Removes one or all the ILMRTSPServerMedia interface from the list of Media objects supported by the RTSP server.

Parameters

pMedia

The ILMRTSPServerMedia interface to be removed to the list of Media objects supported by the server. If NULL, all Media objects are removed from the list.

Comments

It is very important to call this method before the server is freed to avoid potential problems of objects persisting in memory because of circular references. For example, the object implementing the ILMRTSPServerMedia interface might hold a reference to the ILMRTSPServer object it is freed in the destructor of the ILMRTSPServerMedia interface. But if the ILMRTSPServerMedia interface is still in the list, the destructor for the ILMRTSPServerMedia object will not get called until the destructor for the ILMRTSPServer object is called. But since a reference to ILMRTSPServer is in an inherited object, the destructor for ILMRTSPServer is not called until the ILMRTSPServerMedia is destroyed. This way, they keep each other alive forever in memory. This circular reference count is avoided if RemoveMedia(NULL) is called before freeing the ILMRTSPServer object.

So it is highly recommended that RemoveMedia(NULL) is called before freeing the ILMRTSPServer object.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_INVALIDARG The pMedia parameter is not a valid ILMRTSPServerMedia interface.
LTMM_E_ITEM_NOT_FOUND [0x80050040] The ILMRTSPServerMedia interface is not in the list.

HRESULT StartServer(long port)

Description

Tells the RTSP server to start listening on the specified port. The address used should have been set already by calling IFileSinkFilter::SetFileName(L"rtsp://ip_address").

Parameters

port

The port number on which the server should be listening for connections. The default value is 554.

Comments

The port should be available and not in use by another program (such as the Windows Media Player Network Sharing Service). Port values can be between 1 and 65535. If you choose a port number other than 554 it is recommended to use a port value above 1024. Doing so avoids conflicts with other programs that might be running on your server (many port values below 1024 are restricted for system use or for well-defined protocols such as 80 for HTTP or 554 for RTSP).

For information about running the RTSPServer demo, refer to Why Does Starting a Server on the Default RTSP Port Fail when I Run the Windows 8 RTSPServer Demo?

All Media objects that are going to be supported should be added by calling the AddMedia method.

After calling this method, the server is ready to receive RTSP commands from clients.

Call StopServer(port) to stop the server.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_INVALIDARG The port is invalid (not between 0..65535).
HRESULT_FROM_WIN32(error) [0x80070000..0x8007FFFF] A Win32 error or a Winsock WSAxxx error has occurred. Please consult the Microsoft documentation for a description of the Windows and Winsock error codes. For example, if the port is in use, the WSAEADDRINUSE (10048) Winsock error will be generated. The corresponding HRESULT for this is HRESULT_FROM_WIN32(WSAEADDRINUSE) = 80072740

HRESULT StopServer(long port)

Description

Tells the RTSP server to stop listening on the specified port.

Parameters

port

The port number on which the server should stop listening. This should be the same value that was passed to the StartServer method.

Comments

After calling this method, the server will not process any RTSP commands and any active RTSP connections are aborted.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.

HRESULT FindSession(BSTR sessionID, IUnknown **ppServerMedia, IUnknown **ppServerSession)

Description

Finds a session interface using the sessionID.

Parameters

sessionID

A string identifying the session ID you are looking for.

ppServerMedia

Optional pointer to the address of an IUnknown pointer that will be filled with the pointer to the ILMRTSPServerMedia interface serving this session. This pointer can be NULL if you don't need this information.

ppServerSession

Pointer to the address of an IUnknown pointer that will be filled with the pointer to the ILMRTSPServerSession interface identifying the session.

Comments

Typically, this method is called when an RTSP command is received with a session ID to determine which session is to handle the command. Then determine which capture or convert object corresponds to this ILMRTSPServerSession interface to start running, pause the graph, etc.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
LTMM_E_ITEM_NOT_FOUND [0x80050040] Session ID does not match any active sessions. The session ID might be invalid or it might have been destroyed due to inactivity.

HRESULT GenerateNewSessionID(BSTR *pSessionID)

Description

Generates a new session ID string. It is guaranteed to be different than any other session ID string used by active sessions.

Parameters

pSessionID

Pointer to a string that will be filled with a unique session string identifier.

Comments

Typically this method is used to generate a session ID in response to a SETUP command without a session ID parameter.

RTSP clients will normally send a SETUP command without a session ID parameter when they intend to start playing to request rendering the first stream in the media. At this point, the server is expected to create a session and assign it a session ID. The session ID should be unique and it will be used to identify it from among all the active sessions.

After that, they will typically send another SETUP command with a session ID parameter to add a second stream to the session (if there is a second stream in the media).

Once the SETUP commands are executed, the client would normally pass the PLAY command and again pass the sessionID generated earlier to identify which stream should be played.

This method can be used to generate these unique sessionID strings.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY There was not enough memory to allocate a new string.

HRESULT SendCommandResponse(IUnknown *pCommandParser, IUnknown *pResponseBuilder, DWORD_PTR socket)

Description

Sends a response directly to the RTSP client.

Parameters

pCommandParser

Pointer to a ILMRTSPCommandParser interface containing the RTSP command.

pResponseBuilder

Pointer to a ILMRTSPResponseBuilder interface containing the RTSP response.

socket

The socket on which the command was received. This will be the same socket through which the response should be sent.

Comments

The RTSP response should be completely filled in pResponseBuilder. The parameters are the ones received in the ILMRTSPServerMedia::HandleMedia method.

Normally, the RTSP response is sent by the server automatically after the ILMRTSPServerMedia::HandleMedia method returns.

But in certain situations, a response is unable to be sent immediately after ILMRTSPServerMedia::HandleMedia. In this situation, the server will need to hold the response until the response is explicitly requested.

Another situation might be if the response needs to be sent before ILMRTSPServerMedia::HandleMedia returns. For example, when the PLAY command is handled, data needs to start sending. However, if data starts sending while in ILMRTSPServerMedia::HandleMedia and let the server send the response after ILMRTSPServerMedia::HandleMedia returns, a race condition is created and data might arrive at the RTSP client before it receives the RTSP response. This is not acceptable. So, in this case, send the response with SendCommandResponse first and only after that start the conversion/capture. This way, RTSP response is sent before streaming the audio/video data is started.

Duplicating RTSP responses should be avoided. If a response is sent using the SendCommandResponse method, return LTMM_S_RESPONSE_PENDING [0x00050048] code from ILMRTSPServerMedia::HandleMedia. This special return code tells the server "my Media is capable of handling the command, don't ask any other Media about it. Also, don't send any response, because the responses will be sent directly using SendCommandResponse".

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_OUTOFMEMORY There is not enough memory to complete the command.
HRESULT_FROM_WIN32(WSAECONNRESET) [0x80072746] The connection to the client has been lost.
S_FALSE Something has gone wrong. The response may or may not have reached the client.

HRESULT CloseServerSocket(DWORD_PTR serverSocket)

Description

Breaks off the connection identified by serverSocket. This socket is the same value that was received in the ILMRTSPServerMedia::HandleMedia method.

Parameters

serverSocket

The socket on which the command was received. This will be the same socket through which the response should be sent.

Call this method to disconnect a particular client. This command closes the socket and ensures additional commands will not be received from that socket.

Typically, this method is called in response to receiving the RTSPServerSessionNotification_Timeout notification in the ILMRTSPServerMedia::OnNotification method.

Returns

Return Description
S_OK Successful.
< 0 An error occurred.
E_INVALIDARG The socket is not valid.
LTMM_E_ITEM_NOT_FOUND [0x80050040] The socket seemed valid, but it is not in the list of active connections anymore. It must have been closed through some other means.
Help Version 22.0.2023.2.15
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help

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