/*

* Copyright (c) 2002-2006 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Cone Resource Loader API enables adding and removing 

*                localized resource files into the CONE environment.

*

*/

#ifndef CONERESLOADER_H

#define CONERESLOADER_H

// forward declarations

class CCoeEnv;

/** 

* Class encapsulates methods for opening and closing localised resource files

* in the CONE environment. The actual reading of resources from an opened 

* resource file is done using various CCoeEnv provided resource-reading 

* methods. Cone Resource Loader API consist of the RConeResourceLoader class.

*

* Only one resource at a time may be open by one RConeResourceLoader instance. 

* You can use several RConeResourceLoader instances for accessing several 

* resources simultaneously or use one instance and close the previous resource

* before opening a new one.

*

* The implementation uses BaflUtils::NearestLanguageFile to search for

* a localised resource in proper search order.

* 

* Usage example:  

*

* @code

*  #include <ConeResLoader.h>  

*

*  // Get CCoeEnv instance

*  CEikonEnv* eikEnv = CEikonEnv::Static();

*

*  // Initialize loader

*  RConeResourceLoader rLoader(eikEnv);

*

*  // Open resource file

*  _LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" );

*  TFileName fileName(KSampleResourceFileName);

*  rLoader.OpenL(fileName);

*

*  // Push resource loader to cleanup stack, so that it will always be properly 

*  // closed when popped.

*  CleanupClosePushL(rLoader);

*

*  // Read a resource   

*  iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE);

*

*  // Pop and destroy rLoader from stack. 

*  // This also calls close on rLoader since CleanupClosePushL was used.

*  CleanupStack::PopAndDestroy(); // rLoader

*

* @endcode

*

* @lib commonengine.lib

* @since S60 2.0

*/

class RConeResourceLoader

    {

    public:

        /**

         * Constructor. 

         *

         * @param aEnv is a reference to Control environment in which resource

         * is loaded.

         */

        IMPORT_C RConeResourceLoader(CCoeEnv& aEnv);

        /**

         * Opens the resource file for reading. Only one resource may be open 

         * at a time. Panics if this instance already has a file open. 

         * The implementation uses BaflUtils::NearestLanguageFile to search 

         * for a localized resource file in proper search order.

         * 

         * @param aFileName is the resource file name to open. This parameter

         * value is changed to the best matching language file found. The drive

         * letter is required in the filename.

         * @return a Symbian OS error code.

         *

         * @panic KErrNotSupported The instance already has a file open.

         */

        IMPORT_C TInt Open(TFileName& aFileName);

        /**

         * Opens the resource file for reading. Only one resource may be open 

         * at a time. Leaves if this instance already has a file open.

         * The implementation uses BaflUtils::NearestLanguageFile to search

         * for a localized resource file in proper search order.

         * 

         * @param aFileName Reference for resource file name. Please

         *                  note that drive letter is required ! 

         *

         * @leave KErrNotSupported The instance already has a file open.

         */

        IMPORT_C void OpenL(TFileName& aFileName);

        /**

         * Closes the opened resource file, if one is open. Does nothing if no

         * file has been opened. New resource file may be opened after the 

         * previous has been closed. Always remember to close the resource when 

         * finished using it.

         */

        IMPORT_C void Close();

    private:

        // Prohibit copy constructor and assigment operator because not deriving from CBase.

        RConeResourceLoader(const RConeResourceLoader&);

        RConeResourceLoader& operator= ( const RConeResourceLoader& );

        // Needed for closing

        CCoeEnv& iEnv; 

        TInt iResourceFileOffset;

    };

#endif

// End of File