1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/*
17 * @addtogroup HdiGnss
18 * @{
19 *
20 * @brief Provides unified APIs for GNSS services to access GNSS drivers.
21 *
22 * A GNSS service can obtain a GNSS driver object or agent and then call APIs provided by this object or agent to
23 * access GNSS devices, thereby Start the GNSS chip, start the navigation,
24 * set the GNSS working mode, inject reference information, obtain the positioning result, obtain the nmea,
25 * obtain the satellite status information, and obtain the cache location information.
26 *
27 * @since 5.0
28 */
29
30/*
31 * @file IGnssInterface.idl
32 *
33 * @brief Declares the APIs provided by the GNSS module for Start the GNSS chip, start the navigation,
34 * set the GNSS working mode, inject reference information, Delete auxiliary data, inject PGNSS data,
35 * obtain the number of GNSS cache locations, and obtain all cache locations.
36 *
37 * @since 5.0
38 * @version 2.0
39 */
40
41package ohos.hdi.location.gnss.v2_0;
42
43import ohos.hdi.location.gnss.v2_0.IGnssCallback;
44import ohos.hdi.location.gnss.v2_0.GnssTypes;
45import ohos.hdi.location.gnss.v2_0.IGnssMeasurementCallback;
46
47/*
48 * @brief Defines the functions for performing basic operations on GNSS.
49 *
50 * The functions include  Start the GNSS chip, start the navigation,
51 * set the GNSS working mode, inject reference information, Delete auxiliary data, inject PGNSS data,
52 * obtain the number of GNSS cache locations, and obtain all cache locations.
53 *
54 * @since 5.0
55 */
56interface IGnssInterface {
57    /*
58     * @brief Setting GNSS configuration parameters.
59     *
60     * @param para Indicates GNSS configuration parameters, including basic GNSS parameters and GNSS cache
61     * function configuration parameters. For details, see {@link GnssConfigPara}.
62     * @return Returns <b>0</b> If the setting is successful; returns a negative value otherwise.
63     *
64     * @since 5.0
65     * @version 2.0
66     */
67    SetGnssConfigPara([in] struct GnssConfigPara para);
68
69    /*
70     * @brief Enable the GNSS module and transmit the callback of the upper layer to the GNSS module.
71     *
72     * @param callback Indicates Callback function sent by the upper layer to the GNSS driver. The GNSS driver returns
73     * location results and satellite status information by the callbacks. For details, see {@link IGnssCallback}.
74     * @return Returns <b>0</b> if the GNSS is successfully enabled; returns a negative value otherwise.
75     *
76     * @since 5.0
77     * @version 2.0
78     */
79    EnableGnss([in] IGnssCallback callbackObj);
80
81    /*
82     * @brief Disable the GNSS module.
83     *
84     * @return Returns <b>0</b> if the GNSS is successfully disabled; returns a negative value otherwise.
85     *
86     * @since 5.0
87     * @version 2.0
88     */
89    DisableGnss();
90
91    /*
92     * @brief Start the navigation function.
93     *
94     * @param type Indicates the GNSS startup type, which is used to distinguish between common GNSS positioning
95     * and GNSS caching function. For details, see {@link GnssStartType}.
96     * @return Returns <b>0</b> if the GNSS navigation is successfully started; returns a negative value otherwise.
97     *
98     * @since 5.0
99     * @version 2.0
100     */
101    StartGnss([in] enum GnssStartType type);
102
103    /*
104     * @brief Stop the navigation function.
105     *
106     * @param type Indicates the GNSS startup type, which is used to distinguish between common GNSS positioning
107     * and GNSS caching function. For details, see {@link GnssStartType}.
108     * @return Returns <b>0</b> if the GNSS navigation is successfully stopped; returns a negative value otherwise.
109     *
110     * @since 5.0
111     * @version 2.0
112     */
113    StopGnss([in] enum GnssStartType type);
114
115    /*
116     * @brief Inject reference information to the GNSS module.
117     *
118     * @param refInfo Indicates the GNSS reference information structure, including the reference time and reference
119     * location. For details, see {@link GnssRefInfo}.
120     * @return Returns <b>0</b> if ingestion succeeded; returns a negative value otherwise.
121     *
122     * @since 5.0
123     * @version 2.0
124     */
125    SetGnssReferenceInfo([in] struct GnssRefInfo refInfo);
126
127    /*
128     * @brief Delete the specified auxiliary data.
129     *
130     * @param data Indicates the type of auxiliary data to be deleted. For details, see {@link GnssAuxiliaryDataType}.
131     * @return Returns <b>0</b> if deleted successfully; returns a negative value otherwise.
132     *
133     * @since 5.0
134     * @version 2.0
135     */
136    DeleteAuxiliaryData([in] unsigned short data);
137
138    /*
139     * @brief Ingesting Predict Gnss Data.
140     *
141     * @param data Indicates Predict Gnss Data.
142     * @return Returns <b>0</b> if ingesting successfully; returns a negative value otherwise.
143     *
144     * @since 5.0
145     * @version 2.0
146     */
147    SetPredictGnssData([in] String data);
148
149    /*
150     * @brief Obtain the number of locations that can be cached by the GNSS module.
151     *
152     * @param size Indicates an output parameter used to receive the number of locations that can be
153     * cached by the GNSS module.
154     * @return Returns <b>0</b> if obtain size successfully; returns a negative value otherwise.
155     *
156     * @since 5.0
157     * @version 2.0
158     */
159    GetCachedGnssLocationsSize([out] int size);
160
161    /*
162     * @brief Request to obtain all the location information in the GNSS cache at a time and clear the cache buffer.
163     * The cache location is reported through callback.
164     *
165     * @return Returns <b>0</b> if sending request successfully; returns a negative value otherwise.
166     * @since 5.0
167     * @version 2.0
168     */
169    GetCachedGnssLocations();
170
171    /*
172     * @brief Send NI user response command.
173     *
174     * @param gnssNiNotificationId Indicates the id of GNSS NI notifications.
175     * @param userResponse Indicates user reponse command.
176     * @return Returns <b>0</b> if sending response successfully; returns a negative value otherwise.
177     *
178     * @since 5.0
179     * @version 2.0
180     */
181    SendNiUserResponse([in] int gnssNiNotificationId, [in] enum GnssNiResponseCmd userResponse);
182
183    /*
184     * @brief Send network initiated message.
185     *
186     * @param msg Indicates the network initiated message.
187     * @param length Indicates length of network initiated message.
188     * @return Returns <b>0</b> if sending message successfully; returns a negative value otherwise.
189     *
190     * @since 5.0
191     * @version 2.0
192     */
193    SendNetworkInitiatedMsg([in] String msg, [in] int length);
194
195    /*
196     * @brief Enable GNSS measurement and listen to measurement information.
197     *
198     * @param callbackObj Indicates callback for reporting GNSS Measurement information.
199     * For details, see {@link IGnssMeasurementCallback}.
200     * @return Returns <b>0</b> if the GNSS Measurement is successfully enabled; returns a negative value otherwise.
201     *
202     * @since 5.0
203     * @version 1.0
204     */
205    EnableGnssMeasurement([in] IGnssMeasurementCallback callbackObj);
206
207    /*
208     * @brief Disable GNSS measurement reporting.
209     *
210     * @return Returns <b>0</b> if the GNSS Measurement is successfully disabled; returns a negative value otherwise.
211     *
212     * @since 5.0
213     * @version 1.0
214     */
215    DisableGnssMeasurement();
216}
217/** @} */