Managing Media Servers
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/27/2008
The Media Query Engine (MQE) supports multiple media servers on a local network. The MQE allows an application to enumerate all locally available servers and select one of them to be the source of media content.
The MQE internally maintains a list of UPnP media servers that it has discovered. The MQE notifies the host application about new server discoveries. The user can choose any of the available servers to be the source of media content using the user interface provided by the host application.
Changing the Maximum Number of Media Servers
If you are running your networked media device on a subnet that has many media servers, you can change the entry NumMaxServers in the MQE registry to list more than the default maximum number of servers, which is 10.
HKEY_LOCAL_MACHINE\Software\MediaQueryEngine\NumMaxServers
Starting and Stopping the Media Query Engine
The Initialize and Start steps bring the MQE to the Running state where the MQE is fully functional.
The following table shows the states of the MQE.
| State | Description |
|---|---|
Un-Initialized |
No memory is allocated. |
Stopped |
Allocated memory supports event sink registration. |
Running |
Actively searching for UPnP servers, delivering events, and making media queries as requested. |
Error |
An error was encountered during state transition (for example, memory allocation error). |
The following code sample demonstrates how to start the MQE:
If( MediaQueryEn[gine_t::Initialize() )
{
MediaQueryEngine_t::AddSink( <Your MQE Sink > );
if( MediaQueryEngine_t::Start() )
{
//MQE is Running – CreateNewQuery, KnownMediaServers
}
else
{
//Try freeing some memory, uninitialize MQE and initialize and try
//again
}
}
Else
{
//Try freeing some memory, uninitialize MQE and try again
}
The following code sample demonstrates how to stop the MQE:
void Main_t::UnInitMQELib()
{
MediaQueryEngine_t::Stop();
//Release MQE related resources
delete[] m_ItemBatches;
delete[] m_SavedQueries;
MediaQueryEngine_t::UnInitialize();
}
Getting Server Information
Users call the KnownMediaServers function to access media server information. This information is returned as a ServerInfoCollection object. You can iterate over the collection to get specific information.
Void Settings_t::ShowAllKnownMediaServers()
{
m_ServerInfoCollection = MediaQueryEngine_t::KnownMediaServers();
for( int Index=0; Index< m_ServerInfoColection.TotalServers(); ++Index)
{
ServerInfo_t Sinfo = m_ServerInfoCollection.GetServerInfo( Index );
// Call Sinfo.UniqueDeviceName(), Sinfo.FriendlyDeviceName(),
//Sinfo.DeviceStatus() to get the information to display
//Provides means for end user to activate one of the attached
//servers
}
}
Void Settings_t::UserSelectedOptionToActivateAServer(int ServerIndex)
{
ServerInfo_t Sinfo = m_ServerInfoCollection.GetServerInfo(ServerIndex);
Sinfo.Activate();
//Return value of Activate would indicate if the operation
//was successful.
//MQE will send ActiveServerChanged notification if the requested
//server is activated
}
Managing Content Metadata
In UPnP terminology, the MQE acts as a control point. The MQE searches for UPnP media servers and provides a networked media device metadata about available media. One of the metadata is the URL for the media item. Using the URL, you can stream or download media content and play it on your device.
Note
There is a limit of 260 characters for streaming media URLs.
Managing Event Notifications
The MQE provides the host application with information about changes in network status, device authorization, and server status by means of events. When a UPnP server becomes unavailable, the MQE informs the host application about the loss of the server. Also, when content on the server changes, the MQE notifies the host application about the change.
The MQE registers with the selected media server to receive this information.
To receive the events, you call the method AddSink. To stop receiving the events you call the method RemoveSink.
Class UserSink_t:public QueryEngineSink_t
{
void
SinkProc(
QueryEngineEvents_e event
long AdditionalInfo
)
{
<Your Code>
}
}
Queries
Each query session with a media server is represented as a MediaQuery object. The query object does memory management for the data that is retrieved from the media server. Each item in the media library is represented as a MediaItem_t object, allowing access to the content's metadata.
The result of a query can be 10,000 or more media items. In order to use memory and network resources efficiently and have a good response time, the MQE downloads result sets in batches. A batch is represented by the MediaItemBatch_t object.
You call the function CreateNewQuery to get media data. The resulting data is organized in batches. You call the method GetNextBatch on the MediaQuery object to get a batch of media items. Calling the method GetMediaItem on the MediaItemBatch object returns a MediaItem object. This is demonstrated in the following code:
Void GetData_t::GetAllMusicData( )
{
QueryParams_t QueryParam(Music,
SearchBy_None,
NULL,SortBy_None,
s_BatchSize);
m_CurrentQuery = MediaQueryEngine_t::CreateNewQuery(QueryParam);
if( m_CurrentQuery.IsValid() )
{
//Display number of results – m_CurrentQuery.TotalItems()
//Use m_CurrentQuery.GetNextBatch() to retrieve a media item batch
}
}
Void GetData_t::ShowQueryResult()
{
MediaItemBatch_t CurrentBatch = m_CurrentQuery.GetNextBatch();
for( int Index=0; Index < CurrentBatch.TotalItems(); ++Index )
{
MediaItem_t MediaItem = CurrentBatch.GetMediaItem(Index);
if( MediaItem.GetItemAttribute(Attr_Title,
<Your Buffer>,
<Your Buffer Length>)
{
SendMessage(m_ListBox, LB_INSERTSTRING, <Your Buffer>, -1 );
}
else
{
//check buffer length
}
}
}