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

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

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

Interface 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.

Interface Methods:

HRESULT ResetToDefaultsEx(LMRTSPServer_APILEVEL ApiLevel)

Parameters

ApiLevel

Specifies which defaults should be used by the filter.

Description

Resets the filter to default values. The ApiLevel parameter determines which default values to use. Current applications should set ApiLevel to LMRTSPServer_APILEVEL_1 = 0.

The filter might change in the future and have different properties or default behaviour. 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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_INVALIDARG

The ApiLevel parameter is invalid

HRESULT AddMedia(IUnknown *pMedia)

Parameters

pMedia

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

Description

Use this method add a ILMRTSPServerMedia interface to the list of Media objects supported by the RTSP server. 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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

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.

Description

Use this method remove one or all the ILMRTSPServerMedia interface from the list of Media objects supported by the RTSP server.

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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

Parameters

port

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

Description

This method 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").

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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

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.

Description

This method tells the RTSP server to stop listening on the specified port.

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

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

N/A

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

Parameters

sessionID

A string identifying the session ID you are looking for.

ppServerMedia

Optional pointer to the address of a 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 a IUnknown pointer that will be filled with the pointer to the ILMRTSPServerSession interface identifying the session.

Description

This method finds a session interface using the sessionID. 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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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)

Parameters

pSessionID

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

Description

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

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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

E_OUTOFMEMORY

There was not enough memory to allocate a new string.

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

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.

Description

Use this method to send a response directly to the RTSP client. 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 commandis 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

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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 socket)

Parameters

socket

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

Description

Use this method to break off the connection identified by 'socket'. This socket is the same value that was received in the ILMRTSPServerMedia::HandleMedia method.

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

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

Returns

S_OK if successful, < 0 if an error occurred.

Common Error Codes

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 20.0.2020.3.31
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2020 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help