Symbian S60下载S60API文档

API具体说明

  1. 定位API只提供包装好的定位依据给第三方应用程序，第三方应用程序使用定位依据向定位服务器请求当前的位置。
  2. 第三方应用可以通过异步回调或同步获取的方式使用定位API。
  3. 定位API可设置一个异步回调的最小时间间隔及一个最大时间间隔(以秒计)。
    当位置发生变化时, 如果时间间隔太小, 则忽略变化；如果太长时间位置未变化也应发生一次回调。
    如果第三方应用未设置最小时间间隔或最大时间间隔，客户端API默认的时间间隔为最小时间间隔为3分钟（180s），最大时间间隔为10分钟（600s）
  4. 定位API可以设置敏感度, 以便第三方应用判断变化以及防抖。目前敏感度定义如下:

    5. 超高: 一般不建议使用超高；
    高: 希望位置敏感一点；
    中:一般应该选择中；
    低: 对位置不敏感的用低。
  5. 变化通知：根据应用设定的敏感度及时间间隔, 定位API开始采集定位依据,发生匹配敏感度设置及时间间隔的数据变化后即通知应用。
  6. GPS有默认的刷新频率，定位API自行检查GPS设备，如果开启则需要进行数据采集，在第三方应用程序请求定位依据时一并送上。
API

定位API组成

定位API针对不同的S60平台使用不同的版本，每个版本都由三个部分组成，分别为定位插件（peplocserver.sis）、定位LIB（peplocmanager.lib）及定位接口。使用定位API时，首先必须安装定位插件，然后在应用中使用定位LIB及提供的接口完成定位。

MMP文件设置

要使用定位API，必须包含peplocmanager.lib，且必须放在所有包含的lib的最前面。其余需要包含的lib包括：euser.lib，bafl.lib和estlib.lib。

MMP文件LIB部分设置如下所示：
LIBRARY peplocmanager.lib
LIBRARY euser.lib
LIBRARY bafl.lib
LIBRARY estlib.lib

定位API接口

异步回调接口
01 class MLBSNotifier
02 {
03 public:
04 virtual void NotifyCompleteL( CLBSManager& aLBSManager ) = 0;
05 virtual void HandleError( TInt aErr ) = 0;
06 };
定位依据管理类
01 class CLBSManager
02 {
03 public:
04     // 变化敏感度
05     enum TSensitivity
06     {
07         ESensitivitySuper,
08         ESensitivityHigh,
09         ESensitivityNormal,
10         ESensitivityLow
11     };
12    
13 public:
14     // 注册和移除观察者的方法
15     void RegisterNotifier( MLBSNotifier* aNotifier ); // 注册观察者
16     void RemoveNotifier( MLBSNotifier* aNotifier );   // 移除观察者
17
18    
19     // 设置变化的敏感度
20     void SetSensitivity( TSensitivity aSensitivity );
21     TSensitivity GetSensitivity() const;
22    
23     // 异步回调的最短和最长时间间隔
24     void SetMinNotifyInterval( TInt aSecond );
25     TInt GetMinNotifyInterval() const;
26     void SetMaxNotifyInterval( TInt aSecond );
27     TInt GetMaxNotifyInterval() const;
28    
29     // 开始和停止采集定位依据
       // 用户使用定位API时，应该在主程序启动时即启动定位插件，
       // 以采集连续的定位数据，获得较为理想的定位效果，并在主程序终止前才结束定位插件。
30     void Start();
31     void Stop();
32    
33     // 取得定位依据数据
34     HBufC8* GetLBSDataL() const;
35    
36     // 取得标定用户的ID
37     HBufC8* GetIdL() const;
38 };

如果使用异步回调方式，第三方应用需要继承 MLBSNotifier 类，并且在 CLBSManager中进行注册，CLBSManager会在定位依据发生变化时产生通知，第三方应用程序即可通过GetLBSDataL()方法获取最新的定位依据。如果使用同步获取方式，第三方应用程序只需初始化CLBSManager类，直接通过GetLBSDataL()方法获取定位依据。

定位API使用范例

用户使用定位API时，应该在主程序启动时即启动定位插件，以采集连续的定位数据，获得较为理想的定位效果，并在主程序终止前才结束定位插件。
MyClass.h

01 Class CMyClass : public CBase, public MLBSNotifier
02 {
03 ...
04 public:
05 virtual void NotifyCompleteL( CLBSManager& aLBSManager );
06 virtual void HandleError( TInt aErr );
07
08 private:
09     CLBSManager* iLbsManager;
10 };

MyClass.cpp

1. 初始化定位API
01 void CMyClass::ConstructL()
02 {
03 // Initialize CLBSManager
04 iLbsManager = CLBSManager::NewL();
05 iLbsManager->RegisterNotifier(this);
06 iLbsManager->SetMinNotifyInterval(180); //最小更新时间为180s
07 iLbsManager->SetMaxNotifyInterval(600); //最大更新时间为600s
08 iLbsManager->SetSensitivity(CLBSManager::ESensitivityNormal); //设置敏感度
09 iLbsManager->Start(); //开始采集数据
10
11 // Other Initialize
12 ...
13 }

2. 定位依据获取
01 void CMyClass::NotifyCompleteL(CLBSManager& aLBSManager)
02 {
03     HBufC8* lbsData = aLBSManager.GetLBSDataL(); // 获取定位依据
04 if(NULL != lbsData)
05 {
06     // use the data
07     ...
08     delete lbsData;
09     lbsData = NULL;
10 }
11 }

3. 错误处理
01 void CMyClass:: HandleError(TInt aErr)
02 {
03 switch(aErr)
04 {
05         case KErrNotFound:
06             // 定位服务找不到，需要重新安装
07             break;
08         case KErrServerTerminated:
09         case KErrDisconnected:
10             // 定位服务已终止
11             break;
12         default:
13             break;
14 }
15 }

4. 定位依据采集的终止
01 void CMyClass::Stop()
02 {
03 iLbsManager->Stop();
04 }

5. 释放定位API
01 void CMyClass::~CMyClass
02 {
3     delete iLbsManager;
04     iLbsManager = NULL;
05 }