1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/inc/data.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,888 @@
1.4 +/*
1.5 +* Copyright (c) 2003-2008 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 +@publishedAll
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 + */
1.55 + class CData : public CBase
1.56 + {
1.57 + public:
1.58 + /**
1.59 + Creates a new CData object.
1.60 +
1.61 + @param aVirtualPath The content object to read
1.62 + @param aIntent The intended use of the content.
1.63 + @param aShareMode The file share mode used to open this content.
1.64 + @return The new CData object.
1.65 +
1.66 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.67 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.68 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.69 + @leave KErrCANoRights No rights exist for the content object.
1.70 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.71 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.72 + @leave KErrAccessDenied The content is already in use.
1.73 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.74 + or one of the other system-wide error codes
1.75 + for any other errors.
1.76 + */
1.77 + IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,
1.78 + TIntent aIntent, TContentShareMode aShareMode);
1.79 +
1.80 + /**
1.81 + Creates a new CData object.
1.82 +
1.83 + @param aVirtualPath The content object to read.
1.84 + @param aShareMode The file share mode used to open this content.
1.85 + @return The new CData object.
1.86 +
1.87 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.88 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.89 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.90 + @leave KErrCANoRights No rights exist for the content object.
1.91 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.92 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.93 + @leave KErrAccessDenied The content is already in use.
1.94 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.95 + or one of the other system-wide error codes for
1.96 + any other errors.
1.97 + */
1.98 + IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,
1.99 + TContentShareMode aShareMode);
1.100 +
1.101 +
1.102 + /**
1.103 + Creates a new CData object
1.104 +
1.105 + @param aVirtualPath The content object to read.
1.106 + @param aIntent The intended use of the content.
1.107 + @param aShareMode The file share mode used to open this content.
1.108 + @return The new CData object.
1.109 +
1.110 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.111 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.112 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.113 + @leave KErrCANoRights No rights exist for the content object.
1.114 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.115 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.116 + @leave KErrAccessDenied The content is already in use.
1.117 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.118 + or one of the other system-wide error codes for
1.119 + any other errors.
1.120 + */
1.121 + IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,
1.122 + TIntent aIntent, TContentShareMode aShareMode);
1.123 +
1.124 + /**
1.125 + Creates a new CData object
1.126 +
1.127 + @param aVirtualPath The content object to read.
1.128 + @param aShareMode The file share mode used to open this content.
1.129 + @return The new CData object.
1.130 +
1.131 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.132 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.133 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.134 + @leave KErrCANoRights No rights exist for the content object.
1.135 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.136 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.137 + @leave KErrAccessDenied The content is already in use.
1.138 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.139 + or one of the other system-wide error codes for
1.140 + any other errors.
1.141 + */
1.142 + IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,
1.143 + TContentShareMode aShareMode);
1.144 +
1.145 +
1.146 + /**
1.147 + Creates a new CData object.
1.148 +
1.149 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.150 + 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.151 + @param aUniqueId The content object to read.
1.152 + @param aIntent The intended use of the content.
1.153 + @return The new CData object.
1.154 +
1.155 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.156 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.157 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.158 + @leave KErrCANoRights No rights exist for the content object.
1.159 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.160 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.161 + @leave KErrAccessDenied The content is already in use.
1.162 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.163 + or one of the other system-wide error codes for
1.164 + any other errors.
1.165 + */
1.166 + IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.167 +
1.168 + /**
1.169 + Creates a new CData object.
1.170 +
1.171 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.172 + 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.173 + @param aUniqueId The content object to read.
1.174 + @return The new CData object.
1.175 +
1.176 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.177 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.178 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.179 + @leave KErrCANoRights No rights exist for the content object.
1.180 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.181 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.182 + @leave KErrAccessDenied The content is already in use.
1.183 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.184 + or one of the other system-wide error codes for
1.185 + any other errors.
1.186 + */
1.187 + IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId);
1.188 +
1.189 + /**
1.190 + Creates a new CData object.
1.191 +
1.192 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.193 + 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.194 + @param aUniqueId The content object to read.
1.195 + @param aIntent The intended use of the content.
1.196 + @return The new CData object.
1.197 +
1.198 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.199 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.200 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.201 + @leave KErrCANoRights No rights exist for the content object.
1.202 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.203 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.204 + @leave KErrAccessDenied The content is already in use.
1.205 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.206 + or one of the other system-wide error codes
1.207 + for any other errors.
1.208 + */
1.209 + IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.210 +
1.211 + /**
1.212 + Creates a new CData object.
1.213 +
1.214 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.215 + 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.216 + @param aUniqueId The content object to read.
1.217 + @return The new CData object.
1.218 +
1.219 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.220 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.221 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.222 + @leave KErrCANoRights No rights exist for the content object.
1.223 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.224 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.225 + @leave KErrAccessDenied The content is already in use.
1.226 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.227 + or one of the other system-wide error codes
1.228 + for any other errors.
1.229 + */
1.230 + IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId);
1.231 +
1.232 + /**
1.233 + Creates a new CData object.
1.234 +
1.235 + @param aAgentUid The agent determined to support this content.
1.236 + @param aVirtualPath The content object to read.
1.237 + @param aIntent The intended use of the content.
1.238 + @param aShareMode The file share mode used to open this content.
1.239 + @return The new CData object.
1.240 +
1.241 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.242 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.243 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.244 + @leave KErrCANoRights No rights exist for the content object.
1.245 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.246 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.247 + @leave KErrAccessDenied The content is already in use.
1.248 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.249 + or one of the other system-wide error codes
1.250 + for any other errors.
1.251 + */
1.252 + static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath,
1.253 + TIntent aIntent, TContentShareMode aShareMode);
1.254 +
1.255 + /**
1.256 + Creates a new CData object.
1.257 +
1.258 + @param aAgentUid The Uid of the agent who supports this content.
1.259 + @param aFile An open RFile handle, the agent will make a duplicate of this handle.
1.260 + 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.261 + @param aUniqueId The content object to read.
1.262 + @param aIntent The intended use of the content.
1.263 + @return The new CData object.
1.264 +
1.265 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.266 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.267 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.268 + @leave KErrCANoRights No rights exist for the content object.
1.269 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.270 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.271 + @leave KErrAccessDenied The content is already in use.
1.272 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.273 + or one of the other system-wide error codes for
1.274 + any other errors.
1.275 +
1.276 + */
1.277 + static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.278 +
1.279 +#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.280 +
1.281 + /**
1.282 + Creates a new CData object.
1.283 + @param aHeaderData Header data of WMDRM file/stream content.
1.284 + @return CData object.
1.285 + @leave One of the CAF error codes defined in caferr.h or one of the
1.286 + system-wide error for any other errors.
1.287 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.288 + Access to unprotected content is unrestricted.
1.289 + */
1.290 +
1.291 + IMPORT_C static CData* NewL(const TDesC8& aHeaderData);
1.292 +
1.293 + /**
1.294 + Creates a new CData object.
1.295 + @param aHeaderData Header data of WMDRM file/stream content.
1.296 + @param aIntent The intended use of the content.
1.297 + @return CData object.
1.298 + @leave One of the CAF error codes defined in caferr.h or one of the
1.299 + system-wide error for any other errors.
1.300 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.301 + Access to unprotected content is unrestricted.
1.302 + */
1.303 +
1.304 + IMPORT_C static CData* NewL(const TDesC8& aHeaderData, TIntent aIntent);
1.305 +
1.306 + /**
1.307 + Creates a new CData object.
1.308 + @param aHeaderData Header data of WMDRM file/stream content.
1.309 + @return CData object.
1.310 + @leave One of the CAF error codes defined in caferr.h or one of the
1.311 + system-wide error for any other errors.
1.312 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.313 + Access to unprotected content is unrestricted.
1.314 + */
1.315 +
1.316 + IMPORT_C static CData* NewLC(const TDesC8& aHeaderData);
1.317 +
1.318 + /**
1.319 + Creates a new CData object.
1.320 + @param aHeaderData Header data of WMDRM file/stream content.
1.321 + @param aIntent The intended use of the content.
1.322 + @return CData object.
1.323 + @leave One of the CAF error codes defined in caferr.h or one of the
1.324 + system-wide error for any other errors.
1.325 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.326 + Access to unprotected content is unrestricted.
1.327 + */
1.328 +
1.329 + IMPORT_C static CData* NewLC(const TDesC8& aHeaderData, TIntent aIntent);
1.330 +
1.331 + /**
1.332 + Creates a new CData object.
1.333 + @param aAgentUid UID of an agent which supports this content.
1.334 + @param aHeaderData Header data of WMDRM file/stream content.
1.335 + @param aIntent The intended use of the content.
1.336 + @return CData object.
1.337 + @leave One of the CAF error codes defined in caferr.h or one of the
1.338 + system-wide error for any other errors.
1.339 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.340 + Access to unprotected content is unrestricted.
1.341 +
1.342 + */
1.343 +
1.344 + static CData* NewLC(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent);
1.345 +
1.346 +#endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.347 +
1.348 + /** destructor */
1.349 + virtual ~CData();
1.350 +
1.351 + /**
1.352 + Reads from a content object up to the maximum length of the
1.353 + descriptor or the end of the content object.
1.354 +
1.355 + When an attempt is made to read beyond the end of the content,
1.356 + no error is returned. The descriptor’s length is set to the
1.357 + number of bytes that were read into it. Therefore, when reading
1.358 + through content, the end has been reached when the
1.359 + descriptor length (given by TDesC::Length()) is zero.
1.360 +
1.361 + @param aDes Descriptor into which binary data is read. Any existing
1.362 + contents are overwritten. On return, its length is set
1.363 + to the number of bytes read.
1.364 + @return KErrNone if successful.
1.365 + @return One of the CAF error codes defined in \c caferr.h or
1.366 + one of the other system-wide error codes.
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 TInt Read(TDes8& aDes) const;
1.370 +
1.371 + /**
1.372 + Reads from a content object up to the specified length of the
1.373 + descriptor or the end of the content object.
1.374 +
1.375 + @see Read(TDes8& aDes)
1.376 +
1.377 + @param aDes Descriptor into which binary data is read. Any existing
1.378 + contents are overwritten. On return, its length is set
1.379 + to the number of bytes read.
1.380 + @param aLength The number of bytes to read from the file,
1.381 + or to the end of the file, whichever is encountered first.
1.382 + The length of the buffer is set to the number of bytes actually read.
1.383 + @return KErrNone if successful.
1.384 + @return Otherwise one of the CAF error codes defined in \c caferr.h or
1.385 + one of the other system-wide error codes.
1.386 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.387 + */
1.388 + IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const;
1.389 +
1.390 + /**
1.391 + Read content asynchronously up to the maximum length of the descriptor
1.392 + or until the end of the content object is reached.
1.393 + NB: It is important that the descriptor passed to
1.394 + aDes remains in scope until the request has completed.
1.395 +
1.396 + @see Read(TDes8& aDes)
1.397 +
1.398 + @param aDes Descriptor into which binary data is read. Any
1.399 + existing contents are overwritten. On return,
1.400 + its length is set to the number of bytes read.
1.401 + @param aStatus Asynchronous request status. On completion this will contain one
1.402 + of the following error codes: KErrNone if the data was
1.403 + successfully read. Otherwise one of the CAF error codes defined in
1.404 + \c caferr.h or one of the other standard system-wide
1.405 + error codes for any other errors.
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 void Read(TDes8& aDes, TRequestStatus& aStatus) const;
1.409 +
1.410 + /**
1.411 + Read content asynchronously up to the specified length
1.412 + or until the end of the content object is reached.
1.413 + NB: It is important that the descriptor passed to
1.414 + aDes remains in scope until the request has completed.
1.415 +
1.416 + @see Read(TDes8& aDes)
1.417 +
1.418 + @param aDes Descriptor into which binary data is read. Any
1.419 + existing contents are overwritten. On return,
1.420 + its length is set to the number of bytes read.
1.421 + @param aLength The number of bytes to read from the file,
1.422 + or to the end of the file, whichever is encountered first.
1.423 + The length of the buffer is set to the number of bytes actually read.
1.424 + @param aStatus Asynchronous request status. On completion this will contain one
1.425 + of the following error codes: KErrNone if the data was
1.426 + successfully read. Otherwise one of the CAF error codes defined in
1.427 + \c caferr.h or one of the other standard system-wide
1.428 + error codes for any other errors.
1.429 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.430 + */
1.431 + IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.432 +
1.433 + /**
1.434 + Cancels asynchronous read.
1.435 +
1.436 + @param aStatus Asynchronous request status. This parameter should have been supplied earlier to
1.437 + an asynchronous Read call. If it has not been previously supplied to a Read call,
1.438 + this function will not have any effect.
1.439 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.440 + */
1.441 + IMPORT_C void ReadCancel(TRequestStatus &aStatus) const;
1.442 +
1.443 +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.444 + /**
1.445 + Reads content asynchronously. The data is read from a specified offset
1.446 + up to a specified number of bytes or until the end of the content object
1.447 + is reached. The data is read into the descriptor buffer supplied.
1.448 + NB: It is important that the descriptor passed to
1.449 + aDes remains in scope until the request has completed.
1.450 + If agent does not support 64bit, fallback to 32bit Read is provided automatically by CAF
1.451 +
1.452 + @see Read(TDes8& aDes)
1.453 +
1.454 + @param aPos Position of first byte to be read.
1.455 + This is an offset from the start of the file.
1.456 + @param aDes Descriptor into which binary data is read. Any
1.457 + existing contents are overwritten. On return,
1.458 + its length is set to the number of bytes read.
1.459 + @param aLength The number of bytes to read from the file,
1.460 + or to the end of the file, whichever is encountered first.
1.461 + The length of the buffer is set to the number of bytes actually read.
1.462 + @param aStatus Asynchronous request status. On completion this will contain one
1.463 + of the following error codes: KErrNone if the data was
1.464 + successfully read. Otherwise one of the CAF error codes defined in
1.465 + \c caferr.h or one of the other standard system-wide
1.466 + error codes for any other errors.
1.467 + @return KErrNone if the async read request was successfully submitted.
1.468 + @return KErrArgument if a negative offset is supplied.
1.469 + @return KErrCANotSupported if the agent does not support this operation.
1.470 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.471 + */
1.472 + IMPORT_C TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.473 +#else
1.474 + /**
1.475 + Reads content asynchronously. The data is read from a specified offset
1.476 + up to a specified number of bytes or until the end of the content object
1.477 + is reached. The data is read into the descriptor buffer supplied.
1.478 +
1.479 + @see Read(TDes8& aDes)
1.480 +
1.481 + @param aPos Position of first byte to be read.
1.482 + This is an offset from the start of the file.
1.483 + @param aDes Descriptor into which binary data is read. Any
1.484 + existing contents are overwritten. On return,
1.485 + its length is set to the number of bytes read.
1.486 + @param aLength The number of bytes to read from the file,
1.487 + or to the end of the file, whichever is encountered first.
1.488 + The length of the buffer is set to the number of bytes actually read.
1.489 + @param aStatus Asynchronous request status. On completion this will contain one
1.490 + of the following error codes: KErrNone if the data was
1.491 + successfully read. Otherwise one of the CAF error codes defined in
1.492 + \c caferr.h or one of the other standard system-wide
1.493 + error codes for any other errors.
1.494 + @return KErrNone if the async read request was successfully submitted.
1.495 + @return KErrArgument if a negative offset is supplied.
1.496 + @return KErrCANotSupported if the agent does not support this operation.
1.497 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.498 + */
1.499 + IMPORT_C TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.500 +#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.501 +
1.502 + /**
1.503 + Gets the data size in bytes.
1.504 +
1.505 + @param aSize On return this will contain the size of the plaintext data in bytes.
1.506 + @leave KErrCASizeNotDetermined Size could not be determined by the managing agent.
1.507 + @leave ... One of the other CAF error codes defined in \c caferr.h or one of the
1.508 + system-wide error codes for any other errors.
1.509 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.510 + */
1.511 + IMPORT_C void DataSizeL(TInt& aSize);
1.512 +
1.513 +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.514 + /**
1.515 + This is the 64bit version of CData::DataSizeL
1.516 + Client can call this function instead of CData::DataSizeL. If it's not implemented by the agent,
1.517 + fallback to 32bit counterpart will be provided automatically
1.518 +
1.519 + @see DataSizeL(TInt& aSize)
1.520 + */
1.521 + IMPORT_C void DataSize64L(TInt64& aSize);
1.522 +#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.523 +
1.524 + /**
1.525 + Changes or retrieves the location of the file pointer within
1.526 + the content object.
1.527 +
1.528 + NOTE: Some operations may fail if the content data is sourced over a network connection.
1.529 +
1.530 + There are four seek modes used:
1.531 +
1.532 + @li ESeekStart - Sets the file pointer aPos bytes from the start of the
1.533 + content object. aPos is not modified by the call to Seek()
1.534 + @li ESeekEnd - Sets the file pointer aPos bytes from the end of the
1.535 + content object. The aPos parameter supplied should be zero or negative
1.536 + when using ESeekEnd. Upon completion aPos is updated with the current
1.537 + position relative to the start of the content object.
1.538 + @li ESeekCurrent - Moves the file pointer aPos bytes from the current
1.539 + position. Upon completion aPos is updated with the new position relative
1.540 + to the start of the content object. Suppling a zero value for the aPos Parameter can be
1.541 + used to retrieve the current file pointer location
1.542 + @li ESeekAddress Sets the aPos parameter to the address of the byte
1.543 + aPos bytes from the start of the content object
1.544 +
1.545 + @see TSeek
1.546 +
1.547 + @param aMode Seek mode - controls the destination of the
1.548 + seek operation.
1.549 +
1.550 + @param aPos Offset from either the start, end or current position depending upon
1.551 + the seek mode. Negative offsets are used to seek before the current position or
1.552 + relative to the end of the file.
1.553 +
1.554 + @return KErrNone if successful.
1.555 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one
1.556 + of the other system-wide error codes.
1.557 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.558 + */
1.559 + IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const;
1.560 +
1.561 +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.562 + /**
1.563 + This is the 64bit version of CData::Seek
1.564 + Client can call this function instead of CData::Seek. If it's not implemented by the agent,
1.565 + fallback to 32bit counterpart will be provided automatically
1.566 +
1.567 + @see Seek(TSeek aMode,TInt& aPos)
1.568 + */
1.569 + IMPORT_C TInt Seek64(TSeek aMode,TInt64& aPos) const;
1.570 +#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.571 +
1.572 + /** Request the agent handling this content to set a property value. If the property is set
1.573 + it is only set for this CData session and does not impact other CAF users.
1.574 +
1.575 + For example setting the buffer-size to 256 bytes can be achieved as follows:
1.576 +
1.577 + @code
1.578 + MyData->SetProperty(EAgentPropertyBufferSize, 256);
1.579 + @endcode
1.580 +
1.581 + @see ContentAccess::TAgentProperty
1.582 +
1.583 + @param aProperty The property to set.
1.584 + @param aValue The value of the property.
1.585 + @return Whether or not the property was set.
1.586 + @return KErrNone if the property was set.
1.587 + @return KErrCANotSupported if the agent does not support the property or value.
1.588 + @return KErrAccessDenied if the agent does not permit the property to be changed.
1.589 + @return KErrPermissionDenied if the application does not have the necessary capability to change the property.
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 TInt SetProperty(TAgentProperty aProperty, TInt aValue);
1.593 +
1.594 + /**
1.595 + Allows a client to verify that the intent is supported by the
1.596 + current rights for the data object.
1.597 +
1.598 + @note Since the intent is only evaluated the agent will not decrement
1.599 + any rights-state such as play counts.
1.600 +
1.601 + @see ContentAccess::TIntent
1.602 +
1.603 + @param aIntent The intended way the content will be used.
1.604 + @return Whether rights exist allowing the content to be used for this intent.
1.605 + @return KErrNone if the intent is permitted.
1.606 + @return KErrNoRights if no rights exist for the specified content object.
1.607 + @return KErrCANoPermission if rights exist but the specified intent is not permitted.
1.608 + @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
1.609 + @return KErrNoPermission if rights exist but none permit the specified intent.
1.610 + @return KErrPermissionDenied if the client is not allowed to use this content object.
1.611 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.612 + other system-wide error codes for any other errors.
1.613 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.614 + */
1.615 + IMPORT_C TInt EvaluateIntent(TIntent aIntent);
1.616 +
1.617 + /**
1.618 + Execute intent allows the application to signal it is about to carry out
1.619 + the specified intent on protected content.The agent will decrement applicable
1.620 + stateful rights such as play counts where necessary.
1.621 +
1.622 + Applications should be very careful to use this function correctly.
1.623 + @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever
1.624 + @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely.
1.625 +
1.626 + Usually it would be best to call ExecuteIntent immediately before the content
1.627 + is displayed or the instant playback begins. ExecuteIntent should not be considered a
1.628 + prerequisite for calling the Read functions. It is valid for an application to read from
1.629 + the file before calling ExecuteIntent.
1.630 +
1.631 + @note Since rights are executed here the agent will decrement any rights-state such as
1.632 + play counts that apply.
1.633 +
1.634 + @param aIntent The intent indicator.
1.635 + @return The result of attempting executing the intent.
1.636 + @return KErrNone if the intent is permitted and stateful rights may have been decremented.
1.637 + @return KErrNoRights if no rights exist for the specified content object.
1.638 + @return KErrCANoPermission if rights exist but the specified intent is not permitted.
1.639 + @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
1.640 + @return KErrNoPermission if rights exist but none permit the specified intent.
1.641 + @return KErrPermissionDenied if the client is not allowed to use this content object.
1.642 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the.
1.643 + other system-wide error codes for any other errors.
1.644 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.645 + */
1.646 + IMPORT_C TInt ExecuteIntent(TIntent aIntent);
1.647 +
1.648 + /** Get an attribute for the content object
1.649 +
1.650 + @see ContentAccess::TAttribute
1.651 +
1.652 + @code
1.653 + CContent* content = CContent::NewL(uri);
1.654 + CData* data = content->OpenContentL(EPlay, uniqueId);
1.655 + delete content;
1.656 +
1.657 + TInt value = 0;
1.658 + TInt err = data->GetAttribute(EIsProtected, value);
1.659 + if(err == KErrNone && value)
1.660 + {
1.661 + DisplayPadLock();
1.662 + }
1.663 +
1.664 + delete data;
1.665 + @endcode
1.666 +
1.667 + @param aAttribute The attribute to query, from ContentAccess::TAttribute.
1.668 + @param aValue Used to return the attribute value.
1.669 + @return Whether the attribute was updated.
1.670 + @return KErrNone if the value of the attribute was updated.
1.671 + @return KErrCANotSupported if the requested attribute does not exist.
1.672 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.673 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.674 + other system-wide error codes for any other errors.
1.675 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.676 + */
1.677 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const;
1.678 +
1.679 + /** Get a set of attributes for the content object
1.680 +
1.681 + @see ContentAccess::TAttribute
1.682 +
1.683 + The following example determines whether the content object
1.684 + is protected and has rights that will enable it to be viewed by the
1.685 + user
1.686 +
1.687 + @code
1.688 + // CData* data = a data object
1.689 +
1.690 + RAttributeSet attributeSet;
1.691 + CleanupClosePushL(attributeSet);
1.692 + attributeSet->AddL(EProtected);
1.693 + attributeSet->AddL(ECanView);
1.694 +
1.695 + User::LeaveIfError(data->GetAttributeSet(attributeSet);
1.696 +
1.697 + TInt err = attributeSet.GetValue(EProtected, value);
1.698 + if(err == KErrNone && value)
1.699 + {
1.700 + // file is DRM protected
1.701 + }
1.702 +
1.703 + err = attributeSet.GetValue(ECanView, value);
1.704 + if(err == KErrNone && value)
1.705 + {
1.706 + // File has rights that allow it to be displayed on screen
1.707 + }
1.708 +
1.709 + // Finished
1.710 + CleanupStack::PopAndDestroy(); // attributeSet.Close()
1.711 + @endcode
1.712 +
1.713 +
1.714 + @param aAttributeSet The set of attributes to query and update.
1.715 + @return Whether the attribute set was updated.
1.716 + @return KErrNone if the attributes were retrieved successfully.
1.717 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.718 + @return Otherwise one of the 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(RAttributeSet& aAttributeSet) const;
1.723 +
1.724 +
1.725 + /** Get text string attributes or meta-data for the content object
1.726 +
1.727 + @see ContentAccess::TStringAttribute
1.728 +
1.729 + @code
1.730 + CContent* content = CContent::NewLC(uri);
1.731 + CData* data = content->OpenContentLC(EPlay, uniqueId);
1.732 + CleanupStack::PopAndDestroy(content);
1.733 +
1.734 + TBuf <MAX_PATH> previewUri;
1.735 + TInt err = data->GetStringAttribute(EPreviewURI, previewUri);
1.736 + if(err == KErrNone)
1.737 + {
1.738 + DisplayPreview(previewUri);
1.739 + }
1.740 +
1.741 + CleanupStack::PopAndDestroy(data);
1.742 + @endcode
1.743 +
1.744 + @param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
1.745 + @param aValue Returns the value of the attribute.
1.746 + @return Whether the value was updated.
1.747 + @return KErrNone if the attribute was retrieved.
1.748 + @return KErrOverflow if the buffer was not large enough to return the result.
1.749 + @return KErrCANotSupported if the requested attribute does not exist.
1.750 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.751 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.752 + other system-wide error codes for any other errors.
1.753 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.754 + */
1.755 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const;
1.756 +
1.757 +
1.758 +
1.759 + /** Obtain a set of string attributes for the content object
1.760 +
1.761 + @see ContentAccess::TStringAttribute
1.762 +
1.763 + @code
1.764 + CContent* content = CContent::NewLC(uri);
1.765 + CData* data = content->OpenContentLC(EPlay, uniqueId);
1.766 +
1.767 + // create the attribute set, add the attributes we are interested in
1.768 + RStringAttributeSet stringAttributeSet;
1.769 + CleanupClosePushL(stringAttributeSet);
1.770 + stringAttributeSet.AddL(EPreviewURI);
1.771 + stringAttributeSet.AddL(ETitle);
1.772 +
1.773 + User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet));
1.774 +
1.775 + // Pass the value of the string attribute to DisplayPreview()
1.776 + TFileName previewUri;
1.777 + TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
1.778 + if(err == KErrNone)
1.779 + {
1.780 + DisplayPreview(previewUri);
1.781 + }
1.782 +
1.783 + CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet
1.784 + @endcode
1.785 +
1.786 +
1.787 + @param aStringAttributeSet The set of attributes to query and update.
1.788 + @return Whether the string attribute set was updated.
1.789 + @return KErrNone if the attributes were retrieved successfully.
1.790 + @return KErrNotFound if the default content object was not found.
1.791 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.792 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.793 + other system-wide error codes for any other errors.
1.794 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.795 + */
1.796 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;
1.797 +
1.798 +
1.799 +#ifndef REMOVE_CAF1
1.800 + /** Set Qos attribute
1.801 + @param aQosAttr The Qos attribute to set.
1.802 + @param aValue The value of the attribute.
1.803 + @deprecated
1.804 + */
1.805 + IMPORT_C void SetQosL(TQosAttribute aQosAttr, TInt aValue);
1.806 +
1.807 + /** Get the mime type of the content
1.808 + @param aMimeType Buffer to store the mime type provided by the agent.
1.809 + @return ETrue if the mime type was retrieved successfully.
1.810 + @deprecated
1.811 + */
1.812 + IMPORT_C TBool GetMimeTypeL(TDes8& aMimeType) const;
1.813 +#endif // REMOVE_CAF1
1.814 +
1.815 +#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.816 + /**
1.817 + Decrypts the encrypted input data packet.
1.818 +
1.819 + @param aEncryptedInputDataPacket Buffer descriptor containing the encrypted data packet supplied by client application.
1.820 + @param aDecryptedOutputDataPacket Buffer descriptor supplied by the client application into which the decrypted data is written.
1.821 + The length of this descriptor must be equal to or greater than the input packet.
1.822 + @return KErrNone if successful.KErrInsufficientDataPacketLength if a part of input packet is provided,
1.823 + otherwise one of the CAF error codes defined in \c caferr.h or
1.824 + one of the other system-wide error codes.
1.825 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.826 + Access to unprotected content is unrestricted.
1.827 + */
1.828 +
1.829 + IMPORT_C TInt Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket) const;
1.830 +
1.831 + /**
1.832 + Decrypts the encrypted input data packet asynchronously.
1.833 + @param aEncryptedInputDataPacket Buffer descriptor containing the encrypted data packet supplied by client application.
1.834 + @param aDecryptedOutputDataPacket Buffer descriptor supplied by the client application into which the decrypted data is written.
1.835 + The length of this descriptor must be equal to or greater than the input packet.
1.836 + @param aStatus Asynchronous request status. On completion this will contain one of the following error codes:
1.837 + KErrNone if the data packet was successfully decrypted.KErrInsufficientDataPacketLength if a
1.838 + part of input packet is provided, otherwise one of the CAF error codes defined in \c caferr.h or
1.839 + one of the other system-wide error codes.
1.840 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability.
1.841 + Access to unprotected content is unrestricted.
1.842 + */
1.843 + IMPORT_C void Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket, TRequestStatus& aStatus) const;
1.844 +
1.845 +#endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.846 +
1.847 + private:
1.848 + CData();
1.849 + void ConstructL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.850 + void ConstructL(const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode);
1.851 + void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);
1.852 + void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode);
1.853 +
1.854 + void ConstructL(RFile& aFile, const TDesC& aUniqueId);
1.855 + void ConstructL(const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode);
1.856 + void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId);
1.857 + void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode);
1.858 +
1.859 +#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.860 +
1.861 + void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent);
1.862 + void ConstructL(const TDesC8& aHeaderData);
1.863 + void ConstructL(const TDesC8& aHeaderData, TIntent aIntent);
1.864 + void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData);
1.865 +
1.866 +#endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
1.867 +
1.868 +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.869 + /*
1.870 + * This is the obselete 32bit Read and replaced by its 64bit counterpart
1.871 + * TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const
1.872 + * However, this function still exits at its original ordinal to avoid BC break.
1.873 + * Upgrade to 64bit Read is done automatically upon recompling the client code which uses CAF interfaces
1.874 + */
1.875 + IMPORT_C TInt Read_Unused(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;
1.876 +#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
1.877 +
1.878 + private:
1.879 + // The agent handling this content
1.880 + CAgentData* iAgentData;
1.881 +
1.882 + // Defacto ECOM session handle
1.883 + CAgentFactory* iAgentFactory;
1.884 +
1.885 + // Uid of the agent
1.886 + TUid iAgentUid;
1.887 + };
1.888 +
1.889 +} // namespace ContentAccess
1.890 +#endif /* __DATA_H__ */
1.891 +