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

*/