--- 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()
 {

--- 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
 {

--- 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()
 {