Opening a file using CDocumentHandler

Article Metadata

---

Tested with

Devices(s): Nokia N95 8GB

---

Compatibility

Platform(s): S60 3rd Edition, FP1

---

Article

Keywords: CDocumentHandler, TDataType, MAknServerAppExitObserver, CDocumentHandler::OpenL(), CDocumentHandler::OpenFileEmbeddedL(), CDocumentHandler::HandlerAppUid(), TApaTaskList::FindApp(), TApaTask::Exists(), TApaTask::SwitchOpenFile(), CDocumentHandler::SetExitObserver(), MAknServerAppExitObserver::HandleServerAppExit()

Created: tapla (09 Jun 2008)

Last edited: hamishwillee (13 Jun 2012)

Overview

This code snippet demonstrates how to open a file using the Document Handler API (CDocumentHandler). Two different techniques are demonstrated:

1. Opening a file in a standalone handler application.
2. Opening a file as embedded in the launching application.

MMP file

The following capabilities and libraries are required:

CAPABILITY SwEvent  // TApaTask::SwitchOpenFile() (Standalone version only)

LIBRARY apgrfx.lib    // TApaTaskList, TApaTask (Standalone version only)
LIBRARY apmime.lib    // TDataType
LIBRARY commonui.lib  // CDocumentHandler

Header file (standalone version)

#include <DocumentHandler.h>

class CMyAppUi : public CAknAppUi
    {
    // ...
 
    private:  // Private functions
        void LaunchFileL(const TDesC& aFilename);
        void RefreshDocumentFileL(const TUid& aUid, const TDesC& aFileName);
 
    private:  // Data
        CDocumentHandler* iDocHandler;
    }

Source file (standalone version)

To launch the file in a standalone handler, use the CDocumentHandler::OpenFileL() method. In addition, the following code shows how to update the file if it has already been opened in the handler.

#include <DocumentHandler.h>

void CMyAppUi::ConstructL()
    {
    // Create the document handler
    iDocHandler = CDocumentHandler::NewL(CEikonEnv::Static()->Process());
 
    // ...
    }

void CMyAppUi::LaunchFileL(const TDesC& aFilename)
    {
    TDataType emptyDataType = TDataType();
    // Open a file in a standalone handler application
    iDocHandler->OpenFileL(aFilename, emptyDataType);
 
    TUid handlerUid; 
    TInt err = KErrNone;
    err = iDocHandler->HandlerAppUid(handlerUid);
    if (!err)
        {
        RefreshDocumentFileL(handlerUid, aFilename);
        }
    }
 
/**
 * Refreshes the file opened in a standalone handler. Does nothing if the file
 * has not been already opened.
 */
void CMyAppUi::RefreshDocumentFileL(const TUid& aUid, const TDesC& aFileName)
    {
    TApaTaskList taskList(iCoeEnv->WsSession());
    TApaTask task = taskList.FindApp(aUid);
 
    // If the standalone handler is already running, then update the file
    if (task.Exists())
        {
        User::LeaveIfError(task.SwitchOpenFile(aFileName));
        }
    }

Header file (embedded version)

#include <aknserverapp.h>  // MAknServerAppExitObserver
#include <DocumentHandler.h>

class CMyAppUi : public CAknAppUi, public MAknServerAppExitObserver
    {
    // ...
 
    private:  // Functions from base classes
        /**
         * From MAknServerAppExitObserver.
         * Handles the exit of a connected server application.
         */ 
        void HandleServerAppExit(TInt aReason);
 
    private:  // Private functions
        void LaunchFileEmbeddedL(const TDesC& aFilename);
 
    private:  // Data
        CDocumentHandler* iDocHandler;
    };

Source file (embedded version)

To launch the file as embedded, use the CDocumentHandler::OpenFileEmbeddedL() method:

#include <aknserverapp.h>  // MAknServerAppExitObserver
#include <DocumentHandler.h>

void CMyAppUi::ConstructL()
    {
    // Create the document handler
    iDocHandler = CDocumentHandler::NewL(CEikonEnv::Static()->Process());
 
    // ...
    }

void CMyAppUi::LaunchFileEmbeddedL(const TDesC& aFilename)
    {
    //Set the exit observer so HandleServerAppExit will be called
    iDocHandler->SetExitObserver(this);   
 
    TDataType emptyDataType = TDataType();
    //Open a file embedded
    iDocHandler->OpenFileEmbeddedL(aFilename, emptyDataType);             
    }
 
void CMyAppUi::HandleServerAppExit(TInt aReason)
    {
    //Handle closing the handler application
    MAknServerAppExitObserver::HandleServerAppExit(aReason);
    }

Postconditions

The file denoted by aFilename is opened with CDocumentHandler.

See also

• S60 Platform: Document Handler Example