2 * Copyright (C) 2010 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef ANDROID_INCLUDE_HARDWARE_GPS_H
18 #define ANDROID_INCLUDE_HARDWARE_GPS_H
21 #include <sys/cdefs.h>
22 #include <sys/types.h>
25 #include <hardware/hardware.h>
30 * The id of this module
32 #define GPS_HARDWARE_MODULE_ID "gps"
35 /** Milliseconds since January 1, 1970 */
36 typedef int64_t GpsUtcTime
;
38 /** Maximum number of SVs for gps_sv_status_callback(). */
39 #define GPS_MAX_SVS 32
41 /** Requested operational mode for GPS operation. */
42 typedef uint32_t GpsPositionMode
;
43 // IMPORTANT: Note that the following values must match
44 // constants in GpsLocationProvider.java.
45 /** Mode for running GPS standalone (no assistance). */
46 #define GPS_POSITION_MODE_STANDALONE 0
47 /** AGPS MS-Based mode. */
48 #define GPS_POSITION_MODE_MS_BASED 1
49 /** AGPS MS-Assisted mode. */
50 #define GPS_POSITION_MODE_MS_ASSISTED 2
52 /** Requested recurrence mode for GPS operation. */
53 typedef uint32_t GpsPositionRecurrence
;
54 // IMPORTANT: Note that the following values must match
55 // constants in GpsLocationProvider.java.
56 /** Receive GPS fixes on a recurring basis at a specified period. */
57 #define GPS_POSITION_RECURRENCE_PERIODIC 0
58 /** Request a single shot GPS fix. */
59 #define GPS_POSITION_RECURRENCE_SINGLE 1
61 /** GPS status event values. */
62 typedef uint16_t GpsStatusValue
;
63 // IMPORTANT: Note that the following values must match
64 // constants in GpsLocationProvider.java.
65 /** GPS status unknown. */
66 #define GPS_STATUS_NONE 0
67 /** GPS has begun navigating. */
68 #define GPS_STATUS_SESSION_BEGIN 1
69 /** GPS has stopped navigating. */
70 #define GPS_STATUS_SESSION_END 2
71 /** GPS has powered on but is not navigating. */
72 #define GPS_STATUS_ENGINE_ON 3
73 /** GPS is powered off. */
74 #define GPS_STATUS_ENGINE_OFF 4
76 /** Flags to indicate which values are valid in a GpsLocation. */
77 typedef uint16_t GpsLocationFlags
;
78 // IMPORTANT: Note that the following values must match
79 // constants in GpsLocationProvider.java.
80 /** GpsLocation has valid latitude and longitude. */
81 #define GPS_LOCATION_HAS_LAT_LONG 0x0001
82 /** GpsLocation has valid altitude. */
83 #define GPS_LOCATION_HAS_ALTITUDE 0x0002
84 /** GpsLocation has valid speed. */
85 #define GPS_LOCATION_HAS_SPEED 0x0004
86 /** GpsLocation has valid bearing. */
87 #define GPS_LOCATION_HAS_BEARING 0x0008
88 /** GpsLocation has valid accuracy. */
89 #define GPS_LOCATION_HAS_ACCURACY 0x0010
91 /** Flags for the gps_set_capabilities callback. */
93 /** GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode.
94 If this is not set, then the framework will use 1000ms for min_interval
95 and will start and call start() and stop() to schedule the GPS.
97 #define GPS_CAPABILITY_SCHEDULING 0x0000001
98 /** GPS supports MS-Based AGPS mode */
99 #define GPS_CAPABILITY_MSB 0x0000002
100 /** GPS supports MS-Assisted AGPS mode */
101 #define GPS_CAPABILITY_MSA 0x0000004
102 /** GPS supports single-shot fixes */
103 #define GPS_CAPABILITY_SINGLE_SHOT 0x0000008
104 /** GPS supports on demand time injection */
105 #define GPS_CAPABILITY_ON_DEMAND_TIME 0x0000010
107 /** Flags used to specify which aiding data to delete
108 when calling delete_aiding_data(). */
109 typedef uint16_t GpsAidingData
;
110 // IMPORTANT: Note that the following values must match
111 // constants in GpsLocationProvider.java.
112 #define GPS_DELETE_EPHEMERIS 0x0001
113 #define GPS_DELETE_ALMANAC 0x0002
114 #define GPS_DELETE_POSITION 0x0004
115 #define GPS_DELETE_TIME 0x0008
116 #define GPS_DELETE_IONO 0x0010
117 #define GPS_DELETE_UTC 0x0020
118 #define GPS_DELETE_HEALTH 0x0040
119 #define GPS_DELETE_SVDIR 0x0080
120 #define GPS_DELETE_SVSTEER 0x0100
121 #define GPS_DELETE_SADATA 0x0200
122 #define GPS_DELETE_RTI 0x0400
123 #define GPS_DELETE_CELLDB_INFO 0x8000
124 #define GPS_DELETE_ALL 0xFFFF
127 typedef uint16_t AGpsType
;
128 #define AGPS_TYPE_SUPL 1
129 #define AGPS_TYPE_C2K 2
131 typedef uint16_t AGpsSetIDType
;
132 #define AGPS_SETID_TYPE_NONE 0
133 #define AGPS_SETID_TYPE_IMSI 1
134 #define AGPS_SETID_TYPE_MSISDN 2
137 * String length constants
139 #define GPS_NI_SHORT_STRING_MAXLEN 256
140 #define GPS_NI_LONG_STRING_MAXLEN 2048
143 * GpsNiType constants
145 typedef uint32_t GpsNiType
;
146 #define GPS_NI_TYPE_VOICE 1
147 #define GPS_NI_TYPE_UMTS_SUPL 2
148 #define GPS_NI_TYPE_UMTS_CTRL_PLANE 3
151 * GpsNiNotifyFlags constants
153 typedef uint32_t GpsNiNotifyFlags
;
154 /** NI requires notification */
155 #define GPS_NI_NEED_NOTIFY 0x0001
156 /** NI requires verification */
157 #define GPS_NI_NEED_VERIFY 0x0002
158 /** NI requires privacy override, no notification/minimal trace */
159 #define GPS_NI_PRIVACY_OVERRIDE 0x0004
162 * GPS NI responses, used to define the response in
165 typedef int GpsUserResponseType
;
166 #define GPS_NI_RESPONSE_ACCEPT 1
167 #define GPS_NI_RESPONSE_DENY 2
168 #define GPS_NI_RESPONSE_NORESP 3
171 * NI data encoding scheme
173 typedef int GpsNiEncodingType
;
174 #define GPS_ENC_NONE 0
175 #define GPS_ENC_SUPL_GSM_DEFAULT 1
176 #define GPS_ENC_SUPL_UTF8 2
177 #define GPS_ENC_SUPL_UCS2 3
178 #define GPS_ENC_UNKNOWN -1
180 /** AGPS status event values. */
181 typedef uint16_t AGpsStatusValue
;
182 /** GPS requests data connection for AGPS. */
183 #define GPS_REQUEST_AGPS_DATA_CONN 1
184 /** GPS releases the AGPS data connection. */
185 #define GPS_RELEASE_AGPS_DATA_CONN 2
186 /** AGPS data connection initiated */
187 #define GPS_AGPS_DATA_CONNECTED 3
188 /** AGPS data connection completed */
189 #define GPS_AGPS_DATA_CONN_DONE 4
190 /** AGPS data connection failed */
191 #define GPS_AGPS_DATA_CONN_FAILED 5
193 #define AGPS_REF_LOCATION_TYPE_GSM_CELLID 1
194 #define AGPS_REF_LOCATION_TYPE_UMTS_CELLID 2
195 #define AGPS_REG_LOCATION_TYPE_MAC 3
197 /** Network types for update_network_state "type" parameter */
198 #define AGPS_RIL_NETWORK_TYPE_MOBILE 0
199 #define AGPS_RIL_NETWORK_TYPE_WIFI 1
200 #define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS 2
201 #define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL 3
202 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN 4
203 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI 5
204 #define AGPS_RIL_NETWORK_TTYPE_WIMAX 6
207 * Name for the GPS XTRA interface.
209 #define GPS_XTRA_INTERFACE "gps-xtra"
212 * Name for the GPS DEBUG interface.
214 #define GPS_DEBUG_INTERFACE "gps-debug"
217 * Name for the AGPS interface.
219 #define AGPS_INTERFACE "agps"
222 * Name for NI interface
224 #define GPS_NI_INTERFACE "gps-ni"
227 * Name for the AGPS-RIL interface.
229 #define AGPS_RIL_INTERFACE "agps_ril"
231 /** Represents a location. */
233 /** set to sizeof(GpsLocation) */
235 /** Contains GpsLocationFlags bits. */
237 /** Represents latitude in degrees. */
239 /** Represents longitude in degrees. */
241 /** Represents altitude in meters above the WGS 84 reference
244 /** Represents speed in meters per second. */
246 /** Represents heading in degrees. */
248 /** Represents expected accuracy in meters. */
250 /** Timestamp for the location fix. */
251 GpsUtcTime timestamp
;
254 /** Represents the status. */
256 /** set to sizeof(GpsStatus) */
258 GpsStatusValue status
;
261 /** Represents SV information. */
263 /** set to sizeof(GpsSvInfo) */
265 /** Pseudo-random number for the SV. */
267 /** Signal to noise ratio. */
269 /** Elevation of SV in degrees. */
271 /** Azimuth of SV in degrees. */
275 /** Represents SV status. */
277 /** set to sizeof(GpsSvStatus) */
280 /** Number of SVs currently visible. */
283 /** Contains an array of SV information. */
284 GpsSvInfo sv_list
[GPS_MAX_SVS
];
286 /** Represents a bit mask indicating which SVs
287 * have ephemeris data.
289 uint32_t ephemeris_mask
;
291 /** Represents a bit mask indicating which SVs
294 uint32_t almanac_mask
;
297 * Represents a bit mask indicating which SVs
298 * were used for computing the most recent position fix.
300 uint32_t used_in_fix_mask
;
304 /* In 3G lac is discarded */
311 } AGpsRefLocationCellID
;
315 } AGpsRefLocationMac
;
317 /** Represents ref locations */
321 AGpsRefLocationCellID cellID
;
322 AGpsRefLocationMac mac
;
326 /** Callback with location information.
327 * Can only be called from a thread created by create_thread_cb.
329 typedef void (* gps_location_callback
)(GpsLocation
* location
);
331 /** Callback with status information.
332 * Can only be called from a thread created by create_thread_cb.
334 typedef void (* gps_status_callback
)(GpsStatus
* status
);
336 /** Callback with SV status information.
337 * Can only be called from a thread created by create_thread_cb.
339 typedef void (* gps_sv_status_callback
)(GpsSvStatus
* sv_info
);
341 /** Callback for reporting NMEA sentences.
342 * Can only be called from a thread created by create_thread_cb.
344 typedef void (* gps_nmea_callback
)(GpsUtcTime timestamp
, const char* nmea
, int length
);
346 /** Callback to inform framework of the GPS engine's capabilities.
347 * Capability parameter is a bit field of GPS_CAPABILITY_* flags.
349 typedef void (* gps_set_capabilities
)(uint32_t capabilities
);
351 /** Callback utility for acquiring the GPS wakelock.
352 * This can be used to prevent the CPU from suspending while handling GPS events.
354 typedef void (* gps_acquire_wakelock
)();
356 /** Callback utility for releasing the GPS wakelock. */
357 typedef void (* gps_release_wakelock
)();
359 /** Callback for requesting NTP time */
360 typedef void (* gps_request_utc_time
)();
362 /** Callback for creating a thread that can call into the Java framework code.
363 * This must be used to create any threads that report events up to the framework.
365 typedef pthread_t (* gps_create_thread
)(const char* name
, void (*start
)(void *), void* arg
);
367 /** GPS callback structure. */
369 /** set to sizeof(GpsCallbacks) */
371 gps_location_callback location_cb
;
372 gps_status_callback status_cb
;
373 gps_sv_status_callback sv_status_cb
;
374 gps_nmea_callback nmea_cb
;
375 gps_set_capabilities set_capabilities_cb
;
376 gps_acquire_wakelock acquire_wakelock_cb
;
377 gps_release_wakelock release_wakelock_cb
;
378 gps_create_thread create_thread_cb
;
379 gps_request_utc_time request_utc_time_cb
;
383 /** Represents the standard GPS interface. */
385 /** set to sizeof(GpsInterface) */
388 * Opens the interface and provides the callback routines
389 * to the implemenation of this interface.
391 int (*init
)( GpsCallbacks
* callbacks
);
393 /** Starts navigating. */
394 int (*start
)( void );
396 /** Stops navigating. */
399 /** Closes the interface. */
400 void (*cleanup
)( void );
402 /** Injects the current time. */
403 int (*inject_time
)(GpsUtcTime time
, int64_t timeReference
,
406 /** Injects current location from another location provider
407 * (typically cell ID).
408 * latitude and longitude are measured in degrees
409 * expected accuracy is measured in meters
411 int (*inject_location
)(double latitude
, double longitude
, float accuracy
);
414 * Specifies that the next call to start will not use the
415 * information defined in the flags. GPS_DELETE_ALL is passed for
418 void (*delete_aiding_data
)(GpsAidingData flags
);
421 * min_interval represents the time between fixes in milliseconds.
422 * preferred_accuracy represents the requested fix accuracy in meters.
423 * preferred_time represents the requested time to first fix in milliseconds.
425 int (*set_position_mode
)(GpsPositionMode mode
, GpsPositionRecurrence recurrence
,
426 uint32_t min_interval
, uint32_t preferred_accuracy
, uint32_t preferred_time
);
428 /** Get a pointer to extension information. */
429 const void* (*get_extension
)(const char* name
);
432 /** Callback to request the client to download XTRA data.
433 * The client should download XTRA data and inject it by calling inject_xtra_data().
434 * Can only be called from a thread created by create_thread_cb.
436 typedef void (* gps_xtra_download_request
)();
438 /** Callback structure for the XTRA interface. */
440 gps_xtra_download_request download_request_cb
;
441 gps_create_thread create_thread_cb
;
444 /** Extended interface for XTRA support. */
446 /** set to sizeof(GpsXtraInterface) */
449 * Opens the XTRA interface and provides the callback routines
450 * to the implemenation of this interface.
452 int (*init
)( GpsXtraCallbacks
* callbacks
);
453 /** Injects XTRA data into the GPS. */
454 int (*inject_xtra_data
)( char* data
, int length
);
457 /** Extended interface for DEBUG support. */
459 /** set to sizeof(GpsDebugInterface) */
463 * This function should return any information that the native
464 * implementation wishes to include in a bugreport.
466 size_t (*get_internal_state
)(char* buffer
, size_t bufferSize
);
469 /** Represents the status of AGPS. */
471 /** set to sizeof(AGpsStatus) */
475 AGpsStatusValue status
;
479 /** Callback with AGPS status information.
480 * Can only be called from a thread created by create_thread_cb.
482 typedef void (* agps_status_callback
)(AGpsStatus
* status
);
484 /** Callback structure for the AGPS interface. */
486 agps_status_callback status_cb
;
487 gps_create_thread create_thread_cb
;
491 /** Extended interface for AGPS support. */
493 /** set to sizeof(AGpsInterface) */
497 * Opens the AGPS interface and provides the callback routines
498 * to the implemenation of this interface.
500 void (*init
)( AGpsCallbacks
* callbacks
);
502 * Notifies that a data connection is available and sets
503 * the name of the APN to be used for SUPL.
505 int (*data_conn_open
)( const char* apn
);
507 * Notifies that the AGPS data connection has been closed.
509 int (*data_conn_closed
)();
511 * Notifies that a data connection is not available for AGPS.
513 int (*data_conn_failed
)();
515 * Sets the hostname and port for the AGPS server.
517 int (*set_server
)( AGpsType type
, const char* hostname
, int port
);
521 /** Represents an NI request */
523 /** set to sizeof(GpsNiNotification) */
527 * An ID generated by HAL to associate NI notifications and UI
533 * An NI type used to distinguish different categories of NI
534 * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ...
539 * Notification/verification options, combinations of GpsNiNotifyFlags constants
541 GpsNiNotifyFlags notify_flags
;
544 * Timeout period to wait for user response.
545 * Set to 0 for no time out limit.
550 * Default response when time out.
552 GpsUserResponseType default_response
;
557 char requestor_id
[GPS_NI_SHORT_STRING_MAXLEN
];
560 * Notification message. It can also be used to store client_id in some cases
562 char text
[GPS_NI_LONG_STRING_MAXLEN
];
565 * Client name decoding scheme
567 GpsNiEncodingType requestor_id_encoding
;
570 * Client name decoding scheme
572 GpsNiEncodingType text_encoding
;
575 * A pointer to extra data. Format:
579 char extras
[GPS_NI_LONG_STRING_MAXLEN
];
583 /** Callback with NI notification.
584 * Can only be called from a thread created by create_thread_cb.
586 typedef void (*gps_ni_notify_callback
)(GpsNiNotification
*notification
);
588 /** GPS NI callback structure. */
592 * Sends the notification request from HAL to GPSLocationProvider.
594 gps_ni_notify_callback notify_cb
;
595 gps_create_thread create_thread_cb
;
599 * Extended interface for Network-initiated (NI) support.
603 /** set to sizeof(GpsNiInterface) */
606 /** Registers the callbacks for HAL to use. */
607 void (*init
) (GpsNiCallbacks
*callbacks
);
609 /** Sends a response to HAL. */
610 void (*respond
) (int notif_id
, GpsUserResponseType user_response
);
613 struct gps_device_t
{
614 struct hw_device_t common
;
617 * Set the provided lights to the provided values.
619 * Returns: 0 on succes, error code on failure.
621 const GpsInterface
* (*get_gps_interface
)(struct gps_device_t
* dev
);
624 #define AGPS_RIL_REQUEST_SETID_IMSI (1<<0L)
625 #define AGPS_RIL_REQUEST_SETID_MSISDN (1<<1L)
627 #define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L)
628 #define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L)
630 typedef void (*agps_ril_request_set_id
)(uint32_t flags
);
631 typedef void (*agps_ril_request_ref_loc
)(uint32_t flags
);
634 agps_ril_request_set_id request_setid
;
635 agps_ril_request_ref_loc request_refloc
;
636 gps_create_thread create_thread_cb
;
639 /** Extended interface for AGPS_RIL support. */
641 /** set to sizeof(AGpsRilInterface) */
644 * Opens the AGPS interface and provides the callback routines
645 * to the implemenation of this interface.
647 void (*init
)( AGpsRilCallbacks
* callbacks
);
650 * Sets the reference location.
652 void (*set_ref_location
) (const AGpsRefLocation
*agps_reflocation
, size_t sz_struct
);
656 void (*set_set_id
) (AGpsSetIDType type
, const char* setid
);
659 * Send network initiated message.
661 void (*ni_message
) (uint8_t *msg
, size_t len
);
664 * Notify GPS of network status changes.
665 * These parameters match values in the android.net.NetworkInfo class.
667 void (*update_network_state
) (int connected
, int type
, int roaming
, const char* extra_info
);
670 * Notify GPS of network status changes.
671 * These parameters match values in the android.net.NetworkInfo class.
673 void (*update_network_availability
) (int avaiable
, const char* apn
);
678 #endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */