epoc32/include/caf/manager.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
/*
williamr@2
     2
* Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     5
* under the terms of the License "Eclipse Public License v1.0"
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description: 
williamr@2
    15
*
williamr@2
    16
*/
williamr@2
    17
williamr@2
    18
williamr@2
    19
williamr@2
    20
/** 
williamr@2
    21
@file
williamr@2
    22
williamr@2
    23
@publishedPartner
williamr@2
    24
@released
williamr@2
    25
*/
williamr@2
    26
williamr@2
    27
williamr@2
    28
#ifndef __MANAGER_H__
williamr@2
    29
#define __MANAGER_H__
williamr@2
    30
williamr@2
    31
#include <e32base.h>
williamr@2
    32
#include <f32file.h>
williamr@2
    33
#include <caf/caftypes.h>
williamr@2
    34
#include <caf/agent.h>
williamr@2
    35
class CDir;
williamr@2
    36
williamr@2
    37
namespace ContentAccess
williamr@2
    38
	{
williamr@2
    39
	class CAgentResolver;
williamr@2
    40
	class CRightsManager;
williamr@2
    41
	class RAttributeSet;
williamr@2
    42
	class RStringAttributeSet;
williamr@2
    43
	class CDirStreamable;
williamr@2
    44
	class CAgentManager;
williamr@2
    45
	class TVirtualPathPtr;
williamr@2
    46
	
williamr@2
    47
williamr@2
    48
	/** 
williamr@2
    49
	Manages files and content access agents
williamr@2
    50
	
williamr@2
    51
	@publishedPartner
williamr@2
    52
	@released
williamr@2
    53
	*/
williamr@2
    54
	class CManager : public CBase
williamr@2
    55
		{
williamr@2
    56
	public:
williamr@2
    57
williamr@2
    58
		/** Creates a CManager 
williamr@2
    59
williamr@2
    60
		@return A CManager object
williamr@2
    61
		*/
williamr@2
    62
		IMPORT_C static CManager* NewL();
williamr@2
    63
williamr@2
    64
		/** Creates a CManager 
williamr@2
    65
williamr@2
    66
		@return A CManager object
williamr@2
    67
		*/
williamr@2
    68
		IMPORT_C static CManager* NewLC();
williamr@2
    69
williamr@2
    70
		/** destructor 
williamr@2
    71
		*/
williamr@2
    72
		virtual ~CManager();
williamr@2
    73
williamr@2
    74
williamr@2
    75
		/** 
williamr@2
    76
		Delete a file on the device
williamr@2
    77
williamr@2
    78
		The agent who manages the file will be used to delete it.
williamr@2
    79
		   
williamr@2
    80
		In the case of a DRM agent implementation it may delete rights that 
williamr@2
    81
		were associated with the file at the same time. If an agent deletes 
williamr@2
    82
		rights at the same time as the content it will display a confirmation 
williamr@2
    83
		dialog that makes it clear that the rights will be also deleted. 
williamr@2
    84
		 
williamr@2
    85
		Access to the agent private directories is permitted at the 
williamr@2
    86
		agents discretion.
williamr@2
    87
williamr@2
    88
		@param aFileName The full pathname of the file to delete.
williamr@2
    89
		@return The outcome of the delete operation.
williamr@2
    90
		@return KErrNone if the file was deleted successfully.
williamr@2
    91
		@return KErrCancel if the user selects cancel in an agent supplied confirmation screen.
williamr@2
    92
		@return KErrAccessDenied if the agent does not allow the file to be deleted.
williamr@2
    93
		@return KErrCANotSupported if the agent does not support file deletion
williamr@2
    94
		@return KErrPermissionDenied if the client does not have the necessary capabilities to delete the file.
williamr@2
    95
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
    96
				other system-wide error codes for any other errors.
williamr@2
    97
		@capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 
williamr@2
    98
		*/
williamr@2
    99
		IMPORT_C TInt DeleteFile(const TDesC &aFileName) const;
williamr@2
   100
williamr@2
   101
		/**
williamr@2
   102
		Make a copy of a file (eg to removable media) 
williamr@2
   103
williamr@2
   104
		Access to the agents private directory is permitted at the 
williamr@2
   105
		agents discretion.
williamr@2
   106
williamr@2
   107
  		@param aSource The full pathname of the source file.
williamr@2
   108
		@param aDestination The full pathname of the destination file.
williamr@2
   109
		@return The outcome of the copy operation.
williamr@2
   110
		@return KErrNone if the file was copied successfully.
williamr@2
   111
		@return KErrAccessDenied if the agent does not allow the file to be copied.
williamr@2
   112
		@return KErrCANotSupported if the agent does not support file copying.
williamr@2
   113
		@return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
williamr@2
   114
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   115
				other system-wide error codes for any other errors.
williamr@2
   116
  		@capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
williamr@2
   117
		*/
williamr@2
   118
		IMPORT_C TInt CopyFile(const TDesC& aSource, const TDesC& aDestination) const;
williamr@2
   119
williamr@2
   120
		/**
williamr@2
   121
		Make a copy of a file (eg to removable media) using a file handle
williamr@2
   122
williamr@2
   123
		Access to the agents private directory is permitted at the 
williamr@2
   124
		agents discretion.
williamr@2
   125
williamr@2
   126
  		@param aSourceFile The handle the source file.
williamr@2
   127
		@param aDestination The full pathname of the destination file.
williamr@2
   128
		@return The outcome of the copy operation.
williamr@2
   129
		@return KErrNone if the file was copied successfully.
williamr@2
   130
		@return KErrAccessDenied if the agent does not allow the file to be copied.
williamr@2
   131
		@return KErrCANotSupported if the agent does not support file copying.
williamr@2
   132
		@return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
williamr@2
   133
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   134
				other system-wide error codes for any other errors.
williamr@2
   135
  		@capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
williamr@2
   136
		*/
williamr@2
   137
		IMPORT_C TInt CopyFile(RFile& aSourceFile, const TDesC &aDestination) const;
williamr@2
   138
				
williamr@2
   139
		/**
williamr@2
   140
		Rename or move the content file (eg to removable media)
williamr@2
   141
williamr@2
   142
		Access to the agent private directories is permitted at the 
williamr@2
   143
		agents discretion.
williamr@2
   144
williamr@2
   145
		@param aSource The full pathname of the source file.
williamr@2
   146
		@param aDestination The full pathname of the destination file.
williamr@2
   147
		@return The outcome of the Rename operation.
williamr@2
   148
		@return KErrNone if the file was moved or renamed successfully.
williamr@2
   149
		@return KErrAccessDenied if the agent does not allow the file to be moved or renamed.
williamr@2
   150
		@return KErrCANotSupported if the agent does not support file renaming.
williamr@2
   151
		@return KErrPermissionDenied if the client does not have the necessary capabilities to move or rename the file.
williamr@2
   152
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   153
				other system-wide error codes for any other errors.
williamr@2
   154
  		@capability DRM Moving DRM protected files is not permitted for processes without DRM capability. Moving unprotected files is permitted
williamr@2
   155
		*/
williamr@2
   156
		IMPORT_C TInt RenameFile(const TDesC& aSource, const TDesC& aDestination) const;
williamr@2
   157
williamr@2
   158
		/** Create a directory
williamr@2
   159
williamr@2
   160
		This function can be used to create a directory within in the agent's 
williamr@2
   161
		private directory. Access to the agents private directory is permitted at the 
williamr@2
   162
		agents discretion. 
williamr@2
   163
williamr@2
   164
		@param aPath The full pathname of the directory to create.
williamr@2
   165
		@return The outcome of the MkDir operation.
williamr@2
   166
		@return KErrNone if the directory was created successfully.
williamr@2
   167
		@return KErrAccessDenied if the agent does not allow the directory to be created.
williamr@2
   168
		@return KErrCANotSupported if the agent does not support directory creation.
williamr@2
   169
		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
williamr@2
   170
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   171
				other system-wide error codes for any other errors.
williamr@2
   172
		@capability DRM Required when attempting to access an agents private directory.
williamr@2
   173
		*/
williamr@2
   174
		IMPORT_C TInt MkDir(const TDesC& aPath) const;
williamr@2
   175
williamr@2
   176
		/** Create all directories in the given path if they do not exist
williamr@2
   177
williamr@2
   178
		This function can be used to create directories within in the agent's 
williamr@2
   179
		private directory. Access to the agents private directory is permitted at the 
williamr@2
   180
		agents discretion. 
williamr@2
   181
		
williamr@2
   182
		@param aPath The full pathname of the directory to create.
williamr@2
   183
		@return The outcome of the MkDirAll operation.
williamr@2
   184
		@return KErrNone if the directory was created successfully.
williamr@2
   185
		@return KErrAccessDenied if the agent does not allow the directory to be created.
williamr@2
   186
		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
williamr@2
   187
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   188
				other system-wide error codes for any other errors.
williamr@2
   189
		@capability DRM Required when attempting to access an agents private directory.
williamr@2
   190
		*/
williamr@2
   191
		IMPORT_C TInt MkDirAll(const TDesC& aPath) const;
williamr@2
   192
williamr@2
   193
		/** Remove a directory
williamr@2
   194
williamr@2
   195
		This function can be used to remove a directory from within the agent's 
williamr@2
   196
		private directory. Access to the agents private directory is permitted 
williamr@2
   197
		at the agents discretion. 
williamr@2
   198
		
williamr@2
   199
		@param aPath The full pathname of the directory to remove.
williamr@2
   200
		@return The outcome of the RmDir operation.
williamr@2
   201
		@return KErrNone if the directory was removed successfully.
williamr@2
   202
		@return KErrAccessDenied if the agent does not allow the directory to be removed.
williamr@2
   203
		@return KErrCANotSupported if the agent does not support directory removal.
williamr@2
   204
		@return KErrPermissionDenied if the client does not have the necessary capabilities to remove directories.
williamr@2
   205
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   206
				other system-wide error codes for any other errors.
williamr@2
   207
		@capability DRM Required when attempting to access an agents private directory
williamr@2
   208
		*/
williamr@2
   209
		IMPORT_C TInt RmDir(const TDesC& aPath) const;
williamr@2
   210
williamr@2
   211
williamr@2
   212
		/** Rename a directory
williamr@2
   213
williamr@2
   214
		This function can be used to rename a directory from within the agent's 
williamr@2
   215
		private directory. Access to the agents private directory is permitted 
williamr@2
   216
		at the agents discretion. 
williamr@2
   217
		
williamr@2
   218
		@param aOldName The existing pathname of the directory to rename.
williamr@2
   219
		@param aNewName The new pathname of the directory.
williamr@2
   220
		@return The outcome of the RenameDir operation.
williamr@2
   221
		@return KErrNone if the directory was removed successfully.
williamr@2
   222
		@return KErrAccessDenied f the agent does not allow the directory to be removed.
williamr@2
   223
		@return KErrCANotSupported if the agent does not support directory removal.
williamr@2
   224
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   225
				other system-wide error codes for any other errors.
williamr@2
   226
		@return Otherwise one of the other system-wide error codes for any other errors.
williamr@2
   227
		*/
williamr@2
   228
		IMPORT_C TInt RenameDir(const TDesC& aOldName, const TDesC& aNewName) const;
williamr@2
   229
williamr@2
   230
williamr@2
   231
		/**  Gets a filtered list of a directory's contents. 
williamr@2
   232
williamr@2
   233
		The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.
williamr@2
   234
williamr@2
   235
		Notes:
williamr@2
   236
		-# 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.
williamr@2
   237
		-# 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.
williamr@2
   238
		-# The caller of this function is responsible for deleting aFileList after the function has returned.
williamr@2
   239
williamr@2
   240
		Access to agent private directories is permitted at 
williamr@2
   241
		the agents discretion. 
williamr@2
   242
		
williamr@2
   243
		@see TEntryKey
williamr@2
   244
williamr@2
   245
  		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.
williamr@2
   246
		@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 
williamr@2
   247
		@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. 
williamr@2
   248
		@param aEntryList On return contains a filtered list of directory and file entries.
williamr@2
   249
		@return The outcome of the GetDir operation.
williamr@2
   250
		@return KErrNone if the directory contents were listed successfully.
williamr@2
   251
		@return KErrCANotSupported if the agent does not allow clients to view its private directory.
williamr@2
   252
		@return KErrPermissionDenied if the process does not have the correct capabilities to view the directory.
williamr@2
   253
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   254
				other system-wide error codes for any other errors.
williamr@2
   255
		@capability DRM Required when attempting to access an agents private directory
williamr@2
   256
		*/
williamr@2
   257
		IMPORT_C TInt GetDir(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList) const;
williamr@2
   258
williamr@2
   259
		/**  Gets a filtered list of the directory and file entries contained in a directory and a list of the directory entries only
williamr@2
   260
williamr@2
   261
		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.
williamr@2
   262
williamr@2
   263
		Notes:
williamr@2
   264
		-# 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.
williamr@2
   265
		-# 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.
williamr@2
   266
		-# The caller of this function is responsible for deleting aFileList and aDirList after the function has returned.
williamr@2
   267
williamr@2
   268
		Access to agent private directories is permitted at 
williamr@2
   269
		the agents discretion. 
williamr@2
   270
williamr@2
   271
		@see TEntryKey
williamr@2
   272
williamr@2
   273
		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 
williamr@2
   274
		@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.
williamr@2
   275
		@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. 
williamr@2
   276
		@param aEntryList On return contains a filtered list of directory and file entries. 
williamr@2
   277
		@param aDirList On return contains a filtered list of directory entries only.
williamr@2
   278
		@return The outcome of the GetDir operation.
williamr@2
   279
		@return KErrNone The directory contents were listed successfully.
williamr@2
   280
		@return KErrCANotSupported The agent does not allow clients to view its private directory.
williamr@2
   281
		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
williamr@2
   282
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   283
				other system-wide error codes for any other errors.
williamr@2
   284
		@capability DRM Required when attempting to access an agents private directory.
williamr@2
   285
		*/
williamr@2
   286
		IMPORT_C TInt GetDir(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList, CDir*& aDirList) const;
williamr@2
   287
williamr@2
   288
		/**  Gets a filtered list of a directory's contents by UID
williamr@2
   289
williamr@2
   290
		The aUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.
williamr@2
   291
williamr@2
   292
		Notes:
williamr@2
   293
		-# 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.
williamr@2
   294
		-# The caller of this function is responsible for deleting aFileList after the function has returned.
williamr@2
   295
williamr@2
   296
		Access to agent private directories is permitted at 
williamr@2
   297
		the agents discretion. 
williamr@2
   298
williamr@2
   299
		@see TEntryKey
williamr@2
   300
williamr@2
   301
		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 
williamr@2
   302
		@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. 
williamr@2
   303
		@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.
williamr@2
   304
		@param aFileList On return contains a filtered list of directory and file entries.
williamr@2
   305
		@return The outcome of the GetDir operation.
williamr@2
   306
		@return KErrNone The directory contents were listed successfully.
williamr@2
   307
		@return KErrCANotSupported The agent does not allow clients to view its private directory.
williamr@2
   308
		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
williamr@2
   309
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   310
				other system-wide error codes for any other errors.
williamr@2
   311
		@capability DRM Required when attempting to access an agents private directory.
williamr@2
   312
		*/
williamr@2
   313
		IMPORT_C TInt GetDir(const TDesC& aName, const TUidType& aEntryUid, TUint aEntrySortKey, CDir*& aFileList) const;
williamr@2
   314
williamr@2
   315
		/**  Get an attribute from a content object
williamr@2
   316
williamr@2
   317
		@see ContentAccess::TAttribute
williamr@2
   318
williamr@2
   319
		e.g.
williamr@2
   320
williamr@2
   321
		@code
williamr@2
   322
		TInt value = 0;
williamr@2
   323
		CManager* manager = CManager::NewL();
williamr@2
   324
		
williamr@2
   325
		err = manager->GetAttribute(EIsProtected, value, aVirtualPath);
williamr@2
   326
		if(err == KErrNone && value)
williamr@2
   327
			{
williamr@2
   328
			DisplayPadLock();
williamr@2
   329
			}
williamr@2
   330
		@endcode
williamr@2
   331
	
williamr@2
   332
		@param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
williamr@2
   333
		@param aValue Used to return the value of the attribute.
williamr@2
   334
		@param aVirtualPath The content object whose attributes are to be queried.
williamr@2
   335
		@return Whether the attribute value was updated.
williamr@2
   336
		@return KErrNone if the attribute value was updated.
williamr@2
   337
		@return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.
williamr@2
   338
		@return KErrCANotSupported if the requested attribute is not supported for this content object.
williamr@2
   339
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   340
				other system-wide error codes for any other errors.
williamr@2
   341
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   342
		*/
williamr@2
   343
		IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) const;
williamr@2
   344
williamr@2
   345
		/** Get a set of attributes from a content object
williamr@2
   346
williamr@2
   347
		@see ContentAccess::TAttribute
williamr@2
   348
williamr@2
   349
		The following example determines whether the content object is protected
williamr@2
   350
		and has rights that will enable it to be viewed by the user
williamr@2
   351
		
williamr@2
   352
		@code
williamr@2
   353
		TInt err = KErrNone;
williamr@2
   354
		TInt value = 0;
williamr@2
   355
		
williamr@2
   356
		// The manager		
williamr@2
   357
		CManager* manager = CManager::NewLC();
williamr@2
   358
williamr@2
   359
		// Prepare the RAttributeSet object with the attributes to query		
williamr@2
   360
		RAttributeSet attributeSet;
williamr@2
   361
		CleanupClosePushL(attributeSet);
williamr@2
   362
		attributeSet.AddL(EProtected);
williamr@2
   363
		attributeSet.AddL(ECanView);
williamr@2
   364
		
williamr@2
   365
		// Retrieve the attributes from the agent
williamr@2
   366
		User::LeaveIfError(manager->GetAttributeSet(attributeSet, aVirtualPath));
williamr@2
   367
		
williamr@2
   368
		// Check if the content object is protected
williamr@2
   369
		err =attributeSet.GetValue(EProtected, value);
williamr@2
   370
		if(err == KErrNone && value)
williamr@2
   371
			{
williamr@2
   372
			// content object is DRM protected
williamr@2
   373
			}
williamr@2
   374
		
williamr@2
   375
		// Check if the content object can be display on screen
williamr@2
   376
		err = attributeSet.GetValue(ECanView, value);
williamr@2
   377
		if(err == KErrNone && value)
williamr@2
   378
			{
williamr@2
   379
			// content object is DRM protected
williamr@2
   380
			}
williamr@2
   381
	
williamr@2
   382
  		// Can reuse the RAttributeSet if necessary
williamr@2
   383
		User::LeaveIfError(manager->GetAttributeSet(attributeSet, aVirtualPath));
williamr@2
   384
		
williamr@2
   385
		...
williamr@2
   386
		// Finished
williamr@2
   387
		CleanupStack::PopAndDestroy(2);		// manager, attributeSet.Close()
williamr@2
   388
		
williamr@2
   389
		@endcode
williamr@2
   390
williamr@2
   391
williamr@2
   392
		@param aAttributeSet The set of attributes to query and update.
williamr@2
   393
		@param aVirtualPath The content object to retrieve attributes from.
williamr@2
   394
		@return Whether the attribute set was updated.
williamr@2
   395
		@return KErrNone if the attribute set was updated successfully.
williamr@2
   396
		@return KErrNotFound if the content object was not found.
williamr@2
   397
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   398
				other system-wide error codes for any other errors.
williamr@2
   399
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   400
		*/
williamr@2
   401
		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
williamr@2
   402
williamr@2
   403
		/**  Get text string attributes or meta-data from the file 
williamr@2
   404
		
williamr@2
   405
		@see ContentAccess::TStringAttribute
williamr@2
   406
williamr@2
   407
		e.g.
williamr@2
   408
		@code
williamr@2
   409
		CManager* manager = CManager::NewLC();
williamr@2
   410
		
williamr@2
   411
		TBuf <MAX_PATH> previewUri;
williamr@2
   412
		if(manager->GetStringAttribute(EPreviewURI, previewUri, uri) == KErrNone)
williamr@2
   413
			{
williamr@2
   414
			DisplayPreview(previewUri);
williamr@2
   415
			}
williamr@2
   416
			
williamr@2
   417
		CleanupStack::PopAndDestroy();	// manager
williamr@2
   418
		@endcode
williamr@2
   419
williamr@2
   420
		@param aAttribute The attribute to retrieve, from ContentAccess::TStringAttribute.
williamr@2
   421
		@param aValue Used to return the value of the attribute.
williamr@2
   422
		@param aVirtualPath The content object whose attributes are to be retrieved.
williamr@2
   423
		@return Whether the value was updated.
williamr@2
   424
		@return KErrNone if the attribute was retrieved successfully.
williamr@2
   425
		@return KErrNotFound if the content object does not exist.
williamr@2
   426
		@return KErrCANotSupported if the requested attribute does not apply to this content object.
williamr@2
   427
		@return KErrOverflow if the buffer was not large enough to return the result.
williamr@2
   428
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   429
				other system-wide error codes for any other errors.
williamr@2
   430
		*/
williamr@2
   431
		IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) const;
