<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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 

"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: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-0B4D4675-2CFB-5964-A869-7275202AC71D"><title>Implement a subclass of CPositioner</title><shortdesc>This section describes the coding tasks necessary to implement a PSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><context><p> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita"><apiname>CPositioner</apiname></xref> is the interface between the Location Framework and a PSY. A PSY must implement a <codeph>CPositioner</codeph> subclass to handle positioning requests from the Location Framework. The Location Framework uses the PSY <codeph>CPositioner</codeph> subclass object to handle the use cases of the Positioning Plug-in API. </p> <p>The use cases of the Positioning Plug-in API are as follows: </p> <ul><li id="GUID-4933506B-31B9-5D44-BF73-C7CA95495009"><p>The Location Framework loads the PSY either directly of via a Proxy PSY. </p> </li> <li id="GUID-E1F338F7-F330-5401-9EE2-0AAF213B6D2F"><p>The Location Server sets update options on the PSY. </p> </li> <li id="GUID-2EC6EEF3-A214-5CC6-B3D5-11C456DE0171"><p>The Location Server requests a position update. </p> </li> <li id="GUID-FFA81271-B344-5815-A23B-6ED96291B15B"><p>The Location Server requests periodic position updates. </p> </li> <li id="GUID-358F91F2-6015-5DF7-B040-EF5D843285B4"><p>The Location Server cancels a location request. </p> </li> <li id="GUID-FD3CDD6D-CCE3-519B-B7F3-41467568A91B"><p>The PSY reports its status to the Location Server. </p> </li> </ul> </context> <steps id="GUID-DE141BC8-A365-5635-8EE0-DC901945B1A1"><step id="GUID-ED65A686-A47C-5E5C-AE83-1A1BAE6397D4"><cmd>Create a sub-class of CPositioner </cmd> <info>The <xref href="GUID-893737B2-4863-5BB9-8AA1-6AB5045FADC9.dita">Positioning Module API</xref> describes the classes of the API. </info> <info>A PSY must implement the two overloaded <codeph>NewL()</codeph> methods of the API to allow it to be loaded by the Location Framework or by a Proxy PSY. The two cases are described in more detail as follows: </info> <substeps id="GUID-23A99F1B-077B-5612-98A4-4351EA460CA8"><substep id="GUID-CEE0F0D6-C6C4-5D42-998D-BD6EDC2C5772"><cmd/><info>Location Framework loads the PSY </info> <info>When the Location Framework loads a PSY it instantiates an instance of the <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita"><apiname>CPositioner</apiname></xref> subclass using the <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-D9F3B20A-A6EC-366B-9457-E92B9F9B4C60"><apiname>CPositioner::NewL()</apiname></xref> method. The subclass implementation must define a <codeph>NewL</codeph> (<codeph>TAny* aConstructionParameters</codeph>) constructor. </info> <info>This constructor must call <codeph>CPositioner::BaseConstructL</codeph> (<codeph>TAny*

                     aConstructionParameters</codeph>) first after the instance has been created. The construction parameters received in <codeph>NewL()</codeph> must be forwarded to BaseConstructL(). It is not permitted to pass a NULL pointer. The pointer is used for the internal construction of the <codeph>CPositioner</codeph> instance. </info> </substep> <substep id="GUID-8C30DA5F-1E52-534C-9CBF-2E4E326CF067"><cmd/><info>A Proxy PSY loads the PSY </info> <info>A Proxy PSY (such as the Default Proxy PSY) can instantiate other PSYs. When the Proxy PSY instantiates a PSY it must use the overloaded static constructor <codeph>NewL(TUid aImplementationUid, const CPositioner&amp;

                     aPositioner)</codeph> where <codeph>aImplementationUid</codeph> is the UID of the PSY that must be constructed and the <codeph>CPositioner</codeph> parameter is the Proxy PSY instance. </info> <info>The constructor parameters for the PSY are derived from the Proxy PSY instance in this case. A Proxy PSY must not use the constructor used by the Location Framework since the construction parameters are not public. </info> <info>A PSY must also report the device status when it is loaded and unloaded. </info> </substep> </substeps> <info>The following code example shows an example PSY static constructor implementation. </info> <stepxmp><codeblock id="GUID-08683B8A-0BAC-5190-862D-A67013E0041F" xml:space="preserve">CPosExamplePositioner* CPosExamplePositioner::NewL(

    TAny* aConstructionParameters)

    {

    CPosExamplePositioner* self =

        new (ELeave) CPosExamplePositioner;

    CleanupStack::PushL(self);

    self->ConstructL(aConstructionParameters);

    CleanupStack::Pop();

    return self;

    }

