1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/inc/manager.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,800 @@
1.4 +/*
1.5 +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +/**
1.23 + @file
1.24 + @publishedPartner
1.25 + @released
1.26 +*/
1.27 +
1.28 +
1.29 +#ifndef __MANAGER_H__
1.30 +#define __MANAGER_H__
1.31 +
1.32 +#include <e32base.h>
1.33 +#include <f32file.h>
1.34 +#include <caf/caftypes.h>
1.35 +#include <caf/agent.h>
1.36 +class CDir;
1.37 +
1.38 +namespace ContentAccess
1.39 + {
1.40 + class CAgentResolver;
1.41 + class CRightsManager;
1.42 + class RAttributeSet;
1.43 + class RStringAttributeSet;
1.44 + class CDirStreamable;
1.45 + class CAgentManager;
1.46 + class TVirtualPathPtr;
1.47 +
1.48 +
1.49 + /**
1.50 + Manages files and content access agents
1.51 +
1.52 + @publishedPartner
1.53 + @released
1.54 + */
1.55 + class CManager : public CBase
1.56 + {
1.57 + public:
1.58 +
1.59 + /** Creates a CManager
1.60 +
1.61 + @return A CManager object
1.62 + */
1.63 + IMPORT_C static CManager* NewL();
1.64 +
1.65 + /** Creates a CManager
1.66 +
1.67 + @return A CManager object
1.68 + */
1.69 + IMPORT_C static CManager* NewLC();
1.70 +
1.71 + /** destructor
1.72 + */
1.73 + virtual ~CManager();
1.74 +
1.75 +
1.76 + /**
1.77 + Delete a file on the device
1.78 +
1.79 + The agent who manages the file will be used to delete it.
1.80 +
1.81 + In the case of a DRM agent implementation it may delete rights that
1.82 + were associated with the file at the same time. If an agent deletes
1.83 + rights at the same time as the content it will display a confirmation
1.84 + dialog that makes it clear that the rights will be also deleted.
1.85 +
1.86 + Access to the agent private directories is permitted at the
1.87 + agents discretion.
1.88 +
1.89 + @param aFileName The full pathname of the file to delete.
1.90 + @return The outcome of the delete operation.
1.91 + @return KErrNone if the file was deleted successfully.
1.92 + @return KErrCancel if the user selects cancel in an agent supplied confirmation screen.
1.93 + @return KErrAccessDenied if the agent does not allow the file to be deleted.
1.94 + @return KErrCANotSupported if the agent does not support file deletion
1.95 + @return KErrPermissionDenied if the client does not have the necessary capabilities to delete the file.
1.96 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.97 + other system-wide error codes for any other errors.
1.98 + @capability DRM Deleting DRM protected content is not permitted for processes without DRM capability.
1.99 + */
1.100 + IMPORT_C TInt DeleteFile(const TDesC &aFileName) const;
1.101 +
1.102 + /**
1.103 + Make a copy of a file (eg to removable media)
1.104 +
1.105 + Access to the agents private directory is permitted at the
1.106 + agents discretion.
1.107 +
1.108 + @param aSource The full pathname of the source file.
1.109 + @param aDestination The full pathname of the destination file.
1.110 + @return The outcome of the copy operation.
1.111 + @return KErrNone if the file was copied successfully.
1.112 + @return KErrAccessDenied if the agent does not allow the file to be copied.
1.113 + @return KErrCANotSupported if the agent does not support file copying.
1.114 + @return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
1.115 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.116 + other system-wide error codes for any other errors.
1.117 + @capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
1.118 + */
1.119 + IMPORT_C TInt CopyFile(const TDesC& aSource, const TDesC& aDestination) const;
1.120 +
1.121 + /**
1.122 + Make a copy of a file (eg to removable media) using a file handle
1.123 +
1.124 + Access to the agents private directory is permitted at the
1.125 + agents discretion.
1.126 +
1.127 + @param aSourceFile The handle the source file.
1.128 + @param aDestination The full pathname of the destination file.
1.129 + @return The outcome of the copy operation.
1.130 + @return KErrNone if the file was copied successfully.
1.131 + @return KErrAccessDenied if the agent does not allow the file to be copied.
1.132 + @return KErrCANotSupported if the agent does not support file copying.
1.133 + @return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
1.134 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.135 + other system-wide error codes for any other errors.
1.136 + @capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
1.137 + */
1.138 + IMPORT_C TInt CopyFile(RFile& aSourceFile, const TDesC &aDestination) const;
1.139 +
1.140 + /**
1.141 + Rename or move the content file (eg to removable media)
1.142 +
1.143 + Access to the agent private directories is permitted at the
1.144 + agents discretion.
1.145 +
1.146 + @param aSource The full pathname of the source file.
1.147 + @param aDestination The full pathname of the destination file.
1.148 + @return The outcome of the Rename operation.
1.149 + @return KErrNone if the file was moved or renamed successfully.
1.150 + @return KErrAccessDenied if the agent does not allow the file to be moved or renamed.
1.151 + @return KErrCANotSupported if the agent does not support file renaming.
1.152 + @return KErrPermissionDenied if the client does not have the necessary capabilities to move or rename the file.
1.153 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.154 + other system-wide error codes for any other errors.
1.155 + @capability DRM Moving DRM protected files is not permitted for processes without DRM capability. Moving unprotected files is permitted
1.156 + */
1.157 + IMPORT_C TInt RenameFile(const TDesC& aSource, const TDesC& aDestination) const;
1.158 +
1.159 + /** Create a directory
1.160 +
1.161 + This function can be used to create a directory within in the agent's
1.162 + private directory. Access to the agents private directory is permitted at the
1.163 + agents discretion.
1.164 +
1.165 + @param aPath The full pathname of the directory to create.
1.166 + @return The outcome of the MkDir operation.
1.167 + @return KErrNone if the directory was created successfully.
1.168 + @return KErrAccessDenied if the agent does not allow the directory to be created.
1.169 + @return KErrCANotSupported if the agent does not support directory creation.
1.170 + @return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
1.171 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.172 + other system-wide error codes for any other errors.
1.173 + @capability DRM Required when attempting to access an agents private directory.
1.174 + */
1.175 + IMPORT_C TInt MkDir(const TDesC& aPath) const;
1.176 +
1.177 + /** Create all directories in the given path if they do not exist
1.178 +
1.179 + This function can be used to create directories within in the agent's
1.180 + private directory. Access to the agents private directory is permitted at the
1.181 + agents discretion.
1.182 +
1.183 + @param aPath The full pathname of the directory to create.
1.184 + @return The outcome of the MkDirAll operation.
1.185 + @return KErrNone if the directory was created successfully.
1.186 + @return KErrAccessDenied if the agent does not allow the directory to be created.
1.187 + @return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
1.188 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.189 + other system-wide error codes for any other errors.
1.190 + @capability DRM Required when attempting to access an agents private directory.
1.191 + */
1.192 + IMPORT_C TInt MkDirAll(const TDesC& aPath) const;
1.193 +
1.194 + /** Remove a directory
1.195 +
1.196 + This function can be used to remove a directory from within the agent's
1.197 + private directory. Access to the agents private directory is permitted
1.198 + at the agents discretion.
1.199 +
1.200 + @param aPath The full pathname of the directory to remove.
1.201 + @return The outcome of the RmDir operation.
1.202 + @return KErrNone if the directory was removed successfully.
1.203 + @return KErrAccessDenied if the agent does not allow the directory to be removed.
1.204 + @return KErrCANotSupported if the agent does not support directory removal.
1.205 + @return KErrPermissionDenied if the client does not have the necessary capabilities to remove directories.
1.206 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.207 + other system-wide error codes for any other errors.
1.208 + @capability DRM Required when attempting to access an agents private directory
1.209 + */
1.210 + IMPORT_C TInt RmDir(const TDesC& aPath) const;
1.211 +
1.212 +
1.213 + /** Rename a directory
1.214 +
1.215 + This function can be used to rename a directory from within the agent's
1.216 + private directory. Access to the agents private directory is permitted
1.217 + at the agents discretion.
1.218 +
1.219 + @param aOldName The existing pathname of the directory to rename.
1.220 + @param aNewName The new pathname of the directory.
1.221 + @return The outcome of the RenameDir operation.
1.222 + @return KErrNone if the directory was removed successfully.
1.223 + @return KErrAccessDenied f the agent does not allow the directory to be removed.
1.224 + @return KErrCANotSupported if the agent does not support directory removal.
1.225 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.226 + other system-wide error codes for any other errors.
1.227 + @return Otherwise one of the other system-wide error codes for any other errors.
1.228 + @capability DRM Required when attempting to access an agents private directory
1.229 + */
1.230 + IMPORT_C TInt RenameDir(const TDesC& aOldName, const TDesC& aNewName) const;
1.231 +
1.232 +
1.233 + /** Gets a filtered list of a directory's contents.
1.234 +
1.235 + The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.
1.236 +
1.237 + Notes:
1.238 + -# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.
1.239 + -# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.
1.240 + -# The caller of this function is responsible for deleting aFileList after the function has returned.
1.241 +
1.242 + Access to agent private directories is permitted at
1.243 + the agents discretion.
1.244 +
1.245 + @see TEntryKey
1.246 +
1.247 + @param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.
1.248 + @param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in the listing. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes
1.249 + @param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.
1.250 + @param aEntryList On return contains a filtered list of directory and file entries.
1.251 + @return The outcome of the GetDir operation.
1.252 + @return KErrNone if the directory contents were listed successfully.
1.253 + @return KErrCANotSupported if the agent does not allow clients to view its private directory.
1.254 + @return KErrPermissionDenied if the process does not have the correct capabilities to view the directory.
1.255 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.256 + other system-wide error codes for any other errors.
1.257 + @capability DRM Required when attempting to access an agents private directory
1.258 + */
1.259 + IMPORT_C TInt GetDir(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList) const;
1.260 +
1.261 + /** Gets a filtered list of the directory and file entries contained in a directory and a list of the directory entries only
1.262 +
1.263 + The bitmask determines which file and directory entry types should be listed in aFileList. The contents of the second list, aDirList are not affected by the bitmask; it returns all directory entries contained in directory aName. The sort key determines the order in which both lists are sorted.
1.264 +
1.265 + Notes:
1.266 + -# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.
1.267 + -# The function sets both aFileList and aDirList to NULL, and then allocates memory to them before appending entries to the lists. Therefore, aFileList and aDirList should have no memory allocated to them before this function is called, otherwise the allocated memory will become orphaned.
1.268 + -# The caller of this function is responsible for deleting aFileList and aDirList after the function has returned.
1.269 +
1.270 + Access to agent private directories is permitted at
1.271 + the agents discretion.
1.272 +
1.273 + @see TEntryKey
1.274 +
1.275 + @param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.
1.276 + @param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in aFileList. aDirList is unaffected by this mask. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.
1.277 + @param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries in both lists are to be sorted. These flags are defined by TEntryKey.
1.278 + @param aEntryList On return contains a filtered list of directory and file entries.
1.279 + @param aDirList On return contains a filtered list of directory entries only.
1.280 + @return The outcome of the GetDir operation.
1.281 + @return KErrNone The directory contents were listed successfully.
1.282 + @return KErrCANotSupported The agent does not allow clients to view its private directory.
1.283 + @return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
1.284 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.285 + other system-wide error codes for any other errors.
1.286 + @capability DRM Required when attempting to access an agents private directory.
1.287 + */
1.288 + IMPORT_C TInt GetDir(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList, CDir*& aDirList) const;
1.289 +
1.290 + /** Gets a filtered list of a directory's contents by UID
1.291 +
1.292 + The aUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.
1.293 +
1.294 + Notes:
1.295 + -# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.
1.296 + -# The caller of this function is responsible for deleting aFileList after the function has returned.
1.297 +
1.298 + Access to agent private directories is permitted at
1.299 + the agents discretion.
1.300 +
1.301 + @see TEntryKey
1.302 +
1.303 + @param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.
1.304 + @param aEntryUid Only those files whose UIDs match those specified within this UID type will be included in the file list. Any, or all, of the three UIDs within the UID type may be omitted. Any UID which is omitted acts in a similar manner to a wildcard character, matching to all UIDs.
1.305 + @param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.
1.306 + @param aFileList On return contains a filtered list of directory and file entries.
1.307 + @return The outcome of the GetDir operation.
1.308 + @return KErrNone The directory contents were listed successfully.
1.309 + @return KErrCANotSupported The agent does not allow clients to view its private directory.
1.310 + @return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
1.311 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.312 + other system-wide error codes for any other errors.
1.313 + @capability DRM Required when attempting to access an agents private directory.
1.314 + */
1.315 + IMPORT_C TInt GetDir(const TDesC& aName, const TUidType& aEntryUid, TUint aEntrySortKey, CDir*& aFileList) const;
1.316 +
1.317 + /** Get an attribute from a content object
1.318 +
1.319 + @see ContentAccess::TAttribute
1.320 +
1.321 + e.g.
1.322 +
1.323 + @code
1.324 + TInt value = 0;
1.325 + CManager* manager = CManager::NewL();
1.326 +
1.327 + err = manager->GetAttribute(EIsProtected, value, aVirtualPath);
1.328 + if(err == KErrNone && value)
1.329 + {
1.330 + DisplayPadLock();
1.331 + }
1.332 + @endcode
1.333 +
1.334 + @param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
1.335 + @param aValue Used to return the value of the attribute.
1.336 + @param aVirtualPath The content object whose attributes are to be queried.
1.337 + @return Whether the attribute value was updated.
1.338 + @return KErrNone if the attribute value was updated.
1.339 + @return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.
1.340 + @return KErrCANotSupported if the requested attribute is not supported for this content object.
1.341 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.342 + other system-wide error codes for any other errors.
1.343 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.344 + */
1.345 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) const;
1.346 +
1.347 + /** Get a content's attribute from a file specified by file handle. Can be used when the source file is in the client's private directory.
1.348 +
1.349 + @param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
1.350 + @param aValue Used to return the value of the attribute.
1.351 + @param aFile The file handle for the file containing the content object.
1.352 + @param aUniqueId The unique id of the content object.
1.353 + @return Whether the attribute value was updated.
1.354 + @return KErrNone if the attribute value was updated.
1.355 + @return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.
1.356 + @return KErrCANotSupported if the feature or the requested attribute is not supported for this content object.
1.357 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.358 + other system-wide error codes for any other errors.
1.359 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.360 + */
1.361 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, RFile& aFile, const TDesC& aUniqueId);
1.362 +
1.363 + /** Get a set of attributes from a content object
1.364 +
1.365 + @see ContentAccess::TAttribute
1.366 +
1.367 + The following example determines whether the content object is protected
1.368 + and has rights that will enable it to be viewed by the user
1.369 +
1.370 + @code
1.371 + TInt err = KErrNone;
1.372 + TInt value = 0;
1.373 +
1.374 + // The manager
1.375 + CManager* manager = CManager::NewLC();
1.376 +
1.377 + // Prepare the RAttributeSet object with the attributes to query
1.378 + RAttributeSet attributeSet;
1.379 + CleanupClosePushL(attributeSet);
1.380 + attributeSet.AddL(EProtected);
1.381 + attributeSet.AddL(ECanView);
1.382 +
1.383 + // Retrieve the attributes from the agent
1.384 + User::LeaveIfError(manager->GetAttributeSet(attributeSet, aVirtualPath));
1.385 +
1.386 + // Check if the content object is protected
1.387 + err =attributeSet.GetValue(EProtected, value);
1.388 + if(err == KErrNone && value)
1.389 + {
1.390 + // content object is DRM protected
1.391 + }
1.392 +
1.393 + // Check if the content object can be display on screen
1.394 + err = attributeSet.GetValue(ECanView, value);
1.395 + if(err == KErrNone && value)
1.396 + {
1.397 + // content object is DRM protected
1.398 + }
1.399 +
1.400 + // Can reuse the RAttributeSet if necessary
1.401 + User::LeaveIfError(manager->GetAttributeSet(attributeSet, aVirtualPath));
1.402 +
1.403 + ...
1.404 + // Finished
1.405 + CleanupStack::PopAndDestroy(2); // manager, attributeSet.Close()
1.406 +
1.407 + @endcode
1.408 +
1.409 +
1.410 + @param aAttributeSet The set of attributes to query and update.
1.411 + @param aVirtualPath The content object to retrieve attributes from.
1.412 + @return Whether the attribute set was updated.
1.413 + @return KErrNone if the attribute set was updated successfully.
1.414 + @return KErrNotFound if the content object was not found.
1.415 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.416 + other system-wide error codes for any other errors.
1.417 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.418 + */
1.419 + IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
1.420 +
1.421 + /** Get a content's set of attributes from a file specified by file handle. Can be used when the source file is in the client's private directory.
1.422 +
1.423 + @param aAttributeSet The set of attributes to query and update.
1.424 + @param aFile The file handle for the file containing the content object.
1.425 + @param aUniqueId The unique id of the content object.
1.426 + @return Whether the attribute set was updated.
1.427 + @return KErrNone if the attribute set was updated successfully.
1.428 + @return KErrNotFound if the content object was not found.
1.429 + @return KErrCANotSupported if the feature not supported.
1.430 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.431 + other system-wide error codes for any other errors.
1.432 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.433 + */
1.434 + IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, RFile& aFile, const TDesC& aUniqueId);
1.435 +
1.436 + /** Get text string attributes or meta-data from the file
1.437 +
1.438 + @see ContentAccess::TStringAttribute
1.439 +
1.440 + e.g.
1.441 + @code
1.442 + CManager* manager = CManager::NewLC();
1.443 +
1.444 + TBuf <MAX_PATH> previewUri;
1.445 + if(manager->GetStringAttribute(EPreviewURI, previewUri, uri) == KErrNone)
1.446 + {
1.447 + DisplayPreview(previewUri);
1.448 + }
1.449 +
1.450 + CleanupStack::PopAndDestroy(); // manager
1.451 + @endcode
1.452 +
1.453 + @param aAttribute The attribute to retrieve, from ContentAccess::TStringAttribute.
1.454 + @param aValue Used to return the value of the attribute.
1.455 + @param aVirtualPath The content object whose attributes are to be retrieved.
1.456 + @return Whether the value was updated.
1.457 + @return KErrNone if the attribute was retrieved successfully.
1.458 + @return KErrNotFound if the content object does not exist.
1.459 + @return KErrCANotSupported if the requested attribute does not apply to this content object.
1.460 + @return KErrOverflow if the buffer was not large enough to return the result.
1.461 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.462 + other system-wide error codes for any other errors.
1.463 + */
1.464 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) const;
1.465 +
1.466 + /** Get a content's text string attribute from a file specified by file handle. Can be used when the source file is in the client's private directory.
1.467 +
1.468 + @param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
1.469 + @param aValue Used to return the value of the attribute.
1.470 + @param aFile The file handle for the file containing the content object.
1.471 + @param aUniqueId The unique id of the content object whose attributes are to be retrieved.
1.472 + @return Whether the attribute value was updated.
1.473 + @return KErrNone if the attribute value was updated.
1.474 + @return KErrNotFound if the content object does not exist.
1.475 + @return KErrCANotSupported if the feature or the requested attribute is not supported for this content object.
1.476 + @return KErrOverflow if the buffer was not large enough to return the result.
1.477 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.478 + other system-wide error codes for any other errors.
1.479 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.480 + */
1.481 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, RFile& aFile, const TDesC& aUniqueId);
1.482 +
1.483 + /** Used to obtain a set of string attributes
1.484 +
1.485 + @see ContentAccess::TStringAttribute
1.486 +
1.487 + @code
1.488 + TInt err = KErrNone;
1.489 + TInt value = 0;
1.490 +
1.491 + CManager* manager = CManager::NewLC();
1.492 +
1.493 + // Prepare the RStringAttributeSet object with the attributes to query
1.494 + RStringAttributeSet stringAttributeSet;
1.495 + CleanupClosePushL(stringAttributeSet);
1.496 + stringAttributeSet.AddL(EPreviewURI);
1.497 +
1.498 + // Retrieve the attributes from the agent
1.499 + User::LeaveIfError(manager->GetAttributeSet(stringAttributeSet, aVirtualPath));
1.500 +
1.501 + // display preview
1.502 + TBuf <MAX_PATH> previewUri;
1.503 + if(stringAttributeSet.GetValue(ECanView, previewUri))
1.504 + {
1.505 + DisplayPreview(previewUri);
1.506 + }
1.507 +
1.508 + // Finished
1.509 + CleanupStack::PopAndDestroy(2); // manager, stringAttributeSet.Close()
1.510 + @endcode
1.511 +
1.512 +
1.513 + @param aStringAttributeSet The set of attributes to query and update.
1.514 + @param aVirtualPath The content object whose attributes are to be retrieved.
1.515 + @return Whether the string attribute set was updated.
1.516 + @return KErrNone if the attribute set was updated successfully.
1.517 + @return KErrNotFound if the object with the given virtual path was not found.
1.518 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.519 + other system-wide error codes for any other errors.
1.520 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.521 + */
1.522 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
1.523 +
1.524 + /** Get a content's set of string attributes from a file specified by file handle. Can be used when the source file is in the client's private directory.
1.525 +
1.526 + @param aStringAttributeSet The set of attributes to query and update.
1.527 + @param aFile The file handle for the file containing the content object.
1.528 + @param aUniqueId The unique id of the content object whose attributes are to be retrieved
1.529 + @return Whether the string attribute set was updated.
1.530 + @return KErrNone if the attribute set was updated successfully.
1.531 + @return KErrNotFound if the object with the given virtual path was not found.
1.532 + @return KErrCANotSupported if the feature not supported.
1.533 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.534 + other system-wide error codes for any other errors.
1.535 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.536 + */
1.537 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, RFile& aFile, const TDesC& aUniqueId);
1.538 +
1.539 + /** Notify the caller when the status of a DRM protected content object changes
1.540 +
1.541 + @see ContentAccess::TEventMask
1.542 +
1.543 + @param aURI The location of the file.
1.544 + @param aMask Bitmask of events the caller is interested in.
1.545 + @param aStatus The TRequestStatus object to complete if the event occurs, or KErrCANotSupported if the agent does not support asynchronous notifications.
1.546 + @capability DRM Deleting DRM protected content is not permitted for processes without DRM capability.
1.547 + */
1.548 + IMPORT_C void NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus);
1.549 +
1.550 + /** Cancel a previous notification request
1.551 + @param aURI The URI supplied in the call to NotifyStatusChange().
1.552 + @param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
1.553 + @return The outcome of the cancel request.
1.554 + @return KErrNone if the notification was cancelled.
1.555 + @return KErrNotFound if there was no matching request outstanding.
1.556 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.557 + */
1.558 + IMPORT_C TInt CancelNotifyStatusChange(const TDesC& aURI, TRequestStatus& aStatus);
1.559 +
1.560 + /** Request all agents to set a property value. If the property is set
1.561 + it is only set for this CManager session and does not impact other CAF
1.562 + users.
1.563 +
1.564 + @see ContentAccess::TAgentProperty
1.565 +
1.566 + @param aProperty The property to set.
1.567 + @param aValue The value of the property.
1.568 + @return The outcome of the set property command.
1.569 + @return KErrNone if the property was set by all agents.
1.570 + @return KErrCANotSupported if one of the agent does not support the property or value.
1.571 + @return KErrAccessDenied if one of the agents does not permit the property to be changed.
1.572 + @return KErrPermissionDenied if the application does not have the necessary capability to change the property.
1.573 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.574 + */
1.575 + IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);
1.576 +
1.577 + /** View information associated with a single content object
1.578 +
1.579 + This call blocks execution and only returns once the display is dismissed
1.580 + by the user
1.581 +
1.582 + @see ContentAccess::TDisplayInfo
1.583 +
1.584 + @param aInfo The information to display.
1.585 + @param aVirtualPath The content object.
1.586 + @leave KErrCANotSupported if agent cannot display the requested information.
1.587 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.588 + or one of the system-wide error codes
1.589 + for any other errors.
1.590 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.591 + */
1.592 + IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, const TVirtualPathPtr& aVirtualPath);
1.593 +
1.594 + /** View information associated with a single content object in a file specified by file handle. Can be used when the source file is in the client's private directory.
1.595 +
1.596 + This call blocks execution and only returns once the display is dismissed
1.597 + by the user.
1.598 +
1.599 + @param aInfo The information to display.
1.600 + @param aFile The file handle for the file containing the content object.
1.601 + @param aUniqueId The unique id of the content object.
1.602 + @leave KErrCANotSupported if the feature not supported or if agent cannot display the requested information.
1.603 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.604 + or one of the system-wide error codes
1.605 + for any other errors.
1.606 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.607 + */
1.608 + IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, RFile& aFile, const TDesC& aUniqueId);
1.609 +
1.610 + /** List all the agents installed on the device (except F32Agent)
1.611 +
1.612 + The caller must call RPointerArray::ResetAndDestroy() on the array
1.613 + when it has finished.
1.614 +
1.615 + @param aAgents On completion this will contain a list of all the agents.
1.616 + */
1.617 + IMPORT_C void ListAgentsL(RArray <TAgent>& aAgents);
1.618 +
1.619 + /** Allows extended synchronous calls to an agent
1.620 +
1.621 + @param aAgent The agent.
1.622 + @param aCommand The agent defined command.
1.623 + @param aInputBuffer Non modifyable input data buffer.
1.624 + @param aOutputBuffer Modifyable output buffer to hold the result of the command.
1.625 + @return The outcome of the agent specific command.
1.626 + @return KErrNone if the command was successful.
1.627 + @return KErrCANotSupported if the agent does not recognize the command.
1.628 + @return KErrPermissionDenied if the agent does not permit the client to execute this command.
1.629 + @return Otherwise one of the other CAF error codes defined in \c caferr.h
1.630 + or one of the other system-wide error codes
1.631 + for any other errors.
1.632 + @capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
1.633 + */
1.634 + IMPORT_C TInt AgentSpecificCommand(TAgent& aAgent, TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);
1.635 +
1.636 + /** Allows extended asynchronous calls to an agent.
1.637 + NB: It is important that the descriptor passed to
1.638 + aOutputBuffer remains in scope until the request has completed.
1.639 +
1.640 + @param aAgent The agent.
1.641 + @param aCommand The agent defined command.
1.642 + @param aInputBuffer Non modifyable input data buffer.
1.643 + @param aOutputBuffer Modifyable output buffer to hold the result of the command.
1.644 + @param aStatus Asynchronous request status. On completion this will
1.645 + contain one of the following error codes: KErrNone if the command
1.646 + was successful. KErrCANotSupported if the agent does
1.647 + not recognize the command. KErrPermissionDenied if the
1.648 + agent does not permit the client to execute this command.
1.649 + Otherwise one of the other CAF error codes
1.650 + defined in \c caferr.h or one of the other
1.651 + system-wide error codes for any other errors.
1.652 + @capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
1.653 + */
1.654 + IMPORT_C void AgentSpecificCommand(TAgent& aAgent, TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);
1.655 +
1.656 + /** Allows a client to display management information for a particular agent
1.657 +
1.658 + This allows a user to see all the specific information associated
1.659 + with a particular agent. In the case of an agent implementing DRM this could
1.660 + include the ability to list, view or delete DRM rights objects.
1.661 +
1.662 + @param aAgent The agent.
1.663 + @leave KErrCANotSupported If the specified agent does not support the display of management information.
1.664 + @capability DRM Agents implementing DRM may not display their management dialog to processes without DRM capability
1.665 + */
1.666 + IMPORT_C void DisplayManagementInfoL(TAgent& aAgent);
1.667 +
1.668 + /** Allow clients to list, view and delete the rights contained by an agent
1.669 + in a generic manner.
1.670 +
1.671 + This function is only relevant for agents implementing a DRM scheme. Other agents
1.672 + will leave with KErrCANotSupported if an application attempts to invoke the
1.673 + rights manager.
1.674 +
1.675 + To manage the rights in a more comprehensive manner the application should use the
1.676 + DisplayManagementInfoL() function where the agent can present its own
1.677 + management information.
1.678 +
1.679 + @param aAgent The agent to create a rights manager object.
1.680 + @return A CRightsManager object for the specified agent.
1.681 +
1.682 + @leave KErrCANotSupported If the agent does not implement DRM or support rights management.
1.683 + @leave KErrPermissionDenied If the agent does not allow the client to create a rights manager.
1.684 + @capability DRM Access to DRM rights is not permitted for processes without DRM capability.
1.685 + */
1.686 + IMPORT_C CRightsManager* CreateRightsManagerL(TAgent& aAgent) const;
1.687 +
1.688 +#ifndef REMOVE_CAF1
1.689 + /** Delete a file
1.690 + @param aFileName The file to delete.
1.691 + @deprecated Use DeleteFile() instead.
1.692 + */
1.693 + IMPORT_C static void DeleteFileL (const TDesC &aFileName);
1.694 +#endif // REMOVE_CAF1
1.695 +
1.696 +#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.697 +
1.698 + /** Get an attribute from WMDRM content.
1.699 +
1.700 + @param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
1.701 + @param aValue Used to return the value of the attribute.
1.702 + @param aHeaderData Header data of WMDRM content.
1.703 + @return Whether the attribute value was updated.
1.704 + @return KErrNone if the attribute value was updated.
1.705 + @return KErrCANotSupported if the requested attribute is not supported for this content.
1.706 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.707 + other system-wide error codes for any other errors.
1.708 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.709 + */
1.710 + IMPORT_C TInt GetAttribute(const TDesC8& aHeaderData, TInt aAttribute, TInt& aValue) const;
1.711 +
1.712 + /** Get a set of attributes from WMDRM content.
1.713 +
1.714 + @param aAttributeSet The set of attributes to query and update.
1.715 + @param aHeaderData Header data of WMDRM content.
1.716 + @return Whether the attribute set was updated.
1.717 + @return KErrNone if the attribute set was updated successfully.
1.718 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.719 + other system-wide error codes for any other errors.
1.720 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.721 + */
1.722 + IMPORT_C TInt GetAttributeSet(const TDesC8& aHeaderData, RAttributeSet& aAttributeSet) const;
1.723 +
1.724 +
1.725 + /** Get text string attributes or meta-data from WMDRM content.
1.726 +
1.727 + @param aAttribute The attribute to retrieve, from ContentAccess::TStringAttribute.
1.728 + @param aValue Used to return the value of the attribute.
1.729 + @param aHeaderData Header data of WMDRM content.
1.730 + @return Whether the value was updated.
1.731 + @return KErrNone if the attribute was retrieved successfully.
1.732 + @return KErrNotFound if the content object does not exist.
1.733 + @return KErrCANotSupported if the requested attribute does not apply to this content object.
1.734 + @return KErrOverflow if the buffer was not large enough to return the result.
1.735 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.736 + other system-wide error codes for any other errors.
1.737 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.738 + */
1.739 + IMPORT_C TInt GetStringAttribute(const TDesC8& aHeaderData, TInt aAttribute, TDes& aValue) const;
1.740 +
1.741 + /** Used to obtain a set of string attributes from WMDRM content.
1.742 +
1.743 + @param aStringAttributeSet The set of attributes to query and update.
1.744 + @param aHeaderData Header data of WMDRM content.
1.745 + @return Whether the string attribute set was updated.
1.746 + @return KErrNone if the attribute set was updated successfully.
1.747 + @return KErrNotFound if the object with the given virtual path was not found.
1.748 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.749 + other system-wide error codes for any other errors.
1.750 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.751 + */
1.752 + IMPORT_C TInt GetStringAttributeSet(const TDesC8& aHeaderData, RStringAttributeSet& aStringAttributeSet) const;
1.753 +
1.754 +#endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.755 +
1.756 + private:
1.757 + CManager();
1.758 + void ConstructL();
1.759 +
1.760 + /** Populate the list of agents in the CDirStreamable
1.761 + @param aDir Reference to a CDir pointer, this pointer must be set to NULL
1.762 + */
1.763 + void GetListOfAgentPrivateDirectoriesL(CDir *&aDir) const;
1.764 +
1.765 + // Implemenetation functions for public exports
1.766 + void DoDeleteFileL(const TDesC &aFileName) const;
1.767 + void DoCopyFileL(const TDesC& aSource, const TDesC& aDestination) const;
1.768 + void DoCopyFileL(RFile& aSourceFile, const TDesC &aDestination) const;
1.769 + void DoRenameFileL(const TDesC& aSource, const TDesC& aDestination) const;
1.770 + void DoMkDirL(const TDesC &aPath) const;
1.771 + void DoMkDirAllL(const TDesC &aPath) const;
1.772 + void DoRmDirL(const TDesC &aPath) const;
1.773 + void DoRenameDirL(const TDesC &aOldName, const TDesC& aNewName) const;
1.774 + void DoGetDirL(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList) const;
1.775 + void DoGetDirL(const TDesC& aName, TUint aEntryAttMask, TUint anEntrySortKey, CDir*& aEntryList, CDir*& aDirList) const;
1.776 + void DoGetDirL(const TDesC &aName, const TUidType &aEntryUid, TUint aEntrySortKey, CDir *&aFileList) const;
1.777 + void DoGetAttributeL(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) const;
1.778 + void DoGetAttributeL(TInt aAttribute, TInt& aValue, RFile& aFile, const TDesC& aUniqueId) const;
1.779 + void DoGetAttributeSetL(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
1.780 + void DoGetAttributeSetL(RAttributeSet& aAttributeSet, RFile& aFile, const TDesC& aUniqueId) const;
1.781 + void DoGetStringAttributeL(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) const;
1.782 + void DoGetStringAttributeL(TInt aAttribute, TDes& aValue, RFile& aFile, const TDesC& aUniqueId) const;
1.783 + void DoGetStringAttributeSetL(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
1.784 + void DoGetStringAttributeSetL(RStringAttributeSet& aStringAttributeSet, RFile& aFile, const TDesC& aUniqueId) const;
1.785 + void DoNotifyStatusChangeL(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus);
1.786 + void DoCancelNotifyStatusChangeL(const TDesC& aURI, TRequestStatus& aStatus);
1.787 + void DoSetPropertyL(TAgentProperty aProperty, TInt aValue);
1.788 +
1.789 +#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.790 + void DoGetAttributeL(const TDesC8& aHeaderData, TInt aAttribute, TInt& aValue) const;
1.791 + void DoGetAttributeSetL(const TDesC8& aHeaderData, RAttributeSet& aAttributeSet) const;
1.792 + void DoGetStringAttributeL(const TDesC8& aHeaderData, TInt aAttribute, TDes& aValue) const;
1.793 + void DoGetStringAttributeSetL(const TDesC8& aHeaderData, RStringAttributeSet& aStringAttributeSet) const;
1.794 +#endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.795 +
1.796 + private:
1.797 + // Holds instances of all the agents
1.798 + CAgentResolver* iResolver;
1.799 + };
1.800 +
1.801 + } // namespace ContentAccess
1.802 +
1.803 +#endif /* __MANAGER_H__ */