williamr@2
   432
williamr@2
   433
		/** Used to obtain a set of string attributes 
williamr@2
   434
williamr@2
   435
		@see ContentAccess::TStringAttribute
williamr@2
   436
williamr@2
   437
		@code
williamr@2
   438
		TInt err = KErrNone;
williamr@2
   439
		TInt value = 0;
williamr@2
   440
		
williamr@2
   441
		CManager* manager = CManager::NewLC();
williamr@2
   442
		
williamr@2
   443
		// Prepare the RStringAttributeSet object with the attributes to query		
williamr@2
   444
		RStringAttributeSet stringAttributeSet;
williamr@2
   445
		CleanupClosePushL(stringAttributeSet);
williamr@2
   446
		stringAttributeSet.AddL(EPreviewURI);
williamr@2
   447
		
williamr@2
   448
		// Retrieve the attributes from the agent
williamr@2
   449
		User::LeaveIfError(manager->GetAttributeSet(stringAttributeSet, aVirtualPath));
williamr@2
   450
		
williamr@2
   451
		// display preview
williamr@2
   452
		TBuf <MAX_PATH> previewUri;
williamr@2
   453
		if(stringAttributeSet.GetValue(ECanView, previewUri))
williamr@2
   454
			{
williamr@2
   455
			DisplayPreview(previewUri);
williamr@2
   456
			}
williamr@2
   457
	
williamr@2
   458
		// Finished
williamr@2
   459
		CleanupStack::PopAndDestroy(2);		// manager, stringAttributeSet.Close()
williamr@2
   460
		@endcode
williamr@2
   461
williamr@2
   462
williamr@2
   463
		@param aStringAttributeSet The set of attributes to query and update.
williamr@2
   464
		@param aVirtualPath The content object whose attributes are to be retrieved.
williamr@2
   465
		@return Whether the string attribute set was updated.
williamr@2
   466
		@return KErrNone if the attribute set was updated successfully.
williamr@2
   467
		@return KErrNotFound if the object with the given virtual path was not found.
williamr@2
   468
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   469
				other system-wide error codes for any other errors.
williamr@2
   470
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   471
		*/
