1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/caf/data.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,725 @@
1.4 +/*
1.5 +* Copyright (c) 2003-2007 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 +/**
1.24 +@file
1.25 +
1.26 +@publishedPartner
1.27 +@released
1.28 +*/
1.29 +
1.30 +
1.31 +#ifndef __DATA_H__
1.32 +#define __DATA_H__
1.33 +
1.34 +#include <e32base.h>
1.35 +#include <f32file.h>
1.36 +#include <caf/caftypes.h>
1.37 +
1.38 +namespace ContentAccess
1.39 +{
1.40 + class CAgentFactory;
1.41 + class CAgentInfo;
1.42 + class TVirtualPathPtr;
1.43 + class CAgentData;
1.44 + class RAttributeSet;
1.45 + class RStringAttributeSet;
1.46 +
1.47 +
1.48 + /**
1.49 + Allows clients to read data from a content object.
1.50 +
1.51 + This class is initialised with an agent implementation that is
1.52 + responsible for this content object.
1.53 +
1.54 + @publishedPartner
1.55 + @released
1.56 + */
1.57 + class CData : public CBase
1.58 + {
1.59 + public:
1.60 + /**
1.61 + Creates a new CData object.
1.62 +
1.63 + @param aVirtualPath The content object to read
1.64 + @param aIntent The intended use of the content.
1.65 + @param aShareMode The file share mode used to open this content.
1.66 + @return The new CData object.
1.67 +
1.68 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.69 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.70 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.71 + @leave KErrCANoRights No rights exist for the content object.
1.72 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.73 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.74 + @leave KErrAccessDenied The content is already in use.
1.75 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.76 + or one of the other system-wide error codes
1.77 + for any other errors.
1.78 + */
1.79 + IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,
1.80 + TIntent aIntent, TContentShareMode aShareMode);
1.81 +
1.82 + /**
1.83 + Creates a new CData object.
1.84 +
1.85 + @param aVirtualPath The content object to read.
1.86 + @param aShareMode The file share mode used to open this content.
1.87 + @return The new CData object.
1.88 +
1.89 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.90 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.91 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.92 + @leave KErrCANoRights No rights exist for the content object.
1.93 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.94 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.95 + @leave KErrAccessDenied The content is already in use.
1.96 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.97 + or one of the other system-wide error codes for
1.98 + any other errors.
1.99 + */
1.100 + IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,
1.101 + TContentShareMode aShareMode);
1.102 +
1.103 +
1.104 + /**
1.105 + Creates a new CData object
1.106 +
1.107 + @param aVirtualPath The content object to read.
1.108 + @param aIntent The intended use of the content.
1.109 + @param aShareMode The file share mode used to open this content.
1.110 + @return The new CData object.
1.111 +
1.112 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.113 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.114 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.115 + @leave KErrCANoRights No rights exist for the content object.
1.116 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.117 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.118 + @leave KErrAccessDenied The content is already in use.
1.119 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.120 + or one of the other system-wide error codes for
1.121 + any other errors.
1.122 + */
1.123 + IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,
1.124 + TIntent aIntent, TContentShareMode aShareMode);
1.125 +
1.126 + /**
1.127 + Creates a new CData object
1.128 +
1.129 + @param aVirtualPath The content object to read.
1.130 + @param aShareMode The file share mode used to open this content.
1.131 + @return The new CData object.
1.132 +
1.133 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.134 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.135 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.136 + @leave KErrCANoRights No rights exist for the content object.
1.137 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.138 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.139 + @leave KErrAccessDenied The content is already in use.
1.140 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.141 + or one of the other system-wide error codes for
1.142 + any other errors.
1.143 + */
1.144 + IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,
1.145 + TContentShareMode aShareMode);
1.146 +
1.147 +
1.148 + /**
1.149 + Creates a new CData object.
1.150 +
1.151 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.152 + The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.
1.153 + @param aUniqueId The content object to read.
1.154 + @param aIntent The intended use of the content.
1.155 + @return The new CData object.
1.156 +
1.157 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.158 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.159 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.160 + @leave KErrCANoRights No rights exist for the content object.
1.161 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.162 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.163 + @leave KErrAccessDenied The content is already in use.
1.164 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.165 + or one of the other system-wide error codes for
1.166 + any other errors.
1.167 + */
1.168 + IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.169 +
1.170 + /**
1.171 + Creates a new CData object.
1.172 +
1.173 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.174 + The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.
1.175 + @param aUniqueId The content object to read.
1.176 + @return The new CData object.
1.177 +
1.178 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.179 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.180 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.181 + @leave KErrCANoRights No rights exist for the content object.
1.182 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.183 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.184 + @leave KErrAccessDenied The content is already in use.
1.185 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.186 + or one of the other system-wide error codes for
1.187 + any other errors.
1.188 + */
1.189 + IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId);
1.190 +
1.191 + /**
1.192 + Creates a new CData object.
1.193 +
1.194 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.195 + The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.
1.196 + @param aUniqueId The content object to read.
1.197 + @param aIntent The intended use of the content.
1.198 + @return The new CData object.
1.199 +
1.200 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.201 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.202 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.203 + @leave KErrCANoRights No rights exist for the content object.
1.204 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.205 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.206 + @leave KErrAccessDenied The content is already in use.
1.207 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.208 + or one of the other system-wide error codes
1.209 + for any other errors.
1.210 + */
1.211 + IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.212 +
1.213 + /**
1.214 + Creates a new CData object.
1.215 +
1.216 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.217 + The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.
1.218 + @param aUniqueId The content object to read.
1.219 + @return The new CData object.
1.220 +
1.221 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.222 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.223 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.224 + @leave KErrCANoRights No rights exist for the content object.
1.225 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.226 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.227 + @leave KErrAccessDenied The content is already in use.
1.228 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.229 + or one of the other system-wide error codes
1.230 + for any other errors.
1.231 + */
1.232 + IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId);
1.233 +
1.234 + /**
1.235 + Creates a new CData object.
1.236 +
1.237 + @param aAgentUid The agent determined to support this content.
1.238 + @param aVirtualPath The content object to read.
1.239 + @param aIntent The intended use of the content.
1.240 + @param aShareMode The file share mode used to open this content.
1.241 + @return The new CData object.
1.242 +
1.243 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.244 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.245 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.246 + @leave KErrCANoRights No rights exist for the content object.
1.247 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.248 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.249 + @leave KErrAccessDenied The content is already in use.
1.250 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.251 + or one of the other system-wide error codes
1.252 + for any other errors.
1.253 +
1.254 + @internalComponent
1.255 + @released
1.256 + */
1.257 + static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath,
1.258 + TIntent aIntent, TContentShareMode aShareMode);
1.259 +
1.260 + /**
1.261 + Creates a new CData object.
1.262 +
1.263 + @param aAgentUid The Uid of the agent who supports this content.
1.264 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.265 + The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.
1.266 + @param aUniqueId The content object to read.
1.267 + @param aIntent The intended use of the content.
1.268 + @return The new CData object.
1.269 +
1.270 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.271 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.272 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.273 + @leave KErrCANoRights No rights exist for the content object.
1.274 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.275 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.276 + @leave KErrAccessDenied The content is already in use.
1.277 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.278 + or one of the other system-wide error codes for
1.279 + any other errors.
1.280 +
1.281 + @internalComponent
1.282 + @released
1.283 + */
1.284 + static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.285 +
1.286 + /** destructor */
1.287 + virtual ~CData();
1.288 +
1.289 + /**
1.290 + Reads from a content object up to the maximum length of the
1.291 + descriptor or the end of the content object.
1.292 +
1.293 + When an attempt is made to read beyond the end of the content,
1.294 + no error is returned. The descriptor’s length is set to the
1.295 + number of bytes that were read into it. Therefore, when reading
1.296 + through content, the end has been reached when the
1.297 + descriptor length (given by TDesC::Length()) is zero.
1.298 +
1.299 + @param aDes Descriptor into which binary data is read. Any existing
1.300 + contents are overwritten. On return, its length is set
1.301 + to the number of bytes read.
1.302 + @return KErrNone if successful.
1.303 + @return One of the CAF error codes defined in \c caferr.h or
1.304 + one of the other system-wide error codes.
1.305 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.306 + */
1.307 + IMPORT_C TInt Read(TDes8& aDes) const;
1.308 +
1.309 + /**
1.310 + Reads from a content object up to the specified length of the
1.311 + descriptor or the end of the content object.
1.312 +
1.313 + @see Read(TDes8& aDes)
1.314 +
1.315 + @param aDes Descriptor into which binary data is read. Any existing
1.316 + contents are overwritten. On return, its length is set
1.317 + to the number of bytes read.
1.318 + @param aLength The number of bytes to read from the file,
1.319 + or to the end of the file, whichever is encountered first.
1.320 + The length of the buffer is set to the number of bytes actually read.
1.321 + @return KErrNone if successful.
1.322 + @return Otherwise one of the CAF error codes defined in \c caferr.h or
1.323 + one of the other system-wide error codes.
1.324 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.325 + */
1.326 + IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const;
1.327 +
1.328 + /**
1.329 + Read content asynchronously up to the maximum length of the descriptor
1.330 + or until the end of the content object is reached.
1.331 + NB: It is important that the descriptor passed to
1.332 + aDes remains in scope until the request has completed.
1.333 +
1.334 + @see Read(TDes8& aDes)
1.335 +
1.336 + @param aDes Descriptor into which binary data is read. Any
1.337 + existing contents are overwritten. On return,
1.338 + its length is set to the number of bytes read.
1.339 + @param aStatus Asynchronous request status. On completion this will contain one
1.340 + of the following error codes: KErrNone if the data was
1.341 + successfully read. Otherwise one of the CAF error codes defined in
1.342 + \c caferr.h or one of the other standard system-wide
1.343 + error codes for any other errors.
1.344 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.345 + */
1.346 + IMPORT_C void Read(TDes8& aDes, TRequestStatus& aStatus) const;
1.347 +
1.348 + /**
1.349 + Read content asynchronously up to the specified length
1.350 + or until the end of the content object is reached.
1.351 + NB: It is important that the descriptor passed to
1.352 + aDes remains in scope until the request has completed.
1.353 +
1.354 + @see Read(TDes8& aDes)
1.355 +
1.356 + @param aDes Descriptor into which binary data is read. Any
1.357 + existing contents are overwritten. On return,
1.358 + its length is set to the number of bytes read.
1.359 + @param aLength The number of bytes to read from the file,
1.360 + or to the end of the file, whichever is encountered first.
1.361 + The length of the buffer is set to the number of bytes actually read.
1.362 + @param aStatus Asynchronous request status. On completion this will contain one
1.363 + of the following error codes: KErrNone if the data was
1.364 + successfully read. Otherwise one of the CAF error codes defined in
1.365 + \c caferr.h or one of the other standard system-wide
1.366 + error codes for any other errors.
1.367 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.368 + */
1.369 + IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.370 +
1.371 + /**
1.372 + Cancels asynchronous read.
1.373 +
1.374 + @param aStatus Asynchronous request status. This parameter should have been supplied earlier to
1.375 + an asynchronous Read call. If it has not been previously supplied to a Read call,
1.376 + this function will not have any effect.
1.377 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.378 + */
1.379 + IMPORT_C void ReadCancel(TRequestStatus &aStatus) const;
1.380 +
1.381 + /**
1.382 + Reads content asynchronously. The data is read from a specified offset
1.383 + up to a specified number of bytes or until the end of the content object
1.384 + is reached. The data is read into the descriptor buffer supplied.
1.385 + NB: It is important that the descriptor passed to
1.386 + aDes remains in scope until the request has completed.
1.387 +
1.388 + @see Read(TDes8& aDes)
1.389 +
1.390 + @param aPos Position of first byte to be read.
1.391 + This is an offset from the start of the file.
1.392 + @param aDes Descriptor into which binary data is read. Any
1.393 + existing contents are overwritten. On return,
1.394 + its length is set to the number of bytes read.
1.395 + @param aLength The number of bytes to read from the file,
1.396 + or to the end of the file, whichever is encountered first.
1.397 + The length of the buffer is set to the number of bytes actually read.
1.398 + @param aStatus Asynchronous request status. On completion this will contain one
1.399 + of the following error codes: KErrNone if the data was
1.400 + successfully read. Otherwise one of the CAF error codes defined in
1.401 + \c caferr.h or one of the other standard system-wide
1.402 + error codes for any other errors.
1.403 + @return KErrNone if the async read request was successfully submitted.
1.404 + @return KErrArgument if a negative offset is supplied.
1.405 + @return KErrCANotSupported if the agent does not support this operation.
1.406 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.407 + */
1.408 + IMPORT_C TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.409 +
1.410 + /**
1.411 + Gets the data size in bytes.
1.412 +
1.413 + @param aSize On return this will contain the size of the plaintext data in bytes.
1.414 + @leave KErrCASizeNotDetermined Size could not be determined by the managing agent.
1.415 + @leave ... One of the other CAF error codes defined in \c caferr.h or one of the
1.416 + 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 void DataSizeL(TInt& aSize);
1.420 +
1.421 + /**
1.422 + Changes or retrieves the location of the file pointer within
1.423 + the content object.
1.424 +
1.425 + NOTE: Some operations may fail if the content data is sourced over a network connection.
1.426 +
1.427 + There are four seek modes used:
1.428 +
1.429 + @li ESeekStart - Sets the file pointer aPos bytes from the start of the
1.430 + content object. aPos is not modified by the call to Seek()
1.431 + @li ESeekEnd - Sets the file pointer aPos bytes from the end of the
1.432 + content object. The aPos parameter supplied should be zero or negative
1.433 + when using ESeekEnd. Upon completion aPos is updated with the current
1.434 + position relative to the start of the content object.
1.435 + @li ESeekCurrent - Moves the file pointer aPos bytes from the current
1.436 + position. Upon completion aPos is updated with the new position relative
1.437 + to the start of the content object. Suppling a zero value for the aPos Parameter can be
1.438 + used to retrieve the current file pointer location
1.439 + @li ESeekAddress Sets the aPos parameter to the address of the byte
1.440 + aPos bytes from the start of the content object
1.441 +
1.442 + @see TSeek
1.443 +
1.444 + @param aMode Seek mode - controls the destination of the
1.445 + seek operation.
1.446 +
1.447 + @param aPos Offset from either the start, end or current position depending upon
1.448 + the seek mode. Negative offsets are used to seek before the current position or
1.449 + relative to the end of the file.
1.450 +
1.451 + @return KErrNone if successful.
1.452 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one
1.453 + of the other system-wide error codes.
1.454 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.455 + */
1.456 + IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const;
1.457 +
1.458 +
1.459 + /** Request the agent handling this content to set a property value. If the property is set
1.460 + it is only set for this CData session and does not impact other CAF users.
1.461 +
1.462 + For example setting the buffer-size to 256 bytes can be achieved as follows:
1.463 +
1.464 + @code
1.465 + MyData->SetProperty(EAgentPropertyBufferSize, 256);
1.466 + @endcode
1.467 +
1.468 + @see ContentAccess::TAgentProperty
1.469 +
1.470 + @param aProperty The property to set.
1.471 + @param aValue The value of the property.
1.472 + @return Whether or not the property was set.
1.473 + @return KErrNone if the property was set.
1.474 + @return KErrCANotSupported if the agent does not support the property or value.
1.475 + @return KErrAccessDenied if the agent does not permit the property to be changed.
1.476 + @return KErrPermissionDenied if the application does not have the necessary capability to change the property.
1.477 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.478 + */
1.479 + IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);
1.480 +
1.481 + /**
1.482 + Allows a client to verify that the intent is supported by the
1.483 + current rights for the data object.
1.484 +
1.485 + @note Since the intent is only evaluated the agent will not decrement
1.486 + any rights-state such as play counts.
1.487 +
1.488 + @see ContentAccess::TIntent
1.489 +
1.490 + @param aIntent The intended way the content will be used.
1.491 + @return Whether rights exist allowing the content to be used for this intent.
1.492 + @return KErrNone if the intent is permitted.
1.493 + @return KErrNoRights if no rights exist for the specified content object.
1.494 + @return KErrCANoPermission if rights exist but the specified intent is not permitted.
1.495 + @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
1.496 + @return KErrNoPermission if rights exist but none permit the specified intent.
1.497 + @return KErrPermissionDenied if the client is not allowed to use this content object.
1.498 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.499 + other system-wide error codes for any other errors.
1.500 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.501 + */
1.502 + IMPORT_C TInt EvaluateIntent(TIntent aIntent);
1.503 +
1.504 + /**
1.505 + Execute intent allows the application to signal it is about to carry out
1.506 + the specified intent on protected content.The agent will decrement applicable
1.507 + stateful rights such as play counts where necessary.
1.508 +
1.509 + Applications should be very careful to use this function correctly.
1.510 + @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever
1.511 + @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely.
1.512 +
1.513 + Usually it would be best to call ExecuteIntent immediately before the content
1.514 + is displayed or the instant playback begins. ExecuteIntent should not be considered a
1.515 + prerequisite for calling the Read functions. It is valid for an application to read from
1.516 + the file before calling ExecuteIntent.
1.517 +
1.518 + @note Since rights are executed here the agent will decrement any rights-state such as
1.519 + play counts that apply.
1.520 +
1.521 + @param aIntent The intent indicator.
1.522 + @return The result of attempting executing the intent.
1.523 + @return KErrNone if the intent is permitted and stateful rights may have been decremented.
1.524 + @return KErrNoRights if no rights exist for the specified content object.
1.525 + @return KErrCANoPermission if rights exist but the specified intent is not permitted.
1.526 + @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
1.527 + @return KErrNoPermission if rights exist but none permit the specified intent.
1.528 + @return KErrPermissionDenied if the client is not allowed to use this content object.
1.529 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the.
1.530 + other system-wide error codes for any other errors.
1.531 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.532 + */
1.533 + IMPORT_C TInt ExecuteIntent(TIntent aIntent);
1.534 +
1.535 + /** Get an attribute for the content object
1.536 +
1.537 + @see ContentAccess::TAttribute
1.538 +
1.539 + @code
1.540 + CContent* content = CContent::NewL(uri);
1.541 + CData* data = content->OpenContentL(EPlay, uniqueId);
1.542 + delete content;
1.543 +
1.544 + TInt value = 0;
1.545 + TInt err = data->GetAttribute(EIsProtected, value);
1.546 + if(err == KErrNone && value)
1.547 + {
1.548 + DisplayPadLock();
1.549 + }
1.550 +
1.551 + delete data;
1.552 + @endcode
1.553 +
1.554 + @param aAttribute The attribute to query, from ContentAccess::TAttribute.
1.555 + @param aValue Used to return the attribute value.
1.556 + @return Whether the attribute was updated.
1.557 + @return KErrNone if the value of the attribute was updated.
1.558 + @return KErrCANotSupported if the requested attribute does not exist.
1.559 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.560 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.561 + other system-wide error codes for any other errors.
1.562 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.563 + */
1.564 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const;
1.565 +
1.566 + /** Get a set of attributes for the content object
1.567 +
1.568 + @see ContentAccess::TAttribute
1.569 +
1.570 + The following example determines whether the content object
1.571 + is protected and has rights that will enable it to be viewed by the
1.572 + user
1.573 +
1.574 + @code
1.575 + // CData* data = a data object
1.576 +
1.577 + RAttributeSet attributeSet;
1.578 + CleanupClosePushL(attributeSet);
1.579 + attributeSet->AddL(EProtected);
1.580 + attributeSet->AddL(ECanView);
1.581 +
1.582 + User::LeaveIfError(data->GetAttributeSet(attributeSet);
1.583 +
1.584 + TInt err = attributeSet.GetValue(EProtected, value);
1.585 + if(err == KErrNone && value)
1.586 + {
1.587 + // file is DRM protected
1.588 + }
1.589 +
1.590 + err = attributeSet.GetValue(ECanView, value);
1.591 + if(err == KErrNone && value)
1.592 + {
1.593 + // File has rights that allow it to be displayed on screen
1.594 + }
1.595 +
1.596 + // Finished
1.597 + CleanupStack::PopAndDestroy(); // attributeSet.Close()
1.598 + @endcode
1.599 +
1.600 +
1.601 + @param aAttributeSet The set of attributes to query and update.
1.602 + @return Whether the attribute set was updated.
1.603 + @return KErrNone if the attributes were retrieved successfully.
1.604 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.605 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.606 + other system-wide error codes for any other errors.
1.607 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.608 + */
1.609 + IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const;
1.610 +
1.611 +
1.612 + /** Get text string attributes or meta-data for the content object
1.613 +
1.614 + @see ContentAccess::TStringAttribute
1.615 +
1.616 + @code
1.617 + CContent* content = CContent::NewLC(uri);
1.618 + CData* data = content->OpenContentLC(EPlay, uniqueId);
1.619 + CleanupStack::PopAndDestroy(content);
1.620 +
1.621 + TBuf <MAX_PATH> previewUri;
1.622 + TInt err = data->GetStringAttribute(EPreviewURI, previewUri);
1.623 + if(err == KErrNone)
1.624 + {
1.625 + DisplayPreview(previewUri);
1.626 + }
1.627 +
1.628 + CleanupStack::PopAndDestroy(data);
1.629 + @endcode
1.630 +
1.631 + @param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
1.632 + @param aValue Returns the value of the attribute.
1.633 + @return Whether the value was updated.
1.634 + @return KErrNone if the attribute was retrieved.
1.635 + @return KErrOverflow if the buffer was not large enough to return the result.
1.636 + @return KErrCANotSupported if the requested attribute does not exist.
1.637 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.638 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.639 + other system-wide error codes for any other errors.
1.640 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.641 + */
1.642 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const;
1.643 +
1.644 +
1.645 +
1.646 + /** Obtain a set of string attributes for the content object
1.647 +
1.648 + @see ContentAccess::TStringAttribute
1.649 +
1.650 + @code
1.651 + CContent* content = CContent::NewLC(uri);
1.652 + CData* data = content->OpenContentLC(EPlay, uniqueId);
1.653 +
1.654 + // create the attribute set, add the attributes we are interested in
1.655 + RStringAttributeSet stringAttributeSet;
1.656 + CleanupClosePushL(stringAttributeSet);
1.657 + stringAttributeSet.AddL(EPreviewURI);
1.658 + stringAttributeSet.AddL(ETitle);
1.659 +
1.660 + User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet));
1.661 +
1.662 + // Pass the value of the string attribute to DisplayPreview()
1.663 + TFileName previewUri;
1.664 + TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
1.665 + if(err == KErrNone)
1.666 + {
1.667 + DisplayPreview(previewUri);
1.668 + }
1.669 +
1.670 + CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet
1.671 + @endcode
1.672 +
1.673 +
1.674 + @param aStringAttributeSet The set of attributes to query and update.
1.675 + @return Whether the string attribute set was updated.
1.676 + @return KErrNone if the attributes were retrieved successfully.
1.677 + @return KErrNotFound if the default content object was not found.
1.678 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.679 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.680 + other system-wide error codes for any other errors.
1.681 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.682 + */
1.683 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;
1.684 +
1.685 +#ifndef REMOVE_CAF1
1.686 + /** Set Qos attribute
1.687 + @param aQosAttr The Qos attribute to set.
1.688 + @param aValue The value of the attribute.
1.689 + @deprecated
1.690 + */
1.691 + IMPORT_C void SetQosL(TQosAttribute aQosAttr, TInt aValue);
1.692 +
1.693 + /** Get the mime type of the content
1.694 + @param aMimeType Buffer to store the mime type provided by the agent.
1.695 + @return ETrue if the mime type was retrieved successfully.
1.696 + @deprecated
1.697 + */
1.698 + IMPORT_C TBool GetMimeTypeL(TDes8& aMimeType) const;
1.699 +#endif // REMOVE_CAF1
1.700 +
1.701 +
1.702 + private:
1.703 + CData();
1.704 + void ConstructL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.705 + void ConstructL(const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode);
1.706 + void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.707 + void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode);
1.708 +
1.709 + void ConstructL(RFile& aFile, const TDesC& aUniqueId);
1.710 + void ConstructL(const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode);
1.711 + void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId);
1.712 + void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode);
1.713 +
1.714 +
1.715 + private:
1.716 + // The agent handling this content
1.717 + CAgentData* iAgentData;
1.718 +
1.719 + // Defacto ECOM session handle
1.720 + CAgentFactory* iAgentFactory;
1.721 +
1.722 + // Uid of the agent
1.723 + TUid iAgentUid;
1.724 + };
1.725 +
1.726 +} // namespace ContentAccess
1.727 +#endif /* __DATA_H__ */
1.728 +