# HG changeset patch # User Sampo Huttunen # Date 1288779480 -7200 # Node ID b4d83ea1d6e2beeb6977a8c1719bbdf2d9a4ddb1 # Parent 08b5eae9f9ffc7175cfa4a2065a396e59873a13b Added comments to the example application diff -r 08b5eae9f9ff -r b4d83ea1d6e2 dlnasrv_exampleapp/src/exampleappengine.cpp --- a/dlnasrv_exampleapp/src/exampleappengine.cpp Wed Nov 03 11:45:09 2010 +0200 +++ b/dlnasrv_exampleapp/src/exampleappengine.cpp Wed Nov 03 12:18:00 2010 +0200 @@ -22,6 +22,13 @@ /*! /class ExampleAppEngine /brief Implements the playback engine and DLNA interface for the UI. + In general this class calls the private implementation functions for + a minimal implementation required to enable media rendering on a + DLNA rendering device. + + For a real application implementing this functionality, more robust + error handling should be applied, this version mostly relies on the + function calls to return succesfully. */ /*! @@ -48,10 +55,7 @@ } /*! - description - - /a - /return + Checks for connected IAP. */ void ExampleAppEngine::construct() { @@ -64,10 +68,7 @@ } /*! - description - - /a - /return + Returns the id of the currently connected IAP. */ int ExampleAppEngine::getIap() const { @@ -84,10 +85,7 @@ } /*! - description - - /a - /return + Returns the name of the currently connected IAP */ QString ExampleAppEngine::getIapName() const { @@ -104,10 +102,8 @@ } /*! - description - - /a - /return + Returns a boolean describing whether the selected renderer + supports seek functionality. */ bool ExampleAppEngine::isSeekSupported() const { @@ -124,10 +120,7 @@ } /*! - description - - /a - /return + Returns the playback state of the selected renderer. */ int ExampleAppEngine::getPlaybackState() const { @@ -144,10 +137,8 @@ } /*! - description - - /a - /return + Returns a boolean describing whether the selected renderer + supports pause functionality. */ bool ExampleAppEngine::isPauseSupported() const { @@ -164,10 +155,8 @@ } /*! - description - - /a - /return + Initiate renderer search. Each renderer found from the current + IAP will cause a renderingDeviceFound() signal to be emitted */ void ExampleAppEngine::searchRenderingDevices() { @@ -180,10 +169,10 @@ } /*! - description - - /a - /return + Prepares the renderer for accepting further commands. When this function + returns, there should be a rendering session opened to the renderer whose + uuid was passed in /a uuid. + */ void ExampleAppEngine::prepareRenderingDevice(const QString &uuid) { @@ -196,10 +185,10 @@ } /*! - description - - /a - /return + Calls the private implementation of the engine, which will cause + the /a file to be shared as a DLNA item on the local push server. + When the file is ready to be shared, an initComplete() signal is + emitted. */ int ExampleAppEngine::initFile(const QString& file) { @@ -216,10 +205,7 @@ } /*! - description - - /a - /return + Issues the play() command to the renderer. */ void ExampleAppEngine::play() { @@ -232,10 +218,7 @@ } /*! - description - - /a - /return + Issues the pause() command to the renderer. */ void ExampleAppEngine::pause() { @@ -248,10 +231,7 @@ } /*! - description - - /a - /return + Issues the stop() command to the renderer. */ void ExampleAppEngine::stop() { @@ -264,10 +244,7 @@ } /*! - description - - /a - /return + Issues the volumeUp() command to the renderer. */ void ExampleAppEngine::volumeUp() { @@ -280,10 +257,7 @@ } /*! - description - - /a - /return + Issues the volumeDown() command to the renderer. */ void ExampleAppEngine::volumeDown() { @@ -296,10 +270,7 @@ } /*! - description - - /a - /return + Issues the rew() command to the renderer. */ void ExampleAppEngine::rew() { @@ -312,10 +283,7 @@ } /*! - description - - /a - /return + Issues the ff() command to the renderer. */ void ExampleAppEngine::ff() { diff -r 08b5eae9f9ff -r b4d83ea1d6e2 dlnasrv_exampleapp/src/exampleappengine_p.cpp --- a/dlnasrv_exampleapp/src/exampleappengine_p.cpp Wed Nov 03 11:45:09 2010 +0200 +++ b/dlnasrv_exampleapp/src/exampleappengine_p.cpp Wed Nov 03 12:18:00 2010 +0200 @@ -35,6 +35,10 @@ /*! /class ExampleAppEnginePrivate /brief Implements interface to Symbian side DLNA APIs. + + This is the "rendering engine" class, implementing various UPnP callback + interfaces. Some of the callbacks are lacking implementation because this + simple example application does not require all that functionality. */ /*! @@ -98,10 +102,7 @@ } /*! - description - - /a - /return + Checks for connected IAP. */ void ExampleAppEnginePrivate::construct() { @@ -112,10 +113,7 @@ } /*! - description - - /a - /return + Returns currently connected IAP. */ int ExampleAppEnginePrivate::getConnectedIap() const { @@ -125,10 +123,7 @@ } /*! - description - - /a - /return + Returns the name of the currently connected IAP. */ QString ExampleAppEnginePrivate::getConnectedIapName() const { @@ -138,10 +133,7 @@ } /*! - description - - /a - /return + Returns the current playback state. */ int ExampleAppEnginePrivate::getPlaybackState() const { @@ -151,10 +143,7 @@ } /*! - description - - /a - /return + Returns whether the currently selected renderer supports seek functionality. */ bool ExampleAppEnginePrivate::isSeekSupported() const { @@ -166,10 +155,7 @@ } /*! - description - - /a - /return + Returns whether the currently selected renderer supports pause functionality. */ bool ExampleAppEnginePrivate::isPauseSupported() const { @@ -186,10 +172,11 @@ } /*! - description - - /a - /return + This function causes renderingDeviceFound() signals to be emitted in two different ways: + first the current device list in UPnP AV Controller is gone through and for each + renderer device found from there one signal is emitted. Also, this object is set as a + device observer to the UPnP AV Controller, causing it to call this class's callback + function UPnPDeviceDiscovered() upon every new device that is discovered from the current network. */ void ExampleAppEnginePrivate::searchRenderingDevices() { @@ -214,10 +201,7 @@ } /*! - description - - /a - /return + Start a rendering session with the renderer provided in /a uuid. */ void ExampleAppEnginePrivate::prepareRenderingDevice(const QString &uuid) { @@ -227,10 +211,7 @@ } /*! - description - - /a - /return + Start file initialization for sharing. */ int ExampleAppEnginePrivate::initFile(const QString& file) { @@ -242,10 +223,7 @@ } /*! - description - - /a - /return + Issues the play() command to the renderer. */ void ExampleAppEnginePrivate::play() { @@ -255,10 +233,7 @@ } /*! - description - - /a - /return + Issues the pause() command to the renderer. */ void ExampleAppEnginePrivate::pause() { @@ -268,10 +243,7 @@ } /*! - description - - /a - /return + Issues the stop() command to the renderer. */ void ExampleAppEnginePrivate::stop() { @@ -281,10 +253,7 @@ } /*! - description - - /a - /return + Issues the volumeUp() command to the renderer. */ void ExampleAppEnginePrivate::volumeUp() { @@ -294,10 +263,7 @@ } /*! - description - - /a - /return + Issues the volumeDown() command to the renderer. */ void ExampleAppEnginePrivate::volumeDown() { @@ -307,10 +273,7 @@ } /*! - description - - /a - /return + Issues the rew() command to the renderer. */ void ExampleAppEnginePrivate::rew() { @@ -320,10 +283,7 @@ } /*! - description - - /a - /return + Issues the ff() command to the renderer. */ void ExampleAppEnginePrivate::ff() { @@ -332,11 +292,10 @@ // TODO: implement } -/*! - description - - /a - /return +/*! + Callback function that UPnP AV Controller calls when a new UPnP AV Device is + found from the network. + From MUPnPAVDeviceObserver */ void ExampleAppEnginePrivate::UPnPDeviceDiscovered(const CUpnpAVDevice& aDevice) { @@ -346,10 +305,9 @@ } /*! - description - - /a - /return + Callback function that UPnP AV Controller calls when a UPnP AV Device has + disappeared from the network. + From MUPnPAVDeviceObserver */ void ExampleAppEnginePrivate::UPnPDeviceDisappeared(const CUpnpAVDevice& aDevice) { @@ -389,10 +347,10 @@ } /*! - description - - /a - /return + Callback function that UPnP AV Controller calls when the WLAN + connection has been lost. All existing sessions should be considered + invalid. + From MUPnPAVDeviceObserver */ void ExampleAppEnginePrivate::WLANConnectionLost() { @@ -402,10 +360,8 @@ } /*! - description - - /a - /return + Just pass to volume state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::VolumeResult(TInt aError, TInt aVolumeLevel, @@ -420,10 +376,8 @@ } /*! - description - - /a - /return + Just pass to volume state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::MuteResult(TInt aError, TBool aMute, @@ -438,10 +392,8 @@ } /*! - description - - /a - /return + Just pass to rendering state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::InteractOperationComplete(TInt aError, TUPnPAVInteractOperation aOperation) @@ -455,10 +407,8 @@ } /*! - description - - /a - /return + Just pass to rendering state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::PositionInfoResult(TInt aError, const TDesC8& aTrackPosition, @@ -473,10 +423,8 @@ } /*! - description - - /a - /return + Just pass to rendering state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::SetURIResult(TInt aError) { @@ -489,10 +437,8 @@ } /*! - description - - /a - /return + Just pass to rendering state machine + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::SetNextURIResult(TInt aError) { @@ -505,10 +451,9 @@ } /*! - description - - /a - /return + Renderer to which there was an active session has disappeared. The session should be + considered invalid. + From MUPnPAVRenderingSessionObserver */ void ExampleAppEnginePrivate::MediaRendererDisappeared(TUPnPDeviceDisconnectedReason /*aReason*/) { @@ -518,10 +463,9 @@ } /*! - description - - /a - /return + Callback for telling that the rendering state machine is in synch with + the rendering device. + From MUpnpRenderingStateMachineObserver */ void ExampleAppEnginePrivate::RendererSyncReady(TInt /*aError*/, Upnp::TState /*aState*/) { @@ -531,10 +475,8 @@ } /*! - description - - /a - /return + Rendering device's state has been changed. + From MUpnpRenderingStateMachineObserver */ void ExampleAppEnginePrivate::RenderingStateChanged(TInt aError, Upnp::TState aState, @@ -578,10 +520,9 @@ } /*! - description - - /a - /return + For synchronizing UI with the progress of the playback on the + rendering device. + From MUpnpRenderingStateMachineObserver */ void ExampleAppEnginePrivate::PositionSync(TInt /*aError*/, Upnp::TPositionMode /*aMode*/, @@ -594,10 +535,9 @@ } /*! - description - - /a - /return + Callback for telling that the volume state machine is in synch with + the rendering device. + From MUpnpVolumeStateMachineObserver */ void ExampleAppEnginePrivate::VolumeSyncReady(TInt /*aError*/) { @@ -607,10 +547,8 @@ } /*! - description - - /a - /return + Rendering device's volume has changed. + From MUpnpVolumeStateMachineObserver */ void ExampleAppEnginePrivate::VolumeChanged(TInt /*aError*/, TInt /*aVolume*/, @@ -622,10 +560,8 @@ } /*! - description - - /a - /return + Mute status of the rendering device has changed. + From MUpnpVolumeStateMachineObserver */ void ExampleAppEnginePrivate::MuteChanged(TInt /*aError*/, TBool /*aMuteState*/, @@ -637,10 +573,8 @@ } /*! - description - - /a - /return + Resolving a file as an URI to be shared on media server has been completed. + From MUPnPItemResolverObserver */ void ExampleAppEnginePrivate::ResolveComplete(const MUPnPItemResolver& /*aResolver*/, TInt aError) @@ -653,10 +587,8 @@ } /*! - description - - /a - /return + WLAN connection has been lost. + From MUPnPConnectionMonitorObserver */ void ExampleAppEnginePrivate::ConnectionLost(TBool /*aUserOriented*/) { @@ -672,10 +604,8 @@ } /*! - description - - /a - /return + WLAN connection has been created. + From MUPnPConnectionMonitorObserver */ void ExampleAppEnginePrivate::ConnectionCreated(TInt /*aConnectionId*/) { @@ -689,10 +619,8 @@ } /*! - description - - /a - /return + Iterate through the AV Devices of the UPnP AV Controller, + i.e. the already found devices stored in the AV Controller. */ void ExampleAppEnginePrivate::searchRenderingDevicesL() { @@ -711,10 +639,8 @@ } /*! - description - - /a - /return + Iterate through found AV Devices, and signal renderingDeviceFound() + for each renderer. */ void ExampleAppEnginePrivate::upnpDeviceDiscoveredL(const CUpnpAVDevice& aDevice) { @@ -753,10 +679,8 @@ } /*! - description - - /a - /return + Ensure that there is an active rendering session for the device + passed in as /a uuid. */ void ExampleAppEnginePrivate::prepareRenderingDeviceL(const QString &uuid) { @@ -798,10 +722,9 @@ } /*! - description - - /a - /return + Start rendering session to /a device. Rendering state machine and + volume state machine will call observer interface once they are in + synch. */ void ExampleAppEnginePrivate::startRenderingSessionL(const CUpnpAVDevice &device) { @@ -823,10 +746,7 @@ } /*! - description - - /a - /return + Stop rendering session and perform needed cleanup. */ void ExampleAppEnginePrivate::stopRenderingSession() { @@ -858,10 +778,12 @@ } /*! - description - - /a - /return + Start file initialization for sharing. If a renderer device is selected, + instruct local item resolver to to resolve the /a file passed as a + parameter, i.e. prepare the URI that can be used to locate the shared + file on the push server. When resolving is done, the callback function + ResolveComplete() is called. + */ void ExampleAppEnginePrivate::initFileL(const QString &file) { @@ -887,10 +809,7 @@ } /*! - description - - /a - /return + Check if it's ok to issue playback commands. */ bool ExampleAppEnginePrivate::isReadyForPlayback() const { @@ -910,10 +829,7 @@ } /*! - description - - /a - /return + Issues the play command to the renderer. */ void ExampleAppEnginePrivate::playL() { @@ -930,10 +846,7 @@ } /*! - description - - /a - /return + Issues the pause command to the renderer. */ void ExampleAppEnginePrivate::pauseL() { @@ -958,10 +871,7 @@ } /*! - description - - /a - /return + Issues the stop command to the renderer. */ void ExampleAppEnginePrivate::stopL() { @@ -978,10 +888,9 @@ } /*! - description - - /a - /return + Check that there is an active connection and store that IAP for further + usage. Note that there is no functionality in this application to + initialize connection setup, if no active connection exists. */ void ExampleAppEnginePrivate::resolveIapL() { @@ -1022,10 +931,8 @@ } /*! - description - - /a - /return + Resolve the IAP name that's stored in UPnP Settings Engine as the + currently active IAP. */ void ExampleAppEnginePrivate::resolveIapNameL() { @@ -1041,10 +948,7 @@ } /*! - description - - /a - /return + Helper function for Symbian descriptor to Qt string conversion. */ QString ExampleAppEnginePrivate::asString(const TDesC &desc) const { @@ -1052,10 +956,7 @@ } /*! - description - - /a - /return + Helper function for Symbian descriptor to Qt string conversion. */ QString ExampleAppEnginePrivate::asString8(const TDesC8 &desc) const { diff -r 08b5eae9f9ff -r b4d83ea1d6e2 dlnasrv_exampleapp/src/exampleappui.cpp --- a/dlnasrv_exampleapp/src/exampleappui.cpp Wed Nov 03 11:45:09 2010 +0200 +++ b/dlnasrv_exampleapp/src/exampleappui.cpp Wed Nov 03 12:18:00 2010 +0200 @@ -31,6 +31,24 @@ /*! \class ExampleAppUi \brief Implements the application UI for Dlnasrv example application. + + The application provides a simple UI for selecting a renderer device + (from a connected WLAN AP, if none is connected that needs to be done + outside the application UI) and selecting a file to be rendered and + control buttons for controlling the playback on the renderer device. + + So the first step is to have a WLAN connection active. Only then the + renderer search and selection can be done. + + The next step is to select a rendering device. When rendering device + search is initiated, the underlying UPnP AV control server is queried + for existing renderers. Also all new renderers appearing in the AP + get signalled with renderingDeviceFound() + + When a renderer is selected, the next step is to select a file to be + pushed to the renderer. When selecting a file, it gets published in + the push server as a DLNA item. When that is done, the controls for + playback are enabled and the renderer can be controlled with those. */ /*! @@ -64,10 +82,8 @@ } /*! - description - - /a - /return + Creates application engine and the UI. Also the state of the WLAN AP + connection gets queried and updated on the UI. */ void ExampleAppUi::construct() { @@ -78,10 +94,7 @@ } /*! - description - - /a - /return + Creates the UI components. */ void ExampleAppUi::createUi() { @@ -117,10 +130,7 @@ } /*! - description - - /a - /return + Creates the UI for showing and selecting WLAN AP connection status. */ QLayout *ExampleAppUi::createApSelectionUi() { @@ -152,10 +162,7 @@ } /*! - description - - /a - /return + Creates the UI for showing and selecting renderer device. */ QLayout *ExampleAppUi::createRendererSelectionUi() { @@ -201,10 +208,7 @@ } /*! - description - - /a - /return + Creates the UI for showing and selecting media file to be rendered. */ QLayout *ExampleAppUi::createFileSelectionUi() { @@ -242,10 +246,7 @@ } /*! - description - - /a - /return + Creates the push buttons for controlling the playback. */ QLayout *ExampleAppUi::createPlaybackUi() { @@ -299,10 +300,7 @@ } /*! - description - - /a - /return + Creates the application engine and resolves the current connection status. */ void ExampleAppUi::createEngine() { @@ -320,10 +318,7 @@ } /*! - description - - /a - /return + This function gets called by the engine, when the renderer changes its state. */ void ExampleAppUi::updateState(int newState) { @@ -360,10 +355,9 @@ } /*! - description - - /a - /return + Launches QFile dialog for selecting a media file from the local + file system. Then the file is sent to the engine for sharing, i.e. + it will get resolved as an URI on the UPnP push server. */ void ExampleAppUi::selectFile() { @@ -407,10 +401,7 @@ } /*! - description - - /a - /return + Shows searching string on UI during search if no renderers are found yet. */ void ExampleAppUi::deviceSearchStarted() { @@ -423,10 +414,7 @@ } /*! - description - - /a - /return + Adds a renderer to the UI's model. */ void ExampleAppUi::addRenderingDevice(const QString &name, const QString &uuid) { @@ -436,10 +424,7 @@ } /*! - description - - /a - /return + Removes a renderer from the UI's model. */ void ExampleAppUi::removeRenderingDevice(const QString &/*name*/, const QString &uuid) { @@ -458,10 +443,7 @@ } /*! - description - - /a - /return + Set the renderer selected from the UI as the current renderer on the engine side. */ void ExampleAppUi::selectRenderingDevice(int index) { @@ -478,10 +460,8 @@ } /*! - description - - /a - /return + Enables/disables the pushbuttons for renderer control according to the + current state. */ void ExampleAppUi::enablePlayback(int result) { @@ -536,10 +516,7 @@ } /*! - description - - /a - /return + Disables all renderer control pushbuttons. */ void ExampleAppUi::disablePlayback() { @@ -553,10 +530,7 @@ } /*! - description - - /a - /return + Enables file selection button. Called when a renderer is selected. */ void ExampleAppUi::enableFileSelection() { @@ -566,10 +540,7 @@ } /*! - description - - /a - /return + Disables file selection. */ void ExampleAppUi::disableFileSelection() { @@ -579,10 +550,7 @@ } /*! - description - - /a - /return + Enables the rendering device selection pushbutton. Called when a WLAN AP is in use. */ void ExampleAppUi::enableRenderingDeviceSelection(int iap) { @@ -596,10 +564,7 @@ } /*! - description - - /a - /return + Disables the rendering device selection pushbutton. */ void ExampleAppUi::disableRenderingDeviceSelection() {