williamr@2
   472
		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) const;
williamr@2
   473
williamr@2
   474
		/** Notify the caller when the status of a DRM protected content object changes
williamr@2
   475
williamr@2
   476
		@see ContentAccess::TEventMask
williamr@2
   477
williamr@2
   478
		@param aURI The location of the file.
williamr@2
   479
		@param aMask Bitmask of events the caller is interested in.
williamr@2
   480
		@param aStatus The TRequestStatus object to complete if the event occurs, or KErrCANotSupported if the agent does not support asynchronous notifications.
williamr@2
   481
		@capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 
williamr@2
   482
		*/
williamr@2
   483
		IMPORT_C void NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus);
williamr@2
   484
williamr@2
   485
		/** Cancel a previous notification request
williamr@2
   486
		@param aURI The URI supplied in the call to NotifyStatusChange().
williamr@2
   487
		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
williamr@2
   488
		@return The outcome of the cancel request.
williamr@2
   489
		@return KErrNone if the notification was cancelled.
williamr@2
   490
		@return KErrNotFound if there was no matching request outstanding.
williamr@2
   491
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   492
		*/
williamr@2
   493
		IMPORT_C TInt CancelNotifyStatusChange(const TDesC& aURI, TRequestStatus& aStatus);
williamr@2
   494
