sl@0: // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // <hr>
sl@0: // It should be assumed that it is only possible for CAF agents to display 
sl@0: // dialogs on screen if the CAF function is called from a thread where
sl@0: // a static Uikon environment exists.
sl@0: // <hr>
sl@0: // CAF provides several APIs that allow a client application to request an agent to
sl@0: // display information on the screen. Some agents may not support these calls and leave 
sl@0: // with \c KErrCANotSupported.
sl@0: // Both the <code>ContentAccess::CContent::DisplayInfoL()</code> function and the 
sl@0: // <code>ContentAccess::CManager::DisplayInfoL()</code> function allow the application 
sl@0: // to display file information such as last modification date and/or DRM rights information
sl@0: // CManager *manager = CManager::NewL();
sl@0: // manager->DisplayInfoL(EFileProperties, avirtualPath);
sl@0: // Applications can also ask a particular agent to go into management mode, displaying configuration 
sl@0: // information on screen, allowing the user to view and set agent specific information.
sl@0: // // create manager
sl@0: // CManager *manager = CManager::NewL();
sl@0: // // Get a list of the agents
sl@0: // RPointerArray <CAgent> theAgents;
sl@0: // manager->ListAgentsL(theAgents);
sl@0: // // Display management info for the first agent
sl@0: // manager->DisplayManagementInfoL(*theAgents[0]);
sl@0: // <hr> 
sl@0: // The agents will display errors on screen when they occur. Once the error has been acknowledged by the user
sl@0: // the agent will return the error code to the client application.
sl@0: // If a client application does not want errors displayed on screen, it can request to disable the agent UI 
sl@0: // using the <code>SetProperty()</code> functions, e.g. <code>ContentAccess::CContent::SetProperty()</code>. 
sl@0: // The agent may ignore this request and still present dialogs on screen.
sl@0: // CContent *content = CContent::NewL(URI);
sl@0: // // Disable UI
sl@0: // content->SetProperty(EAgentPropertyAgentUI , 0);
sl@0: // // Open CData 
sl@0: // CData *data = content->OpenContentL(EPlay, uniqueId);
sl@0: // <hr> 
sl@0: // Some agents may present confirmation dialogs to the user before allowing them to perform certain operations. A 
sl@0: // good example would be when an application tries to delete a DRM protected file. The user may have been purchased the
sl@0: // content and may have inadvertently pressed delete. The agent can present a dialog asking "are you sure?"
sl@0: // The agent can then return the outcome of the delete to the application, i.e. \c KErrCancel, if the user presses cancel.
sl@0: // The application can use the same <code>SetProperty()</code> as above to disable these dialogs, but some agents may ignore that 
sl@0: // request and display the dialogs regardless.
sl@0: // <hr>
sl@0: // The default implementation of the <code>F32AgentUI.DLL</code> does not do anything. If licensees want the
sl@0: // \c F32Agent to display information on the screen they should replace the existing <code>F32AgentUI.DLL</code>
sl@0: // with one that does support display functions.
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @page CAFUI CAF and the User Interface
sl@0:  - @ref UikonEnv
sl@0:  - @ref AppDisplay
sl@0:  - @ref UIErr
sl@0:  - @ref UIConfirmation
sl@0:  - @ref F32AgentUi
sl@0:  @section UikonEnv Uikon Environment
sl@0:  @section AppDisplay Applications asking the agent to display information
sl@0:  @code
sl@0:  @endcode
sl@0:  @code
sl@0:  @endcode
sl@0:  @section UIErr Error Handling
sl@0:  @code
sl@0:  @endcode
sl@0:  @section UIConfirmation Confirmation Dialogs
sl@0:  @section F32AgentUi F32 Agent UI
sl@0: */