/*

* ============================================================================

*  Name        : lclocationappinfo.h

/*

* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:  Location Application Information structures.

*

*/

/**

 *  @file lclocationappinfo.h

 * 

 *  This file provides the information about the components registered with

 *  Location Centre.

 *

 *  @note The components which can register with Location Centre are of

 *  two types

 *  - Applications

 *  - Location based services / contents.

 *

 *  These Client Applications or Services/Contents which register with Location

 *  Centre will be called Location based Applications henceforth.

 *

 *  @lib lcservice.lib

 *  @since S60 v5.0

 */

#ifndef C_LCLOCATIONAPPINFO_H

#define C_LCLOCATIONAPPINFO_H

// SYSTEM INCLUDES

#include <e32base.h>

// USER INCLUDES

#include "lclocationappfilter.h"

// FORWARD DECLARATIONS

class CGulIcon;

/**

 *  @class CLcLocationAppInfo

 *  Location Application information.

 *

 *  The class defines the information pertaining to an application registered 

 *  with Location Centre.

 *

 *  @lib lcservice.lib

 *  @since S60 v5.0

 */

class CLcLocationAppInfo : public CBase

    {

public:

    /**

     * @enum TLcSystemCharacteristics

     * System Characteristics for the applications registered with Location

     * Centre.

     *

     * These characteristics can be combined and used to form a bit-mask

     * which can then be used while retrieving/displaying registered

     * applications from Location Centre. 

     * The system characteristics are defined by Location Centre when an

     * application registers with it.

     */

    enum TLcSystemCharacteristics

        {

        /**

         * This characteristic can be used to retrieve/display all Location

         * Applications regardless of their System arrtibutes. This

         * characteristic cannot be combined with any other value.

         * This will be used as the default System characteristic.

         */

        ESysCharNone                                = 0,

        /**

         * This characteristic is associated with Location based Applications that

         * are installed on the ROM.

         */

        ESysCharRomBased                            = 1

        };

    /**

     * @enum TLcApplicationCharacteristics

     * Application Characteristics for the applications registered with 

     * Location Centre.

     * 

     * The application characteristics are defined by the Location based Applications

     * when they register with Location Centre. A Location Application can

     * define one or more characteristics when they register. These

     * characteristics can be combined and used to form a bit-mask which can

     * then be used while retrieving/displaying registered applications from

     * Location Centre.

     */

     enum TLcApplicationCharacteristics

        {

        /**

         * This characteristics is used for Location based Applications which do

         * not wish to publish any characteristics. These Location based Applications

         * would get displayed in Location Centre only when Location Centre is

         * launched from the application shell or when the user of the Location

         * Centre API does not specify any other Application characteristics in

         * filtering. This characteristic cannot be combined with any other value.

         * This will be used as the default Application characteristic.             

         */

        EAppCharNone                                = 0,

        /**

         * This characteristic is used for Location based Applications which have

         * Settings related functionality. These Location based Applications are

         * used to configure the user's terminal or the remote server for

         * all Location related features.

         */

        EAppCharSettings                            = 1,

        /**

         * This characteristic is used for Location based Applications which have

         * Personal Data Management related functionality. These Location

         * based Applications enable the user to manage his personal information.

         */

        EAppCharPersonalDataManagement              = 2,

        /**

         * This characteristic is used for Location based Applications which have

         * Navigation related functionality. These Location based Applications

         * help the terminal user to navigate from one location to another.

         */

        EAppCharNavigation                          = 4,

        /**

         * This characteristic is used for Location based Applications which are

         * related to Location based events. These Location based Applications are

         * generally based to trigger certain events based on the terminal's

         * current Location.

         */

        EAppCharLocationBasedEvents                 = 8,

        /**

         * This characteristic is used for Location based Applications which have

         * Remote positioning related functionality. These Location 

         * based Applications are generally involved in determining the current

         * location of other terminals or objects.

         */

        EAppCharRemotePositioning                   = 16,

        /**

         * This characteristic is used for Location based Applications which are

         * related to Network services. These Location based Applications are

         * generally involved in the exchange of Location related information

         * and Location related services over the network.

         */

        EAppCharNetworkService                      = 32,

        /**

         * This characteristic is used for Location based Applications which are

         * used to send Location enhanced messages.

         */

        EAppCharLocationEnhancedMessages            = 64,

        /**

         * This characteristic is used for Location based Applications which

         * provide Location based content which is stored on the terminal. 

         */

        EAppCharOnDeviceLocationBasedContent        = 128,

        /**

         * This characteristic is used for Location based Applications which

         * provide Location based content that is stored remotely and needs

         * to be accessed from the remote server. These Location based Applications

         * would need connection to the network to access the Location based

         * content.

         */

        EAppCharRemoteLocationBasedContent          = 256,

        /**

         * This characteristic is used for Location based Applications which

         * position a particular geographic location of a map.

         */

        EAppCharMaps                                = 512

        };

    /**

     * @enum TLcLaunchMode

     * The mode in which Location Centre needs to launch the application

     * contained in the Location Application information object.

     */

    enum TLcLaunchMode

        {

        /**

         * The corresponding application would be launched in the mode

         * specified by it during registration with Location Centre.

         */

        EDefaultMode                            = 0,

        /**

         * The corresponding application would be launched as a stand

         * alone application.

         */

        EStandAloneMode                         = 1,

         /**

         * The corresponding application would be launched as a

         * chained application.

         */

        EChainedMode                            = 2           

        };

public: // Exported Functions

    /**

     * Constructs a new instance of Location Application information object.

     *

     * @return The new instance of Location Application information object.

     * @leave System wide error code if the object creation fails.

     */

    IMPORT_C static CLcLocationAppInfo* NewL();

    /**

     * Constructs a new instance of Location Application information object.

     * Leaves the created instance on the cleanup stack.

     *

     * @return The new instance of Location Application information object.

     * @leave System wide error code if the object creation fails.         

     */

    IMPORT_C static CLcLocationAppInfo* NewLC();        

    /**

     * Constructs a new instance of Location Application information object.

     *

     * @param[in] aLocAppInfo Location Application Information from which the

     *                        object should be constructed. 

     * @return The new instance of Location Application information object.

     * @leave System wide error code if the object creation fails.

     */

    IMPORT_C static CLcLocationAppInfo* NewL( 

                            const CLcLocationAppInfo&  aLocAppInfo );

    /**

     * Constructs a new instance of Location Application information object.

     * Leaves the created instance on the cleanup stack.

     *

     * @param[in] aLocAppInfo Location Application Information from which the

     *                        object should be constructed.         

     * @return The new instance of Location Application information object.

     * @leave System wide error code if the object creation fails.         

     */

    IMPORT_C static CLcLocationAppInfo* NewLC(

                            const CLcLocationAppInfo&  aLocAppInfo );    

    /**

     * C++ Destructor.

     * Frees all the resources associated with this Location Application

     * information object.

     */

    virtual ~CLcLocationAppInfo();

    /**

     * Gets the Unique identifier identifying the Location Application.

     * This identifier is defined by the Location Application on registration

     * with Location Centre.

     * This is the identifier that must be used by the client of this API for 

     * any operation on the particular Location Application.

     * A reference to the object's internal string is returned.     

     *

     * @since S60 v5.0     

     * @return Unique identifier identifying the Location Application. If the

     *         value of the identifier has not been set then a NULL string

     *         is returned.

     */

    IMPORT_C TPtrC Id() const;

    /**

     * Gets the Logical name for the Location Application.

     * The name is defined by the Location Centre on registration with

     * Location Centre. This is the name which would be displayed by

     * Location Centre for this application.

     * A reference to the object's internal string is returned.

     *

     * @since S60 v5.0     

     * @return Logical name for the Location Application. If the name 

     *         has not been set for the Location Application, then a NULL

     *         string is returned.

     */

    IMPORT_C TPtrC Name() const;

    /**

     * Gets the Icon for the Location Application. 

     * This is the icon that would be displayed in Location Centre for this

     * application. If no icon is defined then a default icon would be used.

     *

     * The ownership of the icon would be transferred back to the caller

     * function.

     *

     * @since S60 v5.0     

     * @return - Icon for the Location Application. 

     *         - NULL, If the Icon has not been set for the Location 

     *                 based Application

     * @leave System wide error codes if the icon allocation or copying

     *        fails.

     */

    IMPORT_C CGulIcon* IconL() const;

    /**

     * Mode in which the Location Application would be launched. 

     * If the mode defined is EDefaultMode, then the default mode specified

     * by the application when registering with Location Centre is used.

     *

     * @since S60 v5.0     

     * @return Mode in which the Location Application would be launched.       

     */

    IMPORT_C TLcLaunchMode LaunchMode() const;

    /**

     * Returns the System characteristics for the Location Application

     *

     * @since S60 v5.0

     * @return - System Characteristics for the Location

     *           Application. All the system characteristics for the 

     *           Location Application would be combined to form an integer

     *           bit-mask and this function returns the bit-mask. The

     *           individual System characteristics are defined by

     *           @ref TLcSystemCharacteristics enumeration.

     */

    IMPORT_C TUint32 SystemCharacteristics() const;

    /**

     * Returns the Application characteristics for the Location Application

     *

     * @since S60 v5.0

     * @return - Application Characteristics for the Location

     *           Application. All the application characteristics for the 

     *           would be combined to form an integer bit-mask and this

     *           function returns the current bit-mask. The individual

     *           Application characteristics are defined by

     *           @ref TLcApplicationCharacteristics enumeration.

     */

    IMPORT_C TUint32 ApplicationCharacteristics() const;

public: // Non exported methods

    /**

     * @internal

     * Set the Unique identifier identifying the Location Application. The

     * identifer is copied.

     *

     * @since S60 v5.0     

     * @param[in] aId Unique identifier identifying the Location Application.

     * @leave KErrNoMemory If there is not enough memory to copy the string.     

     * @leave KErrAlreadyExists If the value of the Location applicaton UID

     *                          has already been set.       

     */

    void SetIdL( const TDesC& aId );

    /**

     * @internal    

     * Set the Logical name for the Location Application. The name is 

     * copied.

     *

     * @since S60 v5.0     

     * @param[in] aName Logical name for the Location Application. 

     *                  The logical string is copied.

     * @leave KErrNoMemory If there is not enough memory to copy the string.

     * @leave KErrAlreadyExists If the value of the Location applicaton name.

     *                          has already been set.

     */

    void SetNameL( const TDesC& aName );

    /**

     * @internal    

     * Set the Icon for the Location Application.

     *

     * @since S60 v5.0     

     * @param[in] aIconType The type of the file which contains the Icon.

     * @param[in] aIconData Opaque data field which contains the actual data information.

     * @param[in] aIconId	Id of the Icon in the Icon file.

     * @leave KErrAlreadyExists If the value of the Location applicaton Icon

     *                          has already been set.         

     */	

	void SetIconL( 		 TInt		aIconType,

				   const TDesC&		aIconData,

				   		 TInt		aIconId = 0 );

    /**

     * @internal    

     * Sets the Mode in which the Location Application would be launched.

     *

     * @since S60 v5.0     

     * @param[in] aLaunchMode Mode in which the Location Application would be

     *                        launched. 

     */

    void SetLaunchMode( TLcLaunchMode  aLaunchMode );

    /**

     * @internal    

     * Sets the system characteristics for the Location Application.

     *

     * @since S60 v5.0     

     * @param[in] aSysCharacteristics System Characteristics for the Location

     *                                Application.

     */

    void SetSystemCharacteristics( TUint32   aSysCharacteristics);

    /**

     * @internal    

     * Sets the Application characteristics for the Location Application.

     *

     * @since S60 v5.0     

     * @param[in] aAppCharacteristics Application Characteristics for the Location

     *                                Application.

     */

    void SetApplicationCharacteristics( TUint32   aAppCharacteristics);

private:

    /**

     * Default C++ Constructor.

     */

    CLcLocationAppInfo();

    /**

     * Overloaded Copy Constructor.

     *

     * @param[in] aLCAppInfo Location Application information object from which

     * the new object should be constructred.

     */

    CLcLocationAppInfo( 

                const CLcLocationAppInfo&     aLCAppInfo );

    /**

     * Overloaded Assignment operator. By default, prohibit assignment

     * operator

     *

     * @param[in] aLCAppInfo Location Application information object from which 

     * the new value needs to be assigned.

     * @return The Location Application information object after assigment.

     */

    CLcLocationAppInfo& operator= ( 

                const CLcLocationAppInfo&   aLCAppInfo );

    /**

     * Second phase of the two phase constructor.

     */

    void ConstructL();

   /**

    * Second phase overloaded constructor

    */

   void ConstructL( const CLcLocationAppInfo&   aLCAppInfo ); 

private: // Data

    /**

     * System wide unique identifier identifying the Location Application. This

     * identifier is defined by the Location Application on registration with

     * Location Centre.

     *

     * Owns

     */

    HBufC*                          iId;

    /**

     * Application Name.

     * Logical name for the Location Application. The name is defined by the

     * Location Centre on registration with Location Centre. This is the name

     * which would be displayed by Location Centre for this application.

     * 

     * Owns

     */

    HBufC*                          iApplicationName;

    /**

     * Application Icon Data.

     * Icon for the Location Application. This is the icon that would be displayed

     * in Location Centre for this application. If no icon is defined then a

     * default icon would be used.

     *

     * Owns

     */

    HBufC*                       	iApplicationIconData;

	/**

	 * Application Icon Type.

	 */

	TInt							iApplicationIconType;

	/**

	 * Application Icon Id.

	 */

	TInt							iIconId;

    /**

     * Mode in which the Location Application would be launched. If the mode

     * defined is EDefaultMode, then the default mode specified by the 

     * application when registering with Location Centre is used.

     */

    TLcLaunchMode                   iLaunchMode; 

   /**

    * Bit-mask containing the System characteristics for the corresponding

    * Location application

    */

    TUint32                         iSystemCharacteristics;

   /**

    * Bit-mask containing the Application characteristics for the corresponding

    * Location application

    */

    TUint32                         iAppCharacteristics;

    /**

     * Reserved for future use.

     */           

    TAny*                           iReserved;

    };

/**

 *  @class CLcLocationAppInfoArray

 *  Array of CLocationAppInfo objects.

 *

 *  Place holder for the information about the applications registered with

 *  Location Centre. The class contains a list of individual Location Application

 *  information items.