williamr@2
   495
		/** Request all agents to set a property value. If the property is set
williamr@2
   496
		it is only set for this CManager session and does not impact other CAF
williamr@2
   497
		users.
williamr@2
   498
williamr@2
   499
		@see ContentAccess::TAgentProperty
williamr@2
   500
williamr@2
   501
		@param aProperty The property to set.
williamr@2
   502
		@param aValue The value of the property.
williamr@2
   503
		@return The outcome of the set property command.
williamr@2
   504
		@return KErrNone if the property was set by all agents.
williamr@2
   505
		@return KErrCANotSupported if one of the agent does not support the property or value.
williamr@2
   506
		@return KErrAccessDenied if one of the agents does not permit the property to be changed.
williamr@2
   507
		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
williamr@2
   508
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   509
		*/
williamr@2
   510
		IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);
williamr@2
   511
williamr@2
   512
		/** View information associated with a single content object
williamr@2
   513
		
williamr@2
   514
		This call blocks execution and only returns once the display is dismissed 
williamr@2
   515
		by the user
williamr@2
   516
williamr@2
   517
		@see ContentAccess::TDisplayInfo
williamr@2
   518
williamr@2
   519
		@param aInfo The information to display.
williamr@2
   520
		@param aVirtualPath The content object.
williamr@2
   521
		@leave KErrCANotSupported if agent cannot display the requested information.
williamr@2
   522
		@leave ...		One of the other CAF error codes defined in \c caferr.h  
williamr@2
   523
		 				or one of the system-wide error codes 
williamr@2
   524
						for any other errors.		
williamr@2
   525
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   526
		*/
