// 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

*/