Debian Codegraph @

src/libqmi-glib/qmi-client.h

raw
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * libqmi-glib -- GLib/GIO based library to control QMI devices
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301 USA.
19 *
20 * Copyright (C) 2012-2017 Aleksander Morgado <[email protected]>
21 */
22
23 #ifndef _LIBQMI_GLIB_QMI_CLIENT_H_
24 #define _LIBQMI_GLIB_QMI_CLIENT_H_
25
26 #if !defined (__LIBQMI_GLIB_H_INSIDE__) && !defined (LIBQMI_GLIB_COMPILATION)
27 #error "Only <libqmi-glib.h> can be included directly."
28 #endif
29
30 #include <glib-object.h>
31
32 #include "qmi-enums.h"
33 #include "qmi-message.h"
34
35 G_BEGIN_DECLS
36
37 /**
38 * SECTION:qmi-client
39 * @title: QmiClient
40 * @short_description: Generic QMI client handling routines
41 *
42 * #QmiClient is a generic type representing a QMI client for any kind of
43 * #QmiService.
44 *
45 * These objects are created by a #QmiDevice with qmi_device_allocate_client(),
46 * and before completely disposing them qmi_device_release_client() needs to be
47 * called in order to release the unique client ID reserved.
48 */
49
50 /**
51 * QMI_CID_NONE:
52 *
53 * A symbol specifying a special CID value that references no CID.
54 *
55 * Since: 1.0
56 */
57 #define QMI_CID_NONE 0x00
58
59 /**
60 * QMI_CID_BROADCAST:
61 *
62 * A symbol specifying the broadcast CID.
63 *
64 * Since: 1.0
65 */
66 #define QMI_CID_BROADCAST 0xFF
67
68 #define QMI_TYPE_CLIENT (qmi_client_get_type ())
69 #define QMI_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), QMI_TYPE_CLIENT, QmiClient))
70 #define QMI_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), QMI_TYPE_CLIENT, QmiClientClass))
71 #define QMI_IS_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), QMI_TYPE_CLIENT))
72 #define QMI_IS_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), QMI_TYPE_CLIENT))
73 #define QMI_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), QMI_TYPE_CLIENT, QmiClientClass))
74
75 typedef struct _QmiClient QmiClient;
76 typedef struct _QmiClientClass QmiClientClass;
77 typedef struct _QmiClientPrivate QmiClientPrivate;
78
79 /**
80 * QMI_CLIENT_DEVICE:
81 *
82 * Symbol defining the #QmiClient:client-device property.
83 *
84 * Since: 1.0
85 */
86 #define QMI_CLIENT_DEVICE "client-device"
87
88 /**
89 * QMI_CLIENT_SERVICE:
90 *
91 * Symbol defining the #QmiClient:client-service property.
92 *
93 * Since: 1.0
94 */
95 #define QMI_CLIENT_SERVICE "client-service"
96
97 /**
98 * QMI_CLIENT_CID:
99 *
100 * Symbol defining the #QmiClient:client-cid property.
101 *
102 * Since: 1.0
103 */
104 #define QMI_CLIENT_CID "client-cid"
105
106 /**
107 * QMI_CLIENT_VERSION_MAJOR:
108 *
109 * Symbol defining the #QmiClient:client-version-major property.
110 *
111 * Since: 1.0
112 */
113 #define QMI_CLIENT_VERSION_MAJOR "client-version-major"
114
115 /**
116 * QMI_CLIENT_VERSION_MINOR:
117 *
118 * Symbol defining the #QmiClient:client-version-minor property.
119 *
120 * Since: 1.0
121 */
122 #define QMI_CLIENT_VERSION_MINOR "client-version-minor"
123
124 /**
125 * QMI_CLIENT_VALID:
126 *
127 * Symbol defining the #QmiClient:client-valid property.
128 *
129 * Since: 1.20
130 */
131 #define QMI_CLIENT_VALID "client-valid"
132
133 /**
134 * QmiClient:
135 *
136 * The #QmiClient structure contains private data and should only be accessed
137 * using the provided API.
138 *
139 * Since: 1.0
140 */
141 struct _QmiClient {
142 /*< private >*/
143 GObject parent;
144 QmiClientPrivate *priv;
145 };
146
147 struct _QmiClientClass {
148 /*< private >*/
149 GObjectClass parent;
150
151 /* Virtual method to get indications processed */
152 void (* process_indication) (QmiClient *self,
153 QmiMessage *message);
154 };
155
156 GType qmi_client_get_type (void);
157 G_DEFINE_AUTOPTR_CLEANUP_FUNC (QmiClient, g_object_unref)
158
159 /**
160 * qmi_client_get_device:
161 * @self: a #QmiClient
162 *
163 * Get the #QmiDevice associated with this #QmiClient.
164 *
165 * Returns: (transfer full): a #GObject that must be freed with g_object_unref().
166 *
167 * Since: 1.0
168 */
169 GObject *qmi_client_get_device (QmiClient *self);
170
171 /**
172 * qmi_client_peek_device:
173 * @self: a #QmiClient.
174 *
175 * Get the #QmiDevice associated with this #QmiClient, without increasing the reference count
176 * on the returned object.
177 *
178 * Returns: (transfer none): a #GObject. Do not free the returned object, it is owned by @self.
179 *
180 * Since: 1.0
181 */
182 GObject *qmi_client_peek_device (QmiClient *self);
183
184 /**
185 * qmi_client_get_service:
186 * @self: A #QmiClient
187 *
188 * Get the service being used by this #QmiClient.
189 *
190 * Returns: a #QmiService.
191 *
192 * Since: 1.0
193 */
194 QmiService qmi_client_get_service (QmiClient *self);
195
196 /**
197 * qmi_client_get_cid:
198 * @self: A #QmiClient
199 *
200 * Get the client ID of this #QmiClient.
201 *
202 * Returns: the client ID.
203 *
204 * Since: 1.0
205 */
206 guint8 qmi_client_get_cid (QmiClient *self);
207
208 /**
209 * qmi_client_is_valid:
210 * @self: a #QmiClient.
211 *
212 * Checks whether #QmiClient is a valid and usable client.
213 *
214 * The client is marked as invalid as soon as the client id is released or when
215 * the associated #QmiDevice is closed.
216 *
217 * This method may be used if the caller needs to ensure validity before a
218 * command is attempted, e.g. if the lifecycle of the object is managed in some
219 * other place and the caller just has a reference to the #QmiClient.
220 *
221 * Returns: %TRUE if the client is valid, %FALSE otherwise.
222 *
223 * Since: 1.20
224 */
225 gboolean qmi_client_is_valid (QmiClient *self);
226
227 /**
228 * qmi_client_get_version:
229 * @self: A #QmiClient
230 * @major: placeholder for the output major version.
231 * @minor: placeholder for the output minor version.
232 *
233 * Get the version of the service handled by this #QmiClient.
234 *
235 * Returns: %TRUE if the version was properly reported, %FALSE otherwise.
236 *
237 * Since: 1.0
238 */
239 gboolean qmi_client_get_version (QmiClient *self,
240 guint *major,
241 guint *minor);
242
243 /**
244 * qmi_client_check_version:
245 * @self: A #QmiClient
246 * @major: a major version.
247 * @minor: a minor version.
248 *
249 * Checks if the version of the service handled by this #QmiClient is greater
250 * or equal than the given version.
251 *
252 * Returns: %TRUE if the version of the service is greater or equal than the one given, %FALSE otherwise.
253 *
254 * Since: 1.0
255 */
256 gboolean qmi_client_check_version (QmiClient *self,
257 guint major,
258 guint minor);
259
260 /**
261 * qmi_client_get_next_transaction_id:
262 * @self: A #QmiClient
263 *
264 * Acquire the next transaction ID of this #QmiClient.
265 * The internal transaction ID gets incremented.
266 *
267 * Returns: the next transaction ID.
268 *
269 * Since: 1.0
270 */
271 guint16 qmi_client_get_next_transaction_id (QmiClient *self);
272
273 /* not part of the public API */
274
275 #if defined (LIBQMI_GLIB_COMPILATION)
276 G_GNUC_INTERNAL
277 void __qmi_client_process_indication (QmiClient *self,
278 QmiMessage *message);
279 #endif
280
281 G_END_DECLS
282
283 #endif /* _LIBQMI_GLIB_QMI_CLIENT_H_ */