williamr@2
   527
		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, const TVirtualPathPtr& aVirtualPath);
williamr@2
   528
		
williamr@2
   529
williamr@2
   530
		/** List all the agents installed on the device (except F32Agent) 
williamr@2
   531
williamr@2
   532
		The caller must call RPointerArray::ResetAndDestroy() on the array 
williamr@2
   533
		when it has finished.
williamr@2
   534
williamr@2
   535
		@param aAgents On completion this will contain a list of all the agents.
williamr@2
   536
		*/
williamr@2
   537
		IMPORT_C void ListAgentsL(RArray <TAgent>& aAgents);
williamr@2
   538
williamr@2
   539
		/** Allows extended synchronous calls to an agent
williamr@2
   540
		
williamr@2
   541
		@param aAgent The agent.
williamr@2
   542
		@param aCommand The agent defined command.
williamr@2
   543
		@param aInputBuffer Non modifyable input data buffer.
williamr@2
   544
		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2
   545
		@return The outcome of the agent specific command.
williamr@2
   546
		@return KErrNone if the command was successful.
williamr@2
   547
		@return KErrCANotSupported if the agent does not recognize the command.
williamr@2
   548
		@return KErrPermissionDenied if the agent does not permit the client to execute this command.
williamr@2
   549
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  
williamr@2
   550
				or one of the other system-wide error codes 
williamr@2
   551
				for any other errors.		
williamr@2
   552
  		@capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
williamr@2
   553
		*/