void CPosExamplePositioner::ConstructL(

    TAny* aConstructionParameters)

    {

    // Must call BaseConstructL first thing during

    // construction.

    BaseConstructL(aConstructionParameters);

    }

</codeblock> </stepxmp> </step> <step id="GUID-82CD3F69-85A8-5D9D-9C38-9F4424A33B4A"><cmd>Write code to handle the Location Server setting GPS options </cmd> <info>The PSY can also be passed options for a position request. The parameters are obtained through accessor methods provided on the <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita"><apiname>CPositioner</apiname></xref> class. </info> <info>The <codeph>CPositioner</codeph> base class provides a default implementation that retrieves the options provided by the client application when it makes a location request. The PSY implementation can override these methods if required: </info> <substeps id="GUID-F357104A-BE9B-5919-8AB6-15114BF7DC17"><substep id="GUID-D91E3CAB-29D6-5CBE-912A-CBAF4A54F83C"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-F72BE40F-537B-3633-B6BF-65B694682681"><apiname>CPositioner::GetMaxAge()</apiname></xref>  </info> <info>A client application may specify a maximum age when performing a position request. This means that a position can be returned from an old measurement as long as the position is not older than the specified maximum age. Supporting maximum age is optional in a PSY. If the PSY developer wants to support the maximum age, the PSY must be implemented to cache the latest position estimate. <codeph>GetMaxAge()</codeph> is the function that the PSY implementation can use to retrieve the maximum age specified by the client. </info> </substep> <substep id="GUID-EFB2A64D-109F-5D1D-94C1-88316F12ADCA"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-53E2D165-76D4-3329-9834-B64EEC11604F"><apiname>CPositioner::IsPartialUpdateAllowed()</apiname></xref>   </info> <info>A client application may specify that it accepts incomplete location information. Incomplete location information is only required to contain the time and the PSY ID. It is not required to include latitude or longitude. For example, a GPS PSY may read NMEA sentences, which does not include a fix because the terminal is indoors. The GPS PSY could still return satellite information to the client if partial updates are allowed. The PSY can check if partial location information is accepted by the client by calling <codeph>IsPartialUpdateAllowed()</codeph>. If <codeph>ETrue</codeph> is returned, then the PSY can return an incomplete fix. </info> </substep> <substep id="GUID-AEA081B2-E438-51D5-8CE8-956BD929AE32"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-C7BB2CA5-3351-3117-B859-C3014B80653C"><apiname>CPositioner::GetRequiredPositionQuality()</apiname></xref>  </info> <info>A client application may specify a required position quality. The PSY can use the position quality if it is possible to specify the required quality of position to the positioning technology that it encapsulates. <codeph>GetRequiredPositionQuality()</codeph> returns <codeph>KErrNotFound</codeph> if no quality has been specified by the client. </info> <info> Important Note:  <codeph>

                     GetRequiredPositionQuality()</codeph> is not currently supported and always returns <codeph>KErrNotFound</codeph>. </info> </substep> </substeps> </step> <step id="GUID-83717E31-D4E4-5937-A6D0-6A8368798C8B"><cmd>Write code to handle a single location request </cmd> <info>When a client requests location information from the Location Framework, the framework forwards the request to a PSY instance. <codeph>CPositioner</codeph> provides a pure virtual method <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-03A37FAC-3129-3483-AC7F-C17A46D9F431"><apiname>CPositioner::NotifyPositionUpdate()</apiname></xref> that must be implemented by the PSY in order to handle a position request. </info> <info> <codeph>NotifyPositionUpdate()</codeph> is an asynchronous call and must be implemented in the PSY to return at once. If positioning takes time, it should be implemented using active objects, otherwise the Location Server is blocked for the time that a position fix is being obtained by the PSY. <codeph>NotifyPositionUpdate()</codeph> has a <codeph>TRequestStatus</codeph> parameter which is used to signal that the position acquisition is complete. </info> <info> <codeph>NotifyPositionUpdate</codeph> () also has a <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref> as an output parameter. This object is used to pass position information back to the client. <codeph>TPositionInfoBase</codeph> is an abstract class and the actual class hierarchy of the position information object can be obtained by calling <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita#GUID-73D6F438-C270-33B9-974B-D4D1583E1738/GUID-CD86897E-5924-3758-BD92-1D324BE4287C"><apiname>TPositionInfoBase::PositionClassType()</apiname></xref>. The PSY must cast the position information object to the actual subclass and the appropriate position information filled in. PSYs can support different sets of position information classes but <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> and <xref href="GUID-ADB30502-C84C-3027-B457-9150FA4AC510.dita"><apiname>HGenericPositionInfo</apiname></xref> are mandatory. The position information class must store data as specified by the WGS84 geodetic datum. </info> <info>The PSY must also report the data quality status while returning position information. </info> <info>This sequence diagram of figure 1 shows the steps that are involved when the Location Framework makes a request for a position update from a PSY. </info> <info><fig id="GUID-E194C421-6C62-5538-809C-DB33A454B930"><title>

                  Figure 1. Handling a request for position information. 

    TPositionInfoBase& aPosInfo,

    TRequestStatus& aStatus)

    {

    TRequestStatus *statusPtr = &aStatus;

    // NotifyPositionUpdate must return quickly. It should

    // be implemented as asynchronous but since Example PSY

    // is very fast, we fetch the position synchronously.

    // The position info object is at least a TPositionInfo

    // Hence casting it to TPositionInfo. Ideally the class type

    // should be obtained and then cast to the specified

    // position information class.

    TPositionInfo* aPosInfo =

        static_cast<TPositionInfo*>(&aPosInfo);

    TPosition pos;

    // Calculate the position and fill in the position info

    // object

    pos.SetCoordinate(65.345, 11.456);

    // set horizontal and vertical accuracy

    pos.SetAccuracy(10.0, 30.0);

    // set time of fix

    pos.SetCurrentTime();

    // Set position in position info.

    posInfo->SetPosition(pos);

    User::RequestComplete(statusPtr, KErrNone);

    } 

