os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/RightsManagerAPI.dox
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/RightsManagerAPI.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,138 @@
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 +// <hr>
1.18 +// The Rights manager API gives simple access to the rights within a CAF agent implementing a DRM scheme.
1.19 +// The rights are represented in a generic form using the <code>ContentAccess::CRightsInfo</code> class. This simple class
1.20 +// just holds a text description of the rights and some simple properties assocaiated with those
1.21 +// rights.
1.22 +// The Rights manager also allows applications to determine which content files are assocated with
1.23 +// each Rights object and vice versa.
1.24 +// <hr>
1.25 +// The <code>ContentAccess::CRightsManager</code> object is created by the <code>ContentAccess::CManager</code> object to look at the rights stored by a
1.26 +// particular content access agent.
1.27 +// // create the CManager object
1.28 +// CManager* manager = CManager::NewL();
1.29 +// //Create RPointerArray to store pointers to the agents
1.30 +// RPointerArray <CAgent> agentArray;
1.31 +// // Get the list of agents
1.32 +// manager->ListAgentsL(agentArray);
1.33 +// // Create a CRightsManager for the first agent
1.34 +// CRightsManager *rightsManager = manager->CreateRightsManagerL(agentArray[0]);
1.35 +// <hr>
1.36 +// The <code>ContentAccess::CRightsManager::ListAllRightsL()</code> function produces a list of all the rights stored
1.37 +// in the given a DRM agent.
1.38 +// // Create the array to store Rights objects
1.39 +// RStreamablePtrArray<CRightsInfo> myArray;
1.40 +// CleanupClosePushL(myArray);
1.41 +// // Get the Rights objects from the agent
1.42 +// rightsManager->ListAllRightsL(myArray);
1.43 +// // count the number of Rights objects
1.44 +// TInt numRights = myArray.Count();
1.45 +// // clear the contents of the array
1.46 +// CleanupStack::PopAndDestroy();
1.47 +// <hr>
1.48 +// The <code>ContentAccess::CRightsManager::ListRightsL()</code> function produces a list of all the rights stored
1.49 +// in the given a DRM agent that are associated with the file at a given URI.
1.50 +// // Create the array to store Rights objects
1.51 +// RStreamablePtrArray<CRightsInfo> myArray;
1.52 +// CleanupClosePushL(myArray);
1.53 +// // Get the Rights objects assocated with the content
1.54 +// rightsManager->ListRightsL(myArray, uri);
1.55 +// // Count the number of Rights objects associated with the content
1.56 +// TInt numRights = myArray.Count();
1.57 +// // clear the contents of the array
1.58 +// CleanupStack::PopAndDestroy();
1.59 +// <hr>
1.60 +// The <code>ContentAccess::CRightsManager::ListRightsL()</code> function produces a list of all the rights stored
1.61 +// in the given a DRM agent that are associated with the content object at a given virtual path
1.62 +// // Create the array to store Rights objects
1.63 +// RStreamablePtrArray<CRightsInfo> myArray;
1.64 +// CleanupClosePushL(myArray);
1.65 +// // Get the Rights objects assocated with the content
1.66 +// rightsManager->ListRightsL(myArray, virtualPath);
1.67 +// // Count the number of Rights objects associated with the content
1.68 +// TInt numRights = myArray.Count();
1.69 +// // clear the contents of the array
1.70 +// CleanupStack::PopAndDestroy();
1.71 +// <hr>
1.72 +// The <code>ContentAccess::CRightsManager::ListContentL()</code> function produces a list of all the content
1.73 +// that is associated with the given Rights object.
1.74 +// // Create the array to store Rights objects
1.75 +// RStreamablePtrArray<CRightsInfo> rightsArray;
1.76 +// CleanupClosePushL(rightsArray);
1.77 +// rightsManager->ListAllRightsL(rightsArray);
1.78 +// // get the first CRightsInfo object
1.79 +// CRightsInfo* rightsObject = rightsArray[0];
1.80 +// RStreamablePtrArray<CVirtualPath> contentArray;
1.81 +// CleanupClosePushL(contentArray);
1.82 +// // Get the array of content objects associated with the rights
1.83 +// rightsManager->ListContentL(contentArray, rightsObject);
1.84 +// // count the number of content objects
1.85 +// TInt numContentObjects = contentArray.Count();
1.86 +// // produce listing
1.87 +// // Finished
1.88 +// CleanupStack::PopAndDestroy(2); // rightsArray, contentArray
1.89 +// <hr>
1.90 +// The <code>ContentAccess::CRightsManager::GetRightsDataL()</code> function allows an application to
1.91 +// retrieve a pointer to a Rights object. The Rights object is derived from <code>MAgentRightsBase</code>.
1.92 +// // Retrieve the full Rights object
1.93 +// // The application will need to cast it to the agent's derived Rights class before using it.
1.94 +// MAgentRightsBase* rightsObject = rightsManager->GetRightsDataL(rightsObject);
1.95 +// <hr>
1.96 +// The <code>ContentAccess::CRightsManager::DeleteRightsObject()</code> function allows an application to
1.97 +// delete rights stored by the agent.
1.98 +// // Delete the Rights object
1.99 +// TInt result = rightsManager->DeleteRightsObject(rightsObject);
1.100 +// It is also possible to delete all the rights associated with a particular content object.
1.101 +// // Delete all the Rights objects associated with the given content object
1.102 +// TInt result = rightsManager->DeleteAllRights(virtualPath);
1.103 +// <hr>
1.104 +//
1.105 +//
1.106 +
1.107 +/**
1.108 + @page CAFRightsManager Rights Manager API
1.109 + - @ref RightsManagerAPI
1.110 + - @ref CreatingRightsManager
1.111 + - @ref ListingAllRights
1.112 + - @ref ListingRightsURI
1.113 + - @ref ListingRightsVP
1.114 + - @ref ListingContent
1.115 + - @ref RetrievingRights
1.116 + - @ref DeletingRights
1.117 + @section RightsManagerAPI Rights manager API
1.118 + @section CreatingRightsManager Creating a CRightsManager Object
1.119 + @code
1.120 + @endcode
1.121 + @section ListingAllRights Listing all Rights objects
1.122 + @code
1.123 + @endcode
1.124 + @section ListingRightsURI List the rights associated with a content file
1.125 + @code
1.126 + @endcode
1.127 + @section ListingRightsVP List the rights associated with a content object
1.128 + @code
1.129 + @endcode
1.130 + @section ListingContent List the content associated with a Rights object
1.131 + @code
1.132 + @endcode
1.133 + @section RetrievingRights Retrieving a Rights Object
1.134 + @code
1.135 + @endcode
1.136 + @section DeletingRights Deleting a Rights Object
1.137 + @code
1.138 + @endcode
1.139 + @code
1.140 + @endcode
1.141 +*/