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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // \n |
|
15 // There are some operations performed on agents that do not relate directly to a particular content file. The <code>ContentAccess::CManager</code> |
|
16 // interface includes some functions that allow an application to work with a particular agent. |
|
17 // <hr> |
|
18 // Before working with one particular agent, the client will need to find out which agents are installed on the device. |
|
19 // The <code>ContentAccess::CManager::ListAgentsL()</code> function provides this list of agents. The \c F32Agent is not included in |
|
20 // the list, since it does not support any management functions. |
|
21 // The <code>ContentAccess::CAgent</code> objects in the list can be used to refer to the particular agent in subsequent |
|
22 // function calls. |
|
23 // // Create a CManager object |
|
24 // CManager* manager = CManager::NewL(); |
|
25 // RPointerArray <CAgent> theAgents; |
|
26 // // Get the list of agents |
|
27 // manager->ListAgents(theAgents); |
|
28 // // Check there is at least one agent |
|
29 // if(theAgents.Count() > 0) |
|
30 // // Find the first agent |
|
31 // CAgent& agent = theAgents[0]; |
|
32 // <hr> |
|
33 // The management API allows applications to request that an agent display management |
|
34 // information on the screen. |
|
35 // The agent could present configuration settings, status or DRM rights information. |
|
36 // Each agent will have unique settings so it is not possible to display one dialog to configure all agents. |
|
37 // // Create a CManager object |
|
38 // CManager* manager = CManager::NewL(); |
|
39 // RPointerArray <CAgent> theAgents; |
|
40 // // Get the list of agents |
|
41 // manager->ListAgents(theAgents); |
|
42 // // Check there is at least one agent |
|
43 // if(theAgents.Count() > 0) |
|
44 // CAgent& agent = (*theAgents)[0]; |
|
45 // // Display the management information for the first agent |
|
46 // manager->DisplayManagementInfoL(agent); |
|
47 // It is possible that some agents will not support this capability and will leave with <code>KErrCANotSupported</code>. |
|
48 // Displaying DRM rights information is only relevant for agents implementing a DRM scheme. It is expected that an Agent |
|
49 // implementing DRM will provide some or all of the following functionality in the dialog: |
|
50 // - Display all rights objects including state (pending, valid, expired, orphaned, etc.) |
|
51 // - Display detailed information on a particular rights object (play count, validity period, the related Content object(s)) |
|
52 // - Allow unwanted, expired or orphaned rights to be deleted. |
|
53 // <hr> |
|
54 // The rights management object is only relevant for agents implementing a DRM scheme. Other agents will |
|
55 // leave with <code>KErrCANotSupported</code>. |
|
56 // An application can ask a particular DRM agent to create a <code>ContentAccess::CRightsManager</code> object that can be used |
|
57 // to provide generic access to DRM rights within that agent. Since it is a generic interface |
|
58 // used by all agents, it will not be able to present all the detailed information available. |
|
59 // CRightsManager* rightsmanager; |
|
60 // // Create a CManager object |
|
61 // CManager* manager = CManager::NewL(); |
|
62 // // create the rights manager object for a particular agent |
|
63 // rightsManager = manager->CreateRightsManagerL(agent); |
|
64 // To manage the rights in a more comprehensive manner the application should use the |
|
65 // <code>ContentAccess::CManager::DisplayManagementInfoL()</code> function, where the agent can present |
|
66 // its own comprehensive information. |
|
67 // <hr> |
|
68 // This is an extension mechanism to allow a client to perform an agent-specific function. The application will need to |
|
69 // know the extended commands that the agent supports and the format of the input and output buffers used in the command. All |
|
70 // of this is specified by the CAF agent, not the Content Access Framework. |
|
71 // The buffers allow agent specific objects to be externalized by an application, passed through CAF and internalized by the |
|
72 // agent. The same principle applies for data returned from the agent to the application. |
|
73 // TInt FancyApplicationFunctionL(CManager& aManager, CAgent& aAgent, CFancyAgentInputObject& aInputObject, CFancyAgentOutputObject& aOutputObject); |
|
74 // // Dynamic buffer to serialize aInputObject |
|
75 // CBufFlat* inputBuffer = CBufFlat::NewL(50); |
|
76 // CleanupStack::PushL(inputBuffer); |
|
77 // // write aInputObject to the dynamic buffer |
|
78 // RBufWriteStream streamIn(*inputBuffer); |
|
79 // CleanupClosePushL(streamIn); |
|
80 // aInputObject.ExternalizeL(streamIn); |
|
81 // CleanupStack::PopAndDestroy(&streamIn); |
|
82 // // Call the agent specific function #42 |
|
83 // TBuf <1000> outputBuffer; |
|
84 // User::LeaveIfError(aManager.AgentSpecificCommand(aAgent, 42 ,inputBuffer->Ptr(0), outputBuffer)); |
|
85 // // Don't need the input buffer any longer |
|
86 // CleanupStack::PopAndDestroy(inputBuffer); |
|
87 // // Create a stream object to read the output buffer |
|
88 // RDesReadStream streamOut(outputBuffer); |
|
89 // CleanupClosePushL(streamOut); |
|
90 // aOutputObject.InternalizeL(streamOut); |
|
91 // CleanupStack::PopAndDestroy(&streamOut); |
|
92 // <hr> |
|
93 // |
|
94 // |
|
95 |
|
96 /** |
|
97 @page CAFManageAgents Managing CAF Agents |
|
98 - @ref ListingAgents |
|
99 - @ref CAFManagementDialog |
|
100 - @ref CreatingRightsManager |
|
101 - @ref AgentSpecificCommand |
|
102 @section ListingAgents Listing the CAF Agents |
|
103 @code |
|
104 @endcode |
|
105 @section CAFManagementDialog Displaying the Agent Management Information |
|
106 @code |
|
107 @endcode |
|
108 @section CreatingRightsManager Create a DRM rights management object |
|
109 @code |
|
110 @endcode |
|
111 @section AgentSpecificCommand Agent Specific Commands |
|
112 @code |
|
113 @endcode |
|
114 */ |
|