</codeblock> </stepxmp> </step> <step id="GUID-100F3359-EDCF-5555-A38B-B379F0A7C572"><cmd>Write code to handle periodic location requests (tracking) </cmd> <info>A client application can request periodic position updates from the Location Framework. This is known as tracking. If the client application continues to reissue position requests as soon as the last request completes then it receives periodic position updates. </info> <info>The Location Framework sends a position request to a PSY when a location update is required by a client. The PSY must be ready to give position information as soon as the Location Framework sends a request. A PSY needs to know about the requirement for periodic position requests if the underlying positioning technology needs to be kept powered in order to provide fast position updates. Conversely, a PSY can go into standby mode if it knows that it is a long time until the next request. </info> <info>To support tracking the PSY must implement the following virtual methods in <codeph>CPositioner</codeph>: </info> <substeps id="GUID-F84A38AA-F86B-5049-984D-296896BB7FAA"><substep id="GUID-65D1CB9C-B8AA-54AF-A4E0-0527F3BC0A52"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-EF23126A-7869-3113-9ED6-530BB57D66A2"><apiname>CPositioner::TrackingOverridden()</apiname></xref> must be implemented by the PSY <codeph>CPositioner</codeph> subclass to return <codeph>ETrue</codeph>. This indicates that the PSY implements specific logic to handle periodic position updates. The default implementation for <codeph>TrackingOverridden</codeph> in <codeph>CPositioner</codeph> returns <codeph>EFalse</codeph>. </info> </substep> <substep id="GUID-57D535CB-67A1-5027-92D7-4998926556E8"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-C0CCADDD-6CD8-37E9-BC7F-19ECF0F72C84"><apiname>CPositioner::StopTracking()</apiname></xref> must be overridden by the PSY <codeph>CPositioner</codeph> subclass. It is called by the Location Framework to signal that the tracking session has been closed so the PSY can put the positioning technology hardware into standby mode. The default implementation for <codeph>StopTracking() </codeph> in <codeph>CPositioner</codeph> does not perform any action. </info> <info>If a PSY implementation returns <codeph>ETrue</codeph> from <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-EF23126A-7869-3113-9ED6-530BB57D66A2"><apiname>CPositioner::TrackingOverridden()</apiname></xref> then it should provide an implementation of <codeph>StopTracking()</codeph>. </info> </substep> <substep id="GUID-EFE1E5CA-E9A4-56BE-82C1-5A2EA31BD985"><cmd/><info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-4DFC679F-F6F6-39A1-91DF-69661ABC0FA8"><apiname>CPositioner::StartTrackingL()</apiname></xref> must be overridden by the PSY <codeph>CPositioner</codeph> subclass. It is called by the Location Framework to signal that the Location Server has started a tracking session. The PSY can start the positioning technology specific device/protocol and keep it in state where position information can be obtained quickly. </info> <info>The periodicity of position updates requested by theclient application is passed as an input parameter to this method. If the PSY cannot support the periodicity, it must return fixes as frequently as possible. The default implementation for <codeph>StartTrackingL()</codeph> in <codeph>CPositioner</codeph> leaves with <codeph>KErrNotSupported</codeph>. If the PSY implementation returns <codeph>ETrue</codeph> from <codeph>TrackingOverridden</codeph> then it needs to provide an implementation of <codeph>StartTrackingL()</codeph>. </info> </substep> </substeps> <info>Figure 2 shows the steps that are involved when the Location Framework initiates a periodic position request from a PSY: </info> <info><fig id="GUID-B62DCC66-0C97-594A-A22F-EEC88E507924"><title>

                  Figure 2. Handling periodic position determination request 

                  Figure 3. Cancelling a position determination request 

    {

    // Since the Example PSY can deliver a position very

    // fast it has been implemented synchronously which

    // means that there will never be an outstanding

    // request to cancel.

    // For your specific PSY cancel any asynchronous request

    // that was made to get the position information from the

    // underlying positioning technology.

    }

