os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/HowToManageAgents.dox
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/HowToManageAgents.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,114 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// \n
1.18 +// There are some operations performed on agents that do not relate directly to a particular content file. The <code>ContentAccess::CManager</code>
1.19 +// interface includes some functions that allow an application to work with a particular agent.
1.20 +// <hr>
1.21 +// Before working with one particular agent, the client will need to find out which agents are installed on the device.
1.22 +// The <code>ContentAccess::CManager::ListAgentsL()</code> function provides this list of agents. The \c F32Agent is not included in
1.23 +// the list, since it does not support any management functions.
1.24 +// The <code>ContentAccess::CAgent</code> objects in the list can be used to refer to the particular agent in subsequent
1.25 +// function calls.
1.26 +// // Create a CManager object
1.27 +// CManager* manager = CManager::NewL();
1.28 +// RPointerArray <CAgent> theAgents;
1.29 +// // Get the list of agents
1.30 +// manager->ListAgents(theAgents);
1.31 +// // Check there is at least one agent
1.32 +// if(theAgents.Count() > 0)
1.33 +// // Find the first agent
1.34 +// CAgent& agent = theAgents[0];
1.35 +// <hr>
1.36 +// The management API allows applications to request that an agent display management
1.37 +// information on the screen.
1.38 +// The agent could present configuration settings, status or DRM rights information.
1.39 +// Each agent will have unique settings so it is not possible to display one dialog to configure all agents.
1.40 +// // Create a CManager object
1.41 +// CManager* manager = CManager::NewL();
1.42 +// RPointerArray <CAgent> theAgents;
1.43 +// // Get the list of agents
1.44 +// manager->ListAgents(theAgents);
1.45 +// // Check there is at least one agent
1.46 +// if(theAgents.Count() > 0)
1.47 +// CAgent& agent = (*theAgents)[0];
1.48 +// // Display the management information for the first agent
1.49 +// manager->DisplayManagementInfoL(agent);
1.50 +// It is possible that some agents will not support this capability and will leave with <code>KErrCANotSupported</code>.
1.51 +// Displaying DRM rights information is only relevant for agents implementing a DRM scheme. It is expected that an Agent
1.52 +// implementing DRM will provide some or all of the following functionality in the dialog:
1.53 +// - Display all rights objects including state (pending, valid, expired, orphaned, etc.)
1.54 +// - Display detailed information on a particular rights object (play count, validity period, the related Content object(s))
1.55 +// - Allow unwanted, expired or orphaned rights to be deleted.
1.56 +// <hr>
1.57 +// The rights management object is only relevant for agents implementing a DRM scheme. Other agents will
1.58 +// leave with <code>KErrCANotSupported</code>.
1.59 +// An application can ask a particular DRM agent to create a <code>ContentAccess::CRightsManager</code> object that can be used
1.60 +// to provide generic access to DRM rights within that agent. Since it is a generic interface
1.61 +// used by all agents, it will not be able to present all the detailed information available.
1.62 +// CRightsManager* rightsmanager;
1.63 +// // Create a CManager object
1.64 +// CManager* manager = CManager::NewL();
1.65 +// // create the rights manager object for a particular agent
1.66 +// rightsManager = manager->CreateRightsManagerL(agent);
1.67 +// To manage the rights in a more comprehensive manner the application should use the
1.68 +// <code>ContentAccess::CManager::DisplayManagementInfoL()</code> function, where the agent can present
1.69 +// its own comprehensive information.
1.70 +// <hr>
1.71 +// This is an extension mechanism to allow a client to perform an agent-specific function. The application will need to
1.72 +// know the extended commands that the agent supports and the format of the input and output buffers used in the command. All
1.73 +// of this is specified by the CAF agent, not the Content Access Framework.
1.74 +// The buffers allow agent specific objects to be externalized by an application, passed through CAF and internalized by the
1.75 +// agent. The same principle applies for data returned from the agent to the application.
1.76 +// TInt FancyApplicationFunctionL(CManager& aManager, CAgent& aAgent, CFancyAgentInputObject& aInputObject, CFancyAgentOutputObject& aOutputObject);
1.77 +// // Dynamic buffer to serialize aInputObject
1.78 +// CBufFlat* inputBuffer = CBufFlat::NewL(50);
1.79 +// CleanupStack::PushL(inputBuffer);
1.80 +// // write aInputObject to the dynamic buffer
1.81 +// RBufWriteStream streamIn(*inputBuffer);
1.82 +// CleanupClosePushL(streamIn);
1.83 +// aInputObject.ExternalizeL(streamIn);
1.84 +// CleanupStack::PopAndDestroy(&streamIn);
1.85 +// // Call the agent specific function #42
1.86 +// TBuf <1000> outputBuffer;
1.87 +// User::LeaveIfError(aManager.AgentSpecificCommand(aAgent, 42 ,inputBuffer->Ptr(0), outputBuffer));
1.88 +// // Don't need the input buffer any longer
1.89 +// CleanupStack::PopAndDestroy(inputBuffer);
1.90 +// // Create a stream object to read the output buffer
1.91 +// RDesReadStream streamOut(outputBuffer);
1.92 +// CleanupClosePushL(streamOut);
1.93 +// aOutputObject.InternalizeL(streamOut);
1.94 +// CleanupStack::PopAndDestroy(&streamOut);
1.95 +// <hr>
1.96 +//
1.97 +//
1.98 +
1.99 +/**
1.100 + @page CAFManageAgents Managing CAF Agents
1.101 + - @ref ListingAgents
1.102 + - @ref CAFManagementDialog
1.103 + - @ref CreatingRightsManager
1.104 + - @ref AgentSpecificCommand
1.105 + @section ListingAgents Listing the CAF Agents
1.106 + @code
1.107 + @endcode
1.108 + @section CAFManagementDialog Displaying the Agent Management Information
1.109 + @code
1.110 + @endcode
1.111 + @section CreatingRightsManager Create a DRM rights management object
1.112 + @code
1.113 + @endcode
1.114 + @section AgentSpecificCommand Agent Specific Commands
1.115 + @code
1.116 + @endcode
1.117 +*/