williamr@2
   554
		IMPORT_C  TInt AgentSpecificCommand(TAgent& aAgent, TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);
williamr@2
   555
williamr@2
   556
		/** Allows extended asynchronous calls to an agent.
williamr@2
   557
		NB: It is important that the descriptor passed to 
williamr@2
   558
		aOutputBuffer remains in scope until the request has completed.
williamr@2
   559
williamr@2
   560
		@param aAgent The agent.
williamr@2
   561
  		@param aCommand The agent defined command.
williamr@2
   562
		@param aInputBuffer Non modifyable input data buffer.
williamr@2
   563
		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2
   564
		@param aStatus 	Asynchronous request status. On completion this will 
williamr@2
   565
						contain one of the following error codes: KErrNone if the command
williamr@2
   566
						was successful. KErrCANotSupported if the agent does 
williamr@2
   567
						not recognize the command. KErrPermissionDenied if the 
williamr@2
   568
						agent does not permit the client to execute this command.
williamr@2
   569
						Otherwise one of the other CAF error codes 
williamr@2
   570
						defined in \c caferr.h  or one of the other 
williamr@2
   571
						system-wide error codes for any other errors.
williamr@2
   572
		@capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
williamr@2
   573
		*/
williamr@2
   574
		IMPORT_C void AgentSpecificCommand(TAgent& aAgent, TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);