</codeblock> </stepxmp> </step> <step id="GUID-E07D18D1-6ABD-55B2-B035-F5CF259D6A39"><cmd>Write code to support advanced PSY functionality </cmd> <info> <codeph>CPositioner</codeph> defines virtual functions that are required to implement advanced functionality. It provides a default implementation for these functions and the PSY can override these if it needs to implement any of the advanced PSY features: </info> <substeps id="GUID-A0D1A0CB-C7FB-500E-9F44-C45C070F069C"><substep id="GUID-87026FC2-ED9A-52E5-9E75-F63CCC4F5D91"><cmd/><info>ServiceL </info> <info>The <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> can be extended to support PSY specific method calls. This means that <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> can be sub-classed to define the new methods. The methods are implemented to pack their parameters and send them to the Location Server by calling <codeph>SendReceive()</codeph>. The Location Server forwards such requests to the <codeph>ServiceL</codeph> () method of the PSY and passes an <codeph>RMessage2</codeph> object that contains the request information. <codeph>RMessage2</codeph> is handled as in an ordinary client/server request. <codeph>ServiceL</codeph> is a virtual function and can be overridden by a PSY developer to support PSY specific method calls. This feature is reserved for future use. </info> </substep> <substep id="GUID-816390F9-835C-5907-95F4-7DF5004AB2DD"><cmd/><info>Handling parallel requests </info> <info> <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita"><apiname>CPositioner</apiname></xref> is instantiated once for each open client handle, which means that the PSY may have to handle many position requests at the same time. However, the position technology used by the PSY may not support parallel requests. This means that the positioner instances cannot work independently. The PSY needs a centralised request control. The suggested solution is to use a singleton object, i.e. an object which is instantiated when the PSY is loaded (when the first <codeph>CPositioner</codeph> object is instantiated) and which is not deleted until the PSY is unloaded (when the last <codeph>CPositioner</codeph> object is deleted). All positioner objects forward their requests to the singleton object which implements the strategy for how parallel requests should be handled. Since a PSY is a DLL, the thread local storage must be used to store the singleton. </info> </substep> <substep id="GUID-0E769C52-8887-5596-841B-34FF47C2562C"><cmd/><info> <codeph>Power management</codeph>  </info> <info>The PSY developer should consider power management. If the positioning technology draws much power, the PSY may enter the power save mode when it has not been used for a while. In such cases the PSY should use tracking (periodic position update requests) effectively and try to keep the device in standby mode when position information is not required immediately. </info> </substep> </substeps> </step> <step id="GUID-7F7A8635-ED93-54C0-8C89-238298680196"><cmd>Write code to report the PSY device status </cmd> <info>A PSY has to report its status to the Location Framework when it is being used. There are two types of status that must be reported: </info> <substeps id="GUID-81D2A032-6CB4-5A44-B80F-CC07CE2FF4A6"><substep id="GUID-6220AB06-B2DB-5E36-A02E-6CF9B160093A"><cmd/><info>The status of the device or positioning technology that is being used by the PSY for obtaining the position information. </info> </substep> <substep id="GUID-0558FCE2-B278-5117-901A-8C2413E4158F"><cmd/><info>The status about the quality of the position fix that the PSY is providing at the moment. The data quality status indicates the accuracy of the data returned by the PSY. </info> </substep> </substeps> <info>In order to report these statuses the PSY needs to use the <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-66091F9F-A685-3A47-8B15-74257B56D4DC"><apiname>CPositioner::PositionerStatus()</apiname></xref> method provided by the <codeph>CPositioner</codeph> class. This method returns an <xref href="GUID-86CB276D-F920-3115-858E-31AF13EABD30.dita"><apiname>MPositionerStatus</apiname></xref> interface through which the status can be reported by calling <xref href="GUID-86CB276D-F920-3115-858E-31AF13EABD30.dita#GUID-86CB276D-F920-3115-858E-31AF13EABD30/GUID-B65B8E39-9AD4-34EA-9961-4FED28AB9D16"><apiname>MPositionerStatus::ReportStatus()</apiname></xref>. </info> <substeps id="GUID-C1877303-E171-5F1F-AB69-97440AD638CE"><substep id="GUID-7AB82D66-BB6A-5BB0-8A6D-1D6B0F43900F"><cmd/><info>Write code to report device status </info> <info>A PSY must report the following device statuses: </info> <info><ul><li id="GUID-3B1A1EA1-494A-5C7A-AEBD-87AC96A36C24"><p>When the Location Framework loads a PSY, the PSY initializes the device providing the location information. Once the device is ready the PSY must report <codeph>EDeviceReady</codeph>. </p> </li> <li id="GUID-CF70A8B4-E567-543A-AC9D-A0AF5E47C24E"><p>When the device is used by the PSY to obtain a location fix then the PSY must report a <codeph>EDeviceActive</codeph> status. </p> </li> <li id="GUID-D6C6BC11-28E9-58ED-B7D2-A40F2CEA549C"><p>The PSY must also set the status to <codeph>EDeviceInactive</codeph> when the PSY is unloaded (i.e. when the last <codeph>CPositioner</codeph> instance is destroyed). </p> </li> </ul> </info> <info>Apart from the statuses listed above there are a few other device status which a PSY can optionally report: </info> <info><ul><li id="GUID-6A0DE1E7-9831-52FA-A31A-ED4DA418593B"><p>When the PSY is loaded and before the device is ready, the PSY can report a <codeph>EDeviceIntialising</codeph> status. </p> </li> <li id="GUID-BD098E6F-2425-5C6F-9061-618C9E72C2E8"><p>The PSY can report <codeph>EDeviceStandby</codeph> if the device has been moved to a sleep or power save mode. At this state it is assumed that the device cannot retrieve location fix immediately. </p> </li> <li id="GUID-8C0009D2-872B-564F-ABF6-4BFB3764BE0E"><p>The PSY can report a <codeph>EDeviceError</codeph> if there are some problems in using the device. </p> </li> <li id="GUID-E8B43FFD-9B02-53A9-A502-594A7607E524"><p>The PSY can report <codeph>EDeviceDisabled</codeph> if the device is unavailable to obtain position information. </p> <p>Note: The device may still be working properly hence this status is different from <codeph>EDeviceError</codeph>. </p> </li> </ul> </info> </substep> <substep id="GUID-C6B5F879-EF34-5A95-AF37-CA47B0CF7C66"><cmd/><info>Write code to report data quality status </info> <info>A PSY must report the quality of the position information that is obtained from the device. The following data quality statuses can be reported: </info> <info><ul><li id="GUID-C3981254-FA2F-570F-911F-2A66CF278767"><p>If the position fix contains all the required information then the PSY should report a <codeph>EDataQualityNormal</codeph> status. </p> </li> <li id="GUID-7C1B588C-A22E-55D1-8CDA-E7771599B95E"><p>If the position information returned by the device does not contain all the necessary fields for a position fix then it should report <codeph>EDataQualityPartial</codeph>. </p> </li> <li id="GUID-806308A3-AE13-5676-A844-FCDAFBDE6C03"><p>If the PSY is unable to obtain any position information from the device then it should report a <codeph>EDataQualityLoss status</codeph>. Note that in this case it is possible that the device is working properly but it is unable to obtain the position information. </p> </li> </ul> </info> <info>The <codeph>CPositioner</codeph> subclass is instantiated by the Location Framework for each open client session. Hence it is possible to have multiple instances of the <codeph>CPositioner</codeph> subclass implemented by the PSY, which means that the PSY may have to handle more than one position request at a time. When handling such parallel requests, the status tracking mechanism in the PSY must also be centralised and the status should be reported only through one of the <codeph>CPositioner</codeph> instances. To achieve this the PSY should report status using a singleton class. </info> </substep> </substeps> </step> <step id="GUID-F6E5F16A-E7AB-579C-9382-7F989B3707A8"><cmd>Write an ECOM factory function </cmd> <info>A PSY is an ECOM plug-in and it must follow certain rules in order to be loaded by the Location Framework. To enable loading, the PSY must define the following function at ordinal 1: </info> <stepxmp><codeblock id="GUID-1BD2AB98-6279-51E3-AB23-B7E1A251C699" xml:space="preserve">const TImplementationProxy* ImplementationGroupProxy(TInt&amp; aTableCount)</codeblock> </stepxmp> <info> <codeph>TImplementationProxy</codeph> is defined by ECOM and it contains information about the available factory functions. The PSY must set aTableCount to 1 and return <codeph>TImplementationProxy</codeph>, which points to the PSY factory function: <xref href="GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350.dita#GUID-0CA8AEC1-FF5E-3556-ACBD-0D4277CF1350/GUID-D9F3B20A-A6EC-366B-9457-E92B9F9B4C60"><apiname>CPositioner::NewL()</apiname></xref> <codeph/>in the <codeph>CPositioner</codeph> subclass. </info> <info>Providing several implementations within one PSY is not supported. </info> <info>The example PSY exports the <xref href="GUID-F23790E7-839F-30A4-89D7-1CB30AEA6489.dita#GUID-F23790E7-839F-30A4-89D7-1CB30AEA6489/GUID-A0334E06-8BF8-38C3-AC53-885D98FADDB1"><apiname>CExamplePositioner::NewL()</apiname></xref> method by providing the following code: </info> <stepxmp><codeblock id="GUID-9C38DE9A-3365-5E28-91C4-137B7BF69DCF" xml:space="preserve">// Note! UID below is implementation UID, not DLL UID.

const TImplementationProxy KFactoryPtr =

    {{KPosExamplePSYImplUid}, (TProxyNewLPtr) CPosExamplePositioner::NewL};

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(

    TInt& aTableCount)

    {

    aTableCount = 1;

    return &KFactoryPtr;

    }

</codeblock> </stepxmp> </step> </steps> <postreq><p>After implementing the code necessary to create the PSY, a device creator must package it as an ECOM plug-in that can be loaded by the LBS subsystem. </p> <p>See <xref href="GUID-2955A35E-1215-5C4A-9C24-0106FB75E295.dita">Provide ECOM registry information for a PSY</xref> for more information. </p> </postreq> </taskbody><related-links><link href="GUID-86AD79A5-E18D-56C6-997A-5E2B24FEE80D.dita"><linktext>Positioning

                Plug-in API Tutorial</linktext> </link> </related-links></task>