LEADTOOLS Filters Help
| LEADTOOLS Filters Help > Filters, Codecs and Interfaces > Streaming Filters > ILMRTSPServer Interface |
This is the interface controlling 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.
|
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. |
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.
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 |
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) |
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. |
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 |
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
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 a 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 doesn't match any active sessions. The session ID might be invalid or it might have been destroyed due to inactivity. |
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. |
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. |
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. |
