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

 // All rights reserved.

 // This component and the accompanying materials are made available

 // under the terms of the License "Eclipse Public License v1.0"

 // which accompanies this distribution, and is available

 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

 //

 // Initial Contributors:

 // Nokia Corporation - initial contribution.

 //

 // Contributors:

 //

 // Description:

 // \n

 // There are some operations performed on agents that do not relate directly to a particular content file. The <code>ContentAccess::CManager</code>

 // interface includes some functions that allow an application to work with a particular agent.

 // <hr>

 // Before working with one particular agent, the client will need to find out which agents are installed on the device.

 // The <code>ContentAccess::CManager::ListAgentsL()</code> function provides this list of agents. The \c F32Agent is not included in

 // the list, since it does not support any management functions.

 // The <code>ContentAccess::CAgent</code> objects in the list can be used to refer to the particular agent in subsequent 

 // function calls.

 // // Create a CManager object

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

 // RPointerArray <CAgent> theAgents;

 // // Get the list of agents

 // manager->ListAgents(theAgents);

 // // Check there is at least one agent

 // if(theAgents.Count() > 0)

 // // Find the first agent

 // CAgent& agent = theAgents[0];

 // <hr>

 // The management API allows applications to request that an agent display management

 // information on the screen.

 // The agent could present configuration settings, status or DRM rights information.

 // Each agent will have unique settings so it is not possible to display one dialog to configure all agents.

 // // Create a CManager object

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

 // RPointerArray <CAgent> theAgents;

 // // Get the list of agents

 // manager->ListAgents(theAgents);

 // // Check there is at least one agent

 // if(theAgents.Count() > 0)

 // CAgent& agent = (*theAgents)[0];

 // // Display the management information for the first agent

 // manager->DisplayManagementInfoL(agent);

 // It is possible that some agents will not support this capability and will leave with <code>KErrCANotSupported</code>. 

 // Displaying DRM rights information is only relevant for agents implementing a DRM scheme. It is expected that an Agent 

 // implementing DRM will provide some or all of the following functionality in the dialog:

 // - Display all rights objects including state (pending, valid, expired, orphaned, etc.)

 // - Display detailed information on a particular rights object (play count, validity period, the related Content object(s))

 // - Allow unwanted, expired or orphaned rights to be deleted.

 // <hr>

 // The rights management object is only relevant for agents implementing a DRM scheme. Other agents will

 // leave with <code>KErrCANotSupported</code>.

 // An application can ask a particular DRM agent to create a <code>ContentAccess::CRightsManager</code> object that can be used

 // to provide generic access to DRM rights within that agent. Since it is a generic interface

 // used by all agents, it will not be able to present all the detailed information available.

 // CRightsManager* rightsmanager;

 // // Create a CManager object

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

 // // create the rights manager object for a particular agent

 // rightsManager = manager->CreateRightsManagerL(agent);

 // To manage the rights in a more comprehensive manner the application should use the 

 // <code>ContentAccess::CManager::DisplayManagementInfoL()</code> function, where the agent can present 

 // its own comprehensive information.

 // <hr>

 // This is an extension mechanism to allow a client to perform an agent-specific function. The application will need to

 // know the extended commands that the agent supports and the format of the input and output buffers used in the command. All

 // of this is specified by the CAF agent, not the Content Access Framework.

 // The buffers allow agent specific objects to be externalized by an application, passed through CAF and internalized by the

 // agent. The same principle applies for data returned from the agent to the application.

 // TInt FancyApplicationFunctionL(CManager& aManager, CAgent& aAgent, CFancyAgentInputObject& aInputObject, CFancyAgentOutputObject& aOutputObject);

 // // Dynamic buffer to serialize aInputObject 

 // CBufFlat* inputBuffer = CBufFlat::NewL(50);

 // CleanupStack::PushL(inputBuffer);

 // // write aInputObject to the dynamic buffer

 // RBufWriteStream streamIn(*inputBuffer);

 // CleanupClosePushL(streamIn);

 // aInputObject.ExternalizeL(streamIn);

 // CleanupStack::PopAndDestroy(&streamIn);

 // // Call the agent specific function #42

 // TBuf <1000> outputBuffer;

 // User::LeaveIfError(aManager.AgentSpecificCommand(aAgent, 42 ,inputBuffer->Ptr(0), outputBuffer));

 // // Don't need the input buffer any longer

 // CleanupStack::PopAndDestroy(inputBuffer);

 // // Create a stream object to read the output buffer

 // RDesReadStream streamOut(outputBuffer);

 // CleanupClosePushL(streamOut);

 // aOutputObject.InternalizeL(streamOut);

 // CleanupStack::PopAndDestroy(&streamOut);

 // <hr>

 // 

 //

 /**

  @page CAFManageAgents Managing CAF Agents

  - @ref ListingAgents

  - @ref CAFManagementDialog

  - @ref CreatingRightsManager

  - @ref AgentSpecificCommand

  @section ListingAgents Listing the CAF Agents

  @code

  @endcode

  @section CAFManagementDialog Displaying the Agent Management Information

  @code

  @endcode

  @section CreatingRightsManager Create a DRM rights management object

  @code

  @endcode

  @section AgentSpecificCommand Agent Specific Commands

  @code

  @endcode

 */