--- a/loc_plat/location_centre_api/inc/lclocationappinfo.h Wed Apr 14 15:50:30 2010 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,669 +0,0 @@
-/*
-* ============================================================================
-* 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.
- *
- * @lib lcservice.lib
- * @since S60 v5.0
- */
-class CLcLocationAppInfoArray : public CBase
- {
-public:
- /**
- * Constructs a new instance of Location Application information array.
- *
- * @return The new instance of Location Application information array.
- * @leave System wide error code if the object creation fails.
- */
- IMPORT_C static CLcLocationAppInfoArray* NewL();
-
- /**
- * Constructs a new instance of Location Application information array.
- * Leaves the created instance on the cleanup stack.
- *
- * @return The new instance of Location Application information array.
- * @leave System wide error code if the object creation fails.
- */
- IMPORT_C static CLcLocationAppInfoArray* NewLC();
-
- /**
- * C++ Destructor.
- * Frees all the resources associated with this Location Application
- * information array. This includes all the Location Application
- * information objects that it owns.
- */
- IMPORT_C virtual ~CLcLocationAppInfoArray();
-
- /**
- * Returns the number of Location Application information objects in the
- * array.
- *
- * @since S60 v5.0
- * @return The number of objects.
- */
- IMPORT_C TInt Count() const;
-
- /**
- * Appends a Location Application information object to the array.
- * The ownership of the inserted object is transferred.
- *
- * @since S60 v5.0
- * @param[in] aLCAppInfo Location Application information object which is
- * to be inserted.
- * @leave System wide error code if the operation fails.
- */
- IMPORT_C void AppendL( CLcLocationAppInfo* aLCAppInfo );
-
- /**
- * Removes a Location Application information object corresponding to the
- * specified array position from the array.
- * The function does not delete the object which is removed but transfers
- * it back to the caller. The ownership of the returned object is also
- * transferred to the caller.
- *
- * @since S60 v5.0
- * @param[in] aIndex Index of the requested object in the array. The
- * position is relative to zero, i.e. zero implies
- * the object pointer at the beginning of the array.
- * @return Pointer to the requested object.
- * @panic @ref TLCPanicCodes::ELcArrayOutofBounds, if there is no object
- * corresponding to the index.
- */
- IMPORT_C CLcLocationAppInfo* Remove( TInt aIndex );
-
- /**
- * Resets the Location Application Info Array. It also deletes all the
- * Location Application Information objects present in the array.
- *
- * @since S60 v5.0
- */
- IMPORT_C void Reset();
-
- /**
- * Returns a Location Application information object corresponding to the
- * specified array position.
- * Only a reference to the internal object is returned, the ownership is
- * not transferred.
- *
- * @since S60 v5.0
- * @param[in] aIndex Index of the requested object in the array. The
- * position is relative to zero, i.e. zero implies
- * the object pointer at the beginning of the array.
- * @return Reference to the requested object.
- * @panic @ref TLcPanicCodes::ELcArrayOutofBounds, if there is no object
- * corresponding to the index.
- */
- IMPORT_C CLcLocationAppInfo& operator[]( TInt aIndex ) const;
-
-private:
- /**
- * Default C++ Constructor.
- */
- CLcLocationAppInfoArray();
-
- /**
- * Overloaded Copy Constructor. By default, prohibit copy constructor
- *
- * @param[in] aLCAppInfoArray Location Application information array from which
- * the new object should be constructred.
- */
- CLcLocationAppInfoArray(
- const CLcLocationAppInfoArray& aLCAppInfoArray );
-
- /**
- * Overloaded Assignment operator. By default, prohibit assignment
- * operator
- *
- * @param[in] aLCAppInfoArray Location Application information array from which
- * the new value needs to be assigned.
- * @return The Location Application information array after
- * assigment
- */
- CLcLocationAppInfoArray& operator=(
- const CLcLocationAppInfoArray& aLCAppInfoArray );
-
- /**
- * Second phase of the two phase constructor.
- */
- void ConstructL();
-
-private: // Data
- /**
- * Array of Location Centre application information objects.
- *
- * Owns
- */
- RPointerArray<CLcLocationAppInfo> iAppInfoArray;
-
- /**
- * Reserved for future use.
- */
- TAny* iReserved;
- };
-
-#endif // C_LCLOCATIONAPPINFO_H