1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/caf/content.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,999 @@
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 +@file
1.24 +
1.25 +@publishedPartner
1.26 +@released
1.27 +*/
1.28 +
1.29 +
1.30 +#ifndef __CONTENT_H__
1.31 +#define __CONTENT_H__
1.32 +
1.33 +#include <e32base.h>
1.34 +#include <f32file.h>
1.35 +
1.36 +#include <caf/caftypes.h>
1.37 +#include <caf/agent.h>
1.38 +#include <caf/streamableptrarray.h>
1.39 +#include <caf/virtualpathptr.h>
1.40 +
1.41 +namespace ContentAccess
1.42 + {
1.43 + class CAgentResolver;
1.44 + class CAgentFactory;
1.45 + class CAgentContent;
1.46 + class CData;
1.47 + class CEmbeddedObject;
1.48 + class RAttributeSet;
1.49 + class RStringAttributeSet;
1.50 +
1.51 +
1.52 +
1.53 +#ifndef REMOVE_CAF1
1.54 + class CAttribute;
1.55 +#endif
1.56 +
1.57 +
1.58 +/**
1.59 + CContent allows applications to browse the content objects contained within a
1.60 + single file and construct a CData object for reading that content.
1.61 +
1.62 + Applications will use an object of this type rather than the traditional
1.63 + RFile mechanisms. They will, however, be required to indicate
1.64 + <i>DRM Intent</i> - something that determines whether (and how) access to
1.65 + the content should be permitted by a Content-Access agent.
1.66 +
1.67 + CContent allows direct access to meta-data such as the attributes of
1.68 + the content and indirect access to the plaintext data itself through
1.69 + the CData class.
1.70 +
1.71 + Applications can use CContent to browse the hierarchy of content objects
1.72 + within a file containing several content objects.
1.73 +
1.74 + During construction CContent loads the correct CAF Agent plugin to handle
1.75 + the file specified by the URI.
1.76 +
1.77 + @publishedPartner
1.78 + @released
1.79 + */
1.80 + class CContent : public CBase
1.81 + {
1.82 + public:
1.83 +
1.84 + /**
1.85 + Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
1.86 +
1.87 + @param aURI The filename, URI or virtual path of the DRM file.
1.88 + @return a new CContent object.
1.89 + @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
1.90 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.91 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.92 + other system-wide error codes for any other errors.
1.93 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.94 + */
1.95 + IMPORT_C static CContent* NewLC(const TDesC& aURI);
1.96 +
1.97 + /**
1.98 + Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
1.99 +
1.100 + @param aURI The filename, URI or virtual path of the DRM file.
1.101 + @return a new CContent object.
1.102 + @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
1.103 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.104 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.105 + other system-wide error codes for any other errors.
1.106 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.107 + */
1.108 + IMPORT_C static CContent* NewL(const TDesC& aURI);
1.109 +
1.110 + /**
1.111 + Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
1.112 +
1.113 + @param aURI The filename, URI or virtual path of the DRM file.
1.114 + @param aShareMode The sharing mode used when accessing the content.
1.115 + @return a new CContent object.
1.116 + @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
1.117 + @leave KErrAccessDenied If the file is already open with a different share mode.
1.118 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.119 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.120 + other system-wide error codes for any other errors.
1.121 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.122 + */
1.123 + IMPORT_C static CContent* NewLC(const TDesC& aURI, TContentShareMode aShareMode);
1.124 +
1.125 + /**
1.126 + Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
1.127 +
1.128 + @param aURI The filename, URI or virtual path of the DRM file.
1.129 + @param aShareMode The sharing mode used when accessing the content.
1.130 + @return a new CContent object.
1.131 + @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
1.132 + @leave KErrAccessDenied If the file is already open with a different share mode.
1.133 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.134 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.135 + other system-wide error codes for any other errors.
1.136 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.137 + */
1.138 + IMPORT_C static CContent* NewL(const TDesC& aURI, TContentShareMode aShareMode);
1.139 +
1.140 + /**
1.141 + Constructs a new CContent object with an open file handle.
1.142 +
1.143 + CContent will use a duplicate of this file handle, the client is
1.144 + free to close its file handle any time after creating the CContent
1.145 + object.
1.146 +
1.147 + @param aFile The file handle. The file must already be open before calling NewLC.
1.148 + 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.149 + @return a new CContent object.
1.150 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.151 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.152 + other system-wide error codes for any other errors.
1.153 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.154 + */
1.155 + IMPORT_C static CContent* NewLC(RFile& aFile);
1.156 +
1.157 + /**
1.158 + Constructs a new CContent object with an open file handle.
1.159 +
1.160 + CContent will use a duplicate of this file handle, the client is
1.161 + free to close its file handle any time after creating the CContent
1.162 + object.
1.163 +
1.164 + @param aFile The file handle. The file must already be open before calling this method.
1.165 + 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.166 + @return a new CContent object.
1.167 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.168 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.169 + other system-wide error codes for any other errors.
1.170 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.171 + */
1.172 + IMPORT_C static CContent* NewL(RFile& aFile);
1.173 +
1.174 + /** destructor */
1.175 + virtual ~CContent();
1.176 +
1.177 + /** Open a Container object within the file.
1.178 +
1.179 + Allows an application to access the content objects and
1.180 + any nested container objects within the specified container.
1.181 +
1.182 + @param aUniqueId The container object's unique ID.
1.183 + @return Whether the container was opened.
1.184 + @return KErrNone if the container was opened successfully.
1.185 + @return KErrNotFound if the container does not exist.
1.186 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.187 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.188 + other system-wide error codes for any other errors.
1.189 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.190 + */
1.191 + IMPORT_C TInt OpenContainer(const TDesC& aUniqueId);
1.192 +
1.193 + /** Close the current container object and go back to previous enclosing
1.194 + container within the file.
1.195 +
1.196 + Allows an application to access the content objects and
1.197 + any nested container objects within parent container.
1.198 +
1.199 + @return Whether the container was closed.
1.200 + @return KErrNone if the container was closed.
1.201 + @return KErrNotFound if there is no enclosing container.
1.202 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.203 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.204 + */
1.205 + IMPORT_C TInt CloseContainer();
1.206 +
1.207 + /** List all the embedded container objects and content objects within the
1.208 + current container
1.209 +
1.210 + The UniqueId() member of CEmbeddedObject can be used to refer directly to
1.211 + a particular object within the file.
1.212 +
1.213 + @code
1.214 + // Create a ccontent object for the file of interest
1.215 + CContent* content = CContent::NewLC(uri);
1.216 +
1.217 + // Define an array to store the results
1.218 + RStreamablePtrArray <CEmbeddedObject> array;
1.219 + CleanupClosePushL(array);
1.220 +
1.221 + // Find all the content and container objects within the current container
1.222 + content->GetEmbeddedObjectsL(array);
1.223 +
1.224 + // Do something with the array
1.225 + ....
1.226 +
1.227 + // Finished
1.228 + CleanupStack::PopAndDestroy(2);
1.229 + @endcode
1.230 +
1.231 + @param aArray The array to be populated with the embedded objects.
1.232 + @leave KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.233 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.234 + other system-wide error codes for any other errors.
1.235 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.236 + */
1.237 + IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) const;
1.238 +
1.239 + /** List all the embedded objects within the current container that
1.240 + are of the specified type
1.241 +
1.242 + @code
1.243 + // Create a ccontent object for the file of interest
1.244 + CContent* content = CContent::NewLC(uri);
1.245 +
1.246 + // Define an array to store the results
1.247 + RStreamablePtrArray <CEmbeddedObject> array;
1.248 + CleanupClosePushL(array);
1.249 +
1.250 + // Find all the content objects within the current container
1.251 + content->GetEmbeddedObjectsL(array, EContentObject);
1.252 +
1.253 + // Do something with the array
1.254 + ....
1.255 +
1.256 + // Finished
1.257 + CleanupStack::PopAndDestroy(2);
1.258 + @endcode
1.259 +
1.260 + @param aArray The array to be populated with the embedded objects.
1.261 + @param aType The type of objects to list.
1.262 + @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
1.263 + @leave ... One of the CAF error codes defined in \c caferr.h or one of the
1.264 + other system-wide error codes for any other errors.
1.265 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.266 + */
1.267 + IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) const;
1.268 +
1.269 + /** Search the current container for content objects with a particular mime type
1.270 +
1.271 + @code
1.272 + _LIT8(KTextPlainMimeType, "text/plain");
1.273 +
1.274 + // Create a ccontent object for the file of interest
1.275 + CContent* content = CContent::NewLC(uri);
1.276 +
1.277 + // Define an array to store the results
1.278 + RStreamablePtrArray <CEmbeddedObject> array;
1.279 + CleanupClosePushL(array);
1.280 +
1.281 + // Recursively search for all the content objects with the
1.282 + // specified mime type
1.283 + User::LeaveIfError(content->Search(array, KTextPlainMimeType(), ETrue));
1.284 +
1.285 + // Do something with the array
1.286 + ....
1.287 +
1.288 + // Finished
1.289 + CleanupStack::PopAndDestroy(2);
1.290 + @endcode
1.291 +
1.292 + @param aArray The array to store the results of the search. The agent will add CEmbeddedObject objects to the supplied array.
1.293 + @param aMimeType The mime type to search for.
1.294 + @param aRecursive ETrue to search inside containers embedded within the current container, EFalse to search only the current container.
1.295 + @return The result of the search.
1.296 + @return KErrNone if the search was successful, even if no content objects were found.
1.297 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.298 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.299 + other system-wide error codes for any other errors.
1.300 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.301 + */
1.302 + IMPORT_C TInt Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive);
1.303 +
1.304 +
1.305 + /** Get an attribute for the default content object within the file
1.306 +
1.307 + @see ContentAccess::TAttribute
1.308 +
1.309 + @code
1.310 + TInt value = 0;
1.311 + CContent* c = CContent::NewL(uri);
1.312 + TInt err =c->GetAttribute(EIsProtected, value);
1.313 + if(err == KErrNone && value)
1.314 + {
1.315 + DisplayPadLock();
1.316 + }
1.317 + @endcode
1.318 +
1.319 + @param aAttribute The attribute to query, from ContentAccess::TAttribute.
1.320 + @param aValue Used to return the attribute value.
1.321 + @return Whether the attribute value was updated.
1.322 + @return KErrNone if the value of the attribute was updated.
1.323 + @return KErrNotFound if the object with the given UniqueId was not found.
1.324 + @return KErrCANotSupported if the requested attribute does not exist.
1.325 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.326 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.327 + other system-wide error codes for any other errors.
1.328 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.329 + */
1.330 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const;
1.331 +
1.332 + /** Get an attribute for an object within the file
1.333 +
1.334 + @see ContentAccess::TAttribute
1.335 +
1.336 + @code
1.337 + TInt value = 0;
1.338 + CContent* c = CContent::NewL(uri);
1.339 + TInt err =c->GetAttribute(EIsProtected, value, uniqueId);
1.340 + if(err == KErrNone && value)
1.341 + {
1.342 + DisplayPadLock();
1.343 + }
1.344 + @endcode
1.345 +
1.346 + @param aAttribute The attribute to query, from ContentAccess::TAttribute.
1.347 + @param aValue Used to return the attribute value.
1.348 + @param aUniqueId The UniqueId of the object within the file.
1.349 + @return Whether the attribute value was updated.
1.350 + @return KErrNone if the value of the attribute was updated.
1.351 + @return KErrNotFound if the object with the given UniqueId was not found.
1.352 + @return KErrCANotSupported if the requested attribute does not exist.
1.353 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.354 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.355 + other system-wide error codes for any other errors.
1.356 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.357 + */
1.358 + IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, const TDesC& aUniqueId) const;
1.359 +
1.360 +
1.361 + /** Get a set of attributes for the default content object within the file
1.362 +
1.363 + @see ContentAccess::TAttribute
1.364 +
1.365 + The following example determines whether the default content object
1.366 + is protected and has rights that will enable it to be viewed by the
1.367 + user
1.368 +
1.369 + @code
1.370 + CContent* content = CContent::NewLC(uri);
1.371 +
1.372 + RAttributeSet attributeSet;
1.373 + CleanupClosePushL(attributeSet);
1.374 + attributeSet->AddL(EProtected);
1.375 + attributeSet->AddL(ECanView);
1.376 +
1.377 + User::LeaveIfError(content->GetAttributeSet(attributeSet);
1.378 +
1.379 + TInt err = attributeSet.GetValue(EProtected, value);
1.380 + if(err == KErrNone && value)
1.381 + {
1.382 + // file is DRM protected
1.383 + }
1.384 +
1.385 + err = attributeSet.GetValue(ECanView, value);
1.386 + if(err == KErrNone && value)
1.387 + {
1.388 + // File has rights that allow it to be displayed on screen
1.389 + }
1.390 +
1.391 + // Finished
1.392 + CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()
1.393 + @endcode
1.394 +
1.395 +
1.396 + @param aAttributeSet The set of attributes to query and update.
1.397 + @return Whether the attribute set was updated.
1.398 + @return KErrNone if the attributes were retrieved successfully.
1.399 + @return KErrNotFound if the default content object was not found.
1.400 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.401 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.402 + other system-wide error codes for any other errors.
1.403 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.404 + */
1.405 + IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const;
1.406 +
1.407 + /** Get a set of attributes from an object within the file
1.408 +
1.409 + @see ContentAccess::TAttribute
1.410 +
1.411 + The following example determines whether the default content object
1.412 + is protected and has rights that will enable it to be viewed by the
1.413 + user
1.414 +
1.415 + @code
1.416 + CContent* content = CContent::NewLC(uri);
1.417 +
1.418 + RAttributeSet attributeSet;
1.419 + CleanupClosePushL(attributeSet);
1.420 + attributeSet->AddL(EProtected);
1.421 + attributeSet->AddL(ECanView);
1.422 +
1.423 + User::LeaveIfError(content->GetAttributeSet(attributeSet, uniqueId);
1.424 +
1.425 + TInt err = attributeSet.GetValue(EProtected, value);
1.426 + if(err == KErrNone && value)
1.427 + {
1.428 + // file is DRM protected
1.429 + }
1.430 +
1.431 + err = attributeSet.GetValue(ECanView, value);
1.432 + if(err == KErrNone && value)
1.433 + {
1.434 + // File has rights that allow it to be displayed on screen
1.435 + }
1.436 +
1.437 + // Finished
1.438 + CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()
1.439 + @endcode
1.440 +
1.441 +
1.442 + @param aAttributeSet The set of attributes to query and update.
1.443 + @param aUniqueId The unique ID of the object within the file.
1.444 + @return Whether that attribute set was updated.
1.445 + @return KErrNone if the attributes were retrieved successfully.
1.446 + @return KErrNotFound if the default content object was not found.
1.447 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.448 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.449 + other system-wide error codes for any other errors.
1.450 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.451 + */
1.452 + IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) const;
1.453 +
1.454 + /** Get text string attributes or meta-data for the default content object within the file
1.455 +
1.456 + @see ContentAccess::TStringAttribute
1.457 +
1.458 + @code
1.459 + TInt err = KErrNone;
1.460 +
1.461 + CContent* c = CContent::NewL(uri);
1.462 + TBuf <MAX_PATH> previewUri;
1.463 + err = c->GetStringAttribute(EPreviewURI, previewUri);
1.464 + if(err == KErrNone)
1.465 + {
1.466 + DisplayPreview(previewUri);
1.467 + }
1.468 + @endcode
1.469 +
1.470 + @param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
1.471 + @param aValue Returns the value of the attribute.
1.472 + @return Whether the attribute value was updated.
1.473 + @return KErrNone if the attribute was retrieved.
1.474 + @return KErrNotFound if the default content object was not found.
1.475 + @return KErrOverflow if the buffer was not large enough to return the result.
1.476 + @return KErrCANotSupported if the requested attribute does not exist.
1.477 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.478 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.479 + other system-wide error codes for any other errors.
1.480 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.481 + */
1.482 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const;
1.483 +
1.484 + /** Get text string attributes or meta-data for an object within the file
1.485 +
1.486 + @see ContentAccess::TStringAttribute
1.487 +
1.488 + @code
1.489 + TInt err = KErrNone;
1.490 +
1.491 + CContent* c = CContent::NewL(uri);
1.492 + TBuf <MAX_PATH> previewUri;
1.493 + err = c->GetStringAttribute(EPreviewURI, previewUri, uniqueId);
1.494 + if(err == KErrNone)
1.495 + {
1.496 + DisplayPreview(previewUri);
1.497 + }
1.498 + @endcode
1.499 +
1.500 + @param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
1.501 + @param aValue Returns the value of the attribute.
1.502 + @param aUniqueId The UniqueId of the object within the file.
1.503 + @return Whether the attribute value was updated.
1.504 + @return KErrNone if the attribute was retrieved.
1.505 + @return KErrNotFound if the object with the given UniqueId was not found.
1.506 + @return KErrOverflow if the buffer was not large enough to return the result.
1.507 + @return KErrCANotSupported if the requested attribute does not exist.
1.508 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.509 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.510 + other system-wide error codes for any other errors.
1.511 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.512 + */
1.513 + IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TDesC& aUniqueId) const;
1.514 +
1.515 + /** Obtain a set of string attributes for the default content object within the file
1.516 +
1.517 + @see ContentAccess::TStringAttribute
1.518 +
1.519 + @code
1.520 + CContent* content = CContent::NewLC(uri);
1.521 +
1.522 + // create the attribute set, add the attributes we are interested in
1.523 + RStringAttributeSet stringAttributeSet;
1.524 + CleanupClosePushL(stringAttributeSet);
1.525 + stringAttributeSet.AddL(EPreviewURI);
1.526 + stringAttributeSet.AddL(ETitle);
1.527 +
1.528 + User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet));
1.529 +
1.530 + // Pass the value of the string attribute to DisplayPreview()
1.531 + TFileName previewUri;
1.532 + TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
1.533 + if(err == KErrNone)
1.534 + {
1.535 + DisplayPreview(previewUri);
1.536 + }
1.537 +
1.538 + CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()
1.539 + @endcode
1.540 +
1.541 +
1.542 + @param aStringAttributeSet The set of attributes to query and update.
1.543 + @return Whether the attribute set was updated.
1.544 + @return KErrNone if the attributes were retrieved successfully.
1.545 + @return KErrNotFound if the default content object was not found.
1.546 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.547 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.548 + other system-wide error codes for any other errors.
1.549 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.550 + */
1.551 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;
1.552 +
1.553 + /** Used to obtain a set of string attributes for an object within the file
1.554 +
1.555 + @see ContentAccess::TStringAttribute
1.556 +
1.557 + @code
1.558 + CContent* content = CContent::NewLC(uri);
1.559 +
1.560 + // create the attribute set, add the attributes we are interested in
1.561 + RStringAttributeSet stringAttributeSet;
1.562 + CleanupClosePushL(stringAttributeSet);
1.563 + stringAttributeSet.AddL(EPreviewURI);
1.564 + stringAttributeSet.AddL(ETitle);
1.565 +
1.566 + User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet, uniqueId));
1.567 +
1.568 + // Pass the value of the string attribute to DisplayPreview()
1.569 + TFileName previewUri;
1.570 + TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
1.571 + if(err == KErrNone)
1.572 + {
1.573 + DisplayPreview(previewUri);
1.574 + }
1.575 +
1.576 + CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()
1.577 + @endcode
1.578 +
1.579 +
1.580 + @param aStringAttributeSet The set of attributes to query and update.
1.581 + @param aUniqueId The UniqueId of the container or content.
1.582 + @return Whether the attribute set was updated.
1.583 + @return KErrNone if the attributes were retrieved successfully.
1.584 + @return KErrNotFound if the object with the given UniqueId was not found.
1.585 + @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
1.586 + @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the
1.587 + other system-wide error codes for any other errors.
1.588 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.589 + */
1.590 + IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TDesC& aUniqueId) const;
1.591 +
1.592 + /** Allows extended synchronous calls to the CAF agent handling this file
1.593 +
1.594 + Applications familiar with the agent can pass objects in and out using serialization.
1.595 +
1.596 + @param aCommand The agent defined command.
1.597 + @param aInputBuffer Non modifyable input data buffer.
1.598 + @param aOutputBuffer Modifyable output buffer to hold the result of the command.
1.599 + @return The outcome of the agent specific command.
1.600 + @return KErrCANotSupported if the agent does not recognize the command.
1.601 + @return KErrOverflow if the output buffer supplied is too small.
1.602 + @return KErrPermissionDenied if the agent does not allow the client to execute the command.
1.603 + @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.604 + other system-wide error codes for any other errors.
1.605 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.606 + */
1.607 + IMPORT_C TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);
1.608 +
1.609 + /** Allows extended synchronous calls to the CAF agent handling this file
1.610 + Applications familiar with the agent can pass objects in and out using serialization.
1.611 + NB: It is important that the descriptor passed to
1.612 + aOutputBuffer remains in scope until the request has completed.
1.613 +
1.614 + @param aCommand The agent defined command.
1.615 + @param aInputBuffer Non modifyable input data buffer.
1.616 + @param aOutputBuffer Modifyable output buffer to hold the result of the command.
1.617 + @param aStatus Asynchronous request status. On completion this will contain
1.618 + one of the following error codes:
1.619 + KErrNone if the command was successfully executed.
1.620 + KErrCANotSupported if the agent does not recognize the command.
1.621 + KErrOverflow if the output buffer supplied is too small.
1.622 + KErrPermissionDenied if the agent does not allow the client
1.623 + to execute the command. Otherwise one of the other CAF error codes defined
1.624 + in \c caferr.h or one of the other system-wide error codes
1.625 + for any other errors.
1.626 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.627 + */
1.628 + IMPORT_C void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);
1.629 +
1.630 +
1.631 + /** Request notification for an event for the default content object within the file
1.632 +
1.633 + @see ContentAccess::TEventMask
1.634 +
1.635 + @param aMask Bitmask of events the caller is interested in.
1.636 + @param aStatus The TRequestStatus object to complete if the event occurs.
1.637 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.638 + */
1.639 + IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus);
1.640 +
1.641 + /** Request notification for an event for an object within the file
1.642 +
1.643 + @see ContentAccess::TEventMask
1.644 +
1.645 + @param aMask Bitmask of events the caller is interested in.
1.646 + @param aStatus The TRequestStatus object to complete if the event occurs.
1.647 + @param aUniqueId The UniqueId of the container or content.
1.648 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.649 + */
1.650 + IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId);
1.651 +
1.652 + /** Cancel a previous notification request for the default content object
1.653 +
1.654 + @param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
1.655 + @return The outcome of the cancel request.
1.656 + @return KErrNone if the request was cancelled.
1.657 + @return KErrNotFound if there was no matching request outstanding.
1.658 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.659 + */
1.660 + IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus);
1.661 +
1.662 + /** Cancel a previous notification request
1.663 +
1.664 + @param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
1.665 + @param aUniqueId The UniqueId of the content object within the file.
1.666 + @return The outcome of the cancel request.
1.667 + @return KErrNone if the request was cancelled.
1.668 + @return KErrNotFound if there was no matching request outstanding.
1.669 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.670 + */
1.671 + IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId);
1.672 +
1.673 + /** Request the agent to obtain rights for the default content object
1.674 +
1.675 + This request may be handled differently by different agents.
1.676 + Some agents may open a browser and direct the user to a URL. Others may
1.677 + download and install the rights in the background.
1.678 +
1.679 + The call should not block execution, applications can wait for a notification
1.680 + if they are interested in the outcome.
1.681 +
1.682 + @param aStatus Asynchronous request status. On completion this will contain
1.683 + one of the following error codes:
1.684 + KErrNone if the rights request was successful.
1.685 + KErrCANotSupported if the agent does not allow rights requests.
1.686 + Otherwise one of the other CAF error codes defined in \c caferr.h
1.687 + or one of the other system-wide error codes
1.688 + for any other errors.
1.689 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.690 + */
1.691 + IMPORT_C void RequestRights(TRequestStatus& aStatus);
1.692 +
1.693 + /** Request the agent to obtain rights for a protected content object
1.694 +
1.695 + This request may be handled differently by different agents.
1.696 + Some agents may open a browser and direct the user to a URL. Others may
1.697 + download and install the rights in the background.
1.698 +
1.699 + The call should not block execution, applications can wait for a notification
1.700 + if they are interested in the outcome.
1.701 +
1.702 + @param aStatus Asynchronous request status. On completion this will contain
1.703 + one of the following error codes:
1.704 + KErrNone if the rights request was successful.
1.705 + KErrCANotSupported if the agent does not allow rights requests.
1.706 + Otherwise one of the other CAF error codes defined in \c caferr.h
1.707 + or one of the other system-wide error codes
1.708 + for any other errors.
1.709 +
1.710 + @param aUniqueId The unique id of the object within the file.
1.711 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.712 + */
1.713 + IMPORT_C void RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
1.714 +
1.715 +
1.716 + /** Cancel a previous RequestRights() request for the default content object
1.717 +
1.718 + @param aStatus The TRequestStatus that was supplied to the RequestRights() function.
1.719 + @return The result of the cancel rights request.
1.720 + @return KErrNone if the rights request was cancelled.
1.721 + @return KErrNotFound if there was no matching rights request outstanding.
1.722 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.723 + */
1.724 + IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus);
1.725 +
1.726 + /** Cancel a previous RequestRights() request
1.727 +
1.728 + @param aStatus The TRequestStatus that was supplied to the RequestRights() function.
1.729 + @param aUniqueId The objects Unique Id that was supplied to the RequestRights() function.
1.730 + @return The result of the cancel rights request.
1.731 + @return KErrNone if the rights request was cancelled.
1.732 + @return KErrNotFound if there was no matching rights request outstanding.
1.733 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.734 + */
1.735 + IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
1.736 +
1.737 + /** View information associated with the default content object
1.738 +
1.739 + This call blocks execution and only returns once the display is dismissed
1.740 + by the user.
1.741 +
1.742 + @see ContentAccess::TDisplayInfo
1.743 +
1.744 + @param aInfo The information to display.
1.745 + @leave KErrCANotSupported if information cannot be displayed or does not exist.
1.746 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.747 + or one of the system-wide error codes for
1.748 + any other errors.
1.749 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.750 + */
1.751 + IMPORT_C void DisplayInfoL(TDisplayInfo aInfo) const;
1.752 +
1.753 + /** View information associated with a single content object
1.754 +
1.755 + This call blocks execution and only returns once the display is dismissed
1.756 + by the user.
1.757 +
1.758 + @see ContentAccess::TDisplayInfo
1.759 +
1.760 + @param aInfo The information to display.
1.761 + @param aUniqueId The unique id of the object within the file.
1.762 + @leave KErrCANotSupported if information cannot be displayed or does not exist.
1.763 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.764 + or one of the system-wide error codes for
1.765 + any other errors.
1.766 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.767 + */
1.768 + IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) const;
1.769 +
1.770 +
1.771 + /** Request the agent handling this content to set a property value. If
1.772 + the property is set it is only set for this CContent session and does not
1.773 + impact other CAF users and is not set for CData products created by the
1.774 + CContent.
1.775 +
1.776 + @see ContentAccess::TAgentProperty
1.777 +
1.778 + @param aProperty The property to set.
1.779 + @param aValue The value of the property.
1.780 + @return Whether the property was set.
1.781 + @return KErrNone if the property was set.
1.782 + @return KErrCANotSupported if the agent does not support the property or value.
1.783 + @return KErrAccessDenied if the agent does not permit the property to be changed.
1.784 + @return KErrPermissionDenied if the application does not have the necessary capability to change the property.
1.785 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.786 + */
1.787 + IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);
1.788 +
1.789 + /**
1.790 + Grants read access to the default content object based on
1.791 + evaluation of the supplied intent information.
1.792 +
1.793 + Note that the intent is simply evaluated and not executed.
1.794 + To force the intent to be executed, clients must use the call
1.795 + ContentAccess::CData::ExecuteIntent().
1.796 +
1.797 + A CData object can be obtained as follows:
1.798 + @code
1.799 + CData* MyData = myContent->OpenContentL(ChosenIntent);
1.800 + ...
1.801 + delete MyData; // when finished accessing plaintext content
1.802 + @endcode
1.803 +
1.804 + @see ContentAccess::TIntent
1.805 +
1.806 + @param aIntent The intent indicator.
1.807 + @return A CData instance. The caller gets ownership of this object.
1.808 +
1.809 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.810 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.811 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.812 + @leave KErrCANoRights No rights exist for the content object.
1.813 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.814 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.815 + @leave KErrAccessDenied The content is already in use.
1.816 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.817 + or one of the other system-wide error codes for any other
1.818 + errors.
1.819 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.820 + */
1.821 + IMPORT_C CData* OpenContentL(TIntent aIntent);
1.822 +
1.823 + /**
1.824 + Grants read access to the default content object based on
1.825 + evaluation of the supplied intent information.
1.826 +
1.827 + Note that the intent is simply evaluated and not executed.
1.828 + To force the intent to be executed, clients must use the call
1.829 + ContentAccess::CData::ExecuteIntent().
1.830 +
1.831 + A CData object can be obtained as follows:
1.832 + @code
1.833 + CData* myData = myContent->OpenContentLC(ChosenIntent);
1.834 + ...
1.835 + // when finished accessing plaintext content
1.836 + CleanupStack::PopAndDestroy(myData);
1.837 + @endcode
1.838 +
1.839 + @see ContentAccess::TIntent
1.840 +
1.841 + @param aIntent The intent indicator.
1.842 + @return A CData instance. The caller gets ownership of this object.
1.843 +
1.844 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.845 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.846 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.847 + @leave KErrCANoRights No rights exist for the content object.
1.848 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.849 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.850 + @leave KErrAccessDenied The content is already in use.
1.851 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.852 + or one of the other system-wide error codes for any other
1.853 + errors.
1.854 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
1.855 + */
1.856 + IMPORT_C CData* OpenContentLC(TIntent aIntent);
1.857 +
1.858 + /**
1.859 + Grants read access to the content object based on evaluation of the
1.860 + supplied intent information.
1.861 +
1.862 + Note that the intent is simply evaluated and not executed.
1.863 + To force the intent to be executed, clients must use the call
1.864 + ContentAccess::CData::ExecuteIntent().
1.865 +
1.866 + A CData object can be obtained as follows:
1.867 + @code
1.868 + CData* MyData = myContent->OpenContentL(ChosenIntent, uniqueId);
1.869 + ...
1.870 + delete MyData; // when finished accessing plaintext content
1.871 + @endcode
1.872 +
1.873 + @see ContentAccess::TIntent
1.874 +
1.875 + @param aIntent The intent indicator.
1.876 + @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
1.877 + @return A CData instance. The caller gets ownership of this object.
1.878 +
1.879 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.880 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.881 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.882 + @leave KErrCANoRights No rights exist for the content object.
1.883 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.884 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.885 + @leave KErrAccessDenied The content is already in use.
1.886 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.887 + or one of the other system-wide error codes for any other
1.888 + errors.
1.889 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.890 + */
1.891 + IMPORT_C CData* OpenContentL(TIntent aIntent, const TDesC& aUniqueId);
1.892 +
1.893 +
1.894 + /**
1.895 + Grants read access to the content object based on evaluation of the
1.896 + supplied intent information.
1.897 +
1.898 + Note that the intent is simply evaluated and not executed.
1.899 + To force the intent to be executed, clients must use the call
1.900 + ContentAccess::CData::ExecuteIntent().
1.901 +
1.902 + A CData object can be obtained as follows:
1.903 + @code
1.904 + CData* MyData = myContent->OpenContentLC(ChosenIntent, uniqueId);
1.905 + ...
1.906 + PopAndDestroy(MyData); // when finished accessing plaintext content
1.907 + @endcode
1.908 +
1.909 + @see ContentAccess::TIntent
1.910 +
1.911 + @param aIntent The intent indicator.
1.912 + @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
1.913 + @return A CData instance. The caller gets ownership of this object.
1.914 +
1.915 + @leave KErrNotFound The content object with the given UniqueId does not exist.
1.916 + @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
1.917 + @leave KErrCANoPermission Rights exist but the specified intent is not permitted.
1.918 + @leave KErrCANoRights No rights exist for the content object.
1.919 + @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object.
1.920 + @leave KErrPermissionDenied The agent does not allow the client to access the content object.
1.921 + @leave KErrAccessDenied The content is already in use.
1.922 + @leave ... One of the other CAF error codes defined in \c caferr.h
1.923 + or one of the other system-wide error codes for any other
1.924 + errors.
1.925 + @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
1.926 + */
1.927 + IMPORT_C CData* OpenContentLC(TIntent aIntent, const TDesC& aUniqueId);
1.928 +
1.929 +
1.930 + /** Find out which agent is handling this file
1.931 + @return The agent handling the File
1.932 + @capability DRM Access to DRM agents is not permitted for processes without DRM capability
1.933 + */
1.934 + IMPORT_C const TAgent& Agent() const;
1.935 +
1.936 +#ifndef REMOVE_CAF1
1.937 + /** Create a CData object for reading the content
1.938 +
1.939 + @see ContentAccess::TIntent
1.940 + @param aIntent The intended use of the content
1.941 + @param aShareMode The mode used to open the file. If EContentShareExclusive is required, use CData::NewL() instead
1.942 + @return A new CData object
1.943 + @leave One of the CAF error codes defined in \c caferr.h or one of the system-wide error codes for any errors.
1.944 + @capability DRM Access to DRM agents is not permitted for processes without DRM capability
1.945 + @deprecated
1.946 + */
1.947 + IMPORT_C CData* OpenContentL(TIntent aIntent, TContentShareMode aShareMode);
1.948 +
1.949 + /** Create a CAttribute object to determine the attributes of the default content object
1.950 +
1.951 + @return The agent handling the File
1.952 + @capability DRM Access to DRM agents is not permitted for processes without DRM capability
1.953 + @deprecated
1.954 + */
1.955 + IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded);
1.956 +
1.957 + /** Create a CAttribute object to determine the attributes of the default content object
1.958 +
1.959 + @return The agent handling the File
1.960 + @capability DRM Access to DRM agents is not permitted for processes without DRM capability
1.961 + @deprecated
1.962 + */
1.963 + IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded, TContentShareMode aShareMode);
1.964 +
1.965 +#endif // REMOVE_CAF1
1.966 +
1.967 + private:
1.968 + CContent();
1.969 + void ConstructL(RFile& aFile);
1.970 + void ConstructL(const TDesC& aURI, TContentShareMode aShareMode);
1.971 +
1.972 + private:
1.973 +
1.974 + /** CAgentFactory object is effectively the ECOM session handle */
1.975 + CAgentFactory* iAgentFactory;
1.976 +
1.977 + /**
1.978 + Agent object used for browsing the contents of a file
1.979 + */
1.980 + CAgentContent* iAgentContent;
1.981 +
1.982 + /** Points to the default content object if the file is opened by name */
1.983 + CVirtualPath* iVirtualPath;
1.984 +
1.985 + /** The content object referred to by CContent, either points to iVirtualPath
1.986 + or points to (KNullDesC(), KDefaultContentObject())
1.987 + */
1.988 + TVirtualPathPtr iDefaultVirtualPath;
1.989 +
1.990 + /* Stores the name and UID of the agent
1.991 + */
1.992 + TAgent iAgent;
1.993 +
1.994 + /** The share mode used to open the content file*/
1.995 + TContentShareMode iShareMode;
1.996 +
1.997 + /** Reference to the file handle if the content was opened with a file handle */
1.998 + RFile iFile;
1.999 + };
1.1000 +
1.1001 + } // namespace ContentAccess
1.1002 +#endif /* __CONTENT_H__ */