// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// Some of the examples below do not include fully comprehensive error checking. They are written this way to simplify the 
// understanding of the basic steps involved. All errors should be handled appropriately in production code.
// <b>Consumer API </b>
// <b>Supplier API </b>
// <hr>
// This example function takes the URI of a file and displays the plaintext version of that content on screen.
// If anything goes wrong, for instance the file does not exist or there are no valid rights
// that will allow the file to be displayed, the function will just leave.
// It's important to notice the call to <code>ContentAccess::CData::ExecuteIntent()</code>, this should always be called, even if you
// think it's unlikely you will open DRM content.
// class CContentViewer : public CBase
// public:
// static CContentViewer* NewL();
// static CContentViewer* NewLC();
// // Display given content.
// void DisplayContent(const TDesC& aUri, TRequestStatus& aStatus)
// TRAPD(err, DisplayContentL(aUri));
// User::RequestComplete(aStatus, err);
// private:
// CContentViewer() : CBase() {}
// ~CContentViewer() {} 
// void DisplayContentL(const TDesC& aUri)
// TInt size = 0;
// TInt i = 0;
// // Create a CContent object
// // CAF will figure out the appropriate agent
// CContent *content = CContent::NewLC(aUri);
// // Create a CData object to read the content
// // Tell the agent we are planning to display the content
// CData *data = content->OpenContentLC(EDisplay);
// // Don't need content object any more
// CleanupStack::PopAndDestroy(content);
// // get the size of the plaintext content
// data->DataSizeL(size);
// // Execute the intent, tell the agent that we plan to display the content
// // It is at this point that any stateful rights will be decremented
// data->ExecuteIntentL(EDisplay);
// // read and display the file until we reach the end of the file
// TBuf <128> buffer;		
// while(i < size)
// // read from the file
// User::LeaveIfError(data->Read(buffer));
// i += buffer.Length();
// // display on screen
// printf(buffer);
// // finished with Data object
// CleanupStack::PopAndDestroy(data);
// <hr>
// This example is the same as before except it attempts to obtain or wait for rights
// to become available rather than just leaving if access to the content is restricted.
// class CContentViewer : public CActive
// public:
// static CContentViewer* NewL();
// static CContentViewer* NewLC();
// // Display given content.
// void DisplayContent(const TDesC& aUri, TRequestStatus& aStatus)
// iUri = aUri;
// iClientStatus = &aStatus;
// iClientStatus = KRequestPending;
// iCurrentState = EOpenFile;
// // trigger our RunL
// iStatus = KRequestPending;
// SetActive();
// User::RequestComplete(iStatus, KErrNone);
// void RunL()
// TInt err = iStatus.Int();
// switch (iCurrentState)
// case EOpenFile:
// iContent = CContent::NewL(aUri);
// TRAP(err, iData = iContent->OpenContentL(EDisplay));
// iCurrentState = EReadAndDisplay;	// follow through...
// case EReadAndDisplay:
// if(err == KErrNone)
// TRAP(err, DisplayFile());
// iCurrentState = EFinished;
// // tell client iStatus that we have finished
// User::RequestComplete(*iClientStatus, err);
// return;
// else if(err == KErrCANoRights)
// // we don't have rights so we need to wait for them
// iCurrentState = EWaitingForRights;
// // ask CAF to initiate download of rights
// iContent->RequestRights(iStatus);
// else if(err == KErrCAPendingRights)
// // waiting for rights to arrive, expected any minute now
// iCurrentState = EWaitingForRights;
// // ask CAF to notify us when they arrive
// iContent->NotifyStatusChange(ERightsAvailable , iStatus);
// // wait for CAF to complete our request 
// iLastError = err;
// iStatus = KRequestPending;
// SetActive();
// break;
// case EWaitingForRights:
// if(ret == KErrNone)
// // change the state to try and display content again
// iCurrentState = EReadAndDisplay;
// // trigger our RunL
// iLastError = err;
// iStatus = KRequestPending;
// SetActive();
// User::RequestComplete(iStatus, KErrNone);
// else
// // couldn't get rights, tell parent active object we're finished
// User::RequestComplete(iClientStatus, err);
// return;
// break;
// protected:		
// void DoCancel()
// if (iLastError == KErrCAPendingRights)
// iContent->CancelNotifyStatusChange(iStatus);
// else if (iLastError == KErrCANoRights)
// iContent->CancelRequestRights(iStatus);
// private:
// CContentViewer() : CActive(EPriorityStandard)
// CActiveScheduler::Add(this); 
// ~CContentViewer() 
// Cancel();
// if (iData) delete iData; 
// if (iContent) delete iContent;
// // Display the content, if any error occurs then leave
// void DisplayContentL();
// TInt size = 0;
// TInt i = 0;
// TBuf <128> buffer;
// // Execute the intent, tell the agent that we plan to display the content
// // It is at this point that any stateful rights will be decremented
// iData->ExecuteIntentL(EDisplay);
// // get the size of the plaintext content
// iData->DataSizeL(size);
// // read and display the file until we reach the end of the file
// while(i < size)
// // read from the file
// User::LeaveIfError(iData->Read(buffer));
// i += buffer.Length();
// // Display on screen
// printf(buffer);
// private:
// enum TState
// EOpenFile = 0,
// EReadAndDisplay,
// EWaitingForRights,
// EFinished
// CContent*	iContent;
// CData* 		iData;
// TDesC		iUri;
// TState			iCurrentState;
// TInt 			iLastError;
// TRequestStatus*		iClientStatus;
// <hr>
// Some servers may wish to prevent access to DRM content by untrusted clients, even if
// the server itself has DRM capability.
// To achieve this the server should use the <code>ContentAccess::TIntent::EUnknown</code> intent when 
// accessing content. Content files that are not DRM protected will still work normally, but
// access to DRM protected content will be blocked.
// // Tell the agent we have no idea what the application plans to do
// CData *data = content->OpenContentL(EUnknown);
// // Execute the intent, tell the agent that we have no idea what the content will be used for
// data->ExecuteIntentL(EUnknown);
// <hr>
// When reading from a particular content object within a file the application must supply
// the \c UniqueId of the object when calling <code>ContentAccess::CContent::OpenContentL()</code>.
// void DisplayTextFileL(const TDesC& aUri)
// TInt size = 0;
// TInt i = 0;
// TBuf <128> buffer;
// // Create a CContent object
// // CAF will figure out the appropriate agent
// CContent *content = CContent::NewLC(aUri);
// // Find the objects in the file with MIME type image/jpeg
// RStreamablePtrArray<CEmbeddedObject> myArray;
// CleanupClosePushL(myArray);
// User::LeaveIfError(content->Search(myArray, _L("image/jpeg"), EFalse));
// // Get the virtual path of the first image/jpeg we find
// TVirtualPathPtr picture = *myArray[0];
// // Tell the agent to open the object with the given UniqueId
// CData *data = content->OpenContentLC(EDisplay, picture.UniqueId());
// // Don't need content object or array any more
// CleanupStack::PopAndDestroy(2);	// content, myArray
// // get the size of the plaintext content
// data->DataSizeL(size);
// // Execute the intent, tell the agent that we plan to display the content
// // It is at this point that any stateful rights will be decremented
// data->ExecuteIntentL(EDisplay);
// // read and display the file until we reach the end of the file
// while(i < size)
// // read from the file
// User::LeaveIfError(data->Read(buffer));
// i += buffer.Length();
// // display on screen
// printf(buffer);
// // finished with Data object
// CleanupStack::PopAndDestroy(data);
// <hr>
// This example shows how a messaging application that has just received
// a message attachment from a mail server can offer the attachment
// to CAF for processing. The output files will be saved in <code>C:\\files\\</code>.
// void CMyApp::ReceiveMessageAttachment(const TDesC8& aContentType, const TDesC8& aMessageAttachment)
// // Create supplier object
// CSupplier* supplier = CSupplier::NewLC();
// // Tell the agent where we would like the output files to be written
// supplier->SetOutputDirectoryL(_L("C:\\files"));
// // Check if CAF can import this attachment we just received
// if(supplier->IsImportSupported(aContentType))
// ProcessAttachmentL(supplier, aContentType, aMessageAttachment);	
// else
// // just save the message to a file in its current form
// RFile theFile;
// theFile.Open(iFs, "myFile");
// theFile.Write(aMessageAttachment);
// theFile.Close();
// // Add the file to the list of attachments
// AddAttachment("myFile");
// void CMyApp::ProcessAttachmentL(CSupplier* aSupplier, const TDesC8& aContentType, const TDesC8& aMessageAttachment)
// TInt err = KErrNone;
// TBuf <128> buf;
// // Create meta-data array
// CMetaDataArray* metaDataArray = new (ELeave) CMetaDataArray();
// CleanupStack::PushL(metaDataArray);
// // Add any useful information we can think of....
// // Obviously these would not be hardcoded this way in a real import
// metaDataArray->AddL(_L("Content Type"), _L("application/vnd.oma.drm.dm"));
// metaDataArray->AddL(_L("Content Length"), _L("1201"));
// metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"), _L("6"));
// // Create the import object
// CImportFile* import = aSupplier->ImportFileL(aContentType, *metaDataArray, _L("myfile"));
// CleanupStack::PushL(import);
// // import the attachment
// err = import->WriteData(aMessageText);
// // tell CAF (and hence the agent) it's now got the entire file
// if (err == KErrNone)
// err = import->WriteDataComplete();
// if (err == KErrNone)
// // Look at the output of the import operation
// for(TInt i = 0; i < import->OutputFileCountL(); i++)
// // for this example only add content output files
// // (absorb any rights in the original attachment 'silently')
// if(import->OutputFilesL(i).OutputType == EContent)
// // Add file to list of attachments for this message
// AddAttachment(import->OutputFilesL(i).FileName());
// // Error handling
// if (err != KErrNone)
// if (err == KErrNotReady)	
// DisplayErrorMsg("Agent not ready for import");
// else if (err == KErrCACorruptContent)
// DisplayErrorMsg("Content data is corrupt");
// else
// DisplayErrorMsg("Unexpected error: %d", err);
// // Finished
// CleanupStack::PopAndDestroy(2);		// metaDataArray, import
// <hr>
// This example shows how a messaging application that has just received
// a message attachment from a mail server can offer the attachment
// to CAF for processing and store the file in its own private directory.
// void CMyApp::ReceiveMessageAttachment(const TDesC8& aContentType, const TDesC8& aMessageAttachment)
// // Create supplier object
// CSupplier* supplier = CSupplier::NewLC();
// // Check if CAF can import this attachment we just received
// if(supplier->IsImportSupported(aContentType))
// ProcessAttachmentL(supplier, aContentType, aMessageAttachment);	
// else
// // just save the message to a file in its current form
// RFile theFile;
// theFile.Open(iFs, "myFile");
// theFile.Write(aMessageAttachment);
// theFile.Close();
// // Add the file to the list of attachments
// AddAttachment("myFile");
// void CMyApp::ProcessAttachmentL(CSupplier* aSupplier, const TDesC8& aContentType, const TDesC8& aMessageAttachment)
// TInt err = KErrNone;
// TBuf <128> buf;
// TBuf <4> fileExtension;
// _LIT(KOutputFileName, "\\private\\12345678\\outputfile.");
// TFileName fileName(KOutputFileExtension);
// RFile file;
// // Create meta-data array
// CMetaDataArray* metaDataArray = CMetaDataArray::NewLC();
// // Add any useful information we can think of....
// // Obviously these would not be hardcoded this way in a real import
// metaDataArray->AddL(_L("Content Type"), _L("application/vnd.oma.drm.dm"));
// metaDataArray->AddL(_L("Content Length"), _L("1201"));
// metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"), _L("6"));
// // Create the import object, no suggested file name implies the application will supply output files
// CImportFile* import = aSupplier->ImportFileL(aContentType, *metaDataArray);
// CleanupStack::PushL(import);
// // Start importing the attachment
// // (if the agent needs one or more output files, continue looping until 
// // the agent finishes the previous)
// TInt err = import->WriteData(aMessageText);
// while(err == KErrCANewFileHandleRequired)
// import->GetSuggestedOutputFileExtension(fileExtension);
// filName.Append(fileExtension);
// User::LeaveIfError(file.Open(iFs, fileName));
// err = import->ContinueWithNewOutputFile(file);
// file.Close();
// if (err == KErrNone)
// // Complete the import process
// err = import->WriteDataComplete();
// while(err == KErrCANewFileHandleRequired)
// import->GetSuggestedOutputFileExtension(fileExtension);
// filName.Append(fileExtension);
// User::LeaveIfError(file.Open(iFs, fileName));
// err = import->ContinueWithNewOutputFile(file);
// file.Close();
// if (err == KErrNone)
// // Look at the output of the import operation
// for(TInt i = 0; i < import->OutputFileCountL(); i++)
// // for this example only add content output files
// // (absorb any rights in the original attachment 'silently')
// if(import->OutputFilesL(i).OutputType == EContent)
// // Add file to list of attachments for this message
// AddAttachment(import->OutputFilesL(i).FileName());
// // Error handling
// if (err != KErrNone)
// if (err == KErrNotReady)	
// DisplayErrorMsg("Agent not ready for import");
// else if (err == KErrCACorruptContent)
// DisplayErrorMsg("Content data is corrupt");
// else
// DisplayErrorMsg("Unexpected error: %d", err);
// // Finshed
// CleanupStack::PopAndDestroy(2);		// metaDataArray, import
// 
//

/**
 @page CAFExamples Example source code using CAF
 - @ref ExampleRead1
 - @ref ExampleReadWithErrCheck
 - @ref PlayingUnprotectedOnly 
 - @ref MultipleContentExample
 - @ref ExampleSupplier1
 - @ref ExampleSupplier2
 @section ExampleRead1 Reading from a file, no error checking
 @code
 @endcode
 @section ExampleReadWithErrCheck Reading from a file, with error checking
 @code
 @endcode
 @section PlayingUnprotectedOnly Preventing access to DRM content
 @code
 @endcode
 @section MultipleContentExample File containing several content objects
 @code
 @endcode
 @section ExampleSupplier1 Importing a content file, agent provides output files
 @code
 @endcode
 @section ExampleSupplier2 Importing a content file, application provides output files
 @code
 @endcode
*/