diff -r 000000000000 -r 522cd55cc3d7 loc_plat/location_centre_api/inc/lclocationappinfo.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/loc_plat/location_centre_api/inc/lclocationappinfo.h Tue Feb 02 00:16:03 2010 +0200 @@ -0,0 +1,669 @@ +/* +* ============================================================================ +* 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 + +// 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 iAppInfoArray; + + /** + * Reserved for future use. + */ + TAny* iReserved; + }; + +#endif // C_LCLOCATIONAPPINFO_H