1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Symbian Foundation License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // <hr>

    15 // It should be assumed that it is only possible for CAF agents to display 

    16 // dialogs on screen if the CAF function is called from a thread where

    17 // a static Uikon environment exists.

    18 // <hr>

    19 // CAF provides several APIs that allow a client application to request an agent to

    20 // display information on the screen. Some agents may not support these calls and leave 

    21 // with \c KErrCANotSupported.

    22 // Both the <code>ContentAccess::CContent::DisplayInfoL()</code> function and the 

    23 // <code>ContentAccess::CManager::DisplayInfoL()</code> function allow the application 

    24 // to display file information such as last modification date and/or DRM rights information

    25 // CManager *manager = CManager::NewL();

    26 // manager->DisplayInfoL(EFileProperties, avirtualPath);

    27 // Applications can also ask a particular agent to go into management mode, displaying configuration 

    28 // information on screen, allowing the user to view and set agent specific information.

    29 // // create manager

    30 // CManager *manager = CManager::NewL();

    31 // // Get a list of the agents

    32 // RPointerArray <CAgent> theAgents;

    33 // manager->ListAgentsL(theAgents);

    34 // // Display management info for the first agent

    35 // manager->DisplayManagementInfoL(*theAgents[0]);

    36 // <hr> 

    37 // The agents will display errors on screen when they occur. Once the error has been acknowledged by the user

    38 // the agent will return the error code to the client application.

    39 // If a client application does not want errors displayed on screen, it can request to disable the agent UI 

    40 // using the <code>SetProperty()</code> functions, e.g. <code>ContentAccess::CContent::SetProperty()</code>. 

    41 // The agent may ignore this request and still present dialogs on screen.

    42 // CContent *content = CContent::NewL(URI);

    43 // // Disable UI

    44 // content->SetProperty(EAgentPropertyAgentUI , 0);

    45 // // Open CData 

    46 // CData *data = content->OpenContentL(EPlay, uniqueId);

    47 // <hr> 

    48 // Some agents may present confirmation dialogs to the user before allowing them to perform certain operations. A 

    49 // good example would be when an application tries to delete a DRM protected file. The user may have been purchased the

    50 // content and may have inadvertently pressed delete. The agent can present a dialog asking "are you sure?"

    51 // The agent can then return the outcome of the delete to the application, i.e. \c KErrCancel, if the user presses cancel.

    52 // The application can use the same <code>SetProperty()</code> as above to disable these dialogs, but some agents may ignore that 

    53 // request and display the dialogs regardless.

    54 // <hr>

    55 // The default implementation of the <code>F32AgentUI.DLL</code> does not do anything. If licensees want the

    56 // \c F32Agent to display information on the screen they should replace the existing <code>F32AgentUI.DLL</code>

    57 // with one that does support display functions.

    58 // 

    59 //

    60 

    61 

    62 

    63 /**

    64  @page CAFUI CAF and the User Interface

    65  - @ref UikonEnv

    66  - @ref AppDisplay

    67  - @ref UIErr

    68  - @ref UIConfirmation

    69  - @ref F32AgentUi

    70  @section UikonEnv Uikon Environment

    71  @section AppDisplay Applications asking the agent to display information

    72  @code

    73  @endcode

    74  @code

    75  @endcode

    76  @section UIErr Error Handling

    77  @code

    78  @endcode

    79  @section UIConfirmation Confirmation Dialogs

    80  @section F32AgentUi F32 Agent UI

    81 */