1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Location information converter plug in API

    15 *

    16 */

    17 

    18 

    19 /**

    20 * @file

    21 * @publishedPartner

    22 * @prototype

    23 */

    24 

    25 

    26 #ifndef LBS_LOC_INFO_CONVERSION_PLUGIN_BASE_H

    27 #define LBS_LOC_INFO_CONVERSION_PLUGIN_BASE_H

    28 

    29 

    30 // System wide

    31 #include <e32base.h>

    32 

    33 // Common LBS data types

    34 #include <lbs/lbslocationinfo.h>

    35 #include <lbs/lbslocationinfoconvertercommon.h>

    36 

    37 // Component specific

    38 #include <lbs/lbslocinfoconverterplugincommon.h>

    39 #include <lbs/lbslocinfoconverterpluginclasstypes.h>

    40 

    41 

    42 class TLbsLocInfoConverterPluginParams;

    43 

    44 

    45 /**

    46 * The MLbsLocInfoConverterPluginObserver class is used in partnership with

    47 * CLbsLocInfoConverterPluginBase. The observer interface is used by a 

    48 * conversion plugin to inform LBS when a coordinate conversion process 

    49 * initiated through the CLbsLocInfoConverterPluginBase class is completed. 

    50 *

    51 * Although all the interface methods in the MLbsLocInfoConverterPluginObserver

    52 * class are synchronous, the LBS subsystem ensures they return quickly.

    53 */

    54 class MLbsLocInfoConverterPluginObserver

    55     {

    56     

    57 public:

    58 

    59 	/** 

    60 	 * Gets the current version of the observer interface.

    61 	 * Derived classes should not change the implementation.

    62 	 * 

    63 	 * @return Version number (currently 1.0.0) 

    64      */

    65 	IMPORT_C virtual TVersion Version() const;

    66 	

    67 	/**

    68 	 * The callback is used by the conversion plugin to inform the LBS

    69 	 * subsystem that a validation request initiated through the 

    70 	 * CLbsLocInfoConverterPluginBase::ValidateClient method is completed. 

    71 	 *

    72 	 * @param aStatusCode Result of the validation operation. 

    73 	 *         KErrNone if the access is granted.

    74 	 *         KErrPermissionDenied due to a potential security violation.

    75          *         Other system wide error codes.

    76 	 */

    77 	IMPORT_C virtual void OnValidationComplete( TInt aStatusCode ) = 0;

    78 

    79     /** 

    80      * The callback is used by the conversion plugin to inform the LBS 

    81      * subsystem that a coordinate conversion process initiated through the 

    82      * CLbsLocInfoConverterPluginBase::ConvertLocationInfoL method is 

    83      * completed.

    84      *

    85      * Receiving the callback indicates that, unless the conversion was not 

    86      * successful, the location data structures passed through the 

    87      * CLbsLocInfoConverterPluginBase::ConvertLocationInfoL method have been 

    88      * updated with the requested information.

    89      *

    90      * @param aStatusCode Result of the conversion operation. 

    91      *         KErrNone if at least one conversion have been successful and 

    92      *         the related location data structure(s) passed through the 

    93      *         CLbsLocInfoConverterPluginBase::ConvertLocationInfoL method 

    94      *         have been updated with the requested information;

    95      *         KErrKErrNotFound if none of conversions have been successful

    96      *         Or other system wide error code otherwise.

    97      */

    98     IMPORT_C virtual void OnConversionComplete( TInt aStatusCode ) = 0;

    99 

   100 private:

   101     

   102 	/** 

   103 	 * This methods is reserved for future expansion and should not be used or 

   104 	 * implemented by derived classes.

   105 	 */	

   106 	IMPORT_C virtual TAny* ExtendedInterface( TInt aFunctionNumber, 

   107                                               TAny* aPtr1, 

   108                                               TAny* aPtr2 );

   109 	

   110     };

   111 

   112 

   113 /**

   114 * The CLbsLocInfoConverterPluginBase is the abstract Ecom interface to a 

   115 * coordinate conversion Plugin. All coordinate conversion Plugins must derive 

   116 * from and implement this interface.

   117 *

   118 * The interface is used in partnership with MLbsLocInfoConverterPluginObserver

   119 * and is used by the LBS subsystem to request conversion of location 

   120 * information between different formats.

   121 *

   122 * Completion of conversions must be indicated by a plugin by invoking 

   123 * callback(s) defined by the MLbsLocInfoConverterPluginObserver class.

   124 *

   125 * Although all the interface methods in the class are synchronous they must 

   126 * return immediately. When the LBS subsystem makes a request via 

   127 * CLbsLocInfoConverterPluginBase the Plugin must queue the request internally 

   128 * and return control to the caller immediately. Later on, when plugin provides

   129 * a response, it uses the corresponding notification method in the

   130 * MLbsLocInfoConverterPluginObserver class.

   131 */

   132 class CLbsLocInfoConverterPluginBase : public CBase

   133     {

   134     	

   135 public:

   136     

   137     /**

   138      * Loads a coordinate conversion Plugin and initalises it.

   139      *

   140      * @param[in] aImplementationUid An implementation Uid of the module to be 

   141      * loaded.

   142      * @param[in] aParams Arguments sent to conversion plugin.

   143      *

   144      * @return Pointer to the new coordinate conversion plugin.

   145      */

   146     IMPORT_C static CLbsLocInfoConverterPluginBase* NewL( 

   147                                    TUid aImplementationUid,

   148                                    TLbsLocInfoConverterPluginParams& aParams );

   149                                                            

   150     /**

   151      * Destructor 

   152      */

   153     IMPORT_C virtual ~CLbsLocInfoConverterPluginBase();

   154 

   155 	/** 

   156 	 * Gets the current version of the interface implemented by a Plugin.

   157      * Derived classes should not change the implementation.

   158      *

   159      * @return Version number (currently 1.0.0) 

   160      */

   161 	IMPORT_C virtual TVersion Version() const;

   162 	

   163 	/**

   164 	 * Validates a client before a request is processed. This method is called

   165 	 * by the Location Monitor Server, everytime, before a conversion request is 

   166 	 * sent. 

   167 	 * The result of validation is indicated by the plugin by invoking the 

   168 	 * MLbsLocInfoConverterPluginObserver::OnValidationComplete callback.

   169 	 *

   170 	 * @param[in] aSecureId The secure ID of the client application/process

   171 	 * @param[in] aVendorId The vendor ID of the client application/process

   172 	 * @param{in] aRequestedInfo The requested converted information. This 

   173 	 * bit field would be checked by the plugin to determine if the specified

   174 	 * conversion can be supported for the requesting client. 

   175 	 */

   176 	IMPORT_C virtual void ValidateClient( const TSecureId& aSecureId, 

   177 	                    const TVendorId& aVendorId, 

   178 	                    const TLbsConversionOutputInfoMask aRequestedInfo) = 0;

   179 	                    

   180 	/**

   181 	 * Cancels an ongoing validation operation.

   182 	 * If there is no ongoing validation operation, the cancellation request 

   183 	 * is ignored.

   184 	 *

   185 	 * The MLbsLocInfoConverterPluginObserver::OnValidationComplete callback is

   186 	 * not invoked.

   187 	 */

   188 	IMPORT_C virtual void CancelValidateClient() = 0;

   189     

   190     /** 

   191      * Converts multiple location information.

   192      * 

   193      * Completion of the conversion is indicated by a Plugin by invoking the

   194      * MLbsLocInfoConverterPluginObserver::OnConversionComplete callback

   195      *

   196      * @param[in] aLocationInfo An array of location information for which 

   197      * corresponding position information is expected.

   198      * @param[in] aConversionPrefs Conversion preferences suggested by client

   199      * @param[in] aRequestedInfo Location information that is requested.

   200         

   201      * @leave KErrNoMemory if there is not enough memory available to perform 

   202      * the conversion.

   203      *   KErrArgument If the location info pointer is NULL.

   204      *   KErrNotSupported if the conversion type specified by aRequestedInfo is 

   205      *   not supported.

   206      *   Or any other system wide error code.

   207      */                                                       

   208     IMPORT_C virtual void ConvertLocationInfoL( 

   209                        RLbsLocationInfoArray& aLocationInfoArray,

   210                        const TLbsConversionPrefs aConversionPrefs, 

   211                        const TLbsConversionOutputInfoMask aRequestedInfo ) = 0;

   212 

   213     /** 

   214      * Cancels an ongoing conversion operation.

   215      * If there is no ongoing conversion the cancellation request is ignored.

   216      *

   217      * The MLbsLocInfoConverterPluginObserver::OnConversionComplete callback is 

   218      * not invoked.

   219      */

   220     IMPORT_C virtual void CancelConvertLocationInfo() = 0;

   221 

   222 	/** 

   223 	 * This method is reserved for future expansion and should not be used 

   224 	 * or implemented by derived classes.

   225 	 */								

   226 	IMPORT_C virtual TAny* ExtendedInterface( TInt aFunctionNumber, 

   227                                                TAny* aPtr1, 

   228                                                TAny* aPtr2 );

   229 

   230 private: // data

   231 

   232     /**

   233      * Instance identifier key. When instance of an implementation is

   234      * created by ECOM framework, the framework will assign UID

   235      * for it. The UID is used in destructor to notify framework that 

   236      * this instance is being destroyed and resources can be released.

   237      */

   238      TUid iDtor_ID_Key;

   239      

   240     };

   241 

   242 

   243 /**

   244 * This class encapsulates the construction parameters for a Coordinate 

   245 * Conversion plugin.

   246 *

   247 * These parameters are passed by the LBS subsystem to the implementation

   248 * of the Plugin module via ECom. The ECom constructor

   249 * should take a single TAny* parameter. That parameter should be cast to

   250 * a variable of type TLbsLocInfoConverterPluginParams.

   251 *

   252 * @see CLbsLocInfoConverterPluginBase::NewL

   253 */

   254 class TLbsLocInfoConverterPluginParams : public TLbsLocInfoConverterPluginClassTypeBase

   255 	{

   256 	

   257 public:

   258     

   259 	/**

   260 	 * This class encapsulates the construction parameters for a Coordinate 

   261 	 * Conversion plugin implementation.

   262      *

   263 	 * When created, the LBS subsystem must provide a reference to the 

   264 	 * plugin's observer.  

   265      *

   266 	 * @see MLbsLocInfoConverterPluginObserver

   267      * @see CLbsLocInfoConverterPluginBase::NewL

   268      */

   269     IMPORT_C TLbsLocInfoConverterPluginParams( 

   270 		MLbsLocInfoConverterPluginObserver& aObserver );

   271 

   272 	/**

   273 	 * Returns a reference to the observer.

   274      *

   275 	 * @see MLbsLocInfoConverterPluginObserver

   276 	 * @see CLbsLocInfoConverterPluginBase::NewL

   277 	 */

   278 	IMPORT_C MLbsLocInfoConverterPluginObserver& Observer() const;

   279 	

   280 protected:

   281     

   282 	/**

   283 	 *  Handle to the plugin observer

   284 	 */

   285     MLbsLocInfoConverterPluginObserver& iObserver;

   286     

   287     /**

   288      * Reserved for future use

   289      */

   290 	TUint8 iReserved[20];

   291 	

   292 	};

   293 

   294 #endif // LBS_LOC_INFO_CONVERSION_PLUGIN_BASE_H