Windows Mobile下载Windows MobileAPI文档

API具体说明

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

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

定位API组成

定位API针对不同的WM平台使用不同的版本，每个版本都由三个部分组成，分别为定位动态链接库（location.dll）、定位LIB（location.lib）及头文件LocationAPI.h。使用定位API时，可参考具体的使用示例。

接口设计

第三方接口

01 typedef void (*LOCATIONCALLBACK)(
02     int nErrCode,    // @parm 返回码,标识调用状态(不成功返回错误码)
03     unsigned char*    buffer,        // @parm 正确时缓冲数据，错误时为错误提示
04     int nLen,        // @parm buffer缓冲数据的长度
05     void *pUserData    // @parm 用户传入参数
06 );

2. 添加删除回调函数
void AddLocationCallback( LOCATIONCALLBACK pCallback, void *pUserData );
void RemoveLocationCallback( LOCATIONCALLBACK pCallback );

3. 设置获取变化的灵敏度
void SetSensitivity( ESensitivity eSensitivity );
ESensitivity GetSensitivity();

4. 设置获取回调方式下的最短最长时间间隔
void SetNotifyInterval( int nMinSecond, int nMaxSecond );
void GetNotifyInterval( int& nMinSecond, int& nMaxSecond );

5. 设置获取gps端口号，默认为com1
void SetGpsPort(int nGpsPort);
int GetGpsPort();

6. 设置获取gps波特率，默认为4800
void SetGpsBaud(int nBaud);
int GetGpsBaud();

7. 得到定位依据
int GetLocationData(unsigned char buffer[], int nBufferLen, int& nWrite);

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

回调错误码描述
ERROR_LOCATION_OK                     //定位成功，正确的数据

数据结构设计

1. 变化敏感度
01 eSensitivitySuper                    //超高
02 eSensitivityHigh                        //高
03 eSensitivityNormal                   //一般
04 eSensitivityLow                        //低

2. 回调函数结构
01 typedef void (*LOCATIONCALLBACK)(
02     int nErrCode,   // @parm 返回码,标识调用状态(不成功返回错误码)
03     unsigned char * buffer,       // @parm 正确时缓冲数据，错误时为错误提示
04     int nLen,       // @parm buffer缓冲数据的长度
05     void *pUserData    // @parm 用户传入参数
06 );

定位API使用范例

C++使用范例
使用步骤如下：
1. 定义回调函数
01 void TestCallBack(int nErrCode, unsigned char* buffer, int nLen, void* pUserData);

2. 定义CLocationAPI类型成员变量
01 //CUseLocation.h
02 class CUseLocation
03 {
04     ……
05     CLocationAPI m_locationAPI;
06 }

3. 设置属性，CLocationAPI有自己的属性默认值，如果第三方不进行设置，则直接使用默认属性值。
01 m_locationAPI.SetSensitivity( eSensitivityHigh );        //设置灵敏度为高
02 m_locationAPI.SetNotifyInterval( 300, 600 );            //设置最大最小更新时间
03 m_locationAPI.SetGpsPort(1);                    //设置GPS端口号
04 m_locationAPI.SetGpsBaud(4800);                    //设置GPS波特率

4. 添加回调函数及其参数
01 m_locationAPI.AddLocationCallback( TestCallBack, this );        //设置回调函数

5. 启动采集定位数据，应该在主程序启动后即启动。
01 m_locationAPI.Start();

6. 回调函数中处理数据
01 void TestCallBack(int nErrCode, unsigned char* buffer, int nLen, void* pUserData);
02 {
03     CUseLocation* pUseLocation = (CUseLocation*)pUserData;
04
05     switch(nErrCode)
06     {
07     case ERROR_LOCATION_OK:
08         //位置变化，buffer中存的是定位依据
09         break;
10     default:
11         break;
12     }
13 }

或者只要m_locationAPI启动了Start()方法，第三方可以在任何地方调用GetLocationData()获取定位依据。

7. 定位结束，应该在主程序终止前才停止定位插件。
m_locationAPI.Stop();

C#使用范例
1.声明接口
01 public enum ESensitivity
02     {
03         eSensitivitySuper,
04         eSensitivityHigh,
05         eSensitivityNormal,
06         eSensitivityLow
07     }
08            public delegate void LocationCallBack(int nErrCode, out string buffer, int nLen, IntPtr pUserData);
09
10         [DllImport("Location.dll")]
11         public static extern int LBS_Start();
12         [DllImport("Location.dll")]
13         public static extern void LBS_Stop();
14         [DllImport("Location.dll")]
15         public static extern void LBS_AddLocationCallback(LocationCallBack pCallback, IntPtr pUserData);
16         [DllImport("Location.dll")]
17         public static extern void LBS_RemoveLocationCallback(LocationCallBack pCallback);
18         [DllImport("Location.dll")]
19         public static extern void LBS_SetSensitivity(ESensitivity eSensitivity);
20         [DllImport("Location.dll")]
21         public static extern ESensitivity LBS_GetSensitivity();
22         [DllImport("Location.dll")]
23         public static extern void LBS_SetNotifyInterval(int nMinSecond, int nMaxSecond);
24         [DllImport("Location.dll")]
25         public static extern void LBS_GetNotifyInterval(out int nMinSecond, out int nMaxSecond);
26         [DllImport("Location.dll")]
27         public static extern void LBS_SetGpsPort(int nGpsPort);
28         [DllImport("Location.dll")]
29         public static extern int LBS_GetGpsPort();
30         [DllImport("Location.dll")]
31         public static extern void LBS_SetGpsBaud(int nBaud);
32         [DllImport("Location.dll")]
33         public static extern int LBS_GetGpsBaud();
34         [DllImport("Location.dll")]
35 public static extern int LBS_GetLocationData( ref byte buffer, int nBufferLen, out int nWrite);
2.使用步骤如下：（具体说明详见4.1） 1) 设置属性
LBS_SetSensitivity (eSensitivityNormal);
LBS_SetNotifyInterval ( 180, 600);
2) 启动采集定位数据
LBS_Start();
3) 获取数据，定期调用该函数
LBS_GetLocationData( ref str[0], 10240, out nWrite);
4) 定位结束
LBS_Stop();