williamr@2
   575
	
williamr@2
   576
		/** Allows a client to display management information for a particular agent
williamr@2
   577
		
williamr@2
   578
		This allows a user to see all the specific information associated
williamr@2
   579
		with a particular agent. In the case of an agent implementing DRM this could 
williamr@2
   580
		include the ability to list, view or delete DRM rights objects.
williamr@2
   581
williamr@2
   582
		@param aAgent The agent.
williamr@2
   583
		@leave KErrCANotSupported If the specified agent does not support the display of management information.
williamr@2
   584
		@capability DRM Agents implementing DRM may not display their management dialog to processes without DRM capability
williamr@2
   585
		*/
williamr@2
   586
		IMPORT_C void DisplayManagementInfoL(TAgent& aAgent);  
williamr@2
   587
williamr@2
   588
		/** Allow clients to list, view and delete the rights contained by an agent 
williamr@2
   589
		in a generic manner.
williamr@2
   590
		
williamr@2
   591
		This function is only relevant for agents implementing a DRM scheme. Other agents
williamr@2
   592
		will leave with KErrCANotSupported if an application attempts to invoke the
williamr@2
   593
		rights manager.
williamr@2
   594
williamr@2
   595
		To manage the rights in a more comprehensive manner the application should use the 
williamr@2
   596
		DisplayManagementInfoL() function where the agent can present its own 
williamr@2
   597
		management information.
williamr@2
   598
williamr@2
   599
		@param aAgent The agent to create a rights manager object.
williamr@2
   600
		@return A CRightsManager object for the specified agent.
williamr@2
   601
williamr@2
   602
		@leave KErrCANotSupported If the agent does not implement DRM or support rights management.
williamr@2
   603
		@leave KErrPermissionDenied If the agent does not allow the client to create a rights manager.
williamr@2
   604
  		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
williamr@2
   605
		*/
