IOCTL_GNSS_CREATE_GEOFENCE IOCTL (gnssdriver.h)

發行項
02/29/2024

GNSS 配接器會使用 IOCTL_GNSS_CREATE_GEOFENCE 控件程式代碼來建立地理柵欄。

適用於 GNSS DDI 第 2 版和更新版本。

主要程序代碼

IRP_MJ_DEVICE_CONTROL

輸入緩衝區

定義要建立之地理柵欄之GNSS_GEOFENCE_CREATE_PARAM 結構的指標。

輸入緩衝區長度

設定為sizeof (GNSS_GEOFENCE_CREATE_PARAM) 。

輸出緩衝區

GNSS_GEOFENCE_CREATE_RESPONSE 結構的指標。

輸出緩衝區長度

設定為sizeof (GNSS_GEOFENCE_CREATE_RESPONSE) 。

狀態區塊

Irp->如果要求成功，IoStatus.Status 會設定為 STATUS_SUCCESS。否則，狀態為適當的錯誤狀況為 NTSTATUS 程式碼。

備註

GNSS 配接器附註

如果呼叫成功，GNSS 引擎會註冊地理柵欄，並指派唯一標識符。 GNSS 配接器會針對此特定地理柵欄的所有驅動程式互動使用唯一標識碼。

如果呼叫失敗，GNSS 驅動程式必須確定 GNSS 引擎最後不會建立地理柵欄並開始追蹤它。失敗應該會在新增此地理柵欄之前，將 GNSS 引擎的狀態復原回先前的狀態。

GNSS 配接器不預期驅動程式會在驅動程式重新啟動時保存地理柵欄。 GNSS 配接器會在適當時間透過 GNSS_ResetGeofencesTracking 命令明確清除 GNSS 驅動程式的所有地理柵欄， (初始化、追蹤失敗後的狀態變更等 ) 。

GNSS 驅動程式注意事項

如果這是第一個地理柵欄，GNSS 驅動程式應該啟動地理柵欄追蹤、以有效率的方式繼續監視裝置目前位置的地理柵欄，並在地理柵欄遭到入侵時引發警示。如果 GNSS 引擎因訊號狀況不良或其他暫時性錯誤而無法追蹤地理柵欄 () ，則必須透過 LISTEN_GEOFENCES_TRACKINGSTATUS 事件引發錯誤狀態。

GNSS 引擎必須遵守下列地理柵欄追蹤指導方針：

裝置追蹤作業和缺口偵測必須經過優化，以考慮地理柵欄的大小和區域。如果所有條件都相同，則相較於較小的地理柵欄，較不積極追蹤較大的地理柵欄。
裝置追蹤作業必須動態優化，以考慮地理柵欄相對於目前位置的相對距離。相較於較接近的地理柵欄，所有條件都相等，較遠的地理柵欄應該較不積極地追蹤，而且當裝置更接近地理柵欄時，應該增加該條件。
缺口偵測機制必須非對稱，才能進入和結束。一般規則是，相較於決定進入地理柵欄的規則，應該放寬決定從地理柵欄結束的規則。
缺口偵測機制必須考慮到裝置位置固有不透明所造成的潛在誤判。例如，如果裝置停留在地理柵欄邊緣附近，則即使裝置並未實際移入和移出，次佳缺口偵測機制可能會產生太多進入和結束事件。非對稱結束偵測和連字元是避免這類錯誤的一般量值。
GNSS 引擎的裝置追蹤作業必須使用SoC上可用的所有可用位置變更訊號形式，或可在低電量使用。這類訊號可能包括加速計和其他感測器的數據、行動數據訊號變更、WiFi 連線/中斷連線等等。
地理柵欄追蹤和缺口偵測作業必須在SoC上的 GNSS 引擎中完全實作。 GNSS 驅動程式和應用程式處理器上的任何其他擴充元件都不應該喚醒裝置追蹤或缺口偵測。
GNSS 驅動程式和 GNSS 引擎必須公開記載的 IHV 特定微調參數，以加速地理柵欄追蹤功能的效能和電源微調。 Microsoft 和 OEM 會使用微調參數，並判斷地理柵欄體驗端對端的服務品質、可靠性和電源成本之間的正確平衡。微調參數可以透過登錄設定或 IHV SoC 組態數據來提供。