williamr@2
   606
		IMPORT_C CRightsManager* CreateRightsManagerL(TAgent& aAgent) const;
williamr@2
   607
		
williamr@2
   608
#ifndef REMOVE_CAF1
williamr@2
   609
		/** Delete a file
williamr@2
   610
		@param aFileName The file to delete.
williamr@2
   611
		@deprecated Use DeleteFile() instead.
williamr@2
   612
		*/
williamr@2
   613
		IMPORT_C static void DeleteFileL (const TDesC &aFileName);
williamr@2
   614
#endif // REMOVE_CAF1
williamr@2
   615
williamr@2
   616
	private:
williamr@2
   617
		CManager();
williamr@2
   618
		void ConstructL();
williamr@2
   619
williamr@2
   620
		/** Populate the list of agents in the CDirStreamable 
williamr@2
   621
		@param aDir Reference to a CDir pointer, this pointer must be set to NULL
williamr@2
   622
		*/
williamr@2
   623
		void GetListOfAgentPrivateDirectoriesL(CDir *&aDir) const;
williamr@2
   624
		
williamr@2
   625
		// Implemenetation functions for public exports
williamr@2
   626
		void DoDeleteFileL(const TDesC &aFileName) const;
williamr@2
   627
		void DoCopyFileL(const TDesC& aSource, const TDesC& aDestination) const;		
williamr@2
   628
		void DoCopyFileL(RFile& aSourceFile, const TDesC &aDestination) const;
williamr@2
   629
		void DoRenameFileL(const TDesC& aSource, const TDesC& aDestination) const;		
williamr@2
   630
		void DoMkDirL(const TDesC &aPath) const;
williamr@2
   631
		void DoMkDirAllL(const TDesC &aPath) const;
williamr@2
   632
		void DoRmDirL(const TDesC &aPath) const;
williamr@2
   633
		void DoRenameDirL(const TDesC &aOldName, const TDesC& aNewName) const;
williamr@2
   634
		void DoGetDirL(const TDesC& aName, TUint aEntryAttMask, TUint aEntrySortKey, CDir*& aEntryList) const;
williamr@2
   635
		void DoGetDirL(const TDesC& aName, TUint aEntryAttMask, TUint anEntrySortKey, CDir*& aEntryList, CDir*& aDirList) const;
williamr@2
   636
		void DoGetDirL(const TDesC &aName, const TUidType &aEntryUid, TUint aEntrySortKey, CDir *&aFileList) const;
williamr@2
   637
		void DoGetAttributeL(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) const;
williamr@2
   638
		void DoGetAttributeSetL(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) const;		
williamr@2
   639
		void DoGetStringAttributeL(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) const;		
williamr@2
   640
		void DoGetStringAttributeSetL(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) const;		
williamr@2
   641
		void DoNotifyStatusChangeL(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus);		
williamr@2
   642
		void DoCancelNotifyStatusChangeL(const TDesC& aURI, TRequestStatus& aStatus);
williamr@2
   643
		void DoSetPropertyL(TAgentProperty aProperty, TInt aValue);		
williamr@2
   644
	private:
williamr@2
   645
		// Holds instances of all the agents
williamr@2
   646
		CAgentResolver* iResolver;
williamr@2
   647
		};
williamr@2
   648
williamr@2
   649
	} // namespace ContentAccess
williamr@2
   650
williamr@2
   651
#endif /* __MANAGER_H__ */
williamr@2
   652
williamr@2
   653